kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-10-12 15:45:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge changes from team/group/appdocsxml

Browse Source 
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
This commit is contained in:
Russell Bryant
2008-11-01 21:10:07 +00:00
parent 1fef0f63bb
commit 5b168ee34b
111 changed files with 8063 additions and 2478 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
include/asterisk/_private.h
View File

@@ -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 */

3
include/asterisk/autoconfig.h.in
View File

@@ -410,6 +410,9 @@
/* Define to 1 if you have the <libintl.h> header file. */
#undef HAVE_LIBINTL_H
/* Define if your system has the LIBXML2 libraries. */
#undef HAVE_LIBXML2
/* Define to 1 if you have the <limits.h> header file. */
#undef HAVE_LIMITS_H

11
include/asterisk/compat.h
View File

@@ -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 <glob.h>
#ifdef SOLARIS
#define MY_GLOB_FLAGS GLOB_NOCHECK
#else
#define MY_GLOB_FLAGS (GLOB_NOMAGIC|GLOB_BRACE)
#endif
#endif

10
include/asterisk/extconf.h
View File

@@ -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 &lt;name&gt;' */
AST_DECLARE_STRING_FIELDS(
AST_STRING_FIELD(synopsis); /*!< Synopsis text for 'show applications' */
AST_STRING_FIELD(description); /*!< Description (help text) for 'show application &lt;name&gt;' */
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 */

17
include/asterisk/module.h
View File

@@ -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.
*

20
include/asterisk/pbx.h
View File

@@ -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 &lt;name&gt;' */
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 */

15
include/asterisk/strings.h
View File

@@ -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

22
include/asterisk/term.h
View File

@@ -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);

122
include/asterisk/xml.h Normal file
View File

@@ -0,0 +1,122 @@
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 2008, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
*
* 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 */