shared/configfile.h

   1 /** \file configfile.h
   2  * Declare routines to read INI-file like files.
   3  */
   4
   5 /* This file is part of LCDd, the lcdproc server.
   6  *
   7  * This file is released under the GNU General Public License. Refer to the
   8  * COPYING file distributed with this package.
   9  *
  10  * Copyright (c) 2001, Joris Robijn
  11  *           (c) 2006,2007 Peter Marschall
  12  *
  13  */
  14
  15 #ifndef CONFIGFILE_H
  16 #define CONFIGFILE_H
  17
  18 #ifdef HAVE_CONFIG_H
  19 #include "config.h"
  20 #endif
  21
  22 /* Opens the specified file and reads everything into memory.
  23  * Returns 0  when config file was successfully parsed
  24  * Returns <0 on errors
  25  */
  26 int config_read_file(const char *filename);
  27
  28 #if defined(LCDPROC_CONFIG_READ_STRING)
  29 /* Reads everything in the string into memory.
  30  * Returns 0  when config file was successfully parsed
  31  * Returns <0 on errors
  32  */
  33 int config_read_string(const char *sectionname, const char *str);
  34 #endif
  35
  36 /* Tries to interpret a value in the config file as a boolean.
  37  * 0, false, off, no, n = false
  38  * 1, true, on, yes, y = true
  39  * If the key is not found or cannot be interpreted, the given default value is
  40  * returned.
  41  * The skip value can be used to iterate over multiple values with the same
  42  * key. Should be 0 to get the first one, 1 for the second etc. and -1 for the
  43  * last.
  44  */
  45 short config_get_bool(const char *sectionname, const char *keyname,
  46                 int skip, short default_value);
  47
  48 /* Tries to interpret a value in the config file as an integer.*/
  49 long int config_get_int(const char *sectionname, const char *keyname,
  50                 int skip, long int default_value);
  51
  52 /* Tries to interpret a value in the config file as a float.*/
  53 double config_get_float(const char *sectionname, const char *keyname,
  54                 int skip, double default_value);
  55
  56 /* Returns a pointer to the string associated with the specified key.
  57  * The strings returned are always NUL-terminated.
  58  * The string should never be modified, and used only short-term.
  59  * In successive calls this function can * re-use the data space !
  60  *
  61  * You can do some things with the returned string:
  62  * 1. Scan or parse it:
  63  *    s = config_get_string(...);
  64  *    sscanf( s, "%dx%d", &w, &h );  // scan format like: 20x4
  65  *    ...and check the w and h values...
  66  * 2. Copy it to a preallocated buffer like device[256]:
  67  *    s = config_get_string(...);
  68  *    strncpy( device, s, sizeof(device));
  69  *    device[sizeof(device)-1] = 0;
  70  * 3. Copy it to a newly allocated space in char *device:
  71  *    s = config_get_string(...);
  72  *    device = malloc(strlen(s)+1);
  73  *    if( device == NULL ) return -5; // or whatever < 0
  74  *    strcpy( device, s );
  75  */
  76 const char *config_get_string(const char *sectionname, const char *keyname,
  77                 int skip, const char *default_value);
  78
  79 /* Checks if a specified section exists.
  80  * Returns whether it exists.
  81  */
  82 int config_has_section(const char *sectionname);
  83
  84 /* Checks if a specified key within the specified section exists.
  85  * Returns the number of times the key exists.
  86  */
  87 int config_has_key(const char *sectionname, const char *keyname);
  88
  89 /* Clears all data stored by the config_read_* functions.
  90  * Should be called if the config should be reread.
  91  */
  92 void config_clear(void);
  93
  94 #endif