Enhance generic configuration parser

git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@12493 d0543943-73ff-0310-b7d9-9358b9ac24b2

diff --git a/src/include/switch_xml_config.h b/src/include/switch_xml_config.h
index 935e3e8f5beb3ed4fc96b378158a3171d96b7175..92cb7b4e342fed92bbc407503f46632a1585b4a1 100644 (file)
--- a/src/include/switch_xml_config.h
+++ b/src/include/switch_xml_config.h
@@ -94,12 +94,35 @@ struct switch_xml_config_item {
        void *defaultvalue;                                     /*< Default value */
        void *data;                                                     /*< Custom data (depending on the type) */
        switch_xml_config_callback_t function;  /*< Callback to be called after the var is parsed */
+       char *syntax;                                                   /*< Optional syntax documentation for this setting */
+       char *helptext;                                                 /*< Optional documentation text for this setting */
 };
 
-#define SWITCH_CONFIG_ITEM(_key, _type, _flags, _ptr, _defaultvalue, _data)    { _key, _type, _flags, _ptr, _defaultvalue, _data, NULL }
-#define SWITCH_CONFIG_ITEM_STRING_STRDUP(_key, _flags, _ptr, _defaultvalue)    { _key, SWITCH_CONFIG_STRING, _flags, _ptr, _defaultvalue, &switch_config_string_strdup, NULL }
-#define SWITCH_CONFIG_ITEM_CALLBACK(_key, _type, _flags, _ptr, _defaultvalue, _data, _functiondata)    { _key, _type, _flags, _ptr, _defaultvalue, _functiondata, _data }
-#define SWITCH_CONFIG_ITEM_END() { NULL, SWITCH_CONFIG_LAST, 0, NULL ,NULL, NULL, NULL }
+#define SWITCH_CONFIG_ITEM(_key, _type, _flags, _ptr, _defaultvalue, _data, _syntax, _helptext)        { _key, _type, _flags, _ptr, _defaultvalue, _data, NULL, _syntax, _helptext }
+#define SWITCH_CONFIG_ITEM_STRING_STRDUP(_key, _flags, _ptr, _defaultvalue, _syntax, _helptext)        { _key, SWITCH_CONFIG_STRING, _flags, _ptr, _defaultvalue, &switch_config_string_strdup, NULL, _helptext}
+#define SWITCH_CONFIG_ITEM_CALLBACK(_key, _type, _flags, _ptr, _defaultvalue, _data, _functiondata, _syntax, _helptext)        { _key, _type, _flags, _ptr, _defaultvalue, _functiondata, _data, _helptext}
+#define SWITCH_CONFIG_ITEM_END() { NULL, SWITCH_CONFIG_LAST, 0, NULL ,NULL, NULL, NULL, NULL, NULL }
+
+/*! 
+ * \brief Gets the int representation of an enum
+ * \param enum_options the switch_xml_config_enum_item_t array for this enum
+ * \param value string value to search 
+ */
+SWITCH_DECLARE(switch_status_t) switch_xml_config_enum_str2int(switch_xml_config_enum_item_t *enum_options, const char *value, int *out);
+
+/*! 
+ * \brief Gets the string representation of an enum
+ * \param enum_options the switch_xml_config_enum_item_t array for this enum
+ * \param value int value to search 
+ */
+SWITCH_DECLARE(const char*) switch_xml_config_enum_int2str(switch_xml_config_enum_item_t *enum_options, int value);
+
+/*!
+ * \brief Prints out an item's documentation on the console 
+ * \param level loglevel to use
+ * \param item item which the doc should be printed
+ */
+SWITCH_DECLARE(void) switch_xml_config_item_print_doc(int level, switch_xml_config_item_t *item);
 
 /*! 
  * \brief Parses all the xml elements, following a ruleset defined by an array of switch_xml_config_item_t 
@@ -108,7 +131,15 @@ struct switch_xml_config_item {
  * \param instructions instrutions on how to parse the elements
  * \see switch_xml_config_item_t
  */
