* (or File object) and SilcConfigEntity (or Entity). The File objects are
* structs directly corresponding to the real files in the filesystem, while
* Entities are a little more abstract.
+ *
* An Entity is composed by delimited area on a File object (it can take the
* whole File object or just part of it), plus a group of known options.
- *
* In order to parse this file, first you need to create a File object with
* the silc_config_open() function, and then you need to create the Entity
* with the silc_config_init() function.
+ *
* Now you can use the newly created Entity to register a group of expected
* known options and sub-blocks, and then you can call the main parsing loop
- * with the silc_config_main() function.
- * When silc_config_main() will return, if some error encoured the object file
- * will point to the file that caused this error (this can be different from
- * the originally opened file if it contained `Include' directives). If no
- * errors encoured then the File objects will still point to the original
- * file.
+ * with the silc_config_main() function. When silc_config_main() will
+ * return, if some error encoured the object file will point to the file
+ * that caused this error (this can be different from the originally
+ * opened file if it contained `Include' directives). If no errors
+ * encoured then the File objects will still point to the original file.
+ *
* While silc_config_main() will take care of destroying Entities before
* returning, you need to take care that the File object you created is freed
* with the silc_config_close() function.
* The config file syntax is pretty straightforward. All lines starting
* with `#' will be skipped, while sub-blocks are delimited by braces (see
* the example below).
+ *
* Options with argument must have the `=' character between the option
* name and the value. Simple words and numbers does not require quoting.
* There is a special built-in directive "Include" which allows you to include
SILC_CONFIG_EEXPECTED, /* Expected data but not found */
SILC_CONFIG_EEXPECTEDEQUAL, /* Expected '=' */
SILC_CONFIG_EUNEXPECTED, /* Unexpected data */
- SILC_CONFIG_EMISSFIELDS, /* Missing needed fields */
+ SILC_CONFIG_EMISSFIELDS, /* Missing mandatory fields */
SILC_CONFIG_EMISSCOLON, /* Missing ';' */
};
/***/
* SYNOPSIS
*
* typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
- * uint32 line, void *val, void *context);
+ * SilcUInt32 line, void *val, void *context);
* DESCRIPTION
*
* This is the callback prototype for the options handler. The pointer
*
***/
typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
- uint32 line, void *val, void *context);
+ SilcUInt32 line, void *val, void *context);
/****s* silcutil/SilcConfigAPI/SilcConfigTable
*
*/
#define SILC_CONFIG_CALLBACK(func) \
static int func(SilcConfigType type, const char *name, \
- uint32 line, void *val, void *context)
+ SilcUInt32 line, void *val, void *context)
/***/
/* Prototypes */
*
* SYNOPSIS
*
- * uint32 silc_config_get_line(SilcConfigFile *file);
+ * SilcUInt32 silc_config_get_line(SilcConfigFile *file);
*
* DESCRIPTION
*
* Returns the current line that file parsing arrived at.
*
***/
-uint32 silc_config_get_line(SilcConfigFile *file);
+SilcUInt32 silc_config_get_line(SilcConfigFile *file);
/****f* silcutil/SilcConfigAPI/silc_config_read_line
*
* SYNOPSIS
*
- * char *silc_config_read_line(SilcConfigFile *file, uint32 line);
+ * char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
*
* DESCRIPTION
*
* silc_config_read_current_line
*
***/
-char *silc_config_read_line(SilcConfigFile *file, uint32 line);
+char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
/****f* silcutil/SilcConfigAPI/silc_config_read_current_line
*
*
* SYNOPSIS
*
- * void silc_config_register(SilcConfigEntity ent, const char *name,
+ * bool silc_config_register(SilcConfigEntity ent, const char *name,
* SilcConfigType type, SilcConfigCallback cb,
* const SilcConfigTable *subtable,
* void *context);
* will be called with the *val pointer pointing to an internally
* allocated storage of type described by `type'.
* If `type' is SILC_CONFIG_ARG_BLOCK, then `subtable' must be a valid
- * pointer to a SilcConfigTable array specified the options in the
+ * pointer to a SilcConfigTable array specifying the options in the
* sub-block.
+ * If the option `name' was already registered in this sub-block or it
+ * matches the reserved word "Include", then this function returns FALSE,
+ * otherwise it returns TRUE.
*
* SEE ALSO
* silc_config_register_table
*
***/
-void silc_config_register(SilcConfigEntity ent, const char *name,
+bool silc_config_register(SilcConfigEntity ent, const char *name,
SilcConfigType type, SilcConfigCallback cb,
const SilcConfigTable *subtable, void *context);
*
* SYNOPSIS
*
- * void silc_config_register_table(SilcConfigEntity ent,
+ * bool silc_config_register_table(SilcConfigEntity ent,
* const SilcConfigTable table[],
* void *context);
*
* all with the same context `context'.
* The `table' array must be terminated with an entry with the name field
* set to NULL.
+ * If the table contains invalid data this function returns FALSE, otherwise
+ * it returns TRUE. If a calling to this function failed, you must destroy
+ * and recreate the entity before retrying, as it's impossible to detect
+ * the point at the function stopped the registering process.
*
* SEE ALSO
* SilcConfigTable
*
***/
-void silc_config_register_table(SilcConfigEntity ent,
+bool silc_config_register_table(SilcConfigEntity ent,
const SilcConfigTable table[], void *context);
/****f* silcutil/SilcConfigAPI/silc_config_main
projects / silc.git / blobdiff