[asterisk-commits] eliel: trunk r153747 - /trunk/apps/
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Sun Nov 2 19:01:26 CST 2008
Author: eliel
Date: Sun Nov 2 19:01:25 2008
New Revision: 153747
URL: http://svn.digium.com/view/asterisk?view=rev&rev=153747
Log:
Add XML documentation for:
- WaitForSilence()
- WaitForNoise()
- WaitForRing()
- IVRDemo()
- DBDel()
- DBDeltree()
(issue #13699)
Reported by: snuffy
Patches:
bug13699_20081016.diff uploaded by snuffy (license 35)
(With minor changes)
Modified:
trunk/apps/app_db.c
trunk/apps/app_ivrdemo.c
trunk/apps/app_waitforring.c
trunk/apps/app_waitforsilence.c
Modified: trunk/apps/app_db.c
URL: http://svn.digium.com/view/asterisk/trunk/apps/app_db.c?view=diff&rev=153747&r1=153746&r2=153747
==============================================================================
--- trunk/apps/app_db.c (original)
+++ trunk/apps/app_db.c Sun Nov 2 19:01:25 2008
@@ -39,22 +39,42 @@
#include "asterisk/astdb.h"
#include "asterisk/lock.h"
+/*** DOCUMENTATION
+ <application name="DBdel" language="en_US">
+ <synopsis>
+ Delete a key from the asterisk database.
+ </synopsis>
+ <syntax argsep="/">
+ <parameter name="family" required="true" />
+ <parameter name="key" required="true" />
+ </syntax>
+ <description>
+ <para>This application will delete a <replaceable>key</replaceable> from the Asterisk
+ database.</para>
+ <note><para>This application has been DEPRECATED in favor of the DB_DELETE function.</para></note>
+ </description>
+ <see-also>
+ <ref type="function">DB_DELETE</ref>
+ </see-also>
+ </application>
+ <application name="DBdeltree" language="en_US">
+ <synopsis>
+ Delete a family or keytree from the asterisk database.
+ </synopsis>
+ <syntax argsep="/">
+ <parameter name="family" required="true" />
+ <parameter name="keytree" />
+ </syntax>
+ <description>
+ <para>This application will delete a <replaceable>family</replaceable> or <replaceable>keytree</replaceable>
+ from the Asterisk database.</para>
+ </description>
+ </application>
+ ***/
+
/*! \todo XXX Remove this application after 1.4 is relased */
-static char *d_descrip =
-" DBdel(family/key): This application will delete a key from the Asterisk\n"
-"database.\n"
-" This application has been DEPRECATED in favor of the DB_DELETE function.\n";
-
-static char *dt_descrip =
-" DBdeltree(family[/keytree]): This application will delete a family or keytree\n"
-"from the Asterisk database\n";
-
static char *d_app = "DBdel";
static char *dt_app = "DBdeltree";
-
-static char *d_synopsis = "Delete a key from the database";
-static char *dt_synopsis = "Delete a family or keytree from the database";
-
static int deltree_exec(struct ast_channel *chan, void *data)
{
@@ -130,8 +150,8 @@
{
int retval;
- retval = ast_register_application(d_app, del_exec, d_synopsis, d_descrip);
- retval |= ast_register_application(dt_app, deltree_exec, dt_synopsis, dt_descrip);
+ retval = ast_register_application_xml(d_app, del_exec);
+ retval |= ast_register_application_xml(dt_app, deltree_exec);
return retval;
}
Modified: trunk/apps/app_ivrdemo.c
URL: http://svn.digium.com/view/asterisk/trunk/apps/app_ivrdemo.c?view=diff&rev=153747&r1=153746&r2=153747
==============================================================================
--- trunk/apps/app_ivrdemo.c (original)
+++ trunk/apps/app_ivrdemo.c Sun Nov 2 19:01:25 2008
@@ -40,11 +40,22 @@
#include "asterisk/lock.h"
#include "asterisk/app.h"
-static char *tdesc = "IVR Demo Application";
+/*** DOCUMENTATION
+ <application name="IVRDemo" language="en_US">
+ <synopsis>
+ IVR Demo Application.
+ </synopsis>
+ <syntax>
+ <parameter name="filename" required="true" />
+ </syntax>
+ <description>
+ <para>This is a skeleton application that shows you the basic structure to create your
+ own asterisk applications and demonstrates the IVR demo.</para>
+ </description>
+ </application>
+ ***/
+
static char *app = "IVRDemo";
-static char *synopsis =
-" This is a skeleton application that shows you the basic structure to create your\n"
-"own asterisk applications and demonstrates the IVR demo.\n";
static int ivr_demo_func(struct ast_channel *chan, void *data)
{
@@ -109,7 +120,7 @@
static int load_module(void)
{
- return ast_register_application(app, skel_exec, tdesc, synopsis);
+ return ast_register_application_xml(app, skel_exec);
}
AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "IVR Demo Application");
Modified: trunk/apps/app_waitforring.c
URL: http://svn.digium.com/view/asterisk/trunk/apps/app_waitforring.c?view=diff&rev=153747&r1=153746&r2=153747
==============================================================================
--- trunk/apps/app_waitforring.c (original)
+++ trunk/apps/app_waitforring.c Sun Nov 2 19:01:25 2008
@@ -35,15 +35,23 @@
#include "asterisk/module.h"
#include "asterisk/lock.h"
-static char *synopsis = "Wait for Ring Application";
-
-static char *desc = " WaitForRing(timeout):\n"
-"Returns 0 after waiting at least timeout seconds. and\n"
-"only after the next ring has completed. Returns 0 on\n"
-"success or -1 on hangup\n";
+/*** DOCUMENTATION
+ <application name="WaitForRing" language="en_US">
+ <synopsis>
+ Wait for Ring Application.
+ </synopsis>
+ <syntax>
+ <parameter name="timeout" required="true" />
+ </syntax>
+ <description>
+ <para>Returns <literal>0</literal> after waiting at least <replaceable>timeout</replaceable> seconds,
+ and only after the next ring has completed. Returns <literal>0</literal> on success or
+ <literal>-1</literal> on hangup.</para>
+ </description>
+ </application>
+ ***/
static char *app = "WaitForRing";
-
static int waitforring_exec(struct ast_channel *chan, void *data)
{
@@ -111,7 +119,7 @@
static int load_module(void)
{
- return ast_register_application(app, waitforring_exec, synopsis, desc);
+ return ast_register_application_xml(app, waitforring_exec);
}
AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Waits until first ring after time");
Modified: trunk/apps/app_waitforsilence.c
URL: http://svn.digium.com/view/asterisk/trunk/apps/app_waitforsilence.c?view=diff&rev=153747&r1=153746&r2=153747
==============================================================================
--- trunk/apps/app_waitforsilence.c (original)
+++ trunk/apps/app_waitforsilence.c Sun Nov 2 19:01:25 2008
@@ -48,37 +48,79 @@
#include "asterisk/dsp.h"
#include "asterisk/module.h"
+/*** DOCUMENTATION
+ <application name="WaitForSilence" language="en_US">
+ <synopsis>
+ Waits for a specified amount of silence.
+ </synopsis>
+ <syntax>
+ <parameter name="silencerequired" required="true" />
+ <parameter name="iterations">
+ <para>If not specified, defaults to <literal>1</literal>.</para>
+ </parameter>
+ <parameter name="timeout">
+ <para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para>
+ </parameter>
+ </syntax>
+ <description>
+ <para>Waits for up to <replaceable>silencerequired</replaceable> milliseconds of silence,
+ <replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable>
+ specified the number of seconds to return after, even if we do not receive the specified amount of silence.
+ Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which
+ is to wait indefinitely until silence is detected on the line. This is particularly useful for reverse-911-type
+ call broadcast applications where you need to wait for an answering machine to complete its spiel before
+ playing a message.</para>
+ <para>Typically you will want to include two or more calls to WaitForSilence when dealing with an answering
+ machine; first waiting for the spiel to finish, then waiting for the beep, etc.</para>
+ <para>Examples:</para>
+ <para>WaitForSilence(500,2) will wait for 1/2 second of silence, twice</para>
+ <para>WaitForSilence(1000) will wait for 1 second of silence, once</para>
+ <para>WaitForSilence(300,3,10) will wait for 300ms silence, 3 times, and returns after 10 sec, even if silence
+ is not detected</para>
+ <para>Sets the channel variable <variable>WAITSTATUS</variable> to one of these values:</para>
+ <variablelist>
+ <variable name="WAITSTATUS">
+ <value name="SILENCE">
+ if exited with silence detected.
+ </value>
+ <value name="TIMEOUT">
+ if exited without silence detected after timeout.
+ </value>
+ </variable>
+ </variablelist>
+ </description>
+ <see-also>
+ <ref type="application">WaitForNoise</ref>
+ </see-also>
+ </application>
+ <application name="WaitForNoise" language="en_US">
+ <synopsis>
+ Waits for a specified amount of noise.
+ </synopsis>
+ <syntax>
+ <parameter name="noiserequired" required="true" />
+ <parameter name="iterations">
+ <para>If not specified, defaults to <literal>1</literal>.</para>
+ </parameter>
+ <parameter name="timeout">
+ <para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para>
+ </parameter>
+ </syntax>
+ <description>
+ <para>Waits for up to <replaceable>noiserequired</replaceable> milliseconds of noise,
+ <replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable>
+ specified the number of seconds to return after, even if we do not receive the specified amount of noise.
+ Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which
+ is to wait indefinitely until noise is detected on the line.</para>
+ </description>
+ <see-also>
+ <ref type="application">WaitForSilence</ref>
+ </see-also>
+ </application>
+ ***/
+
static char *app_silence = "WaitForSilence";
-static char *synopsis_silence = "Waits for a specified amount of silence";
-static char *descrip_silence =
-" WaitForSilence(silencerequired[,iterations][,timeout]):\n"
-"Wait for Silence: Waits for up to 'silencerequired' \n"
-"milliseconds of silence, 'iterations' times or once if omitted.\n"
-"An optional timeout specified the number of seconds to return\n"
-"after, even if we do not receive the specified amount of silence.\n"
-"Use 'timeout' with caution, as it may defeat the purpose of this\n"
-"application, which is to wait indefinitely until silence is detected\n"
-"on the line. This is particularly useful for reverse-911-type\n"
-"call broadcast applications where you need to wait for an answering\n"
-"machine to complete its spiel before playing a message.\n"
-"The timeout parameter is specified only to avoid an infinite loop in\n"
-"cases where silence is never achieved. Typically you will want to\n"
-"include two or more calls to WaitForSilence when dealing with an answering\n"
-"machine; first waiting for the spiel to finish, then waiting for the beep, etc.\n\n"
- "Examples:\n"
-" - WaitForSilence(500,2) will wait for 1/2 second of silence, twice\n"
-" - WaitForSilence(1000) will wait for 1 second of silence, once\n"
-" - WaitForSilence(300,3,10) will wait for 300ms silence, 3 times,\n"
-" and returns after 10 sec, even if silence is not detected\n\n"
-"Sets the channel variable WAITSTATUS with to one of these values:\n"
-"SILENCE - if exited with silence detected\n"
-"TIMEOUT - if exited without silence detected after timeout\n";
-
static char *app_noise = "WaitForNoise";
-static char *synopsis_noise = "Waits for a specified amount of noise";
-static char *descrip_noise =
-"WaitForNoise(noiserequired[,iterations][,timeout]) \n"
-"Wait for Noise: The same as Wait for Silance but waits for noise that is above the threshold specified\n";
static int do_waiting(struct ast_channel *chan, int timereqd, time_t waitstart, int timeout, int wait_for_silence) {
struct ast_frame *f = NULL;
@@ -211,8 +253,8 @@
{
int res;
- res = ast_register_application(app_silence, waitforsilence_exec, synopsis_silence, descrip_silence);
- res |= ast_register_application(app_noise, waitfornoise_exec, synopsis_noise, descrip_noise);
+ res = ast_register_application_xml(app_silence, waitforsilence_exec);
+ res |= ast_register_application_xml(app_noise, waitfornoise_exec);
return res;
}
More information about the asterisk-commits
mailing list