Recorded merge of revisions 193544 via svnmerge from
[asterisk/asterisk.git] / funcs / func_channel.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2006, Digium, Inc.
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16
17 /*! \file
18  *
19  * \brief Channel info dialplan functions
20  *
21  * \author Kevin P. Fleming <kpfleming@digium.com>
22  * \author Ben Winslow
23  * 
24  * \ingroup functions
25  */
26
27 #include "asterisk.h"
28
29 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
30
31 #include <regex.h>
32
33 #include "asterisk/module.h"
34 #include "asterisk/channel.h"
35 #include "asterisk/pbx.h"
36 #include "asterisk/utils.h"
37 #include "asterisk/app.h"
38 #include "asterisk/indications.h"
39 #include "asterisk/stringfields.h"
40
41 /*** DOCUMENTATION
42         <function name="CHANNELS" language="en_US">
43                 <synopsis>
44                         Gets the list of channels, optionally filtering by a regular expression.
45                 </synopsis>
46                 <syntax>
47                         <parameter name="regular_expression" />
48                 </syntax>
49                 <description>
50                         <para>Gets the list of channels, optionally filtering by a <replaceable>regular_expression</replaceable>. If
51                         no argument is provided, all known channels are returned. The
52                         <replaceable>regular_expression</replaceable> must correspond to
53                         the POSIX.2 specification, as shown in <emphasis>regex(7)</emphasis>. The list returned
54                         will be space-delimited.</para>
55                 </description>
56         </function>
57         <function name="CHANNEL" language="en_US">
58                 <synopsis>
59                         Gets/sets various pieces of information about the channel.
60                 </synopsis>
61                 <syntax>
62                         <parameter name="item" required="true">
63                                 <para>Standard items (provided by all channel technologies) are:</para>
64                                 <enumlist>
65                                         <enum name="audioreadformat">
66                                                 <para>R/O format currently being read.</para>
67                                         </enum>
68                                         <enum name="audionativeformat">
69                                                 <para>R/O format used natively for audio.</para>
70                                         </enum>
71                                         <enum name="audiowriteformat">
72                                                 <para>R/O format currently being written.</para>
73                                         </enum>
74                                         <enum name="callgroup">
75                                                 <para>R/W call groups for call pickup.</para>
76                                         </enum>
77                                         <enum name="channeltype">
78                                                 <para>R/O technology used for channel.</para>
79                                         </enum>
80                                         <enum name="language">
81                                                 <para>R/W language for sounds played.</para>
82                                         </enum>
83                                         <enum name="musicclass">
84                                                 <para>R/W class (from musiconhold.conf) for hold music.</para>
85                                         </enum>
86                                         <enum name="name">
87                                                 <para>The name of the channel</para>
88                                         </enum>
89                                         <enum name="parkinglot">
90                                                 <para>R/W parkinglot for parking.</para>
91                                         </enum>
92                                         <enum name="rxgain">
93                                                 <para>R/W set rxgain level on channel drivers that support it.</para>
94                                         </enum>
95                                         <enum name="state">
96                                                 <para>R/O state for channel</para>
97                                         </enum>
98                                         <enum name="tonezone">
99                                                 <para>R/W zone for indications played</para>
100                                         </enum>
101                                         <enum name="transfercapability">
102                                                 <para>R/W ISDN Transfer Capability, one of:</para>
103                                                 <enumlist>
104                                                         <enum name="SPEECH" />
105                                                         <enum name="DIGITAL" />
106                                                         <enum name="RESTRICTED_DIGITAL" />
107                                                         <enum name="3K1AUDIO" />
108                                                         <enum name="DIGITAL_W_TONES" />
109                                                         <enum name="VIDEO" />
110                                                 </enumlist>
111                                         </enum>
112                                         <enum name="txgain">
113                                                 <para>R/W set txgain level on channel drivers that support it.</para>
114                                         </enum>
115                                         <enum name="videonativeformat">
116                                                 <para>R/O format used natively for video</para>
117                                         </enum>
118                                         <enum name="trace">
119                                                 <para>R/W whether or not context tracing is enabled, only available
120                                                 <emphasis>if CHANNEL_TRACE is defined</emphasis>.</para>
121                                         </enum>
122                                 </enumlist>
123                                 <para><emphasis>chan_sip</emphasis> provides the following additional options:</para>
124                                 <enumlist>
125                                         <enum name="peerip">
126                                                 <para>R/O Get the IP address of the peer.</para>
127                                         </enum>
128                                         <enum name="recvip">
129                                                 <para>R/O Get the source IP address of the peer.</para>
130                                         </enum>
131                                         <enum name="from">
132                                                 <para>R/O Get the URI from the From: header.</para>
133                                         </enum>
134                                         <enum name="uri">
135                                                 <para>R/O Get the URI from the Contact: header.</para>
136                                         </enum>
137                                         <enum name="useragent">
138                                                 <para>R/O Get the useragent.</para>
139                                         </enum>
140                                         <enum name="peername">
141                                                 <para>R/O Get the name of the peer.</para>
142                                         </enum>
143                                         <enum name="t38passthrough">
144                                                 <para>R/O <literal>1</literal> if T38 is offered or enabled in this channel,
145                                                 otherwise <literal>0</literal></para>
146                                         </enum>
147                                         <enum name="rtpqos">
148                                                 <para>R/O Get QOS information about the RTP stream</para>
149                                                 <para>    This option takes two additional arguments:</para>
150                                                 <para>    Argument 1:</para>
151                                                 <para>     <literal>audio</literal>             Get data about the audio stream</para>
152                                                 <para>     <literal>video</literal>             Get data about the video stream</para>
153                                                 <para>     <literal>text</literal>              Get data about the text stream</para>
154                                                 <para>    Argument 2:</para>
155                                                 <para>     <literal>local_ssrc</literal>        Local SSRC (stream ID)</para>
156                                                 <para>     <literal>local_lostpackets</literal> Local lost packets</para>
157                                                 <para>     <literal>local_jitter</literal>      Local calculated jitter</para>
158                                                 <para>     <literal>local_maxjitter</literal>   Local calculated jitter (maximum)</para>
159                                                 <para>     <literal>local_minjitter</literal>   Local calculated jitter (minimum)</para>
160                                                 <para>     <literal>local_normdevjitter</literal>Local calculated jitter (normal deviation)</para>
161                                                 <para>     <literal>local_stdevjitter</literal> Local calculated jitter (standard deviation)</para>
162                                                 <para>     <literal>local_count</literal>       Number of received packets</para>
163                                                 <para>     <literal>remote_ssrc</literal>       Remote SSRC (stream ID)</para>
164                                                 <para>     <literal>remote_lostpackets</literal>Remote lost packets</para>
165                                                 <para>     <literal>remote_jitter</literal>     Remote reported jitter</para>
166                                                 <para>     <literal>remote_maxjitter</literal>  Remote calculated jitter (maximum)</para>
167                                                 <para>     <literal>remote_minjitter</literal>  Remote calculated jitter (minimum)</para>
168                                                 <para>     <literal>remote_normdevjitter</literal>Remote calculated jitter (normal deviation)</para>
169                                                 <para>     <literal>remote_stdevjitter</literal>Remote calculated jitter (standard deviation)</para>
170                                                 <para>     <literal>remote_count</literal>      Number of transmitted packets</para>
171                                                 <para>     <literal>remote_ssrc</literal>       Remote SSRC (stream ID)</para>
172                                                 <para>     <literal>remote_lostpackets</literal>Remote lost packets</para>
173                                                 <para>     <literal>remote_jitter</literal>     Remote reported jitter</para>
174                                                 <para>     <literal>remote_maxjitter</literal>  Remote calculated jitter (maximum)</para>
175                                                 <para>     <literal>remote_minjitter</literal>  Remote calculated jitter (minimum)</para>
176                                                 <para>     <literal>remote_normdevjitter</literal>Remote calculated jitter (normal deviation)</para>
177                                                 <para>     <literal>remote_stdevjitter</literal>Remote calculated jitter (standard deviation)</para>
178                                                 <para>     <literal>remote_count</literal>      Number of transmitted packets</para>
179                                                 <para>     <literal>rtt</literal>               Round trip time</para>
180                                                 <para>     <literal>maxrtt</literal>            Round trip time (maximum)</para>
181                                                 <para>     <literal>minrtt</literal>            Round trip time (minimum)</para>
182                                                 <para>     <literal>normdevrtt</literal>        Round trip time (normal deviation)</para>
183                                                 <para>     <literal>stdevrtt</literal>          Round trip time (standard deviation)</para>
184                                                 <para>     <literal>all</literal>               All statistics (in a form suited to logging,
185                                                 but not for parsing)</para>
186                                         </enum>
187                                         <enum name="rtpdest">
188                                                 <para>R/O Get remote RTP destination information.</para>
189                                                 <para>   This option takes one additional argument:</para>
190                                                 <para>    Argument 1:</para>
191                                                 <para>     <literal>audio</literal>             Get audio destination</para>
192                                                 <para>     <literal>video</literal>             Get video destination</para>
193                                         </enum>
194                                 </enumlist>
195                                 <para><emphasis>chan_iax2</emphasis> provides the following additional options:</para>
196                                 <enumlist>
197                                         <enum name="osptoken">
198                                                 <para>R/W Get or set the OSP token information for a call.</para>
199                                         </enum>
200                                         <enum name="peerip">
201                                                 <para>R/O Get the peer's ip address.</para>
202                                         </enum>
203                                         <enum name="peername">
204                                                 <para>R/O Get the peer's username.</para>
205                                         </enum>
206                                 </enumlist>
207                         </parameter>
208                 </syntax>
209                 <description>
210                         <para>Gets/sets various pieces of information about the channel, additional <replaceable>item</replaceable> may
211                         be available from the channel driver; see its documentation for details. Any <replaceable>item</replaceable>
212                         requested that is not available on the current channel will return an empty string.</para>
213                 </description>
214         </function>
215  ***/
216
217 #define locked_copy_string(chan, dest, source, len) \
218         do { \
219                 ast_channel_lock(chan); \
220                 ast_copy_string(dest, source, len); \
221                 ast_channel_unlock(chan); \
222         } while (0)
223 #define locked_string_field_set(chan, field, source) \
224         do { \
225                 ast_channel_lock(chan); \
226                 ast_string_field_set(chan, field, source); \
227                 ast_channel_unlock(chan); \
228         } while (0)
229
230 char *transfercapability_table[0x20] = {
231         "SPEECH", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
232         "DIGITAL", "RESTRICTED_DIGITAL", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
233         "3K1AUDIO", "DIGITAL_W_TONES", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
234         "VIDEO", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", };
235
236 static int func_channel_read(struct ast_channel *chan, const char *function,
237                              char *data, char *buf, size_t len)
238 {
239         int ret = 0;
240
241         if (!strcasecmp(data, "audionativeformat"))
242                 /* use the _multiple version when chan->nativeformats holds multiple formats */
243                 /* ast_getformatname_multiple(buf, len, chan->nativeformats & AST_FORMAT_AUDIO_MASK); */
244                 ast_copy_string(buf, ast_getformatname(chan->nativeformats & AST_FORMAT_AUDIO_MASK), len);
245         else if (!strcasecmp(data, "videonativeformat"))
246                 /* use the _multiple version when chan->nativeformats holds multiple formats */
247                 /* ast_getformatname_multiple(buf, len, chan->nativeformats & AST_FORMAT_VIDEO_MASK); */
248                 ast_copy_string(buf, ast_getformatname(chan->nativeformats & AST_FORMAT_VIDEO_MASK), len);
249         else if (!strcasecmp(data, "audioreadformat"))
250                 ast_copy_string(buf, ast_getformatname(chan->readformat), len);
251         else if (!strcasecmp(data, "audiowriteformat"))
252                 ast_copy_string(buf, ast_getformatname(chan->writeformat), len);
253 #ifdef CHANNEL_TRACE
254         else if (!strcasecmp(data, "trace")) {
255                 ast_channel_lock(chan);
256                 ast_copy_string(buf, ast_channel_trace_is_enabled(chan) ? "1" : "0", len);
257                 ast_channel_unlock(chan);
258         }
259 #endif
260         else if (!strcasecmp(data, "tonezone") && chan->zone)
261                 locked_copy_string(chan, buf, chan->zone->country, len);
262         else if (!strcasecmp(data, "language"))
263                 locked_copy_string(chan, buf, chan->language, len);
264         else if (!strcasecmp(data, "musicclass"))
265                 locked_copy_string(chan, buf, chan->musicclass, len);
266         else if (!strcasecmp(data, "name")) {
267                 locked_copy_string(chan, buf, chan->name, len);
268         } else if (!strcasecmp(data, "parkinglot"))
269                 locked_copy_string(chan, buf, chan->parkinglot, len);
270         else if (!strcasecmp(data, "state"))
271                 locked_copy_string(chan, buf, ast_state2str(chan->_state), len);
272         else if (!strcasecmp(data, "channeltype"))
273                 locked_copy_string(chan, buf, chan->tech->type, len);
274         else if (!strcasecmp(data, "transfercapability"))
275                 locked_copy_string(chan, buf, transfercapability_table[chan->transfercapability & 0x1f], len);
276         else if (!strcasecmp(data, "callgroup")) {
277                 char groupbuf[256];
278                 locked_copy_string(chan, buf,  ast_print_group(groupbuf, sizeof(groupbuf), chan->callgroup), len);
279         } else if (!chan->tech->func_channel_read
280                  || chan->tech->func_channel_read(chan, function, data, buf, len)) {
281                 ast_log(LOG_WARNING, "Unknown or unavailable item requested: '%s'\n", data);
282                 ret = -1;
283         }
284
285         return ret;
286 }
287
288 static int func_channel_write(struct ast_channel *chan, const char *function,
289                               char *data, const char *value)
290 {
291         int ret = 0;
292         signed char gainset;
293
294         if (!strcasecmp(data, "language"))
295                 locked_string_field_set(chan, language, value);
296         else if (!strcasecmp(data, "parkinglot"))
297                 locked_string_field_set(chan, parkinglot, value);
298         else if (!strcasecmp(data, "musicclass"))
299                 locked_string_field_set(chan, musicclass, value);
300 #ifdef CHANNEL_TRACE
301         else if (!strcasecmp(data, "trace")) {
302                 ast_channel_lock(chan);
303                 if (ast_true(value)) 
304                         ret = ast_channel_trace_enable(chan);
305                 else if (ast_false(value)) 
306                         ret = ast_channel_trace_disable(chan);
307                 else {
308                         ret = -1;
309                         ast_log(LOG_WARNING, "Invalid value for CHANNEL(trace).");
310                 }
311                 ast_channel_unlock(chan);
312         }
313 #endif
314         else if (!strcasecmp(data, "tonezone")) {
315                 struct ast_tone_zone *new_zone;
316                 if (!(new_zone = ast_get_indication_zone(value))) {
317                         ast_log(LOG_ERROR, "Unknown country code '%s' for tonezone. Check indications.conf for available country codes.\n", value);
318                         ret = -1;       
319                 } else {
320                         ast_channel_lock(chan);
321                         if (chan->zone) {
322                                 chan->zone = ast_tone_zone_unref(chan->zone);
323                         }
324                         chan->zone = ast_tone_zone_ref(new_zone);
325                         ast_channel_unlock(chan);
326                         new_zone = ast_tone_zone_unref(new_zone);
327                 }
328         } else if (!strcasecmp(data, "callgroup"))
329                 chan->callgroup = ast_get_group(value);
330         else if (!strcasecmp(data, "txgain")) {
331                 sscanf(value, "%hhd", &gainset);
332                 ast_channel_setoption(chan, AST_OPTION_TXGAIN, &gainset, sizeof(gainset), 0);
333         } else if (!strcasecmp(data, "rxgain")) {
334                 sscanf(value, "%hhd", &gainset);
335                 ast_channel_setoption(chan, AST_OPTION_RXGAIN, &gainset, sizeof(gainset), 0);
336         } else if (!strcasecmp(data, "transfercapability")) {
337                 unsigned short i;
338                 for (i = 0; i < 0x20; i++) {
339                         if (!strcasecmp(transfercapability_table[i], value) && strcmp(value, "UNK")) {
340                                 chan->transfercapability = i;
341                                 break;
342                         }
343                 }
344         } else if (!chan->tech->func_channel_write
345                  || chan->tech->func_channel_write(chan, function, data, value)) {
346                 ast_log(LOG_WARNING, "Unknown or unavailable item requested: '%s'\n",
347                                 data);
348                 ret = -1;
349         }
350
351         return ret;
352 }
353
354 static struct ast_custom_function channel_function = {
355         .name = "CHANNEL",
356         .read = func_channel_read,
357         .write = func_channel_write,
358 };
359
360 static int func_channels_read(struct ast_channel *chan, const char *function, char *data, char *buf, size_t maxlen)
361 {
362         struct ast_channel *c = NULL;
363         regex_t re;
364         int res;
365         size_t buflen = 0;
366         struct ast_channel_iterator *iter;
367
368         buf[0] = '\0';
369
370         if (!ast_strlen_zero(data)) {
371                 if ((res = regcomp(&re, data, REG_EXTENDED | REG_ICASE | REG_NOSUB))) {
372                         regerror(res, &re, buf, maxlen);
373                         ast_log(LOG_WARNING, "Error compiling regular expression for %s(%s): %s\n", function, data, buf);
374                         return -1;
375                 }
376         }
377
378         if (!(iter = ast_channel_iterator_all_new(0))) {
379                 if (!ast_strlen_zero(data)) {
380                         regfree(&re);
381                 }
382                 return -1;
383         }
384
385         while ((c = ast_channel_iterator_next(iter))) {
386                 ast_channel_lock(c);
387                 if (ast_strlen_zero(data) || regexec(&re, c->name, 0, NULL, 0) == 0) {
388                         size_t namelen = strlen(c->name);
389                         if (buflen + namelen + (ast_strlen_zero(buf) ? 0 : 1) + 1 < maxlen) {
390                                 if (!ast_strlen_zero(buf)) {
391                                         strcat(buf, " ");
392                                         buflen++;
393                                 }
394                                 strcat(buf, c->name);
395                                 buflen += namelen;
396                         } else {
397                                 ast_log(LOG_WARNING, "Number of channels exceeds the available buffer space.  Output will be truncated!\n");
398                         }
399                 }
400                 ast_channel_unlock(c);
401                 c = ast_channel_unref(c);
402         }
403
404         ast_channel_iterator_destroy(iter);
405
406         if (!ast_strlen_zero(data)) {
407                 regfree(&re);
408         }
409
410         return 0;
411 }
412
413 static struct ast_custom_function channels_function = {
414         .name = "CHANNELS",
415         .read = func_channels_read,
416 };
417
418 static int unload_module(void)
419 {
420         int res = 0;
421         
422         res |= ast_custom_function_unregister(&channel_function);
423         res |= ast_custom_function_unregister(&channels_function);
424         
425         return res;
426 }
427
428 static int load_module(void)
429 {
430         int res = 0;
431         
432         res |= ast_custom_function_register(&channel_function);
433         res |= ast_custom_function_register(&channels_function);
434         
435         return res;
436 }
437
438 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Channel information dialplan functions");