Skip to content

Commit 5b168ee

Browse files
russellbrussellb
committed
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
1 parent 1fef0f6 commit 5b168ee

File tree

111 files changed

+8160
-2575
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

111 files changed

+8160
-2575
lines changed

‎Makefile

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,9 @@ endif
105105
ASTCFLAGS+=$(COPTS)
106106
ASTLDFLAGS+=$(LDOPTS)
107107

108+
# libxml2 cflags
109+
ASTCFLAGS+=$(LIBXML2_INCLUDE)
110+
108111
#Uncomment this to see all build commands instead of 'quiet' output
109112
#NOISY_BUILD=yes
110113

@@ -481,6 +484,20 @@ datafiles: _all
481484
mkdir -p $(DESTDIR)$(AGI_DIR)
482485
$(MAKE) -C sounds install
483486

487+
documentation:
488+
@echo -n "Building Documentation For: "
489+
@echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" > doc/core-en_US.xml
490+
@echo "<!DOCTYPE docs SYSTEM \"appdocsxml.dtd\">" >> doc/core-en_US.xml
491+
@echo "<docs>" >> doc/core-en_US.xml
492+
@for x in $(MOD_SUBDIRS); do \
493+
echo -n "$$x " ; \
494+
for i in $$x/*.c; do \
495+
$(AWK) -f build_tools/get_documentation $$i >> doc/core-en_US.xml ; \
496+
done ; \
497+
done
498+
@echo "</docs>" >> doc/core-en_US.xml
499+
@echo -e "\ndoc/core-en_US.xml --> $(ASTDATADIR)/documentation/core-en_US.xml"
500+
484501
update:
485502
@if [ -d .svn ]; then \
486503
echo "Updating from Subversion..." ; \
@@ -529,12 +546,16 @@ bininstall: _all installdirs $(SUBDIRS_INSTALL)
529546
if [ -n "$(OLDHEADERS)" ]; then \
530547
rm -f $(addprefix $(DESTDIR)$(ASTHEADERDIR)/,$(OLDHEADERS)) ;\
531548
fi
549+
mkdir -p $(DESTDIR)$(ASTDATADIR)/documentation
550+
mkdir -p $(DESTDIR)$(ASTDATADIR)/documentation/thirdparty
532551
mkdir -p $(DESTDIR)$(ASTLOGDIR)/cdr-csv
533552
mkdir -p $(DESTDIR)$(ASTLOGDIR)/cdr-custom
534553
mkdir -p $(DESTDIR)$(ASTDATADIR)/keys
535554
mkdir -p $(DESTDIR)$(ASTDATADIR)/firmware
536555
mkdir -p $(DESTDIR)$(ASTDATADIR)/firmware/iax
537556
mkdir -p $(DESTDIR)$(ASTMANDIR)/man8
557+
$(INSTALL) -m 644 doc/core-*.xml $(ASTDATADIR)/documentation
558+
$(INSTALL) -m 644 doc/appdocsxml.dtd $(ASTVARLIBDIR)/documentation
538559
$(INSTALL) -m 644 keys/iaxtel.pub $(DESTDIR)$(ASTDATADIR)/keys
539560
$(INSTALL) -m 644 keys/freeworlddialup.pub $(DESTDIR)$(ASTDATADIR)/keys
540561
$(INSTALL) -m 644 doc/asterisk.8 $(DESTDIR)$(ASTMANDIR)/man8
@@ -576,7 +597,7 @@ ifneq ($(findstring ~,$(DESTDIR)),)
576597
@exit 1
577598
endif
578599

579-
install: badshell datafiles bininstall
600+
install: badshell datafiles documentation bininstall
580601
@if [ -x /usr/sbin/asterisk-post-install ]; then \
581602
/usr/sbin/asterisk-post-install $(DESTDIR) . ; \
582603
fi
@@ -656,7 +677,7 @@ samples: adsi
656677
echo "astrundir => $(ASTVARRUNDIR)" ; \
657678
echo "astlogdir => $(ASTLOGDIR)" ; \
658679
echo "" ; \
659-
echo ";[options]" ; \
680+
echo "[options]" ; \
660681
echo ";verbose = 3" ; \
661682
echo ";debug = 3" ; \
662683
echo ";alwaysfork = yes ; same as -F at startup" ; \
@@ -686,6 +707,7 @@ samples: adsi
686707
echo ";runuser = asterisk ; The user to run as" ; \
687708
echo ";rungroup = asterisk ; The group to run as" ; \
688709
echo ";lightbackground = yes ; If your terminal is set for a light-colored background" ; \
710+
echo "documentation_language = en_US ; Set the Language you want Documentation displayed in. Value is in the same format as locale names" ; \
689711
echo "" ; \
690712
echo "; Changing the following lines may compromise your security." ; \
691713
echo ";[files]" ; \

‎apps/app_adsiprog.c

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,14 +47,24 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
4747

4848
static char *app = "ADSIProg";
4949

50-
static char *synopsis = "Load Asterisk ADSI Scripts into phone";
50+
/*** DOCUMENTATION
51+
<application name="ADSIProg" language="en_US">
52+
<synopsis>
53+
Load Asterisk ADSI Scripts into phone
54+
</synopsis>
55+
<syntax>
56+
<parameter name="script" required="false">
57+
<para>adsi script to use. If not given uses the default script <filename>asterisk.adsi</filename></para>
58+
</parameter>
59+
</syntax>
60+
<description>
61+
<para>This application programs an ADSI Phone with the given script</para>
62+
</description>
63+
</application>
64+
***/
5165

