lib/silcutil/silcconfig.h

   1 /*
   2
   3   silcconfig.h
   4
   5   Author: Giovanni Giacobbi <giovanni@giacobbi.net>
   6
   7   Copyright (C) 2002 - 2003 Giovanni Giacobbi
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Config Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * The SILC Config util library is based on two main objects, SilcConfigFile
  25  * (or File object) and SilcConfigEntity (or Entity).  The File objects are
  26  * structs directly corresponding to the real files in the filesystem, while
  27  * Entities are a little more abstract.
  28  *
  29  * An Entity is composed by delimited area on a File object (it can take the
  30  * whole File object or just part of it), plus a group of known options.
  31  * In order to parse this file, first you need to create a File object with
  32  * the silc_config_open() function, and then you need to create the Entity
  33  * with the silc_config_init() function.
  34  *
  35  * Now you can use the newly created Entity to register a group of expected
  36  * known options and sub-blocks, and then you can call the main parsing loop
  37  * with the silc_config_main() function. When silc_config_main() will
  38  * return, if some error encoured the object file will point to the file
  39  * that caused this error (this can be different from the originally
  40  * opened file if it contained `Include' directives).  If no errors
  41  * encoured then the File objects will still point to the original file.
  42  *
  43  * While silc_config_main() will take care of destroying Entities before
  44  * returning, you need to take care that the File object you created is freed
  45  * with the silc_config_close() function.
  46  *
  47  * The SILC Config library won't take care about storing the values contained
  48  * in the config file.  You must take care about it with the callback
  49  * functions.
  50  *
  51  * The config file syntax is pretty straightforward.  All lines starting
  52  * with `#' will be skipped, while sub-blocks are delimited by braces (see
  53  * the example below).
  54  *
  55  * Options with argument must have the `=' character between the option
  56  * name and the value.  Simple words and numbers does not require quoting.
  57  * There is a special built-in directive "Include" which allows you to include
  58  * another config file in the point the directive is.  You can also Include
  59  * inside a sub-block body, in this case when parsing the included config file
  60  * it will be assumed that we are within this block, and the included file
  61  * won't be allowed to close his root block.
  62  *
  63  * Example:
  64  *
  65  *    cipher {
  66  *       name = aes-256-cbc;
  67  *       module = "aes.sim.so";
  68  *       key_length = 32;       # usually the default is just fine
  69  *       block_length = 16;
  70  *    };
  71  *    Include "/etc/silc/hash_funcs.conf";
  72  *
  73  ***/
  74
  75 #ifndef SILCCONFIG_H
  76 #define SILCCONFIG_H
  77
  78 /****d* silcutil/SilcConfigAPI/SilcConfigErrno
  79  *
  80  * NAME
  81  *
  82  *    enum { ... } - describe a SILC Config error
  83  *
  84  * DESCRIPTION
  85  *
  86  *    The virtual integer `errno' is returned by the silc_config_main()
  87  *    function and indicates what went wrong.
  88  *    You can convert it to the corresponding error string with the function
  89  *    silc_config_strerror().
  90  *
  91  * SOURCE
  92  */
  93 enum {
  94   SILC_CONFIG_OK,               /* OK */
  95   SILC_CONFIG_ESILENT,          /* Error defined by callback function */
  96   SILC_CONFIG_EPRINTLINE,       /* Error defined by callback function */
  97   SILC_CONFIG_EGENERIC,         /* Invalid syntax */
  98   SILC_CONFIG_EINTERNAL,        /* Internal Error (caused by developer) */
  99   SILC_CONFIG_ECANTOPEN,        /* Can't open specified file */
 100   SILC_CONFIG_EOPENBRACE,       /* Expected open-brace '{' */
 101   SILC_CONFIG_ECLOSEBRACE,      /* Missing close-brace '}' */
 102   SILC_CONFIG_ETYPE,            /* Invalid data type */
 103   SILC_CONFIG_EBADOPTION,       /* Unknown option */
 104   SILC_CONFIG_EINVALIDTEXT,     /* Invalid text */
 105   SILC_CONFIG_EDOUBLE,          /* Double option specification */
 106   SILC_CONFIG_EEXPECTED,        /* Expected data but not found */
 107   SILC_CONFIG_EEXPECTEDEQUAL,   /* Expected '=' */
 108   SILC_CONFIG_EUNEXPECTED,      /* Unexpected data */
 109   SILC_CONFIG_EMISSFIELDS,      /* Missing mandatory fields */
 110   SILC_CONFIG_EMISSCOLON,       /* Missing ';' */
 111 };
 112 /***/
 113
 114 /****d* silcutil/SilcConfigAPI/SilcConfigType
 115  *
 116  * NAME
 117  *
 118  *    typedef enum { ... } SilcConfigType;
 119  *
 120  * DESCRIPTION
 121  *
 122  *    This identifies the parameter type that an option has. This parameter
 123  *    is very important because the callback's *val pointer points to a
 124  *    memory location containing the previously specified data type.
 125  *    For example, if you specified an option with an integer parameter
 126  *    callback's *val will be a pointer to an integer.
 127  *
 128  * SOURCE
 129  */
 130 typedef enum {
 131   SILC_CONFIG_ARG_TOGGLE,       /* TOGGLE on,off; yes,no; true, false; */
 132   SILC_CONFIG_ARG_INT,          /* callback wants an integer */
 133   SILC_CONFIG_ARG_STR,          /* callback expects \0-terminated str */
 134   SILC_CONFIG_ARG_STRE,         /* same as above, but can also be empty */
 135   SILC_CONFIG_ARG_BLOCK,        /* this is a sub-block */
 136   SILC_CONFIG_ARG_SIZE,         /* like int, but accepts suffixes kMG */
 137   SILC_CONFIG_ARG_NONE,         /* does not expect any args */
 138 } SilcConfigType;
 139 /***/
 140
 141 /****f* silcutil/SilcConfigAPI/SilcConfigCallback
 142  *
 143  * SYNOPSIS
 144  *
 145  *    typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
 146  *                                      SilcUInt32 line, void *val,
 147  *                                      void *context);
 148  * DESCRIPTION
 149  *
 150  *    This is the callback prototype for the options handler.  The pointer
 151  *    `val' points to a location of type described by `type'.  `name' points
 152  *    to a null-terminated string with the name of the option which triggered
 153  *    this callback, that is stated at line `line'.  `context' is the
 154  *    user-specified context provided when this option was registered.
 155  *
 156  ***/
 157 typedef int (*SilcConfigCallback)(SilcConfigType type, const char *name,
 158                                   SilcUInt32 line, void *val, void *context);
 159
 160 /****s* silcutil/SilcConfigAPI/SilcConfigTable
 161  *
 162  * SYNOPSIS
 163  *
 164  *    typedef struct { ... } SilcConfigTable;
 165  *
 166  * DESCRIPTION
 167  *
 168  *    SILC Config table defines an easy and quick way of registering options
 169  *    in an entity. The function silc_config_register_table() will take as
 170  *    argument a SilcConfigTable array terminated by a NULL struct, it is
 171  *    important thus, that the `name' field of the terminating struct is set
 172  *    to NULL.
 173  *
 174  *    char *name
 175  *
 176  *       The option name lowercase. The matching is always case-insensitive,
 177  *       but for convention the option specification must always be lowercase.
 178  *
 179  *    SilcConfigType type
 180  *
 181  *       This specifies what kind of parameter this option expects.  The
 182  *       special cases SILC_CONFIG_ARG_BLOCK tells SILC Config that this is
 183  *       not a normal option but the name of a sub-block of the current
 184  *       block (there is no limit to the number of nested blocks allowed).
 185  *
 186  *    SilcConfigCallback callback
 187  *
 188  *       Normally this is the value handler of the current option. If this
 189  *       field is set to NULL then the value is silently discarded. Useful
 190  *       for example to support deprecated options.
 191  *
 192  *    SilcConfigTable *subtable
 193  *
 194  *       If the `type' field is set to SILC_CONFIG_ARG_BLOCK, then this field
 195  *       must point to a valid sub-table NULL-terminated array. If `type' is
 196  *       something else, this valued is unused.
 197  *
 198  ***/
 199 typedef struct SilcConfigTableStruct {
 200   char *name;
 201   SilcConfigType type;
 202   SilcConfigCallback callback;
 203   const struct SilcConfigTableStruct *subtable;
 204 } SilcConfigTable;
 205
 206 /****s* silcutil/SilcConfigAPI/SilcConfigFile
 207  *
 208  * SYNOPSIS
 209  *
 210  *    typedef struct SilcConfigFileObject SilcConfigFile;
 211  *
 212  * DESCRIPTION
 213  *
 214  *    A File object holds the data contained in a previously loaded file by
 215  *    the silc_config_open() function.
 216  *    This is an internally allocated struct and must be used only with the
 217  *    helper functions.
 218  *
 219  ***/
 220 typedef struct SilcConfigFileObject SilcConfigFile;
 221
 222 /****s* silcutil/SilcConfigAPI/SilcConfigEntity
 223  *
 224  * SYNOPSIS
 225  *
 226  *    typedef struct SilcConfigEntityObject *SilcConfigEntity;
 227  *
 228  * DESCRIPTION
 229  *
 230  *    The SILC Config is based on config entities.  An entity contains the
 231  *    SilcConfigFile object we are parsing and the registered options.
 232  *
 233  ***/
 234 typedef struct SilcConfigEntityObject *SilcConfigEntity;
 235
 236 /* Macros */
 237
 238 /****d* silcutil/SilcConfigAPI/SILC_CONFIG_CALLBACK
 239  *
 240  * NAME
 241  *
 242  *    #define SILC_CONFIG_CALLBACK ...
 243  *
 244  * DESCRIPTION
 245  *
 246  *    Generic macro to define SilcConfigCallback functions. This defines a
 247  *    static function with name `func' as a config callback function.
 248  *
 249  * SOURCE
 250  */
 251 #define SILC_CONFIG_CALLBACK(func)                              \
 252 static int func(SilcConfigType type, const char *name,          \
 253                 SilcUInt32 line, void *val, void *context)
 254 /***/
 255
 256 /* Prototypes */
 257
 258 /****f* silcutil/SilcConfigAPI/silc_config_open
 259  *
 260  * SYNOPSIS
 261  *
 262  *    SilcConfigFile *silc_config_open(char *configfile);
 263  *
 264  * DESCRIPTION
 265  *
 266  *    Tries to open the config file `configfile' and returns a valid File
 267  *    object on success, or NULL on failure.
 268  *    An File object created this way must be destroyed with the function
 269  *    silc_config_close().
 270  *
 271  ***/
 272 SilcConfigFile *silc_config_open(const char *configfile);
 273
 274 /****f* silcutil/SilcConfigAPI/silc_config_close
 275  *
 276  * SYNOPSIS
 277  *
 278  *    void silc_config_close(SilcConfigFile *file);
 279  *
 280  * DESCRIPTION
 281  *
 282  *    Closes and frees the File object `file', which must have been returned
 283  *    by a previous call to silc_config_open().  Otherwise, or if
 284  *    this function has already been called before for the same File object,
 285  *    undefined behaviour occurs.
 286  *    If `file' is NULL, no operation is performed.
 287  *
 288  ***/
 289 void silc_config_close(SilcConfigFile *file);
 290
 291 /****f* silcutil/SilcConfigAPI/silc_config_init
 292  *
 293  * SYNOPSIS
 294  *
 295  *    SilcConfigEntity silc_config_init(SilcConfigFile *file);
 296  *
 297  * DESCRIPTION
 298  *
 299  *    Creates an Entity pointing to the valid File object `file', which must
 300  *    be returned by a previous call to silc_config_open(), otherwise NULL
 301  *    is returned.
 302  *    Entities will be automatically destroyed after the call to the
 303  *    silc_config_main() function, because of this no uninit functions are
 304  *    provided.
 305  *
 306  ***/
 307 SilcConfigEntity silc_config_init(SilcConfigFile *file);
 308
 309 /****f* silcutil/SilcConfigAPI/silc_config_strerror
 310  *
 311  * SYNOPSIS
 312  *
 313  *    char *silc_config_strerror(int errnum);
 314  *
 315  * DESCRIPTION
 316  *
 317  *    The silc_config_strerror() function returns a string describing the
 318  *    error code passed in the argument `errnum'.
 319  *
 320  ***/
 321 char *silc_config_strerror(int errnum);
 322
 323 /****f* silcutil/SilcConfigAPI/silc_config_get_filename
 324  *
 325  * SYNOPSIS
 326  *
 327  *    char *silc_config_get_filename(SilcConfigFile *file);
 328  *
 329  * DESCRIPTION
 330  *
 331  *    Returns the original filename of the object file.
 332  *    The returned pointer points to internally allocated storage and must
 333  *    not be freed, modified or stored.
 334  *
 335  ***/
 336 char *silc_config_get_filename(SilcConfigFile *file);
 337
 338 /****f* silcutil/SilcConfigAPI/silc_config_get_line
 339  *
 340  * SYNOPSIS
 341  *
 342  *    SilcUInt32 silc_config_get_line(SilcConfigFile *file);
 343  *
 344  * DESCRIPTION
 345  *
 346  *    Returns the current line that file parsing arrived at.
 347  *
 348  ***/
 349 SilcUInt32 silc_config_get_line(SilcConfigFile *file);
 350
 351 /****f* silcutil/SilcConfigAPI/silc_config_read_line
 352  *
 353  * SYNOPSIS
 354  *
 355  *    char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
 356  *
 357  * DESCRIPTION
 358  *
 359  *    Returns a dynamically allocated null-terminated buffer containing the
 360  *    line `line' of `file'.
 361  *    The returned pointer must be freed when it's not needed any longer.
 362  *
 363  * SEE ALSO
 364  *    silc_config_read_current_line
 365  *
 366  ***/
 367 char *silc_config_read_line(SilcConfigFile *file, SilcUInt32 line);
 368
 369 /****f* silcutil/SilcConfigAPI/silc_config_read_current_line
 370  *
 371  * SYNOPSIS
 372  *
 373  *    char *silc_config_read_current_line(SilcConfigFile *file);
 374  *
 375  * DESCRIPTION
 376  *
 377  *    Returns a dynamically allocated buffer containing the line that the
 378  *    parser stopped at.  This is a convenience function for
 379  *    silc_config_read_line.
 380  *    The returned pointer must be freed when it's not needed any longer.
 381  *
 382  ***/
 383 char *silc_config_read_current_line(SilcConfigFile *file);
 384
 385 /****f* silcutil/SilcConfigAPI/silc_config_register
 386  *
 387  * SYNOPSIS
 388  *
 389  *    SilcBool silc_config_register(SilcConfigEntity ent, const char *name,
 390  *                              SilcConfigType type, SilcConfigCallback cb,
 391  *                              const SilcConfigTable *subtable,
 392  *                              void *context);
 393  *
 394  * DESCRIPTION
 395  *
 396  *    Register option `name' in the entity `ent'. If `cb' is not NULL, it
 397  *    will be called with the *val pointer pointing to an internally
 398  *    allocated storage of type described by `type'.
 399  *
 400  *    If `type' is SILC_CONFIG_ARG_BLOCK, then `subtable' must be a valid
 401  *    pointer to a SilcConfigTable array specifying the options in the
 402  *    sub-block.
 403  *
 404  *    If the option `name' was already registered in this sub-block or it
 405  *    matches the reserved word "Include", then this function returns FALSE,
 406  *    otherwise it returns TRUE.
 407  *
 408  * SEE ALSO
 409  *    silc_config_register_table
 410  *
 411  ***/
 412 SilcBool silc_config_register(SilcConfigEntity ent, const char *name,
 413                           SilcConfigType type, SilcConfigCallback cb,
 414                           const SilcConfigTable *subtable, void *context);
 415
 416 /****f* silcutil/SilcConfigAPI/silc_config_register_table
 417  *
 418  * SYNOPSIS
 419  *
 420  *    SilcBool silc_config_register_table(SilcConfigEntity ent,
 421  *                                    const SilcConfigTable table[],
 422  *                                    void *context);
 423  *
 424  * DESCRIPTION
 425  *
 426  *    Register the tableset of options `table' automatically in the entity
 427  *    `ent'.  If defined in the table, the callback functions will be called
 428  *    all with the same context `context'.
 429  *
 430  *    The `table' array must be terminated with an entry with the name field
 431  *    set to NULL.
 432  *
 433  *    If the table contains invalid data this function returns FALSE, otherwise
 434  *    it returns TRUE.  If a calling to this function failed, you must destroy
 435  *    and recreate the entity before retrying, as it's impossible to detect
 436  *    the point at the function stopped the registering process.
 437  *
 438  * SEE ALSO
 439  *    SilcConfigTable
 440  *
 441  ***/
 442 SilcBool silc_config_register_table(SilcConfigEntity ent,
 443                                 const SilcConfigTable table[], void *context);
 444
 445 /****f* silcutil/SilcConfigAPI/silc_config_main
 446  *
 447  * SYNOPSIS
 448  *
 449  *    int silc_config_main(SilcConfigEntity ent);
 450  *
 451  * DESCRIPTION
 452  *
 453  *    Enter the main parsing loop. When this function returns the parsing
 454  *    is finished in the current block (and sub-blocks).
 455  *
 456  *    When this function exits, the entity is already destroyed, because
 457  *    of this you should set it to NULL right after the function call.
 458  *
 459  ***/
 460 int silc_config_main(SilcConfigEntity ent);
 461
 462 #endif  /* !SILCCONFIG_H */