[asterisk-commits] bkruse: branch group/appdocsxml r127971 - in /team/group/appdocsxml: ./ apps/...

SVN commits to the Asterisk project asterisk-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 asterisk-commits mailing list