Thu Oct 9 06:45:20 2008

Asterisk developer's documentation

---

config.h File Reference

Configuration File Parser. More...

#include <stdarg.h>

Include dependency graph for config.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_config_engine
struct	ast_variable
Typedefs
typedef ast_config *	config_load_func (const char *database, const char *table, const char *configfile, struct ast_config *config)
typedef ast_config *	realtime_multi_get (const char *database, const char *table, va_list ap)
typedef int	realtime_update (const char *database, const char *table, const char *keyfield, const char *entity, va_list ap)
typedef ast_variable *	realtime_var_get (const char *database, const char *table, va_list ap)
Functions
void	ast_category_append (struct ast_config *config, struct ast_category *cat)
char *	ast_category_browse (struct ast_config *config, const char *prev)
	Goes through categories.
int	ast_category_delete (struct ast_config *cfg, char *category)
void	ast_category_destroy (struct ast_category *cat)
ast_variable *	ast_category_detach_variables (struct ast_category *cat)
int	ast_category_exist (const struct ast_config *config, const char *category_name)
	Check for category duplicates.
ast_category *	ast_category_get (const struct ast_config *config, const char *category_name)
	Retrieve a category if it exists.
ast_category *	ast_category_new (const char *name)
void	ast_category_rename (struct ast_category *cat, const char *name)
int	ast_check_realtime (const char *family)
	Check if realtime engine is configured for family returns 1 if family is configured in realtime and engine exists.
void	ast_config_destroy (struct ast_config *config)
	Destroys a config.
int	ast_config_engine_deregister (struct ast_config_engine *del)
	Deegister config engine.
int	ast_config_engine_register (struct ast_config_engine *newconfig)
	Register config engine.
ast_category *	ast_config_get_current_category (const struct ast_config *cfg)
ast_config *	ast_config_internal_load (const char *configfile, struct ast_config *cfg)
ast_config *	ast_config_load (const char *filename)
	Load a config file.
ast_config *	ast_config_new (void)
void	ast_config_set_current_category (struct ast_config *cfg, const struct ast_category *cat)
ast_variable *	ast_load_realtime (const char *family,...)
	Retrieve realtime configuration.
ast_config *	ast_load_realtime_multientry (const char *family,...)
	Retrieve realtime configuration.
int	ast_update_realtime (const char *family, const char *keyfield, const char *lookup,...)
	Update realtime configuration.
void	ast_variable_append (struct ast_category *category, struct ast_variable *variable)
ast_variable *	ast_variable_browse (const struct ast_config *config, const char *category)
	Goes through variables Somewhat similar in intent as the ast_category_browse. List variables of config file category.
ast_variable *	ast_variable_new (const char *name, const char *value)
char *	ast_variable_retrieve (const struct ast_config *config, const char *category, const char *variable)
	Gets a variable.
void	ast_variables_destroy (struct ast_variable *var)
	Free variable list.
int	config_text_file_save (const char *filename, const struct ast_config *cfg, const char *generator)
void	read_config_maps (void)
int	register_config_cli (void)

---

Detailed Description

Configuration File Parser.

Definition in file config.h.

---

Typedef Documentation

typedef struct ast_config* config_load_func(const char *database, const char *table, const char *configfile, struct ast_config *config)

Definition at line 48 of file config.h.

typedef struct ast_config* realtime_multi_get(const char *database, const char *table, va_list ap)

Definition at line 50 of file config.h.

typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap)

Definition at line 51 of file config.h.

typedef struct ast_variable* realtime_var_get(const char *database, const char *table, va_list ap)

Definition at line 49 of file config.h.

---

Function Documentation

void ast_category_append	(	struct ast_config *	config,
		struct ast_category *	cat
	)

Definition at line 242 of file config.c.

References config.

Referenced by config_odbc(), process_text_line(), realtime_directory(), and realtime_multi_odbc().

{
   if (config->last)
      config->last->next = category;
   else
      config->root = category;
   config->last = category;
   config->current = category;
}

char* ast_category_browse	(	struct ast_config *	config,
		const char *	prev
	)

Goes through categories.

