Asterisk data retrieval API.
[asterisk/asterisk.git] / apps / app_playback.c
index b905a93..45fcfb5 100644 (file)
@@ -39,26 +39,49 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #include "asterisk/say.h"      /* provides config-file based 'say' functions */
 #include "asterisk/cli.h"
 
-static char *app = "Playback";
-
-static char *synopsis = "Play a file";
-
-static char *descrip = 
-"  Playback(filename[&filename2...][,option]):  Plays back given filenames (do not put\n"
-"extension). Options may also be included following a comma.\n"
-"The 'skip' option causes the playback of the message to be skipped if the channel\n"
-"is not in the 'up' state (i.e. it hasn't been  answered  yet). If 'skip' is \n"
-"specified, the application will return immediately should the channel not be\n"
-"off hook.  Otherwise, unless 'noanswer' is specified, the channel will\n"
-"be answered before the sound is played. Not all channels support playing\n"
-"messages while still on hook.\n"
-"This application sets the following channel variable upon completion:\n"
-" PLAYBACKSTATUS    The status of the playback attempt as a text string, one of\n"
-"               SUCCESS | FAILED\n"
-"See Also: Background (application) -- for playing soundfiles that are interruptible\n"
-"          WaitExten (application) -- wait for digits from caller, optionally play music on hold\n"
-;
+/*** DOCUMENTATION
+       <application name="Playback" language="en_US">
+               <synopsis>
+                       Play a file.
+               </synopsis>
+               <syntax>
+                       <parameter name="filenames" required="true" argsep="&amp;">
+                               <argument name="filename" required="true" />
+                               <argument name="filename2" multiple="true" />
+                       </parameter>
+                       <parameter name="options">
+                               <para>Comma separated list of options</para>
+                               <optionlist>
+                                       <option name="skip">
+                                               <para>Do not play if not answered</para>
+                                       </option>
+                                       <option name="noanswer">
+                                               <para>Playback without answering, otherwise the channel will
+                                               be answered before the sound is played.</para>
+                                               <note><para>Not all channel types support playing messages while still on hook.</para></note>
+                                       </option>
+                               </optionlist>
+                       </parameter>
+               </syntax>
+               <description>
+                       <para>Plays back given filenames (do not put extension of wav/alaw etc).
+                       The playback command answer the channel if no options are specified.
+                       If the file is non-existant it will fail</para>
+                       <para>This application sets the following channel variable upon completion:</para>
+                       <variablelist>
+                               <variable name="PLAYBACKSTATUS">
+                                       <para>The status of the playback attempt as a text string.</para>
+                                       <value name="SUCCESS"/>
+                                       <value name="FAILED"/>
+                               </variable>
+                       </variablelist>
+                       <para>See Also: Background (application) -- for playing sound files that are interruptible</para>
+                       <para>WaitExten (application) -- wait for digits from caller, optionally play music on hold</para>
+               </description>
+       </application>
+ ***/
 
+static char *app = "Playback";
 
 static struct ast_config *say_cfg = NULL;
 /* save the say' api calls.
@@ -67,8 +90,8 @@ static struct ast_config *say_cfg = NULL;
  * 'say load [new|old]' will enable the new or old method, or report status
  */
 static const void *say_api_buf[40];
-static const char *say_old = "old";
-static const char *say_new = "new";
+static const char * const say_old = "old";
+static const char * const say_new = "new";
 
 static void save_say_mode(const void *arg)
 {
@@ -200,13 +223,13 @@ static int do_say(say_args_t *a, const char *s, const char *options, int depth)
                ast_debug(2, "doing [%s]\n", fn);
 
                /* locate prefix and data, if any */
-               fmt = index(fn, ':');
+               fmt = strchr(fn, ':');
                if (!fmt || fmt == fn)  {       /* regular filename */
                        ret = s_streamwait3(a, fn);
                        continue;
                }
                fmt++;
-               data = index(fmt, ':'); /* colon before data */
+               data = strchr(fmt, ':');        /* colon before data */
                if (!data || data == fmt) {     /* simple prefix-fmt */
                        ret = do_say(a, fn, options, depth);
                        continue;
@@ -219,14 +242,14 @@ static int do_say(say_args_t *a, const char *s, const char *options, int depth)
                        if (*p == '\'') {/* file name - we trim them */
                                char *y;
                                strcpy(fn2, ast_skip_blanks(p+1));      /* make a full copy */
-                               y = index(fn2, '\'');
+                               y = strchr(fn2, '\'');
                                if (!y) {
                                        p = data;       /* invalid. prepare to end */
                                        break;
                                }
                                *y = '\0';
                                ast_trim_blanks(fn2);
-                               p = index(p+1, '\'');
+                               p = strchr(p+1, '\'');
                                ret = s_streamwait3(a, fn2);
                        } else {
                                int l = fmt-fn;
@@ -357,7 +380,7 @@ static int say_init_mode(const char *mode) {
 static char *__say_cli_init(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 {
        const char *old_mode = say_api_buf[0] ? say_new : say_old;
-       char *mode;
+       const char *mode;
        switch (cmd) {
        case CLI_INIT:
                e->command = "say load [new|old]";
@@ -392,7 +415,7 @@ static struct ast_cli_entry cli_playback[] = {
        AST_CLI_DEFINE(__say_cli_init, "Set or show the say mode"),
 };
 
-static int playback_exec(struct ast_channel *chan, void *data)
+static int playback_exec(struct ast_channel *chan, const char *data)
 {
        int res = 0;
        int mres = 0;
@@ -426,9 +449,10 @@ static int playback_exec(struct ast_channel *chan, void *data)
                if (option_skip) {
                        /* At the user's option, skip if the line is not up */
                        goto done;
-               } else if (!option_noanswer)
+               } else if (!option_noanswer) {
                        /* Otherwise answer unless we're supposed to send this while on-hook */
                        res = ast_answer(chan);
+               }
        }
        if (!res) {
                char *back = args.filenames;
@@ -496,7 +520,7 @@ static int unload_module(void)
 
        res = ast_unregister_application(app);
 
-       ast_cli_unregister_multiple(cli_playback, sizeof(cli_playback) / sizeof(struct ast_cli_entry));
+       ast_cli_unregister_multiple(cli_playback, ARRAY_LEN(cli_playback));
 
        if (say_cfg)
                ast_config_destroy(say_cfg);
@@ -519,8 +543,8 @@ static int load_module(void)
                }
        }
 
-       ast_cli_register_multiple(cli_playback, sizeof(cli_playback) / sizeof(struct ast_cli_entry));
-       return ast_register_application(app, playback_exec, synopsis, descrip);
+       ast_cli_register_multiple(cli_playback, ARRAY_LEN(cli_playback));
+       return ast_register_application_xml(app, playback_exec);
 }
 
 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_DEFAULT, "Sound File Playback Application",