DataSource for C SDK  7.1.5.312018
Configuration API

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_tds_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_tds_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...
 

Detailed Description

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.

Note
Using the default configuration context is acceptable in most cases.

The configuration API allows you to group your configuration options within a configuration context in two ways: either as a group or a section.

Macro Definition Documentation

#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,
 
)

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 Documentation

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.

Parameters
nameName of the option
numNumber of arguments
valuesArray 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.

Function Documentation

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.

Parameters
longoptLong option for use on the command line or in configuration files
helpA short help string
typeConfiguration data type
valueThe address of the start of the array
numPointer 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.

Parameters
longoptLong option for use on the command line or in configuration files
helpA short help string
typeConfiguration data type
valueThe address of the start of the array
numPointer to the current size of the array.
enumsEnumeration 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.

Note
The last value of enums should have a NULL name member
This only works with DS_CONFIG_INT or DS_CONFIG_FLOAT data types
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.

Parameters
longoptLong option for use on the command line or in configuration files
helpA short help string
typeConfiguration data type
valueThe address of the start of the array
numPointer to the current size of the array.
minPointer to the minimum value this option should take
maxPointer 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.

Note
The minimum/maximum values only apply to configuration options of type DS_CONFIG_INT or DS_CONFIG_FLOAT
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.

Parameters
longoptLong option for use on the command line or in configuration files
helpA short help string
typeConfiguration data type
valueThe address of the start of the array
numPointer to the current size of the array.
enumsEnumeration definitions.
minPointer to the minimum acceptable value
maxPointer 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.

Note
The last value of enums should have a NULL name member
This only works with DS_CONFIG_INT or DS_CONFIG_FLOAT data types
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.

Parameters
soptShort option for use on the command line (0 for none)
longoptLong option for use on the command line or in configuration files
helpA short help string
typeConfiguration data type
valueThe address of the current option's value
minThe minimum value that this option can take
maxThe maximum value that this option can take

The value parameter should be the address of the variable that will hold the value.

  • If the option is not found either on the command line or in a configuration file, value will not change.
  • If the option is found either on the command line or in a configuration file, value will be changed accordingly.
  • If the option is within a group then value should be the offset of the member within the ds_config_add_group() group struct. The DS_OFFSET macro should be used to define the offset in that case.
  • If the option is within a section, should simply be the address of that option. The variables may be grouped within a struct or not.
Note
The minimum/maximum values only apply to configuration options of type DS_CONFIG_INT or DS_CONFIG_FLOAT
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.

Parameters
soptShort option for use on the command line (0 for none)
longoptLong option for use on the command line or in configuration files
helpA short help string
typeConfiguration data type
valueThe address of the current option's value
enumsEnumeration definitions.
minPointer to the minimum acceptable value
maxPointer 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.

Note
The last value of enums should have a NULL name member
This only works with DS_CONFIG_INT or DS_CONFIG_FLOAT data types
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.

Parameters
fmtThe format string to write
See also
ds_config_add_error_message()

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)

Add a configuration error to the logfile.

Parameters
msgThe error message to write to the log

This function should be used inside a configuration callback.

1 ds_config_add_option(0, “intval”, “Integer value between 1 and 3”, DS_CONFIG_FUNC, &myfunc);
2 
3 void myfunc(char *cmd, int num, char **values)
4 {
5  int myint = values[0];
6  if ( (myint < 1) || (myint > 3) )
7  {
8  char buffer[255];
9  int linenum = ds_config_get_linenumber();
10  char *filename = ds_config_get_filename();
11  sprintf(buffer, "Value of 'intval' set to %d on line %d of file %s, must be between 1 and 3.\n", myint,linenum, filename);
12  ds_config_add_error_message(buffer);
13  }
14 }
void ds_config_add_error_message_fmt ( const char *  fmt,
  ... 
)

Add a formatted error message to the logfile.

Parameters
fmtThe format string to write
See also
ds_config_add_error_message()

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.

Parameters
fileThe 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.

