[svn-commits] bkruse: branch group/appdocsxml r127971 - in /team/group/appdocsxml: ./ apps/...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Thu Jul 3 20:40:08 CDT 2008
Author: bkruse
Date: Thu Jul 3 20:40:07 2008
New Revision: 127971
URL: http://svn.digium.com/view/asterisk?view=rev&rev=127971
Log:
Sort of a long commit message.
Added a TODO list with ideas that me and
mvanbaak already had (including russells
dialplan idea)
Added a script to pull DOCUMENTATION xml out
of files (will be used at build time to generate
a single xml file, or multiple xml files of documentation)
Updated app_dial to reflect those changes.
(APP/DOCUMENTATION)
Try it with:
awk -f build_tools/get_documentation apps/app_dial.c
Hardcoded iksemel in pbx.c (obviously this is going
to need to be changed, so asterisk does not depend
on iksemel as it currently does)
added ast_register_application_xml that is going
to fetch descrip, etc, from the xml blob.
It builds and loads.
Added:
team/group/appdocsxml/TODO_appdocsxml (with props)
team/group/appdocsxml/build_tools/get_documentation (with props)
Modified:
team/group/appdocsxml/Makefile
team/group/appdocsxml/apps/app_dial.c
team/group/appdocsxml/include/asterisk/module.h
team/group/appdocsxml/main/Makefile
team/group/appdocsxml/main/pbx.c
Modified: team/group/appdocsxml/Makefile
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/Makefile?view=diff&rev=127971&r1=127970&r2=127971
==============================================================================
--- team/group/appdocsxml/Makefile (original)
+++ team/group/appdocsxml/Makefile Thu Jul 3 20:40:07 2008
@@ -291,6 +291,10 @@
MOD_SUBDIRS_EMBED_LDFLAGS:=$(MOD_SUBDIRS:%=%-embed-ldflags)
MOD_SUBDIRS_EMBED_LIBS:=$(MOD_SUBDIRS:%=%-embed-libs)
MOD_SUBDIRS_MENUSELECT_TREE:=$(MOD_SUBDIRS:%=%-menuselect-tree)
+
+# if use xml documentation?
+ ASTCFLAGS+=-DXML_DOCUMENTATION
+ LIBS+=-liksemel
ifneq ($(findstring darwin,$(OSARCH)),)
ASTCFLAGS+=-D__Darwin__
Added: team/group/appdocsxml/TODO_appdocsxml
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/TODO_appdocsxml?view=auto&rev=127971
==============================================================================
--- team/group/appdocsxml/TODO_appdocsxml (added)
+++ team/group/appdocsxml/TODO_appdocsxml Thu Jul 3 20:40:07 2008
@@ -1,0 +1,38 @@
+*****XML Documentation Conversation*****
+
+Goal: To convert the static documentation held within
+all parts of Asterisk (non-code/non-doxygen) into a
+parseable format (XML) to be loaded on runtime.
+
+This would provide all the documentation currently in
+Asterisk to any other source that supports some kind of
+XML Conversion.
+
+One end result usage would be to be able to verify dialplans
+based on arguments/results/types of dialplan applications,
+functions, and anything else that can be regulated to some degree.
+
+
+So far mvanbaak added an example in apps/app_dial.c of
+an XML tree of the Dial application.
+
+
+**** Todo ****
+
+ONCE we have a acceptable format that most agree on, we will
+need to convert all the applications to use this method (obviously).
+
+Define a set of rules/ideas that you want to pull out of the documentation.
+
+The reason for this is so we do not go back and say, "Oh, we should have
+added the ability to do X, which is in the code/documentation and
+can be pulled out in a reliable way. Now we have to do that for
+all the Documentation we have already converted.
+
+
+Finish ast_register_application_xml
+
+Finish the parsing of /var/lib/asterisk/documentation.xml
+
+Add the parsing of files to one xml blob, and copying to
+/var/lib/asterisk/documentation.xml
Propchange: team/group/appdocsxml/TODO_appdocsxml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/group/appdocsxml/TODO_appdocsxml
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: team/group/appdocsxml/TODO_appdocsxml
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: team/group/appdocsxml/apps/app_dial.c
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/apps/app_dial.c?view=diff&rev=127971&r1=127970&r2=127971
==============================================================================
--- team/group/appdocsxml/apps/app_dial.c (original)
+++ team/group/appdocsxml/apps/app_dial.c Thu Jul 3 20:40:07 2008
@@ -62,7 +62,7 @@
#include "asterisk/global_datastores.h"
#include "asterisk/dsp.h"
-/*** APP
+/*** DOCUMENTATION
<application name="Dial">
<synopsis>
Place a call and connect to the current channel.
Added: team/group/appdocsxml/build_tools/get_documentation
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/build_tools/get_documentation?view=auto&rev=127971
==============================================================================
--- team/group/appdocsxml/build_tools/get_documentation (added)
+++ team/group/appdocsxml/build_tools/get_documentation Thu Jul 3 20:40:07 2008
@@ -1,0 +1,3 @@
+/\/\*\*\* DOCUMENTATION/ {printit=1; next}
+/\*\*\*\// {if (printit) exit}
+// {if (printit) print}
Propchange: team/group/appdocsxml/build_tools/get_documentation
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/group/appdocsxml/build_tools/get_documentation
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: team/group/appdocsxml/build_tools/get_documentation
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: team/group/appdocsxml/include/asterisk/module.h
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/include/asterisk/module.h?view=diff&rev=127971&r1=127970&r2=127971
==============================================================================
--- team/group/appdocsxml/include/asterisk/module.h (original)
+++ team/group/appdocsxml/include/asterisk/module.h Thu Jul 3 20:40:07 2008
@@ -401,6 +401,26 @@
int ast_register_application2(const char *app, int (*execute)(struct ast_channel *, void *),
const char *synopsis, const char *description, void *mod);
+/*!
+ * \brief Register an application.
+ *
+ * \param app Short name of the application
+ * \param execute a function callback to execute the application. It should return
+ * non-zero if the channel needs to be hung up.
+ * \param mod module this application belongs to
+ *
+ * This registers an application with Asterisk's internal application list.
+ * \note The individual applications themselves are responsible for registering and unregistering
+ * and unregistering their own CLI commands.
+ *
+ * \note Pulls all application documentation from compile-time composed XML file
+ *
+ * \retval 0 success
+ * \retval -1 failure.
+ */
+int ast_register_application_xml(const char *app, int (*execute)(struct ast_channel *, void *), void *mod);
+
+
/*!
* \brief Unregister an application
*
Modified: team/group/appdocsxml/main/Makefile
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/main/Makefile?view=diff&rev=127971&r1=127970&r2=127971
==============================================================================
--- team/group/appdocsxml/main/Makefile (original)
+++ team/group/appdocsxml/main/Makefile Thu Jul 3 20:40:07 2008
@@ -43,6 +43,7 @@
AST_LIBS += $(SSL_LIB)
AST_LIBS += $(BKTR_LIB)
+AST_LIBS += -liksemel
ifeq ($(POLL_AVAILABLE),)
OBJS+=poll.o
Modified: team/group/appdocsxml/main/pbx.c
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/main/pbx.c?view=diff&rev=127971&r1=127970&r2=127971
==============================================================================
--- team/group/appdocsxml/main/pbx.c (original)
+++ team/group/appdocsxml/main/pbx.c Thu Jul 3 20:40:07 2008
@@ -16,6 +16,10 @@
* at the top of the source tree.
*/
+/*** MODULEINFO
+ <depend>iksemel</depend>
+ ***/
+
/*! \file
*
* \brief Core PBX routines.
@@ -26,6 +30,8 @@
#include "asterisk.h"
ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
+
+#include <iksemel.h>
#include "asterisk/_private.h"
#include "asterisk/paths.h" /* use ast_config_AST_SYSTEM_NAME */
@@ -105,6 +111,9 @@
#define BACKGROUND_NOANSWER (1 << 1)
#define BACKGROUND_MATCHEXTEN (1 << 2)
#define BACKGROUND_PLAYBACK (1 << 3)
+
+/* Don't know what this should be. */
+#define FILE_XML_DOC "/var/lib/asterisk/documentation.xml"
AST_APP_OPTIONS(background_opts, {
AST_APP_OPTION('s', BACKGROUND_SKIP),
@@ -325,6 +334,10 @@
static unsigned int hashtab_hash_priority(const void *obj);
static unsigned int hashtab_hash_labels(const void *obj);
static void __ast_internal_context_destroy( struct ast_context *con);
+#ifdef XML_DOCUMENTATION
+static int xml_tag(void *udata, char *name, char **atts, int type);
+static int xml_cdata(void *udata, char *data, size_t len);
+#endif
/* a func for qsort to use to sort a char array */
static int compare_char(const void *a, const void *b)
@@ -4308,6 +4321,140 @@
return 0;
}
+/*! \brief Throwing away cdata, don't care now. */
+static int xml_cdata(void *udata, char *data, size_t len) {
+ return IKS_OK;
+}
+
+/*! \brief Debug out the information loaded from the document. */
+static int xml_tag(void *udata, char *name, char **atts, int type) {
+
+ switch(type) {
+ case IKS_OPEN:
+ ast_log(LOG_DEBUG, "TAG <%s>\n", name);
+ break;
+ case IKS_CLOSE:
+ ast_log(LOG_DEBUG, "TAG </%s>\n", name);
+ break;
+ case IKS_SINGLE:
+ ast_log(LOG_DEBUG, "TAG <%s/>\n", name);
+ break;
+ }
+
+ if(atts) {
+ int i = 0;
+ while(atts[i]) {
+ ast_log(LOG_DEBUG, " ATTRIB %s='%s'\n", atts[i], atts[i+1]);
+ i += 2;
+ }
+ }
+ return 0;
+}
+
+/* todo: If we cannot read the file, don't allow people to try to register
+ * with ast_register_application_xml */
+
+/*! \brief Load XML Document into buffer for parsing into a list */
+static int ast_load_documentation(void) {
+
+ FILE *xmldoc;
+ iksparser *p;
+ char *buf;
+ long length;
+
+ ast_log(LOG_DEBUG, "************** LOADING XML DOCUMENTATION ********************\n");
+
+ /* For now, I just throw away cdata */
+ p = iks_sax_new(NULL, xml_tag, xml_cdata);
+
+ xmldoc = fopen(FILE_XML_DOC, "r");
+
+ if(!xmldoc) {
+ ast_log(LOG_ERROR, "Could not open XML Doc at '%s'", FILE_XML_DOC);
+ return 1;
+ }
+
+ /* Get filesize, alloc space */
+ fseek(xmldoc, 0, SEEK_END);
+ /* We should have some sort of bounds checking */
+ length = ftell(xmldoc);
+ fseek(xmldoc, 0, SEEK_SET);
+
+ buf = (char *)malloc(length);
+ fclose(xmldoc);
+
+ /* Ok, let's now process it. */
+ /* Check for errors in loading the doc */
+ switch(iks_parse(p, buf, 0, 1)) {
+ case IKS_OK:
+ /* looks good, no more error checking */
+ ast_log(LOG_DEBUG, "Document Successfully Parsed\n");
+ break;
+ case IKS_NOMEM:
+ ast_log(LOG_ERROR, "Not enough memory to parse the xml document.\n");
+ return 1;
+ case IKS_BADXML:
+ ast_log(LOG_ERROR, "Bad XML Format in the xml document.\n");
+ return 1;
+ case IKS_HOOK:
+ ast_log(LOG_ERROR, "XML hooking problem? idk.\n");
+ return 1;
+ }
+
+ iks_parser_delete(p);
+
+ return 0;
+}
+
+/*! \brief Dynamically register a new dial plan application */
+int ast_register_application_xml(const char *app, int (*execute)(struct ast_channel *, void *), void *mod)
+{
+ struct ast_app *tmp, *cur = NULL;
+ char tmps[80];
+ int length, res;
+
+ AST_RWLIST_WRLOCK(&apps);
+ AST_RWLIST_TRAVERSE(&apps, tmp, list) {
+ if (!(res = strcasecmp(app, tmp->name))) {
+ ast_log(LOG_WARNING, "Already have an application '%s'\n", app);
+ AST_RWLIST_UNLOCK(&apps);
+ return -1;
+ } else if (res < 0)
+ break;
+ }
+
+ length = sizeof(*tmp) + strlen(app) + 1;
+
+ if (!(tmp = ast_calloc(1, length))) {
+ AST_RWLIST_UNLOCK(&apps);
+ return -1;
+ }
+
+ strcpy(tmp->name, app);
+ tmp->execute = execute;
+ //tmp->synopsis = synopsis;
+ //tmp->description = description;
+ tmp->module = mod;
+
+ /* Store in alphabetical order */
+ AST_RWLIST_TRAVERSE_SAFE_BEGIN(&apps, cur, list) {
+ if (strcasecmp(tmp->name, cur->name) < 0) {
+ AST_RWLIST_INSERT_BEFORE_CURRENT(tmp, list);
+ break;
+ }
+ }
+ AST_RWLIST_TRAVERSE_SAFE_END;
+ if (!cur)
+ AST_RWLIST_INSERT_TAIL(&apps, tmp, list);
+
+ ast_verb(2, "Registered application '%s'\n", term_color(tmps, tmp->name, COLOR_BRCYAN, 0, sizeof(tmps)));
+
+ AST_RWLIST_UNLOCK(&apps);
+
+ return 0;
+}
+
+
/*
* Append to the list. We don't have a tail pointer because we need
* to scan the list anyways to check for duplicates during insertion.
@@ -8035,6 +8182,11 @@
ast_cli_register_multiple(pbx_cli, sizeof(pbx_cli) / sizeof(struct ast_cli_entry));
__ast_custom_function_register(&exception_function, NULL);
+ #ifdef XML_DOCUMENTATION
+ /* Load Documentation XML Blob */
+ ast_load_documentation();
+ #endif
+
/* Register builtin applications */
for (x = 0; x < sizeof(builtins) / sizeof(struct pbx_builtin); x++) {
ast_verb(1, "[%s]\n", builtins[x].name);
More information about the svn-commits
mailing list