DataSource for C SDK
7.0.3.308987
|
![]() |
Data Structures | |
struct | ds_config_enum_t |
Enumerated types structure. More... | |
Macros | |
#define | DS_CONFIG_BOOL 0x0001 |
#define | DS_CONFIG_CHAR 0x0005 |
#define | DS_CONFIG_CHAR_ARRAY (DS_CONFIG_ARRAY|DS_CONFIG_CHAR) |
#define | DS_CONFIG_DEPRECATED 0x0400 |
#define | DS_CONFIG_FILE 0x0007 |
#define | DS_CONFIG_FLOAT 0x0003 |
#define | DS_CONFIG_FLOAT_ARRAY (DS_CONFIG_ARRAY|DS_CONFIG_FLOAT) |
#define | DS_CONFIG_FUNC 0x0006 |
#define | DS_CONFIG_INT 0x0002 |
#define | DS_CONFIG_INT_ARRAY (DS_CONFIG_ARRAY|DS_CONFIG_INT) |
#define | DS_CONFIG_STR 0x0004 |
#define | DS_CONFIG_STR_ARRAY (DS_CONFIG_ARRAY|DS_CONFIG_STR) |
#define | DS_CONFIG_STRICT 0x0200 |
#define | DS_OFFSET(t, m) |
Typedefs | |
typedef struct _config_ctx | ds_config_ctx_t |
The configuration context data type. More... | |
typedef void(* | ds_config_func) (char *name, int num, char **values) |
Definition of function type used for configuration callbacks. More... | |
Functions | |
void | ds_config_add_array_option (const char *longopt, const char *help, int type, void *value, int *num) |
Adds a configuration option to the current configuration context. More... | |
void | ds_config_add_array_option_enum (const char *longopt, const char *help, int type, void *value, int *num, ds_config_enum_t *enums) |
Add an enumerated option to the configuration context. More... | |
void | ds_config_add_bounded_array_option (const char *longopt, const char *help, int type, void *value, int *num, void *min, void *max) |
Adds a configuration option to the current configuration context. More... | |
void | ds_config_add_bounded_array_option_enum (const char *longopt, const char *help, int type, void *value, int *num, ds_config_enum_t *enums, void *min, void *max) |
Add an enumerated option to the configuration context. More... | |
void | ds_config_add_bounded_option (char sopt, const char *longopt, const char *help, int type, void *value, void *min, void *max) |
Add a bounded configuration option to the current configuration context. More... | |
void | ds_config_add_bounded_option_enum (char sopt, const char *longopt, const char *help, int type, void *value, ds_config_enum_t *enums, void *min, void *max) |
Add an enumerated option to the configuration context. More... | |
void | ds_config_add_config_reading_message_fmt (const char *fmt,...) |
Handle a configuration loading message. Add a formatted message to the list of messages to be logged. Echo the message to standard error if the verbose option is configured. More... | |
void | ds_config_add_error_message (const char *msg) |
Add a configuration error to the logfile. More... | |
void | ds_config_add_error_message_fmt (const char *fmt,...) |
Add a formatted error message to the logfile. More... | |
void | ds_config_add_file (const char *file) |
Add a mandatory configuration file to the current configuration context. More... | |
void | ds_config_add_group (const char *longopt, const char *help, void *base, void *def, size_t size, int *num) |
Add a configuration group to the current configuration context. More... | |
void | ds_config_add_group_with_info (const char *longopt, const char *help, void *base, void *def, size_t size, int *num, int file_offset, int line_offset) |
Add a configuration group to the current configuration context. More... | |
void | ds_config_add_option (char sopt, const char *longopt, const char *help, int type, void *value) |
Add a configuration option to the current configuration context. More... | |
void | ds_config_add_option_enum (char sopt, const char *longopt, const char *help, int type, void *value, ds_config_enum_t *enums) |
Add an enumerated option to the configuration context. More... | |
void | ds_config_add_optional_file (const char *file) |
Add an optional configuration file to the current configuration context. More... | |
void | ds_config_add_search (const char *path) |
Add a directory in which to search for configuration files. More... | |
void | ds_config_add_section (const char *longopt, const char *help) |
Adds a new configuration section to the current configuration context. More... | |
void | ds_config_del_option (const char *longopt) |
Remove an option from the current configuration context. More... | |
void | ds_config_del_test (const char *tag) |
Delete a conditional test. More... | |
void | ds_config_end_group (const char *longopt, const char *help) |
Ends a configuration group. More... | |
void | ds_config_end_section (const char *longopt, const char *help) |
Ends a configuration section. More... | |
void | ds_config_free_ctx (ds_config_ctx_t *ctx) |
Free a configuration context. More... | |
char * | ds_config_get_default_option_value (const char *option_name, char *buf, size_t buf_size) |
Allow external access of default config. More... | |
int | ds_config_get_enum (const char *value, ds_config_enum_t *enums) |
Get the value of an enumerated member. More... | |
char * | ds_config_get_filename (void) |
Return the current line number being parsed in the configuration file. More... | |
int | ds_config_get_linenumber (void) |
Return the name of current configuration file being parsed. More... | |
void | ds_config_list_options () |
Print the options in the current configuration context to standard output. More... | |
void | ds_config_list_values () |
Print the options and values in the current configuration context to standard output. More... | |
ds_config_ctx_t * | ds_config_new_ctx () |
Create a new configuration context. More... | |
void | ds_config_parse_args (int argc, char **argv, int *retargc) |
Parse the configuration options from the command line arguments given. More... | |
int | ds_config_parse_file (const char *unresolved_filename) |
Parse a single configuration file within the configuration context. More... | |
void | ds_config_parse_files () |
Parse all configuration files within the current configuration context. More... | |
ds_config_ctx_t * | ds_config_set_ctx (ds_config_ctx_t *ctx) |
Sets a configuration context as the current one. More... | |
void | ds_config_set_option (const char *name, const char *value) |
Set a particular configuration option. More... | |
void | ds_config_set_test (const char *tag, char **value) |
Adds a conditional test to the configuration file. More... | |
The DataSource SDK configuration API comprises functions that enable you to set configuration options specific to your application. The configuration API gives you additional flexibility when programming your DataSource. By including API functions within configuration files, they can be called to perform configuration tasks that are not covered by the main configuration file.
The configuration API makes use of "configuration contexts". A configuration context enables you to keep sets of configuration options independent of any others.
The configuration API allows you to group your configuration options within a configuration context in two ways: either as a group or a section.
#define DS_CONFIG_BOOL 0x0001 |
Defines the boolean data type.
#define DS_CONFIG_CHAR 0x0005 |
Defines the character data type.
#define DS_CONFIG_CHAR_ARRAY (DS_CONFIG_ARRAY|DS_CONFIG_CHAR) |
Defines the character array data type
#define DS_CONFIG_DEPRECATED 0x0400 |
Defines that this option has been deprecated - the description will give an alternate option to use
#define DS_CONFIG_FILE 0x0007 |
Defines the file data type.
#define DS_CONFIG_FLOAT 0x0003 |
Defines the floating point data type.
#define DS_CONFIG_FLOAT_ARRAY (DS_CONFIG_ARRAY|DS_CONFIG_FLOAT) |
Defines the floating point array data type
#define DS_CONFIG_FUNC 0x0006 |
Defines the configuration function data type. See ds_config_func()
#define DS_CONFIG_INT 0x0002 |
Defines the integer data type.
#define DS_CONFIG_INT_ARRAY (DS_CONFIG_ARRAY|DS_CONFIG_INT) |
Defines the integer array data type. There is no need to allocate space for the array
#define DS_CONFIG_STR 0x0004 |
Defines the string datatype. There is no need to allocate memory for this.
#define DS_CONFIG_STR_ARRAY (DS_CONFIG_ARRAY|DS_CONFIG_STR) |
Defines the string array data type
#define DS_CONFIG_STRICT 0x0200 |
Defines that only the enumerated values should be used, i.e. |&,+ are forbidden
#define DS_OFFSET | ( | t, | |
m | |||
) |
This macro is used to define the offset of a member in a struct. It is used within ds_config_add_option() or ds_config_add_array_option() when it is used as a group. Alternatively if your compiler supports it, you can use the offsetof() macro.
typedef struct _config_ctx ds_config_ctx_t |
The configuration context data type.
typedef void(* ds_config_func) (char *name, int num, char **values) |
Definition of function type used for configuration callbacks.
name | Name of the option |
num | Number of arguments |
values | Array of strings representing the arguments |
This function is used when the standard data types are not suitable or when a number of different arguments are needed. It is called when the relevant option (specified by the name parameter) is found in a configuration file.
void ds_config_add_array_option | ( | const char * | longopt, |
const char * | help, | ||
int | type, | ||
void * | value, | ||
int * | num | ||
) |
Adds a configuration option to the current configuration context.
longopt | Long option for use on the command line or in configuration files |
help | A short help string |
type | Configuration data type |
value | The address of the start of the array |
num | Pointer to the current size of the array. |
value should be the address of a pointer of the type of data, if will normally be NULL when this function is called.
*num will normally be 0 when this function is called. After the configuration files have been parsed, this integer holds the new size of the array.
void ds_config_add_array_option_enum | ( | const char * | longopt, |
const char * | help, | ||
int | type, | ||
void * | value, | ||
int * | num, | ||
ds_config_enum_t * | enums | ||
) |
Add an enumerated option to the configuration context.
longopt | Long option for use on the command line or in configuration files |
help | A short help string |
type | Configuration data type |
value | The address of the start of the array |
num | Pointer to the current size of the array. |
enums | Enumeration definitions. |
value should be the address of a pointer of the type of data, if will normally be NULL when this function is called.
*num will normally be 0 when this function is called. After the configuration files have been parsed, this integer holds the new size of the array.
This function adds a configuration option in the same as ds_config_add_array_option() but allows the use of enumerated names.
void ds_config_add_bounded_array_option | ( | const char * | longopt, |
const char * | help, | ||
int | type, | ||
void * | value, | ||
int * | num, | ||
void * | min, | ||
void * | max | ||
) |
Adds a configuration option to the current configuration context.
longopt | Long option for use on the command line or in configuration files |
help | A short help string |
type | Configuration data type |
value | The address of the start of the array |
num | Pointer to the current size of the array. |
min | Pointer to the minimum value this option should take |
max | Pointer to the maximum value this option should take |
value should be the address of a pointer of the type of data, if will normally be NULL when this function is called.
*num will normally be 0 when this function is called. After the configuration files have been parsed, this integer holds the new size of the array.
void ds_config_add_bounded_array_option_enum | ( | const char * | longopt, |
const char * | help, | ||
int | type, | ||
void * | value, | ||
int * | num, | ||
ds_config_enum_t * | enums, | ||
void * | min, | ||
void * | max | ||
) |
Add an enumerated option to the configuration context.
longopt | Long option for use on the command line or in configuration files |
help | A short help string |
type | Configuration data type |
value | The address of the start of the array |
num | Pointer to the current size of the array. |
enums | Enumeration definitions. |
min | Pointer to the minimum acceptable value |
max | Pointer to the maximum acceptable value |
value should be the address of a pointer of the type of data, if will normally be NULL when this function is called.
*num will normally be 0 when this function is called. After the configuration files have been parsed, this integer holds the new size of the array.
This function adds a configuration option in the same as ds_config_add_array_option() but allows the use of enumerated names.
void ds_config_add_bounded_option | ( | char | sopt, |
const char * | longopt, | ||
const char * | help, | ||
int | type, | ||
void * | value, | ||
void * | min, | ||
void * | max | ||
) |
Add a bounded configuration option to the current configuration context.
sopt | Short option for use on the command line (0 for none) |
longopt | Long option for use on the command line or in configuration files |
help | A short help string |
type | Configuration data type |
value | The address of the current option's value |
min | The minimum value that this option can take |
max | The maximum value that this option can take |
The value parameter should be the address of the variable that will hold the value.
void ds_config_add_bounded_option_enum | ( | char | sopt, |
const char * | longopt, | ||
const char * | help, | ||
int | type, | ||
void * | value, | ||
ds_config_enum_t * | enums, | ||
void * | min, | ||
void * | max | ||
) |
Add an enumerated option to the configuration context.
sopt | Short option for use on the command line (0 for none) |
longopt | Long option for use on the command line or in configuration files |
help | A short help string |
type | Configuration data type |
value | The address of the current option's value |
enums | Enumeration definitions. |
min | Pointer to the minimum acceptable value |
max | Pointer to the maximum acceptable value |
This function performs the same purpose as ds_config_add_option_enum(), but allow the minimum and maximum values to be specified.
void ds_config_add_config_reading_message_fmt | ( | const char * | fmt, |
... | |||
) |
Handle a configuration loading message. Add a formatted message to the list of messages to be logged. Echo the message to standard error if the verbose option is configured.
fmt | The format string to write |
Configuration reading messages are written to the logfile when ds_loop() is called by the DataSource application
void ds_config_add_error_message | ( | const char * | msg | ) |
void ds_config_add_error_message_fmt | ( | const char * | fmt, |
... | |||
) |
Add a formatted error message to the logfile.
fmt | The format string to write |
Configuration errors are written to the logfile when ds_loop() is called by the DataSource application
void ds_config_add_file | ( | const char * | file | ) |
Add a mandatory configuration file to the current configuration context.
file | The filename, absolute or relative to a search path. |
The file will be searched for within all search paths, if it can't be found the program will terminate when trying to parse the file.
void ds_config_add_group | ( | const char * | longopt, |
const char * | help, | ||
void * | base, | ||
void * | def, | ||
size_t | size, | ||
int * | num | ||
) |
Add a configuration group to the current configuration context.
longopt | Long option of this group |
help | A short help string |
base | Pointer to the start of the array of group structs |
def | Point to a structure of default values |
size | The size of the group structure |
num | Pointer to the number of elements in the array of group structs Using ds_config_add_option() after this function will add options to the configuration group, until ds_config_end_group() is called. |
When used inside a group, the value parameter of ds_config_add_option() should give the offset of the member within the group struct.
void ds_config_add_group_with_info | ( | const char * | longopt, |
const char * | help, | ||
void * | base, | ||
void * | def, | ||
size_t | size, | ||
int * | num, | ||
int | file_offset, | ||
int | line_offset | ||
) |
Add a configuration group to the current configuration context.
longopt | Long option of this group |
help | A short help string |
base | Pointer to the start of the array of group structs |
def | Point to a structure of default values |
size | The size of the group structure |
num | Pointer to the number of elements in the array of group structs |
file_offset | Offset within group to where the file this group is found will be kept |
line_offset | Offset to where the line this group is found will be kept |
Using ds_config_add_option() after this function will add options to the configuration group, until ds_config_end_group() is called.
When used inside a group, the value parameter of ds_config_add_option() should give the offset of the member within the group struct.
void ds_config_add_option | ( | char | sopt, |
const char * | longopt, | ||
const char * | help, | ||
int | type, | ||
void * | value | ||
) |
Add a configuration option to the current configuration context.
sopt | Short option for use on the command line (0 for none) |
longopt | Long option for use on the command line or in configuration files |
help | A short help string |
type | Configuration data type |
value | The address of the current option's value |
The value parameter should be the address of the variable that will hold the value.
void ds_config_add_option_enum | ( | char | sopt, |
const char * | longopt, | ||
const char * | help, | ||
int | type, | ||
void * | value, | ||
ds_config_enum_t * | enums | ||
) |
Add an enumerated option to the configuration context.
sopt | Short option for use on the command line (0 for none) |
longopt | Long option for use on the command line or in configuration files |
help | A short help string |
type | Configuration data type |
value | The address of the current option's value |
enums | Enumeration definitions. |
This function adds a configuration option in the same manner as ds_config_add_option() but allows the use of enumerated names.
void ds_config_add_optional_file | ( | const char * | file | ) |
Add an optional configuration file to the current configuration context.
file | The filename, absolute or relative to a search path. |
The file will be searched for within all search paths, if it can't be found the program will not terminate
void ds_config_add_search | ( | const char * | path | ) |
Add a directory in which to search for configuration files.
path | The absolute or relative path to add. |
Search paths are global and not specific to a configuration context
void ds_config_add_section | ( | const char * | longopt, |
const char * | help | ||
) |
Adds a new configuration section to the current configuration context.
longopt | The long option name of this section. |
help | A short help string. |
void ds_config_del_option | ( | const char * | longopt | ) |
Remove an option from the current configuration context.
longopt | The long option name of the option to remove. |
void ds_config_del_test | ( | const char * | tag | ) |
Delete a conditional test.
tag | String to identify this test |
void ds_config_end_group | ( | const char * | longopt, |
const char * | help | ||
) |
Ends a configuration group.
longopt | The long option name of the group to end |
help | A short help string |
void ds_config_end_section | ( | const char * | longopt, |
const char * | help | ||
) |
Ends a configuration section.
longopt | The long option name of the section to end. |
help | A short help string. |
void ds_config_free_ctx | ( | ds_config_ctx_t * | ctx | ) |
Free a configuration context.
ctx | The configuration context to be freed. |
char* ds_config_get_default_option_value | ( | const char * | option_name, |
char * | buf, | ||
size_t | buf_size | ||
) |
Allow external access of default config.
option_name | pointer to string of the default option to be retried |
buf | the character bufer to hold the return value of the string |
buf_size | size of the buffer for the return string |
int ds_config_get_enum | ( | const char * | value, |
ds_config_enum_t * | enums | ||
) |
Get the value of an enumerated member.
value | The enumerated member to get the value of |
enums | The array of enumerated values |
If a numeric string is passed in to this function then the value of it will be returned regardless of whether the value is an enum value.
char* ds_config_get_filename | ( | void | ) |
Return the current line number being parsed in the configuration file.
See ds_config_add_error_message() for an example of usage.
int ds_config_get_linenumber | ( | void | ) |
Return the name of current configuration file being parsed.
See ds_config_add_error_message() for an example of usage.
void ds_config_list_options | ( | ) |
Print the options in the current configuration context to standard output.
void ds_config_list_values | ( | ) |
Print the options and values in the current configuration context to standard output.
ds_config_ctx_t* ds_config_new_ctx | ( | ) |
Create a new configuration context.
void ds_config_parse_args | ( | int | argc, |
char ** | argv, | ||
int * | retargc | ||
) |
Parse the configuration options from the command line arguments given.
argc | The number of arguments |
argv | The array of arguments |
retargc | The number of unparsed arguments |
If retargc is not NULL, when the function returns it will contain the new argc value and the argv array will be shuffled to contain only the elements not found in the configuration context.
int ds_config_parse_file | ( | const char * | unresolved_filename | ) |
Parse a single configuration file within the configuration context.
unresolved_filename | The unresolved name of the configuration file to parse |
0 | The file was not found |
1 | The file was found and parsed |
The file must be absolute or relative to the configuration option application_root . Search paths are not used.
void ds_config_parse_files | ( | ) |
Parse all configuration files within the current configuration context.
A file will be looked for in the search paths identified by ds_config_add_search() in the order the paths were added, until the file is found
ds_config_ctx_t* ds_config_set_ctx | ( | ds_config_ctx_t * | ctx | ) |
Sets a configuration context as the current one.
ctx | The configuration context to be set |
This function returns the current configuration context, which should be used to reset the configuration context after user
void ds_config_set_option | ( | const char * | name, |
const char * | value | ||
) |
Set a particular configuration option.
name | - Name of the option |
value | - Value of the option |
The name should be the long option.
For setting a boolean, value should be either "true" or "false"
void ds_config_set_test | ( | const char * | tag, |
char ** | value | ||
) |
Adds a conditional test to the configuration file.
tag | String to identify this test |
value | Pointer to the string value to test against |
This enables you to change configuration settings dependent on factors such as changes in application or host.
Example use of conditional tests
if application rttpd # we are running a Liberator if host ourhost1 # it is running on ourhost1 - set the port to 80 http-port 80 else # It's not running on ourhost1 if host ourhost2 # It's running on ourhost2 http-port 85 else # It's not running on ourhost1 or ourhost2 http-port 8080 endif endif endif