Parameters:

	config	Which config structure you wish to "browse"
	prev	A pointer to a previous category. 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.

Returns a category on success, or NULL on failure/no-more-categories

Definition at line 265 of file config.c.

References config, ast_category::name, ast_category::next, and next_available_category().

Referenced by authenticate(), complete_sipnotify(), config_load(), iax_provision_reload(), ind_load_module(), load_config(), load_module(), load_moh_classes(), load_odbc_config(), loadconfigurationfile(), misdn_cfg_init(), pbx_load_module(), realtime_directory(), realtime_switch_common(), reload_config(), reload_queues(), rpt_master(), and set_config().

{  
   struct ast_category *cat = NULL;

   if (prev && config->last_browse && (config->last_browse->name == prev))
      cat = config->last_browse->next;
   else if (!prev && config->root)
         cat = config->root;
   else if (prev) {
      for (cat = config->root; cat; cat = cat->next) {
         if (cat->name == prev) {
            cat = cat->next;
            break;
         }
      }
      if (!cat) {
         for (cat = config->root; cat; cat = cat->next) {
            if (!strcasecmp(cat->name, prev)) {
               cat = cat->next;
               break;
            }
         }
      }
   }
   
   if (cat)
      cat = next_available_category(cat);

   config->last_browse = cat;
   if (cat)
      return cat->name;
   else
      return NULL;
}

int ast_category_delete	(	struct ast_config *	cfg,
		char *	category
	)

void ast_category_destroy

(

struct ast_category *

cat

)

Definition at line 252 of file config.c.

References ast_variables_destroy(), free, and ast_category::root.

Referenced by process_text_line(), and realtime_multi_odbc().

{
   ast_variables_destroy(cat->root);
   free(cat);
}

struct ast_variable* ast_category_detach_variables

(

struct ast_category *

cat

)

Definition at line 300 of file config.c.

References ast_category::last, and ast_category::root.

Referenced by realtime_switch_common(), and vm_forwardoptions().

{
   struct ast_variable *v;

   v = cat->root;
   cat->root = NULL;
   cat->last = NULL;

   return v;
}

int ast_category_exist	(	const struct ast_config *	config,
		const char *	category_name
	)

Check for category duplicates.

Parameters:

	config	which config to use
	category_name	name of the category you're looking for This will search through the categories within a given config file for a match.

Return non-zero if found

Definition at line 237 of file config.c.

References ast_category_get(), and config.

{
   return !!ast_category_get(config, category_name);
}

struct ast_category* ast_category_get	(	const struct ast_config *	config,
		const char *	category_name
	)

Retrieve a category if it exists.

Parameters:

	config	which config to use
	category_name	name of the category you're looking for This will search through the categories within a given config file for a match.

Returns pointer to category if found, NULL if not.

Definition at line 232 of file config.c.

References category_get(), and config.

Referenced by ast_category_exist(), ast_variable_browse(), realtime_directory(), realtime_switch_common(), and vm_forwardoptions().

{
   return category_get(config, category_name, 0);
}

struct ast_category* ast_category_new

(

const char *

name

)

Definition at line 202 of file config.c.

References malloc.

Referenced by config_odbc(), process_text_line(), realtime_directory(), and realtime_multi_odbc().

{
   struct ast_category *category;

   category = malloc(sizeof(struct ast_category));
   if (category) {
      memset(category, 0, sizeof(struct ast_category));
      ast_copy_string(category->name, name, sizeof(category->name));
   }

   return category;
}

void ast_category_rename	(	struct ast_category *	cat,
		const char *	name
	)

Definition at line 311 of file config.c.

References ast_category::name.

Referenced by realtime_multi_odbc().

{
   ast_copy_string(cat->name, name, sizeof(cat->name));
}

int ast_check_realtime

(

const char *

family

)

Check if realtime engine is configured for family returns 1 if family is configured in realtime and engine exists.

Parameters:

family

which family/config to be checked

Definition at line 1008 of file config.c.

References find_engine().

Referenced by sip_show_settings().

{
   struct ast_config_engine *eng;

   eng = find_engine(family, NULL, 0, NULL, 0);
   if (eng)
      return 1;
   return 0;

}

void ast_config_destroy