Parameters
longoptLong option of this group
helpA short help string
basePointer to the start of the array of group structs
defPoint to a structure of default values
sizeThe size of the group structure
numPointer 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.

Note
Each option within a group should map onto a variable within a struct which should define the whole group.
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.

Parameters
longoptLong option of this group
helpA short help string
basePointer to the start of the array of group structs
defPoint to a structure of default values
sizeThe size of the group structure
numPointer to the number of elements in the array of group structs
file_offsetOffset within group to where the file this group is found will be kept
line_offsetOffset 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.

Note
Each option within a group should map onto a variable within a struct which should define the whole group.
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.

Parameters
soptShort option for use on the command line (0 for none)
longoptLong option for use on the command line or in configuration files
helpA short help string
typeConfiguration data type
valueThe address of the current option's value

The value parameter should be the address of the variable that will hold the value.

  • If the option is not found either on the command line or in a configuration file, value will not change.
  • If the option is found either on the command line or in a configuration file, value will be changed accordingly.
  • If the option is within a group then value should be the offset of the member within the ds_config_add_group() group struct. The DS_OFFSET macro should be used to define the offset in that case.
  • If the option is within a section, should simply be the address of that option. The variables may be grouped within a struct or not.
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.

Parameters
soptShort option for use on the command line (0 for none)
longoptLong option for use on the command line or in configuration files
helpA short help string
typeConfiguration data type
valueThe address of the current option's value
enumsEnumeration definitions.

This function adds a configuration option in the same manner as ds_config_add_option() but allows the use of enumerated names.

Note
The last value of enums should have a NULL name member
This only works with DS_CONFIG_INT or DS_CONFIG_FLOAT data types
void ds_config_add_optional_file ( const char *  file)

Add an optional configuration file to the current configuration context.

Parameters
fileThe 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.

Parameters
pathThe 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.

Parameters
longoptThe long option name of this section.
helpA short help string.
void ds_config_del_option ( const char *  longopt)

Remove an option from the current configuration context.

Parameters
longoptThe long option name of the option to remove.
void ds_config_del_test ( const char *  tag)

Delete a conditional test.

Parameters
tagString to identify this test
void ds_config_end_group ( const char *  longopt,
const char *  help 
)

Ends a configuration group.

Parameters
longoptThe long option name of the group to end
helpA short help string
void ds_config_end_section ( const char *  longopt,
const char *  help 
)

Ends a configuration section.

Parameters
longoptThe long option name of the section to end.
helpA short help string.
void ds_config_free_ctx ( ds_config_ctx_t ctx)

Free a configuration context.

Parameters
ctxThe 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.

Parameters
option_namepointer to string of the default option to be retried
bufthe character bufer to hold the return value of the string
buf_sizesize of the buffer for the return string
Returns
character array containing string value of the options returned
int ds_config_get_enum ( const char *  value,
ds_config_enum_t enums 
)

Get the value of an enumerated member.

Parameters
valueThe enumerated member to get the value of
enumsThe array of enumerated values
Returns
The value or 0 on failure

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.

Returns
The current line number

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.

Returns
The current filename

See ds_config_add_error_message() for an example of usage.

void ds_config_list_options ( void  )

Print the options in the current configuration context to standard output.

void ds_config_list_values ( void  )

Print the options and values in the current configuration context to standard output.

ds_config_ctx_t* ds_config_new_ctx ( void  )

Create a new configuration context.

Returns
A configuration context
void ds_config_parse_args ( int  argc,
char **  argv,
int *  retargc 
)

Parse the configuration options from the command line arguments given.

Parameters
argcThe number of arguments
argvThe array of arguments
retargcThe 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.

Parameters
unresolved_filenameThe unresolved name of the configuration file to parse
Return values
0The file was not found
1The 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 ( void  )

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.

Parameters
ctxThe configuration context to be set
Returns
The current configuration context

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.

Parameters
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.

Parameters
tagString to identify this test
valuePointer to the string value to test against
Note
Logical operators may not be used in the configuration statements that use the conditional tests.

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

Generated on Sun Oct 21 2018 12:23:28 for DataSource for C SDK