From 5b168ee34babe562be856ec8f1dd14c0abd7c1a5 Mon Sep 17 00:00:00 2001 From: Russell Bryant Date: Sat, 1 Nov 2008 21:10:07 +0000 Subject: Merge changes from team/group/appdocsxml This commit introduces the first phase of an effort to manage documentation of the interfaces in Asterisk in an XML format. Currently, a new format is available for applications and dialplan functions. A good number of conversions to the new format are also included. For more information, see the following message to asterisk-dev: http://lists.digium.com/pipermail/asterisk-dev/2008-October/034968.html git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@153365 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/_private.h | 6 ++ include/asterisk/autoconfig.h.in | 3 + include/asterisk/compat.h | 11 ++++ include/asterisk/extconf.h | 10 +++- include/asterisk/module.h | 17 ++++++ include/asterisk/pbx.h | 20 +++++-- include/asterisk/strings.h | 15 +++++ include/asterisk/term.h | 22 +++++++ include/asterisk/xml.h | 122 +++++++++++++++++++++++++++++++++++++++ 9 files changed, 220 insertions(+), 6 deletions(-) create mode 100644 include/asterisk/xml.h (limited to 'include') diff --git a/include/asterisk/_private.h b/include/asterisk/_private.h index fe9aa2c04..be4542d7a 100644 --- a/include/asterisk/_private.h +++ b/include/asterisk/_private.h @@ -56,4 +56,10 @@ int ast_timing_init(void); /*!< Provided by timing.c */ */ int ast_module_reload(const char *name); +/*! \brief Load XML documentation. Provided by pbx.c + * \retval 1 on error. + * \retval 0 on success. + */ +int ast_load_documentation(void); + #endif /* _ASTERISK__PRIVATE_H */ diff --git a/include/asterisk/autoconfig.h.in b/include/asterisk/autoconfig.h.in index 3417c738e..79134bd3c 100644 --- a/include/asterisk/autoconfig.h.in +++ b/include/asterisk/autoconfig.h.in @@ -410,6 +410,9 @@ /* Define to 1 if you have the header file. */ #undef HAVE_LIBINTL_H +/* Define if your system has the LIBXML2 libraries. */ +#undef HAVE_LIBXML2 + /* Define to 1 if you have the header file. */ #undef HAVE_LIMITS_H diff --git a/include/asterisk/compat.h b/include/asterisk/compat.h index e481fbec4..0b431f5e0 100644 --- a/include/asterisk/compat.h +++ b/include/asterisk/compat.h @@ -182,4 +182,15 @@ typedef unsigned int uint; typedef unsigned long long uint64_t; #endif +/* glob compat stuff */ +#if defined(__Darwin__) || defined(__CYGWIN__) +#define GLOB_ABORTED GLOB_ABEND +#endif +#include +#ifdef SOLARIS +#define MY_GLOB_FLAGS GLOB_NOCHECK +#else +#define MY_GLOB_FLAGS (GLOB_NOMAGIC|GLOB_BRACE) +#endif + #endif diff --git a/include/asterisk/extconf.h b/include/asterisk/extconf.h index 086271ce5..7527c579f 100644 --- a/include/asterisk/extconf.h +++ b/include/asterisk/extconf.h @@ -76,8 +76,14 @@ struct ast_config { /*! \brief A registered application */ struct ast_app { int (*execute)(struct ast_channel *chan, void *data); - const char *synopsis; /*!< Synopsis text for 'show applications' */ - const char *description; /*!< Description (help text) for 'show application <name>' */ + AST_DECLARE_STRING_FIELDS( + AST_STRING_FIELD(synopsis); /*!< Synopsis text for 'show applications' */ + AST_STRING_FIELD(description); /*!< Description (help text) for 'show application <name>' */ + AST_STRING_FIELD(syntax); /*!< Syntax text for 'core show applications' */ + AST_STRING_FIELD(arguments); /*!< Arguments description */ + AST_STRING_FIELD(seealso); /*!< See also */ + ); + enum ast_xmldoc_src docsrc; /*!< Where the documentation come from. */ AST_RWLIST_ENTRY(ast_app) list; /*!< Next app in list */ void *module; /*!< Module this app belongs to */ char name[0]; /*!< Name of the application */ diff --git a/include/asterisk/module.h b/include/asterisk/module.h index f466395c0..640c5af32 100644 --- a/include/asterisk/module.h +++ b/include/asterisk/module.h @@ -380,6 +380,23 @@ static void __restore_globals(void) */ #define ast_register_application(app, execute, synopsis, description) ast_register_application2(app, execute, synopsis, description, ast_module_info->self) +/*! + * \brief Register an application using XML documentation. + * + * \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. + * + * 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. + * + * \retval 0 success + * \retval -1 failure. + */ +#define ast_register_application_xml(app, execute) ast_register_application(app, execute, NULL, NULL) + + /*! * \brief Register an application. * diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h index d2d95acca..3348bb8d7 100644 --- a/include/asterisk/pbx.h +++ b/include/asterisk/pbx.h @@ -26,6 +26,7 @@ #include "asterisk/sched.h" #include "asterisk/chanvars.h" #include "asterisk/hashtab.h" +#include "asterisk/stringfields.h" #if defined(__cplusplus) || defined(c_plusplus) extern "C" { @@ -73,12 +74,23 @@ struct ast_sw; /*! \brief Typedef for devicestate and hint callbacks */ typedef int (*ast_state_cb_type)(char *context, char* id, enum ast_extension_states state, void *data); +/*! \brief From where the documentation come from */ +enum ast_doc_src { + AST_XML_DOC, /*!< From XML documentation */ + AST_STATIC_DOC /*!< From application/function registration */ +}; + /*! \brief Data structure associated with a custom dialplan function */ struct ast_custom_function { - const char *name; /*!< Name */ - const char *synopsis; /*!< Short description for "show functions" */ - const char *desc; /*!< Help text that explains it all */ - const char *syntax; /*!< Syntax description */ + const char *name; /*!< Name */ + AST_DECLARE_STRING_FIELDS( + AST_STRING_FIELD(synopsis); /*!< Synopsis text for 'show functions' */ + AST_STRING_FIELD(desc); /*!< Description (help text) for 'show functions <name>' */ + AST_STRING_FIELD(syntax); /*!< Syntax text for 'core show functions' */ + AST_STRING_FIELD(arguments); /*!< Arguments description */ + AST_STRING_FIELD(seealso); /*!< See also */ + ); + enum ast_doc_src docsrc; /*!< Where the documentation come from */ int (*read)(struct ast_channel *, const char *, char *, char *, size_t); /*!< Read function, if read is supported */ int (*write)(struct ast_channel *, const char *, char *, const char *); /*!< Write function, if write is supported */ struct ast_module *mod; /*!< Module this custom function belongs to */ diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h index 19315b02f..16a60c38a 100644 --- a/include/asterisk/strings.h +++ b/include/asterisk/strings.h @@ -387,6 +387,21 @@ void ast_str_reset(struct ast_str *buf), } ) +/*! \brief Trims trailing whitespace characters from an ast_str string. + * \param buf A pointer to the ast_str string. + */ +AST_INLINE_API( +void ast_str_trim_blanks(struct ast_str *buf), +{ + if (!buf) { + return; + } + while (buf->used && buf->str[buf->used - 1] < 33) { + buf->str[--(buf->used)] = '\0'; + } +} +) + /* * AST_INLINE_API() is a macro that takes a block of code as an argument. * Using preprocessor #directives in the argument is not supported by all diff --git a/include/asterisk/term.h b/include/asterisk/term.h index 3277f0042..8c6cab43e 100644 --- a/include/asterisk/term.h +++ b/include/asterisk/term.h @@ -64,6 +64,28 @@ extern "C" { char *term_color(char *outbuf, const char *inbuf, int fgcolor, int bgcolor, int maxout); +/*! + * \brief Append a color sequence to an ast_str + * + * \param str The string to append to + * \param fgcolor foreground color + * \param bgcolor background color + * + * \retval 0 success + * \retval -1 failure + */ +int ast_term_color_code(struct ast_str **str, int fgcolor, int bgcolor); + +/*! + * \brief Write a color sequence to a string + * + * \param outbuf the location to write to + * \param fgcolor foreground color + * \param bgcolor background color + * \param maxout maximum number of characters to write + * + * \return outbuf + */ char *term_color_code(char *outbuf, int fgcolor, int bgcolor, int maxout); char *term_strip(char *outbuf, char *inbuf, int maxout); diff --git a/include/asterisk/xml.h b/include/asterisk/xml.h new file mode 100644 index 000000000..8ed9ffdfd --- /dev/null +++ b/include/asterisk/xml.h @@ -0,0 +1,122 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2008, Eliel C. Sardanons (LU1ALY) + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +#ifndef _ASTERISK_XML_H +#define _ASTERISK_XML_H + +/*! \file + * \brief Asterisk XML abstraction layer + */ + +struct ast_xml_node; +struct ast_xml_doc; + +/*! \brief Initialize the XML library implementation. + * This function is used to setup everything needed + * to start working with the xml implementation. + * \retval 0 On success. + * \retval 1 On error. + */ +int ast_xml_init(void); + +/*! \brief Cleanup library allocated global data. + * \retval 0 On success. + * \retval 1 On error. + */ +int ast_xml_finish(void); + +/*! \brief Open an XML document. + * \param filename Document path. + * \retval NULL on error. + * \retval The ast_xml_doc reference to the open document. + */ +struct ast_xml_doc *ast_xml_open(char *filename); + +/*! \brief Close an already open document and free the used + * structure. + * \retval doc The document reference. + */ +void ast_xml_close(struct ast_xml_doc *doc); + +/*! \brief Get the document root node. + * \param doc Document reference + * \retval NULL on error + * \retval The root node on success. + */ +struct ast_xml_node *ast_xml_get_root(struct ast_xml_doc *doc); + +/*! \brief Free node + * \param node Node to be released. + */ +void ast_xml_free_node(struct ast_xml_node *node); + +/*! \brief Free an attribute returned by ast_xml_get_attribute() + * \param data pointer to be freed. + */ +void ast_xml_free_attr(const char *attribute); + +/*! \brief Free a content element that was returned by ast_xml_get_text() + * \param text text to be freed. + */ +void ast_xml_free_text(const char *text); + +/*! \brief Get a node attribute by name + * \param node Node where to search the attribute. + * \param attrname Attribute name. + * \retval NULL on error + * \retval The attribute value on success. + */ +const char *ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname); + +/*! \brief Find a node element by name. + * \param node This is the node starting point. + * \param name Node name to find. + * \param attrname attribute name to match (if NULL it won't be matched). + * \param attrvalue attribute value to match (if NULL it won't be matched). + * \retval NULL if not found + * \retval The node on success. + */ +struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue); + +/*! \brief Get an element content string. + * \param node Node from where to get the string. + * \retval NULL on error. + * \retval The text content of node. + */ +const char *ast_xml_get_text(struct ast_xml_node *node); + +/*! \brief Get the name of a node. */ +const char *ast_xml_node_get_name(struct ast_xml_node *node); + +/*! \brief Get the node's children. */ +struct ast_xml_node *ast_xml_node_get_children(struct ast_xml_node *node); + +/*! \brief Get the next node in the same level. */ +struct ast_xml_node *ast_xml_node_get_next(struct ast_xml_node *node); + +/*! \brief Get the previous node in the same leve. */ +struct ast_xml_node *ast_xml_node_get_prev(struct ast_xml_node *node); + +/*! \brief Get the parent of a specified node. */ +struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node); + +/* Features using ast_xml_ */ +#ifdef HAVE_LIBXML2 +#define AST_XML_DOCS +#endif + +#endif /* _ASTERISK_XML_H */ + -- cgit v1.2.3