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 38 SWITCH_BEGIN_EXTERN_C 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 */ 51 SWITCH_CONFIG_LAST 52 } switch_xml_config_type_t; 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 */ 57 } switch_xml_config_enum_item_t; 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 */ 63 } switch_xml_config_string_options_t; 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 { 68 switch_bool_t enforce_min; 69 int min; 70 switch_bool_t enforce_max; 71 int max; 72 } switch_xml_config_int_options_t; 73 74 typedef struct { 75 switch_bool_t enforce_min; 76 uint32_t min; 77 switch_bool_t enforce_max; 78 uint32_t max; 79 } switch_xml_config_atomic_options_t; 80 81 struct switch_xml_config_item; 82 typedef struct switch_xml_config_item switch_xml_config_item_t; 83 84 typedef enum { 85 CONFIG_LOAD, 86 CONFIG_RELOAD, 87 CONFIG_SHUTDOWN 88 } switch_config_callback_type_t; 89 90 typedef enum { 91 CONFIG_RELOADABLE = (1 << 0), 92 CONFIG_REQUIRED = (1 << 1) 93 } switch_config_flags_t; 94 95 typedef switch_status_t (*switch_xml_config_callback_t) (switch_xml_config_item_t *item, const char *newvalue, switch_config_callback_type_t callback_type, 96 switch_bool_t changed); 97 98 /*! 99 * \brief A configuration instruction read by switch_xml_config_parse 100 */ 101 struct switch_xml_config_item { 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 */ 130 SWITCH_DECLARE(switch_status_t) switch_xml_config_enum_str2int(switch_xml_config_enum_item_t *enum_options, const char *value, int *out); 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 */ 144 SWITCH_DECLARE(void) switch_xml_config_item_print_doc(int level, switch_xml_config_item_t *item); 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 */ 153 SWITCH_DECLARE(switch_status_t) switch_xml_config_parse(switch_xml_t xml, switch_bool_t reload, switch_xml_config_item_t *instructions); 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 */ 161 SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_module_settings(const char *file, switch_bool_t reload, switch_xml_config_item_t *instructions); 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 */ 170 SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *event, int count, switch_bool_t reload, 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 */ 186 SWITCH_DECLARE(void) switch_xml_config_cleanup(switch_xml_config_item_t *instructions); 187 188 SWITCH_END_EXTERN_C 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 */ 200