-SWITCH_DECLARE(switch_status_t) switch_xml_config_parse(switch_xml_t xml, int reload, switch_xml_config_item_t *instructions);
+SWITCH_DECLARE(switch_status_t) switch_xml_config_parse(switch_xml_t xml, switch_bool_t reload, switch_xml_config_item_t *instructions);
+
+/*!
+ * \brief Parses a module's settings
+ * \param reload true to skip all non-reloadable options
+ * \param file the configuration file to look for
+ * \param instructions the instructions 
+ */
+SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_module_settings(const char *file, switch_bool_t reload, switch_xml_config_item_t *instructions);
 
 /*! 
  * \brief Parses all of an event's elements, following a ruleset defined by an array of switch_xml_config_item_t 
@@ -117,7 +148,7 @@ SWITCH_DECLARE(switch_status_t) switch_xml_config_parse(switch_xml_t xml, int re
  * \param instructions instrutions on how to parse the elements
  * \see switch_xml_config_item_t
  */
-SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *event, int count, int reload, switch_xml_config_item_t *instructions);
+SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *event, int count, switch_bool_t reload, switch_xml_config_item_t *instructions);
 
 /*!
  * \brief Parses a list of xml elements into an event  
@@ -128,12 +159,12 @@ SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *ev
  */
 SWITCH_DECLARE(switch_size_t) switch_event_import_xml(switch_xml_t xml, const char *keyname, const char *valuename, switch_event_t **event);
 
-
 /*!
  * \brief Free any memory allocated by the configuration
  * \param instructions instrutions on how to parse the elements
  */
 SWITCH_DECLARE(void) switch_xml_config_cleanup(switch_xml_config_item_t *instructions);
+
 #endif /* !defined(SWITCH_XML_CONFIG_H) */
 
 /* For Emacs:

diff --git a/src/switch_xml_config.c b/src/switch_xml_config.c
index ba51bd83366197315768dfa928c6e22e4c2a47f4..093500e499c9ba2a7c5a29060c00883d71f797dd 100644 (file)
--- a/src/switch_xml_config.c
+++ b/src/switch_xml_config.c
@@ -34,6 +34,17 @@
 
 SWITCH_DECLARE_DATA switch_xml_config_string_options_t switch_config_string_strdup = { NULL, 0, NULL };
 
+static switch_xml_config_enum_item_t switch_config_types_enum[] = {
+       {"int",         SWITCH_CONFIG_INT               },
+       {"string",      SWITCH_CONFIG_STRING    },
+       {"bool",        SWITCH_CONFIG_BOOL              },
+       {"custom",      SWITCH_CONFIG_CUSTOM    },
+       {"enum",        SWITCH_CONFIG_ENUM              },
+       {"flag",        SWITCH_CONFIG_FLAG              },
+       {"flagarray",SWITCH_CONFIG_FLAGARRAY},
+       { NULL, 0 }
+};
+
 SWITCH_DECLARE(switch_size_t) switch_event_import_xml(switch_xml_t xml, const char *keyname, const char *valuename, switch_event_t **event)
 {
        switch_xml_t node;
@@ -57,7 +68,35 @@ SWITCH_DECLARE(switch_size_t) switch_event_import_xml(switch_xml_t xml, const ch
        return count;
 }
 
-SWITCH_DECLARE(switch_status_t) switch_xml_config_parse(switch_xml_t xml, int reload, switch_xml_config_item_t *instructions)
+SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_module_settings(const char *file, switch_bool_t reload, switch_xml_config_item_t *instructions)
+{
+       switch_xml_t cfg, xml, settings;
+       switch_status_t status = SWITCH_STATUS_SUCCESS;
+       
+       if (!(xml = switch_xml_open_cfg(file, &cfg, NULL))) {
+               switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "Could not open %s\n", file);
+               return SWITCH_STATUS_FALSE;
+       }
+
+       if ((settings = switch_xml_child(cfg, "settings"))) {
+               status = switch_xml_config_parse(switch_xml_child(settings, "param"), reload, instructions);
+       }
+       
+       switch_xml_free(xml);
+       
+       return status;
+}
+
+SWITCH_DECLARE(void) switch_xml_config_item_print_doc(int level, switch_xml_config_item_t *item)
+{
+       if (item->syntax && item->helptext) {
+               switch_log_printf(SWITCH_CHANNEL_LOG_CLEAN, level, "Item name: [%s]\nType: %s (%s)\nSyntax: %s\nHelp: %s\n\n",
+                       item->key, switch_xml_config_enum_int2str(switch_config_types_enum, item->type), 
+                       switch_test_flag(item, CONFIG_REQUIRED) ? "required" : "optional", item->syntax, item->helptext);
+       }
+}
+
+SWITCH_DECLARE(switch_status_t) switch_xml_config_parse(switch_xml_t xml, switch_bool_t reload, switch_xml_config_item_t *instructions)
 {
        switch_event_t *event = NULL;
        switch_status_t result;
@@ -72,7 +111,29 @@ SWITCH_DECLARE(switch_status_t) switch_xml_config_parse(switch_xml_t xml, int re
        return result;
 }
 
-SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *event, int count, int reload, switch_xml_config_item_t *instructions)
+SWITCH_DECLARE(switch_status_t) switch_xml_config_enum_str2int(switch_xml_config_enum_item_t *enum_options, const char *value, int *out)
+{
+       for (;enum_options->key; enum_options++) {
+               if (!strcasecmp(value, enum_options->key)) {
+                       *out = enum_options->value;
+                       return SWITCH_STATUS_SUCCESS;
+               }
+       }
+       
+       return SWITCH_STATUS_FALSE;
+}
+
+SWITCH_DECLARE(const char*) switch_xml_config_enum_int2str(switch_xml_config_enum_item_t *enum_options, int value)
+{
+       for (;enum_options->key; enum_options++) {
+               if (value == enum_options->value) {
+                       return enum_options->key;
+               }
+       }
+       return NULL;
+}
+
+SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *event, int count, switch_bool_t reload, switch_xml_config_item_t *instructions)
 {
        switch_xml_config_item_t *item;
        int matched_count = 0;
@@ -142,9 +203,9 @@ SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *ev
                                        const char *newstring = NULL;
                                        
                                        if (!string_options) {
-                                               switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "Missing mandatory switch_xml_config_string_options_t structure for parameter [%s], skipping!\n",
+                                               switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_CRIT, "Missing mandatory switch_xml_config_string_options_t structure for parameter [%s], skipping!\n",
                                                                                  item->key);
-                                               continue;
+                                               return SWITCH_STATUS_FALSE;
                                        }
                                        
                                        /* Perform validation */