(

struct ast_config *

config

)

Destroys a config.

Parameters:

config

pointer to config data structure Free memory associated with a given config

Definition at line 342 of file config.c.

References ast_variables_destroy(), cfg, free, ast_category::next, ast_category::root, and ast_config::root.

Referenced by adsi_load(), advanced_options(), ast_config_load(), ast_enum_init(), ast_load_resource(), ast_readconfig(), ast_rtp_reload(), authenticate(), conf_exec(), config_load(), directory_exec(), do_reload(), festival_exec(), find_conf(), handle_save_dialplan(), iax_provision_reload(), ind_load_module(), init_logger_chain(), init_manager(), load_config(), load_module(), load_modules(), load_moh_classes(), load_odbc_config(), loadconfigurationfile(), my_load_module(), odbc_load_module(), parse_config(), pbx_load_module(), play_message(), privacy_exec(), read_agent_config(), read_config_maps(), realtime_directory(), realtime_switch_common(), reload_config(), reload_queues(), rpt_master(), set_config(), setup_zap(), tds_load_module(), and vm_forwardoptions().

{
   struct ast_category *cat, *catn;

   if (!cfg)
      return;

   cat = cfg->root;
   while(cat) {
      ast_variables_destroy(cat->root);
      catn = cat;
      cat = cat->next;
      free(catn);
   }
   free(cfg);
}

int ast_config_engine_deregister

(

struct ast_config_engine *

del

)

Deegister config engine.

Definition at line 873 of file config.c.

References ast_mutex_lock(), ast_mutex_unlock(), config_engine_list, last, and ast_config_engine::next.

Referenced by unload_module().

{
   struct ast_config_engine *ptr, *last=NULL;

   ast_mutex_lock(&config_lock);

   for (ptr = config_engine_list; ptr; ptr=ptr->next) {
      if (ptr == del) {
         if (last)
            last->next = ptr->next;
         else
            config_engine_list = ptr->next;
         break;
      }
      last = ptr;
   }

   ast_mutex_unlock(&config_lock);

   return 0;
}

int ast_config_engine_register

(

struct ast_config_engine *

newconfig

)

Register config engine.

Definition at line 854 of file config.c.

References ast_log(), ast_mutex_lock(), ast_mutex_unlock(), config_engine_list, LOG_NOTICE, ast_config_engine::name, and ast_config_engine::next.

Referenced by load_module().

{
   struct ast_config_engine *ptr;

   ast_mutex_lock(&config_lock);

   if (!config_engine_list) {
      config_engine_list = new;
   } else {
      for (ptr = config_engine_list; ptr->next; ptr=ptr->next);
      ptr->next = new;
   }

   ast_mutex_unlock(&config_lock);
   ast_log(LOG_NOTICE,"Registered Config Engine %s\n", new->name);

   return 1;
}

struct ast_category* ast_config_get_current_category

(

const struct ast_config *

cfg

)

Definition at line 359 of file config.c.

References cfg, and ast_config::current.

Referenced by config_odbc(), and config_text_file_load().

{
   return cfg->current;
}

struct ast_config* ast_config_internal_load	(	const char *	configfile,
		struct ast_config *	cfg
	)

Definition at line 935 of file config.c.

References ast_log(), cfg, config_engine_list, db, extconfig_conf, find_engine(), ast_config::include_level, ast_config_engine::load_func, LOG_WARNING, ast_config::max_include_level, result, table, and text_file_engine.

Referenced by ast_config_load(), config_odbc(), process_text_line(), and read_config_maps().

{
   char db[256];
   char table[256];
   struct ast_config_engine *loader = &text_file_engine;
   struct ast_config *result;

   if (cfg->include_level == cfg->max_include_level) {
      ast_log(LOG_WARNING, "Maximum Include level (%d) exceeded\n", cfg->max_include_level);
      return NULL;
   }

   cfg->include_level++;

   if (strcmp(filename, extconfig_conf) && strcmp(filename, "asterisk.conf") && config_engine_list) {
      struct ast_config_engine *eng;

      eng = find_engine(filename, db, sizeof(db), table, sizeof(table));


      if (eng && eng->load_func) {
         loader = eng;
      } else {
         eng = find_engine("global", db, sizeof(db), table, sizeof(table));
         if (eng && eng->load_func)
            loader = eng;
      }
   }

   result = loader->load_func(db, table, filename, cfg);

   if (result)
      result->include_level--;
   else
      cfg->include_level--;

   return result;
}

