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

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.

A group is a set of options that are repeated within the configuration context.
A section is a set of options that occurs once within the configuration context.

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

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.

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

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.

Parameters

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.

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

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.

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

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.

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

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.

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

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.

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

fmt	The 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

msg	The error message to write to the log

This function should be used inside a configuration callback.

 ds_config_add_option(0, �intval�, �Integer value between 1 and 3�, DS_CONFIG_FUNC, &myfunc);
 
 void myfunc(char *cmd, int num, char **values)
 {
     int myint = values[0];
     if ( (myint < 1) || (myint > 3) )
     {
         char buffer[255];
         int linenum = ds_config_get_linenumber();
         char *filename = ds_config_get_filename();
         sprintf(buffer, "Value of 'intval' set to %d on line %d of file %s, must be between 1 and 3.\n", myint,linenum, filename);
         ds_config_add_error_message(buffer);
     }
 }

void ds_config_add_error_message_fmt	(	const char *	fmt,
			...
	)

Add a formatted error message to the logfile.

Parameters

fmt	The 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

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.

Parameters

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.

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

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.

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

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.

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

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.

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

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.

Parameters

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.

Parameters

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.

Parameters

longopt The long option name of the option to remove.

void ds_config_del_test ( const char * tag )

Delete a conditional test.

Parameters

tag	String to identify this test

void ds_config_end_group	(	const char *	longopt,
		const char *	help
	)

Ends a configuration group.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

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

value	The enumerated member to get the value of
enums	The 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 ( )

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.

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

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.

Parameters

unresolved_filename The unresolved name of the configuration file to parse

Return values

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.

Parameters

ctx	The 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

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

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation