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/mmcblk0p1/pandora/conf:/media/mmcblk1p1/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_filename_e;
  72
  73 typedef struct {
  74   pnd_conf_filename_e id;
  75   char *filename;
  76 } pnd_conf_filename_t;
  77
  78 extern pnd_conf_filename_t pnd_conf_filenames[];
  79
  80 /* config file blackbox type
  81  */
  82 typedef void* pnd_conf_handle;
  83
  84 /*
  85  * config FILE reading public API
  86  */
  87
  88 /* fetch_searchpath() - since near every app may wish to use this piece of code,
  89  * it is encapsulated here.
  90  * Returns a search-path to be used hereafter; free it when done with it!
  91  */
  92 char *pnd_conf_query_searchpath ( void );
  93
  94 /* fetch_by_id() will try to locate the config file as referred to by the enum'd 'id'. If it
  95  * can be found and parsed a handle will be returned, otherwise a handle of 0 (NULL).
  96  * Returns a 0 handle on fail, otherwise a useful handle.
  97  */
  98 pnd_conf_handle pnd_conf_fetch_by_id ( pnd_conf_filename_e id, char *searchpath );
  99
 100 /* if you don't wish to use an 'id', you can fetch by filename. Essentially the fetch_by_id()
 101  * function simply uses this to do the work, but you could use it to load up alternate config-format
 102  * files.
 103  * Returns a 0 handle on fail, otherwise a useful handle.
 104  */
 105 pnd_conf_handle pnd_conf_fetch_by_name ( char *filename, char *searchpath );
 106
 107 /* fetch_by_path() will operate on a specific full filename; this essentially does the
 108  * dirty work for the above functions, but can be used to pull in a specific path for
 109  * whatever purpose.
 110  * Returns a 0 handle on fail, otherwise a useful handle.
 111  */
 112 pnd_conf_handle pnd_conf_fetch_by_path ( char *fullpath );
 113
 114 /*
 115  * config file accessor functions public API
 116  */
 117
 118 /* get_as_char() will attempt to locate the specified key string (of format section.key) in the
 119  * provided config handle. Do not free up this value, it is considered read only.
 120  * Returns NULL on error, otherwise a READ ONLY char* reference to the value.
 121  */
 122 char *pnd_conf_get_as_char ( pnd_conf_handle c, char *key );
 123
 124 #ifdef __cplusplus
 125 } /* "C" */
 126 #endif
 127
 128 #endif