updates.

[silc.git] / lib / silcutil / silcconfig.h

diff --git a/lib/silcutil/silcconfig.h b/lib/silcutil/silcconfig.h
index 87db1cf84fdaec31326dd283d39c1e159a740284..b4f5a70482e677b2054f3973f3b131a631ed0e3a 100644 (file)
--- a/lib/silcutil/silcconfig.h
+++ b/lib/silcutil/silcconfig.h
@@ -26,20 +26,21 @@
  * (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.
@@ -51,6 +52,7 @@
  * 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
@@ -104,7 +106,7 @@ enum {
   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 ';' */
 };
 /***/
@@ -383,7 +385,7 @@ char *silc_config_read_current_line(SilcConfigFile *file);
  *
  * 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);
@@ -394,14 +396,17 @@ char *silc_config_read_current_line(SilcConfigFile *file);
  *    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);
 
@@ -409,7 +414,7 @@ void silc_config_register(SilcConfigEntity ent, const char *name,
  *
  * SYNOPSIS
  *
- *    void silc_config_register_table(SilcConfigEntity ent,
+ *    bool silc_config_register_table(SilcConfigEntity ent,
  *                                    const SilcConfigTable table[],
  *                                    void *context);
  *
@@ -420,12 +425,16 @@ void silc_config_register(SilcConfigEntity ent, const char *name,
  *    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