libini_config  0.5.0
 All Data Structures Functions Variables Enumerations Enumerator Modules Pages
Functions
Value management

Functions

int ini_get_config_valueobj (const char *section, const char *name, struct ini_cfgobj *ini_config, int mode, struct value_obj **vo)
 Retrieve a value object form the configuration. More...
 
int ini_get_int_config_value (struct value_obj *vo, int strict, int def, int *error)
 Convert value to integer number. More...
 
unsigned ini_get_unsigned_config_value (struct value_obj *vo, int strict, unsigned def, int *error)
 Convert value object to a unsigned number. More...
 
long ini_get_long_config_value (struct value_obj *vo, int strict, long def, int *error)
 Convert value to long number. More...
 
unsigned long ini_get_ulong_config_value (struct value_obj *vo, int strict, unsigned long def, int *error)
 Convert value to unsigned long number. More...
 
int32_t ini_get_int32_config_value (struct value_obj *vo, int strict, int32_t def, int *error)
 Convert value to int32_t number. More...
 
uint32_t ini_get_uint32_config_value (struct value_obj *vo, int strict, uint32_t def, int *error)
 Convert value to uint32_t number. More...
 
int64_t ini_get_int64_config_value (struct value_obj *vo, int strict, int64_t def, int *error)
 Convert value to integer number. More...
 
uint64_t ini_get_uint64_config_value (struct value_obj *vo, int strict, uint64_t def, int *error)
 Convert value to integer number. More...
 
double ini_get_double_config_value (struct value_obj *vo, int strict, double def, int *error)
 Convert value to floating point number. More...
 
unsigned char ini_get_bool_config_value (struct value_obj *vo, unsigned char def, int *error)
 Convert value into a logical value. More...
 
char * ini_get_string_config_value (struct value_obj *vo, int *error)
 Get the copy of string stored in the configuration value. More...
 
const char * ini_get_const_string_config_value (struct value_obj *vo, int *error)
 Get the string stored in the configuration value. More...
 
char * ini_get_bin_config_value (struct value_obj *vo, int *length, int *error)
 Convert value into a binary sequence. More...
 
void ini_free_bin_config_value (char *bin)
 Free binary buffer. More...
 
char ** ini_get_string_config_array (struct value_obj *vo, const char *sep, int *size, int *error)
 Convert value to an array of strings. More...
 
char ** ini_get_raw_string_config_array (struct value_obj *vo, const char *sep, int *size, int *error)
 Convert value to an array of strings. More...
 
long * ini_get_long_config_array (struct value_obj *vo, int *size, int *error)
 Convert value to an array of long values. More...
 
double * ini_get_double_config_array (struct value_obj *vo, int *size, int *error)
 Convert value to an array of floating point values. More...
 
void ini_free_string_config_array (char **str_config)
 Free array of string values. More...
 
void ini_free_long_config_array (long *array)
 Free array of long values. More...
 
void ini_free_double_config_array (double *array)
 Free array of floating pointer values. More...
 

Detailed Description

This section contains value management functions. These functions can be used to interpret values that are stored in the configuration object in memory.

Function Documentation

int ini_get_config_valueobj ( const char *  section,
const char *  name,
struct ini_cfgobj *  ini_config,
int  mode,
struct value_obj **  vo 
)

Retrieve a value object form the configuration.

Check return error code first. If the function returns an error there is a serious problem. Then check if object is found. Function will set vo parameter to NULL if no attribute with provided name is found in the collection.

Parameters
[in]sectionSection name. If NULL assumed default.
[in]nameAttribute name to find.
[in]ini_configConfiguration object to search.
[in]modeSee search mode section for more info.
[out]voValue object. Will be set to NULL if element with the given name is not found.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
int ini_get_int_config_value ( struct value_obj *  vo,
int  strict,
int  def,
int *  error 
)

Convert value to integer number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into an int number. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from INT_MIN to INT_MAX.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
unsigned ini_get_unsigned_config_value ( struct value_obj *  vo,
int  strict,
unsigned  def,
int *  error 
)

Convert value object to a unsigned number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into an unsigned number. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from 0 to UINT_MAX.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
long ini_get_long_config_value ( struct value_obj *  vo,
int  strict,
long  def,
int *  error 
)

Convert value to long number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into a long number. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from LONG_MIN to LONG_MAX.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
unsigned long ini_get_ulong_config_value ( struct value_obj *  vo,
int  strict,
unsigned long  def,
int *  error 
)

Convert value to unsigned long number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into an unsigned long number. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from 0 to ULONG_MAX.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
int32_t ini_get_int32_config_value ( struct value_obj *  vo,
int  strict,
int32_t  def,
int *  error 
)

Convert value to int32_t number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into an int32_t number. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from INT_MIN to INT_MAX.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
uint32_t ini_get_uint32_config_value ( struct value_obj *  vo,
int  strict,
uint32_t  def,
int *  error 
)

Convert value to uint32_t number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration value into an uint32_t number. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from 0 to ULONG_MAX.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
int64_t ini_get_int64_config_value ( struct value_obj *  vo,
int  strict,
int64_t  def,
int *  error 
)

Convert value to integer number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into an int64_t number. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from LLONG_MIN to LLONG_MAX.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
uint64_t ini_get_uint64_config_value ( struct value_obj *  vo,
int  strict,
uint64_t  def,
int *  error 
)

Convert value to integer number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into an uint64_t number. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from 0 to ULLONG_MAX.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
double ini_get_double_config_value ( struct value_obj *  vo,
int  strict,
double  def,
int *  error 
)

Convert value to floating point number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into a floating point number. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
unsigned char ini_get_bool_config_value ( struct value_obj *  vo,
unsigned char  def,
int *  error 
)