struct ast_config* ast_config_load

(

const char *

filename

)

Load a config file.

Parameters:

filename

path of file to open. If no preceding '/' character, path is considered relative to AST_CONFIG_DIR Create a config structure from a given configuration file.

Returns NULL on error, or an ast_config data structure on success

Definition at line 974 of file config.c.

References ast_config_destroy(), ast_config_internal_load(), ast_config_new(), cfg, and result.

Referenced by adsi_load(), advanced_options(), ast_enum_init(), ast_load_resource(), ast_readconfig(), ast_rtp_reload(), authenticate(), conf_exec(), config_load(), do_reload(), festival_exec(), find_conf(), handle_save_dialplan(), iax_provision_reload(), ind_load_module(), init_logger_chain(), init_manager(), load_config(), load_module(), load_modules(), load_moh_classes(), load_odbc_config(), loadconfigurationfile(), my_load_module(), odbc_load_module(), parse_config(), pbx_load_module(), play_message(), privacy_exec(), read_agent_config(), realtime_directory(), reload_config(), reload_queues(), rpt_master(), set_config(), setup_zap(), tds_load_module(), and vm_forwardoptions().

{
   struct ast_config *cfg;
   struct ast_config *result;

   cfg = ast_config_new();
   if (!cfg)
      return NULL;

   result = ast_config_internal_load(filename, cfg);
   if (!result)
      ast_config_destroy(cfg);

   return result;
}

struct ast_config* ast_config_new

(

void

)

Definition at line 329 of file config.c.

References config, malloc, and MAX_INCLUDE_LEVEL.

Referenced by ast_config_load(), read_config_maps(), and realtime_multi_odbc().

{
   struct ast_config *config;

   config = malloc(sizeof(*config));
   if (config) {
      memset(config, 0, sizeof(*config));
      config->max_include_level = MAX_INCLUDE_LEVEL;
   }

   return config;
}

void ast_config_set_current_category	(	struct ast_config *	cfg,
		const struct ast_category *	cat
	)

Definition at line 364 of file config.c.

References cfg, and ast_config::current.

{
   /* cast below is just to silence compiler warning about dropping "const" */
   cfg->current = (struct ast_category *) cat;
}

struct ast_variable* ast_load_realtime	(	const char *	family,
			...
	)

Retrieve realtime configuration.

Parameters:

family

which family/config to lookup This will use builtin configuration backends to look up a particular entity in realtime and return a variable list of its parameters. Note that unlike the variables in ast_config, the resulting list of variables MUST be fred with ast_free_runtime() as there is no container.

Definition at line 990 of file config.c.

References db, find_engine(), ast_config_engine::realtime_func, and table.

Referenced by cli_load_realtime(), find_user_realtime(), realtime_exec(), realtime_peer(), realtime_switch_common(), and realtime_user().

{
   struct ast_config_engine *eng;
   char db[256]="";
   char table[256]="";
   struct ast_variable *res=NULL;
   va_list ap;

   va_start(ap, family);
   eng = find_engine(family, db, sizeof(db), table, sizeof(table));
   if (eng && eng->realtime_func) 
      res = eng->realtime_func(db, table, ap);
   va_end(ap);

   return res;
}

struct ast_config* ast_load_realtime_multientry	(	const char *	family,
			...
	)

Retrieve realtime configuration.

Parameters:

family

which family/config to lookup This will use builtin configuration backends to look up a particular entity in realtime and return a variable list of its parameters. Unlike the ast_load_realtime, this function can return more than one entry and is thus stored inside a taditional ast_config structure rather than just returning a linked list of variables.

Definition at line 1019 of file config.c.

References db, find_engine(), ast_config_engine::realtime_multi_func, and table.

Referenced by realtime_directory(), and realtime_switch_common().

