libatalk/iniparser/iniparser.h

   1
   2 /*-------------------------------------------------------------------------*/
   3 /**
   4    @file    iniparser.h
   5    @author  N. Devillard
   6    @date    Sep 2007
   7    @version 3.0
   8    @brief   Parser for ini files.
   9 */
  10 /*--------------------------------------------------------------------------*/
  11
  12 /*
  13         $Id: iniparser.h,v 1.26 2011-03-02 20:15:13 ndevilla Exp $
  14         $Revision: 1.26 $
  15 */
  16
  17 #ifndef _INIPARSER_H_
  18 #define _INIPARSER_H_
  19
  20 /*---------------------------------------------------------------------------
  21                                                                 Includes
  22  ---------------------------------------------------------------------------*/
  23
  24 #include <stdio.h>
  25 #include <stdlib.h>
  26 #include <string.h>
  27
  28 /*
  29  * The following #include is necessary on many Unixes but not Linux.
  30  * It is not needed for Windows platforms.
  31  * Uncomment it if needed.
  32  */
  33 /* #include <unistd.h> */
  34
  35 #include "dictionary.h"
  36
  37 /*-------------------------------------------------------------------------*/
  38 /**
  39   @brief    Get number of sections in a dictionary
  40   @param    d   Dictionary to examine
  41   @return   int Number of sections found in dictionary
  42
  43   This function returns the number of sections found in a dictionary.
  44   The test to recognize sections is done on the string stored in the
  45   dictionary: a section name is given as "section" whereas a key is
  46   stored as "section:key", thus the test looks for entries that do not
  47   contain a colon.
  48
  49   This clearly fails in the case a section name contains a colon, but
  50   this should simply be avoided.
  51
  52   This function returns -1 in case of error.
  53  */
  54 /*--------------------------------------------------------------------------*/
  55
  56 int iniparser_getnsec(dictionary * d);
  57
  58
  59 /*-------------------------------------------------------------------------*/
  60 /**
  61   @brief    Get name for section n in a dictionary.
  62   @param    d   Dictionary to examine
  63   @param    n   Section number (from 0 to nsec-1).
  64   @return   Pointer to char string
  65
  66   This function locates the n-th section in a dictionary and returns
  67   its name as a pointer to a string statically allocated inside the
  68   dictionary. Do not free or modify the returned string!
  69
  70   This function returns NULL in case of error.
  71  */
  72 /*--------------------------------------------------------------------------*/
  73
  74 char * iniparser_getsecname(dictionary * d, int n);
  75
  76
  77 /*-------------------------------------------------------------------------*/
  78 /**
  79   @brief    Save a dictionary to a loadable ini file
  80   @param    d   Dictionary to dump
  81   @param    f   Opened file pointer to dump to
  82   @return   void
  83
  84   This function dumps a given dictionary into a loadable ini file.
  85   It is Ok to specify @c stderr or @c stdout as output files.
  86  */
  87 /*--------------------------------------------------------------------------*/
  88
  89 void iniparser_dump_ini(dictionary * d, FILE * f);
  90
  91 /*-------------------------------------------------------------------------*/
  92 /**
  93   @brief    Dump a dictionary to an opened file pointer.
  94   @param    d   Dictionary to dump.
  95   @param    f   Opened file pointer to dump to.
  96   @return   void
  97
  98   This function prints out the contents of a dictionary, one element by
  99   line, onto the provided file pointer. It is OK to specify @c stderr
 100   or @c stdout as output files. This function is meant for debugging
 101   purposes mostly.
 102  */
 103 /*--------------------------------------------------------------------------*/
 104 void iniparser_dump(dictionary * d, FILE * f);
 105
 106 /*-------------------------------------------------------------------------*/
 107 /**
 108   @brief    Get the string associated to a key
 109   @param    d       Dictionary to search
 110   @param    key     Key string to look for
 111   @param    def     Default value to return if key not found.
 112   @return   pointer to statically allocated character string
 113
 114   This function queries a dictionary for a key. A key as read from an
 115   ini file is given as "section:key". If the key cannot be found,
 116   the pointer passed as 'def' is returned.
 117   The returned char pointer is pointing to a string allocated in
 118   the dictionary, do not free or modify it.
 119  */
 120 /*--------------------------------------------------------------------------*/
 121 char * iniparser_getstring(dictionary * d, char * key, char * def);
 122
 123 /*-------------------------------------------------------------------------*/
 124 /**
 125   @brief    Get the string associated to a key, convert to an int
 126   @param    d Dictionary to search
 127   @param    key Key string to look for
 128   @param    notfound Value to return in case of error
 129   @return   integer
 130
 131   This function queries a dictionary for a key. A key as read from an
 132   ini file is given as "section:key". If the key cannot be found,
 133   the notfound value is returned.
 134
 135   Supported values for integers include the usual C notation
 136   so decimal, octal (starting with 0) and hexadecimal (starting with 0x)
 137   are supported. Examples:
 138
 139   - "42"      ->  42
 140   - "042"     ->  34 (octal -> decimal)
 141   - "0x42"    ->  66 (hexa  -> decimal)
 142
 143   Warning: the conversion may overflow in various ways. Conversion is
 144   totally outsourced to strtol(), see the associated man page for overflow
 145   handling.
 146
 147   Credits: Thanks to A. Becker for suggesting strtol()
 148  */
 149 /*--------------------------------------------------------------------------*/
 150 int iniparser_getint(dictionary * d, char * key, int notfound);
 151
 152 /*-------------------------------------------------------------------------*/
 153 /**
 154   @brief    Get the string associated to a key, convert to a double
 155   @param    d Dictionary to search
 156   @param    key Key string to look for
 157   @param    notfound Value to return in case of error
 158   @return   double
 159
 160   This function queries a dictionary for a key. A key as read from an
 161   ini file is given as "section:key". If the key cannot be found,
 162   the notfound value is returned.
 163  */
 164 /*--------------------------------------------------------------------------*/
 165 double iniparser_getdouble(dictionary * d, char * key, double notfound);
 166
 167 /*-------------------------------------------------------------------------*/
 168 /**
 169   @brief    Get the string associated to a key, convert to a boolean
 170   @param    d Dictionary to search
 171   @param    key Key string to look for
 172   @param    notfound Value to return in case of error
 173   @return   integer
 174
 175   This function queries a dictionary for a key. A key as read from an
 176   ini file is given as "section:key". If the key cannot be found,
 177   the notfound value is returned.
 178
 179   A true boolean is found if one of the following is matched:
 180
 181   - A string starting with 'y'
 182   - A string starting with 'Y'
 183   - A string starting with 't'
 184   - A string starting with 'T'
 185   - A string starting with '1'
 186
 187   A false boolean is found if one of the following is matched:
 188
 189   - A string starting with 'n'
 190   - A string starting with 'N'
 191   - A string starting with 'f'
 192   - A string starting with 'F'
 193   - A string starting with '0'
 194
 195   The notfound value returned if no boolean is identified, does not
 196   necessarily have to be 0 or 1.
 197  */
 198 /*--------------------------------------------------------------------------*/
 199 int iniparser_getboolean(dictionary * d, char * key, int notfound);
 200
 201
 202 /*-------------------------------------------------------------------------*/
 203 /**
 204   @brief    Set an entry in a dictionary.
 205   @param    ini     Dictionary to modify.
 206   @param    entry   Entry to modify (entry name)
 207   @param    val     New value to associate to the entry.
 208   @return   int 0 if Ok, -1 otherwise.
 209
 210   If the given entry can be found in the dictionary, it is modified to
 211   contain the provided value. If it cannot be found, -1 is returned.
 212   It is Ok to set val to NULL.
 213  */
 214 /*--------------------------------------------------------------------------*/
 215 int iniparser_set(dictionary * ini, char * entry, char * val);
 216
 217
 218 /*-------------------------------------------------------------------------*/
 219 /**
 220   @brief    Delete an entry in a dictionary
 221   @param    ini     Dictionary to modify
 222   @param    entry   Entry to delete (entry name)
 223   @return   void
 224
 225   If the given entry can be found, it is deleted from the dictionary.
 226  */
 227 /*--------------------------------------------------------------------------*/
 228 void iniparser_unset(dictionary * ini, char * entry);
 229
 230 /*-------------------------------------------------------------------------*/
 231 /**
 232   @brief    Finds out if a given entry exists in a dictionary
 233   @param    ini     Dictionary to search
 234   @param    entry   Name of the entry to look for
 235   @return   integer 1 if entry exists, 0 otherwise
 236
 237   Finds out if a given entry exists in the dictionary. Since sections
 238   are stored as keys with NULL associated values, this is the only way
 239   of querying for the presence of sections in a dictionary.
 240  */
 241 /*--------------------------------------------------------------------------*/
 242 int iniparser_find_entry(dictionary * ini, char * entry) ;
 243
 244 /*-------------------------------------------------------------------------*/
 245 /**
 246   @brief    Parse an ini file and return an allocated dictionary object
 247   @param    ininame Name of the ini file to read.
 248   @return   Pointer to newly allocated dictionary
 249
 250   This is the parser for ini files. This function is called, providing
 251   the name of the file to be read. It returns a dictionary object that
 252   should not be accessed directly, but through accessor functions
 253   instead.
 254
 255   The returned dictionary must be freed using iniparser_freedict().
 256  */
 257 /*--------------------------------------------------------------------------*/
 258 dictionary * iniparser_load(char * ininame);
 259
 260 /*-------------------------------------------------------------------------*/
 261 /**
 262   @brief    Free all memory associated to an ini dictionary
 263   @param    d Dictionary to free
 264   @return   void
 265
 266   Free all memory associated to an ini dictionary.
 267   It is mandatory to call this function before the dictionary object
 268   gets out of the current context.
 269  */
 270 /*--------------------------------------------------------------------------*/
 271 void iniparser_freedict(dictionary * d);
 272
 273 #endif