Convert value into a logical value.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into a Boolean. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
Returns
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
char* ini_get_string_config_value ( struct value_obj *  vo,
int *  error 
)

Get the copy of string stored in the configuration value.

Function creates a copy of the string value stored in the configuration element. Returned value needs to be freed after use. If error occurred the returned value will be NULL.

Parameters
[in]voValue object to use. It must be retrieved using ini_get_config_valueobj().
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • ENOMEM - No memory.
Returns
Copy of the string or NULL.
const char* ini_get_const_string_config_value ( struct value_obj *  vo,
int *  error 
)

Get the string stored in the configuration value.

Function returns a reference to the string value stored inside the configuration element. This string can't be altered. The string will go out of scope if the value object is deleted.

Parameters
[in]voValue object to use. It must be retrieved using ini_get_config_valueobj().
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
Returns
String from the value object.
char* ini_get_bin_config_value ( struct value_obj *  vo,
int *  length,
int *  error 
)

Convert value into a binary sequence.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into a sequence of bytes. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value.

The function allocates memory. It is the responsibility of the caller to free it after use. Use ini_free_bin_config_value() for this purpose. Functions will return NULL if conversion failed.

Function assumes that the value being interpreted has a special format. The string should be taken in single quotes and consist of hex encoded value represented by two hex digits per byte. Case does not matter.

Example: '0a2BFeCc'

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[out]lengthVariable that optionally receives the length of the binary sequence.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ENOMEM - No memory.
Returns
Converted value. In case of failure the function returns NULL.
void ini_free_bin_config_value ( char *  bin)

Free binary buffer.

Free binary value returned by ini_get_bin_config_value().

Parameters
[in]binBinary buffer to free.
char** ini_get_string_config_array ( struct value_obj *  vo,
const char *  sep,
int *  size,
int *  error 
)

Convert value to an array of strings.

This is a conversion function. It converts the value read from the INI file and stored in the configuration value object into an array of strings. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value.

Separator string includes up to three different separators. If separator NULL, comma is assumed. The spaces are trimmed automatically around separators in the string. The function drops empty tokens from the list. This means that the string like this: "apple, ,banana, ,orange ," will be translated into the list of three items: "apple","banana" and "orange".

The length of the allocated array is returned in "size". Size and error parameters can be NULL. Use ini_free_string_config_array() to free the array after use.

The array is always NULL terminated so it is safe not to get size and just loop until array element is NULL.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]sepString cosisting of separator symbols. For example: ",.;" would mean that comma, dot and semicolon should be treated as separators in the value.
[out]sizeVariable that optionally receives the size of the array.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed.
  • ENOMEM - No memory.
Returns
Array of strings. In case of failure the function returns NULL.
char** ini_get_raw_string_config_array ( struct value_obj *  vo,
const char *  sep,
int *  size,
int *  error 
)

Convert value to an array of strings.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into an array of strings. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value.

Separator string includes up to three different separators. If separator NULL, comma is assumed. The spaces are trimmed automatically around separators in the string. The function does not drop empty tokens from the list. This means that the string like this: "apple, ,banana, ,orange ," will be translated into the list of five items: "apple", "", "banana", "" and "orange".

The length of the allocated array is returned in "size". Size and error parameters can be NULL. Use ini_free_string_config_array() to free the array after use.

The array is always NULL terminated so it is safe not to get size and just loop until array element is NULL.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[in]sepString cosisting of separator symbols. For example: ",.;" would mean that comma, dot and semicolon should be treated as separators in the value.
[out]sizeVariable that optionally receives the size of the array.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed.
  • ENOMEM - No memory.
Returns
Array of strings. In case of failure the function returns NULL.
long* ini_get_long_config_array ( struct value_obj *  vo,
int *  size,
int *  error 
)

Convert value to an array of long values.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into an array of long values. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value.

Separators inside the string are detected automatically. The spaces are trimmed automatically around separators in the string.

The length of the allocated array is returned in "size". Size parameter can't be NULL.

Use ini_free_long_config_array() to free the array after use.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[out]sizeVariable that receives the size of the array.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed.
  • ERANGE - Value is out of range.
  • ENOMEM - No memory.
Returns
Array of long values. In case of failure the function returns NULL.
double* ini_get_double_config_array ( struct value_obj *  vo,
int *  size,
int *  error 
)

Convert value to an array of floating point values.

This is a conversion function. It converts the value read from the INI file and stored in the configuration element into an array of floating point values. Any of the conversion functions can be used to try to convert the value stored as a string inside the value object. The result can be different depending upon how the caller tries to interpret the value.

Separators inside the string are detected automatically. The spaces are trimmed automatically around separators in the string.

The length of the allocated array is returned in "size". Size parameter can't be NULL.

Use ini_free_double_config_array() to free the array after use.

Parameters
[in]voValue object to interpret. It must be retrieved using ini_get_config_valueobj().
[out]sizeVariable that receives the size of the array.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed.
  • ENOMEM - No memory.
Returns
Array of floating point values. In case of failure the function returns NULL.
void ini_free_string_config_array ( char **  str_config)

Free array of string values.

Use this function to free the array returned by ini_get_string_config_array() or by ini_get_raw_string_config_array().

Parameters
[in]str_configArray of string values.
void ini_free_long_config_array ( long *  array)

Free array of long values.

Use this function to free the array returned by ini_get_long_config_array().

Parameters
[in]arrayArray of long values.
void ini_free_double_config_array ( double *  array)

Free array of floating pointer values.

Use this function to free the array returned by ini_get_double_config_array().

Parameters
[in]arrayArray of floating pointer values.