{
   struct ast_config_engine *eng;
   char db[256]="";
   char table[256]="";
   struct ast_config *res=NULL;
   va_list ap;

   va_start(ap, family);
   eng = find_engine(family, db, sizeof(db), table, sizeof(table));
   if (eng && eng->realtime_multi_func) 
      res = eng->realtime_multi_func(db, table, ap);
   va_end(ap);

   return res;
}

int ast_update_realtime	(	const char *	family,
		const char *	keyfield,
		const char *	lookup,
			...
	)

Update realtime configuration.

Parameters:

	family	which family/config to be updated
	keyfield	which field to use as the key
	lookup	which value to look for in the key field to match the entry. This function is used to update a parameter in realtime configuration space.

Definition at line 1036 of file config.c.

References db, find_engine(), table, and ast_config_engine::update_func.

Referenced by change_password_realtime(), cli_update_realtime(), destroy_association(), realtime_update_exec(), and realtime_update_peer().

{
   struct ast_config_engine *eng;
   int res = -1;
   char db[256]="";
   char table[256]="";
   va_list ap;

   va_start(ap, lookup);
   eng = find_engine(family, db, sizeof(db), table, sizeof(table));
   if (eng && eng->update_func) 
      res = eng->update_func(db, table, keyfield, lookup, ap);
   va_end(ap);

   return res;
}

void ast_variable_append	(	struct ast_category *	category,
		struct ast_variable *	variable
	)

Definition at line 116 of file config.c.

References ast_category::last, ast_variable::next, and ast_category::root.

Referenced by config_odbc(), inherit_category(), move_variables(), process_text_line(), realtime_directory(), realtime_multi_odbc(), and vm_forwardoptions().

{
   if (category->last)
      category->last->next = variable;
   else
      category->root = variable;
   category->last = variable;
   while (category->last->next)
      category->last = category->last->next;
}

struct ast_variable* ast_variable_browse	(	const struct ast_config *	config,
		const char *	category
	)

Goes through variables Somewhat similar in intent as the ast_category_browse. List variables of config file category.

Returns ast_variable list on success, or NULL on failure

Definition at line 138 of file config.c.

References ast_category_get(), config, and ast_category::root.

Referenced by adsi_load(), ast_enum_init(), ast_readconfig(), ast_variable_retrieve(), authenticate(), collect_function_digits(), conf_exec(), do_directory(), find_conf(), handle_save_dialplan(), iax_template_parse(), ind_load_module(), init_logger_chain(), load_config(), load_module(), load_modules(), load_moh_classes(), load_odbc_config(), loadconfigurationfile(), misdn_cfg_init(), odbc_load_module(), osp_build(), parse_config(), pbx_load_module(), process_my_load_module(), read_agent_config(), read_config_maps(), reload_config(), reload_queues(), rpt_master(), set_config(), setup_zap(), sip_notify(), store_config(), and tds_load_module().

{
   struct ast_category *cat = NULL;

   if (category && config->last_browse && (config->last_browse->name == category))
      cat = config->last_browse;
   else
      cat = ast_category_get(config, category);

   if (cat)
      return cat->root;
   else
      return NULL;
}

struct ast_variable* ast_variable_new	(	const char *	name,
		const char *	value
	)

Definition at line 99 of file config.c.

References malloc.

Referenced by apply_outgoing(), astman_get_variables(), build_peer(), build_user(), check_access(), check_user_full(), config_odbc(), launch_page(), process_text_line(), realtime_directory(), realtime_multi_odbc(), realtime_odbc(), variable_clone(), and vm_forwardoptions().

{
   struct ast_variable *variable;

   int length = strlen(name) + strlen(value) + 2 + sizeof(struct ast_variable);
   variable = malloc(length);
   if (variable) {
      memset(variable, 0, length);
      variable->name = variable->stuff;
      variable->value = variable->stuff + strlen(name) + 1;    
      strcpy(variable->name,name);
      strcpy(variable->value,value);
   }

   return variable;
}

char* ast_variable_retrieve	(	const struct ast_config *	config,
		const char *	category,
		const char *	variable
	)

Gets a variable.

