include/pnd_conf.h

   1
   2 /*
   3  * libpnd - tools for the Open Pandora device
   4  * This code to be released under the terms of the GPLv2
   5  */
   6
   7 #ifndef h_pnd_conf_h
   8 #define h_pnd_conf_h
   9
  10 #ifdef __cplusplus
  11 extern "C" {
  12 #endif
  13
  14 /* Config file format
  15  * Since we're sticking configs in homedirs and /etc, it seems inappropriate to use XML; further
  16  * of course, XML means a heavy duty parser (expat or something at least) when people really just
  17  * use grep on these guys. Still, XML would afford us unicode which would be nice..
  18  * Anyway, the very basic format of the config file supported herein is derived from .ini really
  19  * (sorry!)
  20  *
  21  * [section]
  22  * key value #comment
  23  *
  24  * Comments and leading/trailing space is removed; embedded space is left.
  25  *
  26  * Thats it; internally, 'section' is prepended to all keys, so it looks something like this.
  27  * Section can be [] to mean 'back to the top level.' I had
  28  * considered having no decorations around [section] (which is to say, a key with no value) but
  29  * I could see cases where folks want to have a valueless key, without something goofy like value
  30  * 'present' 'on' '0', when they just want a key 'use-foo' and don't want 'use foo' value 'no'
  31  * that feals yes/no-ey.
  32  *
  33  * NOTE: If a key is present in a config twice.. well, too bad. No warning is made.
  34  *
  35  * autodiscovery:
  36  * path /mnt/sd1/my/path
  37  *
  38  * Internally becomes:
  39  *
  40  * autodiscovery.path -> /mnt/sd1/my/path
  41  *
  42  */
  43
  44 /* certain paths must be 'givens'; ideally as few assumptions as possible, but to
  45  * find further config files we need to look _somewhere_; note that searchpaths
  46  * are searched in order, so the most-canonicle should be listed last.
  47  *
  48  * NOTE: This search path is used to find the basic config files, which in turn
  49  * can specify a replacement config path .. it may be required to first locate the
  50  * 'conf' config, and then use its suggested searchpath!
  51  *
  52  */
  53 #define PND_CONF_SEARCHPATH "/media/*/pandora/conf:/etc/pandora/conf:./testdata/conf"
  54
  55 /* within the base conf file 'conf', the key for the searchpath is 'conf.searchpath' */
  56 #define PND_CONF_FILE       "conf" /* a config file for config settings! */
  57 #define PND_CONF_KEY        "conf.searchpath" /* if not found, use PND_CONF_SEARCHPATH */
  58
  59 /* we would like to open config files based on enums, so as to minimize specifying
  60  * filenames; ie: It makes it easier to rename them later or display them in a native
  61  * language, etc. It is optional as our API will allow direct open by filename as
  62  * well.
  63  */
  64 typedef enum {
  65   pnd_conf_nil = 0,
  66   pnd_conf_conf,           // provides settings for the config system
  67   pnd_conf_apps,           // provides application search-path, pxml override location, etc.
  68   pnd_conf_startup,        // provides list of startup applications, basic shell application, etc.
  69   pnd_conf_desktop,        // provides settings for the launchers
  70   pnd_conf_categories,     // provides mapping from PXML category to dot-desktop category
  71   pnd_conf_evmap,          // provides mapping from event to sh-script
  72 } pnd_conf_filename_e;
  73
  74 typedef struct {
  75   pnd_conf_filename_e id;
  76   char *filename;
  77 } pnd_conf_filename_t;
  78
  79 extern pnd_conf_filename_t pnd_conf_filenames[];
  80
  81 /* config file blackbox type
  82  */
  83 typedef void* pnd_conf_handle;
  84
  85 /*
  86  * config FILE reading public API
  87  */
  88
  89 /* fetch_searchpath() - since near every app may wish to use this piece of code,
  90  * it is encapsulated here.
  91  * Returns a search-path to be used hereafter; free it when done with it!
  92  */
  93 char *pnd_conf_query_searchpath ( void );
  94
  95 /* fetch_by_id() will try to locate the config file as referred to by the enum'd 'id'. If it
  96  * can be found and parsed a handle will be returned, otherwise a handle of 0 (NULL).
  97  * Returns a 0 handle on fail, otherwise a useful handle.
  98  */
  99 pnd_conf_handle pnd_conf_fetch_by_id ( pnd_conf_filename_e id, char *searchpath );
 100
 101 /* if you don't wish to use an 'id', you can fetch by filename. Essentially the fetch_by_id()
 102  * function simply uses this to do the work, but you could use it to load up alternate config-format
 103  * files.
 104  * Returns a 0 handle on fail, otherwise a useful handle.
 105  */
 106 pnd_conf_handle pnd_conf_fetch_by_name ( char *filename, char *searchpath );
 107
 108 /* fetch_by_path() will operate on a specific full filename; this essentially does the
 109  * dirty work for the above functions, but can be used to pull in a specific path for
 110  * whatever purpose.
 111  * Returns a 0 handle on fail, otherwise a useful handle.
 112  */
 113 pnd_conf_handle pnd_conf_fetch_by_path ( char *fullpath );
 114
 115 /*
 116  * config file accessor functions public API
 117  */
 118
 119 /* get_as_char() will attempt to locate the specified key string (of format section.key) in the
 120  * provided config handle. Do not free up this value, it is considered read only.
 121  * Returns NULL on error, otherwise a READ ONLY char* reference to the value.
 122  */
 123 char *pnd_conf_get_as_char ( pnd_conf_handle c, char *key );
 124 #define PND_CONF_BADNUM (-31337) /* really lame hack, I know */
 125 int pnd_conf_get_as_int ( pnd_conf_handle c, char *key );
 126 int pnd_conf_get_as_int_d ( pnd_conf_handle c, char *key, int def ); // same as _as_int, but returns default instead of BADNUM
 127
 128 /* writes and saves
 129  */
 130 int *pnd_conf_set_int ( pnd_conf_handle c, char *key, int v );
 131 char *pnd_conf_set_char ( pnd_conf_handle c, char *key, char *v );
 132 unsigned char pnd_conf_write ( pnd_conf_handle c, char *fullpath );
 133
 134 #ifdef __cplusplus
 135 } /* "C" */
 136 #endif
 137
 138 #endif