FreeSWITCH API Documentation  1.7.0
switch_xml_config.h
Go to the documentation of this file.
1 /*
2  * FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application
3  * Copyright (C) 2005-2014, Anthony Minessale II <anthm@freeswitch.org>
4  *
5  * Version: MPL 1.1
6  *
7  * The contents of this file are subject to the Mozilla Public License Version
8  * 1.1 (the "License"); you may not use this file except in compliance with
9  * the License. You may obtain a copy of the License at
10  * http://www.mozilla.org/MPL/
11  *
12  * Software distributed under the License is distributed on an "AS IS" basis,
13  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
14  * for the specific language governing rights and limitations under the
15  * License.
16  *
17  * The Original Code is FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application
18  *
19  * The Initial Developer of the Original Code is
20  * Mathieu Rene <mathieu.rene@gmail.com>
21  * Portions created by the Initial Developer are Copyright (C)
22  * the Initial Developer. All Rights Reserved.
23  *
24  * Contributor(s):
25  *
26  * Mathieu Rene <mathieu.rene@gmail.com>
27  *
28  *
29  * switch_xml_config.h - Generic configuration parser
30  *
31  */
32 
33 #ifndef SWITCH_XML_CONFIG_H
34 #define SWITCH_XML_CONFIG_H
35 
36 #include <switch.h>
37 
39 /*! \brief Type of value to parse */
40  typedef enum {
41  SWITCH_CONFIG_INT, /*< (ptr=int* default=int data=NULL) Integer */
42  SWITCH_CONFIG_ATOMIC, /*< (ptr=switch_atomic_t* default=uint32_t data=NULL) Integer */
43  SWITCH_CONFIG_STRING, /*< (ptr=[char* or char ** (for alloc)] default=char* data=switch_xml_config_string_options_t*) Zero-terminated C-string */
44  SWITCH_CONFIG_BOOL, /*< (ptr=switch_bool_t* default=switch_bool_t data=NULL) Yes and no */
45  SWITCH_CONFIG_CUSTOM, /*< (ptr=<custom function data> default=<custom function data> data=switch_xml_config_callback_t) Custom, get value through function pointer */
46  SWITCH_CONFIG_ENUM, /*< (ptr=int* default=int data=switch_xml_config_enum_item_t*) */
47  SWITCH_CONFIG_FLAG, /*< (ptr=int32_t* default=switch_bool_t data=int (flag index) */
48  SWITCH_CONFIG_FLAGARRAY, /*< (ptr=int8_t* default=switch_bool_t data=int (flag index) */
49 
50  /* No more past that line */
53 
54 typedef struct {
55  char *key; /*< The item's key or NULL if this is the last one in the list */
56  int value; /*< The item's value */
58 
59 typedef struct {
60  switch_memory_pool_t *pool; /*< If set, the string will be allocated on the pool (unless the length param is > 0, then you misread this file) */
61  switch_size_t length; /*< Length of the char array, or 0 if memory has to be allocated dynamically */
62  char *validation_regex; /*< Enforce validation using this regular expression */
64 
65 SWITCH_DECLARE_DATA extern switch_xml_config_string_options_t switch_config_string_strdup; /*< String options structure for strdup, no validation */
66 
67 typedef struct {
69  int min;
71  int max;
73 
74 typedef struct {
76  uint32_t min;
78  uint32_t max;
80 
83 
84 typedef enum {
89 
90 typedef enum {
91  CONFIG_RELOADABLE = (1 << 0),
92  CONFIG_REQUIRED = (1 << 1)
94 
96  switch_bool_t changed);
97 
98 /*!
99  * \brief A configuration instruction read by switch_xml_config_parse
100 */
102  const char *key; /*< The key of the element, or NULL to indicate the end of the list */
103  switch_xml_config_type_t type; /*< The type of variable */
104  int flags; /*< True if the var can be changed on reload */
105  void *ptr; /*< Ptr to the var to be changed */
106  const void *defaultvalue; /*< Default value */
107  void *data; /*< Custom data (depending on the type) */
108  switch_xml_config_callback_t function; /*< Callback to be called after the var is parsed */
109  const char *syntax; /*< Optional syntax documentation for this setting */
110  const char *helptext; /*< Optional documentation text for this setting */
111 };
112 
113 #define SWITCH_CONFIG_ITEM(_key, _type, _flags, _ptr, _defaultvalue, _data, _syntax, _helptext) { _key, _type, _flags, _ptr, (void*)_defaultvalue, (void*)_data, NULL, _syntax, _helptext }
114 #define SWITCH_CONFIG_ITEM_STRING_STRDUP(_key, _flags, _ptr, _defaultvalue, _syntax, _helptext) { (_key), SWITCH_CONFIG_STRING, (_flags), (_ptr), ((void*)_defaultvalue), (NULL), (NULL), (_syntax), (_helptext) }
115 #define SWITCH_CONFIG_ITEM_CALLBACK(_key, _type, _flags, _ptr, _defaultvalue, _function, _functiondata, _syntax, _helptext) { _key, _type, _flags, _ptr, (void*)_defaultvalue, _functiondata, _function, _syntax, _helptext }
116 #define SWITCH_CONFIG_ITEM_END() { NULL, SWITCH_CONFIG_LAST, 0, NULL, NULL, NULL, NULL, NULL, NULL }
117 
118 #define SWITCH_CONFIG_SET_ITEM(_item, _key, _type, _flags, _ptr, _defaultvalue, _data, _syntax, _helptext) switch_config_perform_set_item(&(_item), _key, _type, _flags, _ptr, (void*)(_defaultvalue), _data, NULL, _syntax, _helptext)
119 #define SWITCH_CONFIG_SET_ITEM_CALLBACK(_item, _key, _type, _flags, _ptr, _defaultvalue, _data, _function, _syntax, _helptext) switch_config_perform_set_item(&(_item), _key, _type, _flags, _ptr, (void*)(_defaultvalue), _data, _function, _syntax, _helptext)
120 
121 SWITCH_DECLARE(void) switch_config_perform_set_item(switch_xml_config_item_t *item, const char *key, switch_xml_config_type_t type, int flags, void *ptr,
122  const void *defaultvalue, void *data, switch_xml_config_callback_t function, const char *syntax,
123  const char *helptext);
124 
125 /*!
126  * \brief Gets the int representation of an enum
127  * \param enum_options the switch_xml_config_enum_item_t array for this enum
128  * \param value string value to search
129  */
131 
132 /*!
133  * \brief Gets the string representation of an enum
134  * \param enum_options the switch_xml_config_enum_item_t array for this enum
135  * \param value int value to search
136  */
137 SWITCH_DECLARE(const char *) switch_xml_config_enum_int2str(switch_xml_config_enum_item_t *enum_options, int value);
138 
139 /*!
140  * \brief Prints out an item's documentation on the console
141  * \param level loglevel to use
142  * \param item item which the doc should be printed
143  */
145 
146 /*!
147  * \brief Parses all the xml elements, following a ruleset defined by an array of switch_xml_config_item_t
148  * \param xml The first element of the list to parse
149  * \param reload true to skip all non-reloadable options
150  * \param instructions instrutions on how to parse the elements
151  * \see switch_xml_config_item_t
152  */
154 
155 /*!
156  * \brief Parses a module's settings
157  * \param reload true to skip all non-reloadable options
158  * \param file the configuration file to look for
159  * \param instructions the instructions
160  */
162 
163 /*!
164  * \brief Parses all of an event's elements, following a ruleset defined by an array of switch_xml_config_item_t
165  * \param event The event structure containing the key and values to parse
166  * \param reload true to skip all non-reloadable options
167  * \param instructions instrutions on how to parse the elements
168  * \see switch_xml_config_item_t
169  */
171  switch_xml_config_item_t *instructions);
172 
173 /*!
174  * \brief Parses a list of xml elements into an event
175  * \param xml First element of the xml list to parse
176  * \param keyname Name of the key attribute
177  * \param keyvalue Name of the value attribute
178  * \param event [out] event (if *event is NOT NULL, the headers will be appended to the existing event)
179  */
180 SWITCH_DECLARE(switch_size_t) switch_event_import_xml(switch_xml_t xml, const char *keyname, const char *valuename, switch_event_t **event);
181 
182 /*!
183  * \brief Free any memory allocated by the configuration
184  * \param instructions instrutions on how to parse the elements
185  */
187 
189 #endif /* !defined(SWITCH_XML_CONFIG_H) */
190 /* For Emacs:
191  * Local Variables:
192  * mode:c
193  * indent-tabs-mode:t
194  * tab-width:4
195  * c-basic-offset:4
196  * End:
197  * For VIM:
198  * vim:set softtabstop=4 shiftwidth=4 tabstop=4 noet:
199  */
switch_size_t switch_event_import_xml(switch_xml_t xml, const char *keyname, const char *valuename, switch_event_t **event)
Parses a list of xml elements into an event.
switch_config_flags_t
switch_status_t switch_xml_config_enum_str2int(switch_xml_config_enum_item_t *enum_options, const char *value, int *out)
Gets the int representation of an enum.
#define SWITCH_END_EXTERN_C
Definition: switch.h:43
switch_bool_t
Definition: switch_types.h:405
Representation of an event.
Definition: switch_event.h:80
#define SWITCH_DECLARE_DATA
A representation of an XML tree.
Definition: switch_xml.h:76
switch_xml_config_type_t type
A configuration instruction read by switch_xml_config_parse.
switch_status_t switch_xml_config_parse_module_settings(const char *file, switch_bool_t reload, switch_xml_config_item_t *instructions)
Parses a module's settings.
switch_xml_config_type_t
Type of value to parse.
uintptr_t switch_size_t
void switch_xml_config_cleanup(switch_xml_config_item_t *instructions)
Free any memory allocated by the configuration.
void switch_config_perform_set_item(switch_xml_config_item_t *item, const char *key, switch_xml_config_type_t type, int flags, void *ptr, const void *defaultvalue, void *data, switch_xml_config_callback_t function, const char *syntax, const char *helptext)
switch_status_t switch_xml_config_parse_event(switch_event_t *event, int count, switch_bool_t reload, switch_xml_config_item_t *instructions)
Parses all of an event's elements, following a ruleset defined by an array of switch_xml_config_item_...
switch_status_t
Common return values.
void switch_xml_config_item_print_doc(int level, switch_xml_config_item_t *item)
Prints out an item's documentation on the console.
switch_xml_config_string_options_t switch_config_string_strdup
Main Library Header.
#define SWITCH_DECLARE(type)
struct apr_pool_t switch_memory_pool_t
switch_status_t switch_xml_config_parse(switch_xml_t xml, switch_bool_t reload, switch_xml_config_item_t *instructions)
Parses all the xml elements, following a ruleset defined by an array of switch_xml_config_item_t.
const char * switch_xml_config_enum_int2str(switch_xml_config_enum_item_t *enum_options, int value)
Gets the string representation of an enum.
switch_status_t(* switch_xml_config_callback_t)(switch_xml_config_item_t *item, const char *newvalue, switch_config_callback_type_t callback_type, switch_bool_t changed)
switch_config_callback_type_t
#define SWITCH_BEGIN_EXTERN_C
Definition: switch.h:42