Doxygen documentation update from oej (issue #5505)
[asterisk/asterisk.git] / apps / app_playback.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  *
21  * \brief Trivial application to playback a sound file
22  * 
23  */
24  
25 #include <string.h>
26 #include <stdlib.h>
27
28 #include "asterisk.h"
29
30 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
31
32 #include "asterisk/lock.h"
33 #include "asterisk/file.h"
34 #include "asterisk/logger.h"
35 #include "asterisk/channel.h"
36 #include "asterisk/pbx.h"
37 #include "asterisk/module.h"
38 #include "asterisk/translate.h"
39 #include "asterisk/utils.h"
40
41 static char *tdesc = "Sound File Playback Application";
42
43 static char *app = "Playback";
44
45 static char *synopsis = "Play a file";
46
47 static char *descrip = 
48 "  Playback(filename[&filename2...][|option]):  Plays back given filenames (do not put\n"
49 "extension). Options may also be  included following a pipe symbol. The 'skip'\n"
50 "option causes the playback of the message to  be  skipped  if  the  channel\n"
51 "is not in the 'up' state (i.e. it hasn't been  answered  yet. If 'skip' is \n"
52 "specified, the application will return immediately should the channel not be\n"
53 "off hook.  Otherwise, unless 'noanswer' is specified, the channel channel will\n"
54 "be answered before the sound is played. Not all channels support playing\n"
55 "messages while still hook. Returns -1 if the channel was hung up.  If the\n"
56 "file does not exist, will jump to priority n+101 if present.\n";
57
58 STANDARD_LOCAL_USER;
59
60 LOCAL_USER_DECL;
61
62 static int playback_exec(struct ast_channel *chan, void *data)
63 {
64         int res = 0;
65         struct localuser *u;
66         char *tmp = NULL;
67         char *options = NULL;
68         int option_skip=0;
69         int option_noanswer = 0;
70         char *stringp = NULL;
71         char *front = NULL, *back = NULL;
72         
73         if (!data || ast_strlen_zero(data)) {
74                 ast_log(LOG_WARNING, "Playback requires an argument (filename)\n");
75                 return -1;
76         }
77
78         LOCAL_USER_ADD(u);
79
80         tmp = ast_strdupa(data);
81         if (!tmp) {
82                 ast_log(LOG_ERROR, "Out of memory!\n");
83                 LOCAL_USER_REMOVE(u);
84                 return -1;      
85         }
86
87         stringp = tmp;
88         strsep(&stringp, "|");
89         options = strsep(&stringp, "|");
90         if (options && !strcasecmp(options, "skip"))
91                 option_skip = 1;
92         if (options && !strcasecmp(options, "noanswer"))
93                 option_noanswer = 1;
94         
95         if (chan->_state != AST_STATE_UP) {
96                 if (option_skip) {
97                         /* At the user's option, skip if the line is not up */
98                         LOCAL_USER_REMOVE(u);
99                         return 0;
100                 } else if (!option_noanswer)
101                         /* Otherwise answer unless we're supposed to send this while on-hook */
102                         res = ast_answer(chan);
103         }
104         if (!res) {
105                 ast_stopstream(chan);
106                 front = tmp;
107                 while (!res && front) {
108                         if ((back = strchr(front, '&'))) {
109                                 *back = '\0';
110                                 back++;
111                         }
112                         res = ast_streamfile(chan, front, chan->language);
113                         if (!res) { 
114                                 res = ast_waitstream(chan, ""); 
115                                 ast_stopstream(chan);
116                         } else {
117                                 ast_log(LOG_WARNING, "ast_streamfile failed on %s for %s\n", chan->name, (char *)data);
118                                 ast_goto_if_exists(chan, chan->context, chan->exten, chan->priority + 101);
119                                 res = 0;
120                         }
121                         front = back;
122                 }
123         }
124         LOCAL_USER_REMOVE(u);
125         return res;
126 }
127
128 int unload_module(void)
129 {
130         int res;
131
132         res = ast_unregister_application(app);
133
134         STANDARD_HANGUP_LOCALUSERS;
135
136         return res;     
137 }
138
139 int load_module(void)
140 {
141         return ast_register_application(app, playback_exec, synopsis, descrip);
142 }
143
144 char *description(void)
145 {
146         return tdesc;
147 }
148
149 int usecount(void)
150 {
151         int res;
152         STANDARD_USECOUNT(res);
153         return res;
154 }
155
156 char *key()
157 {
158         return ASTERISK_GPL_KEY;
159 }