Parameters:

	config	which (opened) config to use
	category	category under which the variable lies
	variable	which variable you wish to get the data for Goes through a given config file in the given category and searches for the given variable

Returns the variable value on success, or NULL if unable to find it.

Definition at line 153 of file config.c.

References ast_variable_browse(), config, ast_variable::name, ast_category::next, ast_variable::next, ast_category::root, and ast_variable::value.

Referenced by __load_resource(), advanced_options(), ast_rtp_reload(), attempt_reconnect(), authenticate(), config_load(), directory_exec(), do_reload(), festival_exec(), function_ilink(), function_remote(), get_wait_interval(), iax_template_parse(), ind_load_module(), init_logger_chain(), init_manager(), load_config(), load_module(), odbc_load_module(), pbx_load_module(), play_message(), privacy_exec(), process_my_load_module(), read_agent_config(), realtime_directory(), reload_config(), reload_queues(), retrieve_astcfgint(), rpt(), rpt_exec(), rpt_master(), rpt_tele_thread(), set_config(), tds_load_module(), telem_lookup(), and vm_forwardoptions().

{
   struct ast_variable *v;

   if (category) {
      for (v = ast_variable_browse(config, category); v; v = v->next) {
         if (!strcasecmp(variable, v->name))
            return v->value;
      }
   } else {
      struct ast_category *cat;

      for (cat = config->root; cat; cat = cat->next)
         for (v = cat->root; v; v = v->next)
            if (!strcasecmp(variable, v->name))
               return v->value;
   }

   return NULL;
}

void ast_variables_destroy

(

struct ast_variable *

var

)

Free variable list.

Parameters:

var

the linked list of variables to free This function frees a list of variables.

Definition at line 127 of file config.c.

References free, and ast_variable::next.

Referenced by __sip_destroy(), ast_category_destroy(), ast_config_destroy(), ast_pbx_outgoing_app(), ast_pbx_outgoing_exten(), build_peer(), destroy_user(), find_user_realtime(), pvt_destructor(), realtime_canmatch(), realtime_exec(), realtime_exists(), realtime_matchmore(), realtime_odbc(), realtime_peer(), realtime_user(), sip_alloc(), sip_destroy_peer(), and sip_destroy_user().

{
   struct ast_variable *vn;

   while(v) {
      vn = v;
      v = v->next;
      free(vn);
   }
}

int config_text_file_save	(	const char *	filename,
		const struct ast_config *	cfg,
		const char *	generator
	)

Definition at line 680 of file config.c.

References ast_config_AST_CONFIG_DIR, ast_log(), ast_verbose(), cfg, LOG_DEBUG, ast_category::name, ast_category::next, option_debug, option_verbose, ast_category::root, ast_config::root, t, var, and VERBOSE_PREFIX_2.

Referenced by vm_forwardoptions().

{
   FILE *f;
   char fn[256];
   char date[256]="";
   time_t t;
   struct ast_variable *var;
   struct ast_category *cat;
   int blanklines = 0;

   if (configfile[0] == '/') {
      ast_copy_string(fn, configfile, sizeof(fn));
   } else {
      snprintf(fn, sizeof(fn), "%s/%s", ast_config_AST_CONFIG_DIR, configfile);
   }
   time(&t);
   ast_copy_string(date, ctime(&t), sizeof(date));
#ifdef __CYGWIN__ 
   if ((f = fopen(fn, "w+"))) {
#else
   if ((f = fopen(fn, "w"))) {
#endif       
      if (option_verbose > 1)
         ast_verbose(VERBOSE_PREFIX_2 "Saving '%s': ", fn);
      fprintf(f, ";!\n");
      fprintf(f, ";! Automatically generated configuration file\n");
      if (strcmp(configfile, fn))
         fprintf(f, ";! Filename: %s (%s)\n", configfile, fn);
      else
         fprintf(f, ";! Filename: %s\n", configfile);
      fprintf(f, ";! Generator: %s\n", generator);
      fprintf(f, ";! Creation Date: %s", date);
      fprintf(f, ";!\n");
      cat = cfg->root;
      while(cat) {
         /* Dump section with any appropriate comment */
         fprintf(f, "[%s]\n", cat->name);
         var = cat->root;
         while(