5266
/* #define DUMP_MESSAGES */
5367

54-
static char *descrip =
55-
" ADSIProg(script): This application programs an ADSI Phone with the given\n"
56-
"script. If nothing is specified, the default script (asterisk.adsi) is used.\n";
57-
5868
struct adsi_event {
5969
int id;
6070
char *name;
@@ -1570,7 +1580,7 @@ static int unload_module(void)
15701580

15711581
static int load_module(void)
15721582
{
1573-
if (ast_register_application(app, adsi_exec, synopsis, descrip))
1583+
if (ast_register_application_xml(app, adsi_exec))
15741584
return AST_MODULE_LOAD_FAILURE;
15751585
return AST_MODULE_LOAD_SUCCESS;
15761586
}

‎apps/app_alarmreceiver.c

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -63,18 +63,21 @@ struct event_node{
6363
typedef struct event_node event_node_t;
6464

6565
static char *app = "AlarmReceiver";
66-
67-
static char *synopsis = "Provide support for receiving alarm reports from a burglar or fire alarm panel";
68-
static char *descrip =
69-
" AlarmReceiver(): Only 1 signalling format is supported at this time: Ademco\n"
70-
"Contact ID. This application should be called whenever there is an alarm\n"
71-
"panel calling in to dump its events. The application will handshake with the\n"
72-
"alarm panel, and receive events, validate them, handshake them, and store them\n"
73-
"until the panel hangs up. Once the panel hangs up, the application will run the\n"
74-
"system command specified by the eventcmd setting in alarmreceiver.conf and pipe\n"
75-
"the events to the standard input of the application. The configuration file also\n"
76-
"contains settings for DTMF timing, and for the loudness of the acknowledgement\n"
77-
"tones.\n";
66+
/*** DOCUMENTATION
67+
<application name="AlarmReceiver" language="en_US">
68+
<synopsis>
69+
Provide support for receiving alarm reports from a burglar or fire alarm panel
70+
</synopsis>
71+
<syntax />
72+
<description>
73+
<para>This application should be called whenever there is an alarm panel calling in to dump its events.
74+
The application will handshake with the alarm panel, and receive events, validate them, handshake them, and store them until the panel hangs up.
75+
Once the panel hangs up, the application will run the system command specified by the eventcmd setting in <filename>alarmreceiver.conf</filename> and pipe the events to the standard input of the application.
76+
The configuration file also contains settings for DTMF timing, and for the loudness of the acknowledgement tones.</para>
77+
<note><para>Only 1 signalling format is supported at this time: Ademco Contact ID.</para></note>
78+
</description>
79+
</application>
80+
***/
7881

7982
/* Config Variables */
8083
static int fdtimeout = 2000;
@@ -711,7 +714,7 @@ static int unload_module(void)
711714
static int load_module(void)
712715
{
713716
if (load_config()) {
714-
if (ast_register_application(app, alarmreceiver_exec, synopsis, descrip))
717+
if (ast_register_application_xml(app, alarmreceiver_exec))
715718
return AST_MODULE_LOAD_FAILURE;
716719
return AST_MODULE_LOAD_SUCCESS;
717720
} else

‎apps/app_amd.c

Lines changed: 81 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -39,45 +39,88 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
3939
#include "asterisk/config.h"
4040
#include "asterisk/app.h"
4141

42+
/*** DOCUMENTATION
43+
<application name="AMD" language="en_US">
44+
<synopsis>
45+
Attempt to detect answering machines.
46+
</synopsis>
47+
<syntax>
48+
<parameter name="initialSilence" required="false">
49+
<para>Is maximum initial silence duration before greeting.</para>
50+
<para>If this is exceeded set as MACHINE</para>
51+
</parameter>
52+
<parameter name="greeting" required="false">
53+
<para>is the maximum length of a greeting.</para>
54+
<para>If this is exceeded set as MACHINE</para>
55+
</parameter>
56+
<parameter name="afterGreetingSilence" required="false">
57+
<para>Is the silence after detecting a greeting.</para>
58+
<para>If this is exceeded set as HUMAN</para>
59+
</parameter>
60+
<parameter name="totalAnalysis Time" required="false">
61+
<para>Is the maximum time allowed for the algorithm</para>
62+
<para>to decide HUMAN or MACHINE</para>
63+
</parameter>
64+
<parameter name="miniumWordLength" required="false">
65+
<para>Is the minimum duration of Voice considered to be a word</para>
66+
</parameter>
67+
<parameter name="betweenWordSilence" required="false">
68+
<para>Is the minimum duration of silence after a word to
69+
consider the audio that follows to be a new word</para>
70+
</parameter>
71+
<parameter name="maximumNumberOfWords" required="false">
72+
<para>Is the maximum number of words in a greeting</para>
73+
<para>If this is exceeded set as MACHINE</para>
74+
</parameter>
75+
<parameter name="silenceThreshold" required="false">
76+
<para>How long do we consider silence</para>
77+
</parameter>
78+
<parameter name="maximumWordLength" required="false">
79+
<para>Is the maximum duration of a word to accept.</para>
80+
<para>If exceeded set as MACHINE</para>
81+
</parameter>
82+
</syntax>
83+
<description>
84+
<para>This application attempts to detect answering machines at the beginning
85+
of outbound calls. Simply call this application after the call
86+
has been answered (outbound only, of course).</para>
87+
<para>When loaded, AMD reads amd.conf and uses the parameters specified as
88+
default values. Those default values get overwritten when the calling AMD
89+
with parameters.</para>
90+
<para>This application sets the following channel variables:</para>
91+
<variablelist>
92+
<variable name="AMDSTATUS">
93+
<para>This is the status of the answering machine detection</para>
94+
<value name="MACHINE" />
95+
<value name="HUMAN" />
96+
<value name="NOTSURE" />
97+
<value name="HANGUP" />
98+
</variable>
99+
<variable name="AMDCAUSE">
100+
<para>Indicates the cause that led to the conclusion</para>
101+
<value name="TOOLONG">
102+
Total Time.
103+
</value>
104+
<value name="INITIALSILENCE">
105+
Silence Duration - Initial Silence.
106+
</value>
107+
<value name="HUMAN">
108+
Silence Duration - afterGreetingSilence.
109+
</value>
110+
<value name="LONGGREETING">
111+
Voice Duration - Greeting.
112+
</value>
113+
<value name="MAXWORDLENGTH">
114+
Word Count - maximum number of words.
115+
</value>
116+
</variable>
117+
</variablelist>
118+
</description>
119+
</application>
120+
121+
***/
42122

43123
static char *app = "AMD";
44-
static char *synopsis = "Attempts to detect answering machines";
45-
static char *descrip =
46-
" AMD([initialSilence],[greeting],[afterGreetingSilence],[totalAnalysisTime]\n"
47-
" ,[minimumWordLength],[betweenWordsSilence],[maximumNumberOfWords]\n"
48-
" ,[silenceThreshold],[|maximumWordLength])\n"
49-
" This application attempts to detect answering machines at the beginning\n"
50-
" of outbound calls. Simply call this application after the call\n"
51-
" has been answered (outbound only, of course).\n"
52-
" When loaded, AMD reads amd.conf and uses the parameters specified as\n"
53-
" default values. Those default values get overwritten when calling AMD\n"
54-
" with parameters.\n"
55-
"- 'initialSilence' is the maximum silence duration before the greeting. If\n"
56-
" exceeded then MACHINE.\n"
57-
"- 'greeting' is the maximum length of a greeting. If exceeded then MACHINE.\n"
58-
"- 'afterGreetingSilence' is the silence after detecting a greeting.\n"
59-
" If exceeded then HUMAN.\n"
60-
"- 'totalAnalysisTime' is the maximum time allowed for the algorithm to decide\n"
61-
" on a HUMAN or MACHINE.\n"
62-
"- 'minimumWordLength'is the minimum duration of Voice to considered as a word.\n"
63-
"- 'betweenWordsSilence' is the minimum duration of silence after a word to \n"
64-
" consider the audio that follows as a new word.\n"
65-
"- 'maximumNumberOfWords'is the maximum number of words in the greeting. \n"
66-
" If exceeded then MACHINE.\n"
67-
"- 'silenceThreshold' is the silence threshold.\n"
68-
"- 'maximumWordLength' is the maximum duration of a word to accept. If exceeded then MACHINE\n"
69-
"This application sets the following channel variables upon completion:\n"
70-
" AMDSTATUS - This is the status of the answering machine detection.\n"
71-
" Possible values are:\n"
72-
" MACHINE | HUMAN | NOTSURE | HANGUP\n"
73-
" AMDCAUSE - Indicates the cause that led to the conclusion.\n"
74-
" Possible values are:\n"
75-
" TOOLONG-<%d total_time>\n"
76-
" INITIALSILENCE-<%d silenceDuration>-<%d initialSilence>\n"
77-
" HUMAN-<%d silenceDuration>-<%d afterGreetingSilence>\n"
78-
" MAXWORDS-<%d wordsCount>-<%d maximumNumberOfWords>\n"
79-
" LONGGREETING-<%d voiceDuration>-<%d greeting>\n"
80-
" MAXWORDLENGTH-<%d consecutiveVoiceDuration>\n";
81124

82125
#define STATE_IN_WORD 1
83126
#define STATE_IN_SILENCE 2
@@ -437,7 +480,7 @@ static int load_module(void)
437480
{
438481
if (load_config(0))
439482
return AST_MODULE_LOAD_DECLINE;
440-
if (ast_register_application(app, amd_exec, synopsis, descrip))
483+
if (ast_register_application_xml(app, amd_exec))
441484
return AST_MODULE_LOAD_FAILURE;
442485
return AST_MODULE_LOAD_SUCCESS;
443486
}

‎apps/app_authenticate.c

Lines changed: 47 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -54,31 +54,52 @@ AST_APP_OPTIONS(auth_app_options, {
5454

5555

5656
static char *app = "Authenticate";
57-
58-
static char *synopsis = "Authenticate a user";
59-
60-
static char *descrip =
61-
" Authenticate(password[,options[,maxdigits[,prompt]]]): This application asks the caller\n"
62-
"to enter a given password in order to continue dialplan execution. If the password\n"
63-
"begins with the '/' character, it is interpreted as a file which contains a list of\n"
64-
"valid passwords, listed 1 password per line in the file.\n"
65-
" When using a database key, the value associated with the key can be anything.\n"
66-
"Users have three attempts to authenticate before the channel is hung up.\n"
67-
" Options:\n"
68-
" a - Set the channels' account code to the password that is entered\n"
69-
" d - Interpret the given path as database key, not a literal file\n"
70-
" m - Interpret the given path as a file which contains a list of account\n"
71-
" codes and password hashes delimited with ':', listed one per line in\n"
72-
" the file. When one of the passwords is matched, the channel will have\n"
73-
" its account code set to the corresponding account code in the file.\n"
74-
" r - Remove the database key upon successful entry (valid with 'd' only)\n"
75-
" maxdigits - maximum acceptable number of digits. Stops reading after\n"
76-
" maxdigits have been entered (without requiring the user to\n"
77-
" press the '#' key).\n"
78-
" Defaults to 0 - no limit - wait for the user press the '#' key.\n"
79-
" prompt - Override the agent-pass prompt file.\n"
80-
;
81-
;
57+
/*** DOCUMENTATION
58+
<application name="Authenticate" language="en_US">
59+
<synopsis>
60+
Authenticate a user
61+
</synopsis>
62+
<syntax>
63+
<parameter name="password" required="true">
64+
<para>Password the user should know</para>
65+
</parameter>
66+
<parameter name="options" required="false">
67+
<optionlist>
68+
<option name="a">
69+
<para>Set the channels' account code to the password that is entered</para>
70+
</option>
71+
<option name="d">
72+
<para>Interpret the given path as database key, not a literal file</para>
73+
</option>
74+
<option name="m">
75+
<para>Interpret the given path as a file which contains a list of account
76+
codes and password hashes delimited with <literal>:</literal>, listed one per line in
77+
the file. When one of the passwords is matched, the channel will have
78+
its account code set to the corresponding account code in the file.</para>
79+
</option>
80+
<option name="r">
81+
<para>Remove the database key upon successful entry (valid with <literal>d</literal> only)</para>
82+
</option>
83+
</optionlist>
84+
</parameter>
85+
<parameter name="maxdigits" required="false">
86+
<para>maximum acceptable number of digits. Stops reading after
87+
maxdigits have been entered (without requiring the user to press the <literal>#</literal> key).
88+
Defaults to 0 - no limit - wait for the user press the <literal>#</literal> key.</para>
89+
</parameter>
90+
<parameter name="prompt" required="false">
91+
<para>Override the agent-pass prompt file.</para>
92+
</parameter>
93+
</syntax>
94+
<description>
95+
<para>This application asks the caller to enter a given password in order to continue dialplan execution.</para>
96+
<para>If the password begins with the <literal>/</literal> character,
97+
it is interpreted as a file which contains a list of valid passwords, listed 1 password per line in the file.</para>
98+
<para>When using a database key, the value associated with the key can be anything.</para>
99+
<para>Users have three attempts to authenticate before the channel is hung up.</para>
100+
</description>
101+
</application>
102+
***/
82103

83104
static int auth_exec(struct ast_channel *chan, void *data)
84105
{
@@ -225,7 +246,7 @@ static int unload_module(void)
225246

226247
static int load_module(void)
227248
{
228-
if (ast_register_application(app, auth_exec, synopsis, descrip))
249+
if (ast_register_application_xml(app, auth_exec))
229250
return AST_MODULE_LOAD_FAILURE;
230251
return AST_MODULE_LOAD_SUCCESS;
231252
}

0 commit comments

Comments
 (0)