include/asterisk/config.h

   1 /*
   2  * Asterisk -- A telephony toolkit for Linux.
   3  *
   4  * Configuration File Parser
   5  *
   6  * Copyright (C) 1999, Mark Spencer
   7  *
   8  * Mark Spencer <markster@linux-support.net>
   9  *
  10  * This program is free software, distributed under the terms of
  11  * the GNU General Public License
  12  */
  13
  14 #ifndef _ASTERISK_CONFIG_H
  15 #define _ASTERISK_CONFIG_H
  16
  17 #if defined(__cplusplus) || defined(c_plusplus)
  18 extern "C" {
  19 #endif
  20
  21 struct ast_config;
  22
  23 struct ast_comment {
  24         struct ast_comment *next;
  25         char cmt[0];
  26 };
  27
  28 struct ast_variable {
  29         char *name;
  30         char *value;
  31         int lineno;
  32         int object;             /* 0 for variable, 1 for object */
  33         int blanklines;         /* Number of blanklines following entry */
  34         struct ast_comment *precomments;
  35         struct ast_comment *sameline;
  36         struct ast_variable *next;
  37 };
  38
  39 //! Load a config file
  40 /*!
  41  * \param configfile path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
  42  * Create a config structure from a given configuration file.
  43  * Returns NULL on error, or an ast_config data structure on success
  44  */
  45 struct ast_config *ast_load(char *configfile);
  46
  47 //! Removes a config
  48 /*!
  49  * \param config config data structure associated with the config.
  50  * Free memory associated with a given config
  51  * Returns nothing
  52  */
  53 void ast_destroy(struct ast_config *config);
  54
  55 //! Goes through categories
  56 /*!
  57  * \param config Which config file you wish to "browse"
  58  * \param prev A pointer to a previous category.
  59  * This funtion is kind of non-intuitive in it's use.  To begin, one passes NULL as the second arguement.  It will return a pointer to the string of the first category in the file.  From here on after, one must then pass the previous usage's return value as the second pointer, and it will return a pointer to the category name afterwards.  Note:  If you manually strcpy a string into a character array and pass it thinking it will return your category, it will not; the comparisons are not done doing strcmp, they are done by checking whether the value of the string POINTER is the same.
  60  * Returns a category on success, or NULL on failure/no-more-categories
  61  */
  62 char *ast_category_browse(struct ast_config *config, char *prev);
  63
  64 //! Goes through variables
  65 /*!
  66  * Somewhat similar in intent as the ast_category_browse.  The category MUST be an actual pointer to an actual category (such as one obtained by using ast_category_browse()).
  67  * List variables of config file
  68  * Returns ast_variable list on success, or NULL on failure
  69  */
  70 struct ast_variable *ast_variable_browse(struct ast_config *config, char *category);
  71
  72 //! Gets a variable
  73 /*!
  74  * \param config which (opened) config to use
  75  * \param category category under which the variable lies (must be a pointer to the category, such as one given by ast_category_browse)
  76  * \param value which variable you wish to get the data for
  77  * Goes through a given config file in the given category and searches for the given variable
  78  * Returns the variable value on success, or NULL if unable to find it.
  79  * Retrieve a specific variable */
  80 char *ast_variable_retrieve(struct ast_config *config, char *category, char *value);
  81
  82 //! Make sure something is true
  83 /*!
  84  * Determine affermativeness of a boolean value.
  85  * This function checks to see whether a string passed to it is an indication of an affirmitave value.  It checks to see if the string is "yes", "true", "y", "t", and "1".
  86  * Returns 0 if the value of s is a NULL pointer, 0 on "truth", and -1 on falsehood.
  87  */
  88 int ast_true(char *val);
  89
  90 //! Make sure something is false
  91 /*!
  92  * Determine falseness of a boolean value.
  93  * This function checks to see whether a string passed to it is an indication of a negatirve value.  It checks to see if the string is "no", "false", "n", "f", and "0".
  94  * Returns 0 if the value of s is a NULL pointer, 0 on "truth", and -1 on falsehood.
  95  */
  96 int ast_false(char *val);
  97
  98 //! Check for category duplicates
  99 /*!
 100  * \param config which config to use
 101  * \param category_name name of the category you're looking for
 102  * This will search through the categories within a given config file and search for a match.  The passed category_name can be a regular string (as opposed to a pointer of an existent string, lol)
 103  * Browse config structure and check for category duplicity Return non-zero if found */
 104 int ast_category_exist(struct ast_config *config, char *category_name);
 105
 106 /* These are only in the config engine at this point */
 107 struct ast_variable *ast_variable_append_modify(struct ast_config *cfg, char *category, char *variable, char *newvalue, int newcat, int newvar, int move);
 108
 109 int ast_category_delete(struct ast_config *cfg, char *category);
 110 int ast_variable_delete(struct ast_config *cfg, char *category, char *variable, char *value);
 111 int ast_save(char *filename, struct ast_config *cfg, char *generator);
 112
 113 #if defined(__cplusplus) || defined(c_plusplus)
 114 }
 115 #endif
 116
 117
 118
 119 #endif