@@ -155,7 +216,8 @@ SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *ev
                                                        } else {
                                                                newstring = (char*)item->defaultvalue;  /* Regex failed */
                                                                switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "Invalid value [%s] for parameter [%s], setting default [%s]\n", 
-                                                                       value, item->key, newstring);
+                                                                       value, item->key, newstring ? newstring : "(null)");
+                                                               switch_xml_config_item_print_doc(SWITCH_LOG_ERROR, item);
                                                        }
                                                } else {
                                                        newstring = value; /* No validation */
@@ -204,6 +266,7 @@ SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *ev
                                                newval = (switch_bool_t)(intptr_t)item->defaultvalue;
                                                switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "Invalid value [%s] for parameter [%s], setting default [%s]\n",  
                                                                                value, item->key, newval ? "true" : "false");
+                                               switch_xml_config_item_print_doc(SWITCH_LOG_ERROR, item);
                                        } else {
                                                newval = (switch_bool_t)(intptr_t)item->defaultvalue;
                                        }
@@ -221,21 +284,18 @@ SWITCH_DECLARE(switch_status_t) switch_xml_config_parse_event(switch_event_t *ev
                                        switch_xml_config_enum_item_t *enum_options = (switch_xml_config_enum_item_t*)item->data;
                                        int *dest = (int*)item->ptr;
                                        int newval = 0;
+                                       switch_status_t lookup_result;
                                        
                                        if (value) {
-                                               for (;enum_options->key; enum_options++) {
-                                                       if (!strcasecmp(value, enum_options->key)) {
-                                                               newval = enum_options->value;
-                                                               break;
-                                                       }
-                                               }
+                                               lookup_result = switch_xml_config_enum_str2int(enum_options, value, &newval);
                                        } else {
                                                newval = (int)(intptr_t)item->defaultvalue; 
                                        }
                                        
-                                       if (!enum_options->key) { /* if (!found) */
+                                       if (value != SWITCH_STATUS_SUCCESS) {
                                                newval = (int)(intptr_t)item->defaultvalue;
                                                switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "Invalid value [%s] for parameter [%s]\n",  value, item->key);
+                                               switch_xml_config_item_print_doc(SWITCH_LOG_ERROR, item);
                                        }
                                        
                                        if (*dest != newval) {