AST-2009-005
[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 #include <ctype.h>
33
34 #include "asterisk/module.h"
35 #include "asterisk/channel.h"
36 #include "asterisk/pbx.h"
37 #include "asterisk/utils.h"
38 #include "asterisk/app.h"
39 #include "asterisk/indications.h"
40 #include "asterisk/stringfields.h"
41
42 /*** DOCUMENTATION
43         <function name="CHANNELS" language="en_US">
44                 <synopsis>
45                         Gets the list of channels, optionally filtering by a regular expression.
46                 </synopsis>
47                 <syntax>
48                         <parameter name="regular_expression" />
49                 </syntax>
50                 <description>
51                         <para>Gets the list of channels, optionally filtering by a <replaceable>regular_expression</replaceable>. If
52                         no argument is provided, all known channels are returned. The
53                         <replaceable>regular_expression</replaceable> must correspond to
54                         the POSIX.2 specification, as shown in <emphasis>regex(7)</emphasis>. The list returned
55                         will be space-delimited.</para>
56                 </description>
57         </function>
58         <function name="CHANNEL" language="en_US">
59                 <synopsis>
60                         Gets/sets various pieces of information about the channel.
61                 </synopsis>
62                 <syntax>
63                         <parameter name="item" required="true">
64                                 <para>Standard items (provided by all channel technologies) are:</para>
65                                 <enumlist>
66                                         <enum name="audioreadformat">
67                                                 <para>R/O format currently being read.</para>
68                                         </enum>
69                                         <enum name="audionativeformat">
70                                                 <para>R/O format used natively for audio.</para>
71                                         </enum>
72                                         <enum name="audiowriteformat">
73                                                 <para>R/O format currently being written.</para>
74                                         </enum>
75                                         <enum name="callgroup">
76                                                 <para>R/W call groups for call pickup.</para>
77                                         </enum>
78                                         <enum name="channeltype">
79                                                 <para>R/O technology used for channel.</para>
80                                         </enum>
81                                         <enum name="language">
82                                                 <para>R/W language for sounds played.</para>
83                                         </enum>
84                                         <enum name="musicclass">
85                                                 <para>R/W class (from musiconhold.conf) for hold music.</para>
86                                         </enum>
87                                         <enum name="name">
88                                                 <para>The name of the channel</para>
89                                         </enum>
90                                         <enum name="parkinglot">
91                                                 <para>R/W parkinglot for parking.</para>
92                                         </enum>
93                                         <enum name="rxgain">
94                                                 <para>R/W set rxgain level on channel drivers that support it.</para>
95                                         </enum>
96                                         <enum name="state">
97                                                 <para>R/O state for channel</para>
98                                         </enum>
99                                         <enum name="tonezone">
100                                                 <para>R/W zone for indications played</para>
101                                         </enum>
102                                         <enum name="transfercapability">
103                                                 <para>R/W ISDN Transfer Capability, one of:</para>
104                                                 <enumlist>
105                                                         <enum name="SPEECH" />
106                                                         <enum name="DIGITAL" />
107                                                         <enum name="RESTRICTED_DIGITAL" />
108                                                         <enum name="3K1AUDIO" />
109                                                         <enum name="DIGITAL_W_TONES" />
110                                                         <enum name="VIDEO" />
111                                                 </enumlist>
112                                         </enum>
113                                         <enum name="txgain">
114                                                 <para>R/W set txgain level on channel drivers that support it.</para>
115                                         </enum>
116                                         <enum name="videonativeformat">
117                                                 <para>R/O format used natively for video</para>
118                                         </enum>
119                                         <enum name="trace">
120                                                 <para>R/W whether or not context tracing is enabled, only available
121                                                 <emphasis>if CHANNEL_TRACE is defined</emphasis>.</para>
122                                         </enum>
123                                 </enumlist>
124                                 <para><emphasis>chan_sip</emphasis> provides the following additional options:</para>
125                                 <enumlist>
126                                         <enum name="peerip">
127                                                 <para>R/O Get the IP address of the peer.</para>
128                                         </enum>
129                                         <enum name="recvip">
130                                                 <para>R/O Get the source IP address of the peer.</para>
131                                         </enum>
132                                         <enum name="from">
133                                                 <para>R/O Get the URI from the From: header.</para>
134                                         </enum>
135                                         <enum name="uri">
136                                                 <para>R/O Get the URI from the Contact: header.</para>
137                                         </enum>
138                                         <enum name="useragent">
139                                                 <para>R/O Get the useragent.</para>
140                                         </enum>
141                                         <enum name="peername">
142                                                 <para>R/O Get the name of the peer.</para>
143                                         </enum>
144                                         <enum name="t38passthrough">
145                                                 <para>R/O <literal>1</literal> if T38 is offered or enabled in this channel,
146                                                 otherwise <literal>0</literal></para>
147                                         </enum>
148                                         <enum name="rtpqos">
149                                                 <para>R/O Get QOS information about the RTP stream</para>
150                                                 <para>    This option takes two additional arguments:</para>
151                                                 <para>    Argument 1:</para>
152                                                 <para>     <literal>audio</literal>             Get data about the audio stream</para>
153                                                 <para>     <literal>video</literal>             Get data about the video stream</para>
154                                                 <para>     <literal>text</literal>              Get data about the text stream</para>
155                                                 <para>    Argument 2:</para>
156                                                 <para>     <literal>local_ssrc</literal>        Local SSRC (stream ID)</para>
157                                                 <para>     <literal>local_lostpackets</literal> Local lost packets</para>
158                                                 <para>     <literal>local_jitter</literal>      Local calculated jitter</para>
159                                                 <para>     <literal>local_maxjitter</literal>   Local calculated jitter (maximum)</para>
160                                                 <para>     <literal>local_minjitter</literal>   Local calculated jitter (minimum)</para>
161                                                 <para>     <literal>local_normdevjitter</literal>Local calculated jitter (normal deviation)</para>
162                                                 <para>     <literal>local_stdevjitter</literal> Local calculated jitter (standard deviation)</para>
163                                                 <para>     <literal>local_count</literal>       Number of received packets</para>
164                                                 <para>     <literal>remote_ssrc</literal>       Remote SSRC (stream ID)</para>
165                                                 <para>     <literal>remote_lostpackets</literal>Remote lost packets</para>
166                                                 <para>     <literal>remote_jitter</literal>     Remote reported jitter</para>
167                                                 <para>     <literal>remote_maxjitter</literal>  Remote calculated jitter (maximum)</para>
168                                                 <para>     <literal>remote_minjitter</literal>  Remote calculated jitter (minimum)</para>
169                                                 <para>     <literal>remote_normdevjitter</literal>Remote calculated jitter (normal deviation)</para>
170                                                 <para>     <literal>remote_stdevjitter</literal>Remote calculated jitter (standard deviation)</para>
171                                                 <para>     <literal>remote_count</literal>      Number of transmitted packets</para>
172                                                 <para>     <literal>remote_ssrc</literal>       Remote SSRC (stream ID)</para>
173                                                 <para>     <literal>remote_lostpackets</literal>Remote lost packets</para>
174                                                 <para>     <literal>remote_jitter</literal>     Remote reported jitter</para>
175                                                 <para>     <literal>remote_maxjitter</literal>  Remote calculated jitter (maximum)</para>
176                                                 <para>     <literal>remote_minjitter</literal>  Remote calculated jitter (minimum)</para>
177                                                 <para>     <literal>remote_normdevjitter</literal>Remote calculated jitter (normal deviation)</para>
178                                                 <para>     <literal>remote_stdevjitter</literal>Remote calculated jitter (standard deviation)</para>
179                                                 <para>     <literal>remote_count</literal>      Number of transmitted packets</para>
180                                                 <para>     <literal>rtt</literal>               Round trip time</para>
181                                                 <para>     <literal>maxrtt</literal>            Round trip time (maximum)</para>
182                                                 <para>     <literal>minrtt</literal>            Round trip time (minimum)</para>
183                                                 <para>     <literal>normdevrtt</literal>        Round trip time (normal deviation)</para>
184                                                 <para>     <literal>stdevrtt</literal>          Round trip time (standard deviation)</para>
185                                                 <para>     <literal>all</literal>               All statistics (in a form suited to logging,
186                                                 but not for parsing)</para>
187                                         </enum>
188                                         <enum name="rtpdest">
189                                                 <para>R/O Get remote RTP destination information.</para>
190                                                 <para>   This option takes one additional argument:</para>
191                                                 <para>    Argument 1:</para>
192                                                 <para>     <literal>audio</literal>             Get audio destination</para>
193                                                 <para>     <literal>video</literal>             Get video destination</para>
194                                         </enum>
195                                 </enumlist>
196                                 <para><emphasis>chan_iax2</emphasis> provides the following additional options:</para>
197                                 <enumlist>
198                                         <enum name="osptoken">
199                                                 <para>R/W Get or set the OSP token information for a call.</para>
200                                         </enum>
201                                         <enum name="peerip">
202                                                 <para>R/O Get the peer's ip address.</para>
203                                         </enum>
204                                         <enum name="peername">
205                                                 <para>R/O Get the peer's username.</para>
206                                         </enum>
207                                 </enumlist>
208                                 <para><emphasis>chan_dahdi</emphasis> provides the following additional options:</para>
209                                 <enumlist>
210                                         <enum name="reversecharge">
211                                                 <para>R/O Reverse Charging Indication, one of:</para>
212                                                 <enumlist>
213                                                         <enum name="-1 - None" />
214                                                         <enum name="1 - Reverse Charging Requested" />
215                                                 </enumlist>
216                                         </enum>
217                                 </enumlist>
218                         </parameter>
219                 </syntax>
220                 <description>
221                         <para>Gets/sets various pieces of information about the channel, additional <replaceable>item</replaceable> may
222                         be available from the channel driver; see its documentation for details. Any <replaceable>item</replaceable>
223                         requested that is not available on the current channel will return an empty string.</para>
224                 </description>
225         </function>
226  ***/
227
228 #define locked_copy_string(chan, dest, source, len) \
229         do { \
230                 ast_channel_lock(chan); \
231                 ast_copy_string(dest, source, len); \
232                 ast_channel_unlock(chan); \
233         } while (0)
234 #define locked_string_field_set(chan, field, source) \
235         do { \
236                 ast_channel_lock(chan); \
237                 ast_string_field_set(chan, field, source); \
238                 ast_channel_unlock(chan); \
239         } while (0)
240
241 static const char * const transfercapability_table[0x20] = {
242         "SPEECH", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
243         "DIGITAL", "RESTRICTED_DIGITAL", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
244         "3K1AUDIO", "DIGITAL_W_TONES", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
245         "VIDEO", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", };
246
247 static int func_channel_read(struct ast_channel *chan, const char *function,
248                              char *data, char *buf, size_t len)
249 {
250         int ret = 0;
251
252         if (!strcasecmp(data, "audionativeformat"))
253                 /* use the _multiple version when chan->nativeformats holds multiple formats */
254                 /* ast_getformatname_multiple(buf, len, chan->nativeformats & AST_FORMAT_AUDIO_MASK); */
255                 ast_copy_string(buf, ast_getformatname(chan->nativeformats & AST_FORMAT_AUDIO_MASK), len);
256         else if (!strcasecmp(data, "videonativeformat"))
257                 /* use the _multiple version when chan->nativeformats holds multiple formats */
258                 /* ast_getformatname_multiple(buf, len, chan->nativeformats & AST_FORMAT_VIDEO_MASK); */
259                 ast_copy_string(buf, ast_getformatname(chan->nativeformats & AST_FORMAT_VIDEO_MASK), len);
260         else if (!strcasecmp(data, "audioreadformat"))
261                 ast_copy_string(buf, ast_getformatname(chan->readformat), len);
262         else if (!strcasecmp(data, "audiowriteformat"))
263                 ast_copy_string(buf, ast_getformatname(chan->writeformat), len);
264 #ifdef CHANNEL_TRACE
265         else if (!strcasecmp(data, "trace")) {
266                 ast_channel_lock(chan);
267                 ast_copy_string(buf, ast_channel_trace_is_enabled(chan) ? "1" : "0", len);
268                 ast_channel_unlock(chan);
269         }
270 #endif
271         else if (!strcasecmp(data, "tonezone") && chan->zone)
272                 locked_copy_string(chan, buf, chan->zone->country, len);
273         else if (!strcasecmp(data, "language"))
274                 locked_copy_string(chan, buf, chan->language, len);
275         else if (!strcasecmp(data, "musicclass"))
276                 locked_copy_string(chan, buf, chan->musicclass, len);
277         else if (!strcasecmp(data, "name")) {
278                 locked_copy_string(chan, buf, chan->name, len);
279         } else if (!strcasecmp(data, "parkinglot"))
280                 locked_copy_string(chan, buf, chan->parkinglot, len);
281         else if (!strcasecmp(data, "state"))
282                 locked_copy_string(chan, buf, ast_state2str(chan->_state), len);
283         else if (!strcasecmp(data, "channeltype"))
284                 locked_copy_string(chan, buf, chan->tech->type, len);
285         else if (!strcasecmp(data, "accountcode"))
286                 locked_copy_string(chan, buf, chan->accountcode, len);
287         else if (!strcasecmp(data, "peeraccount"))
288                 locked_copy_string(chan, buf, chan->peeraccount, len);
289         else if (!strcasecmp(data, "hangupsource"))
290                 locked_copy_string(chan, buf, chan->hangupsource, len);
291         else if (!strcasecmp(data, "appname") && chan->appl)
292                 locked_copy_string(chan, buf, chan->appl, len);
293         else if (!strcasecmp(data, "appdata") && chan->data)
294                 locked_copy_string(chan, buf, chan->data, len);
295         else if (!strcasecmp(data, "exten") && chan->data)
296                 locked_copy_string(chan, buf, chan->exten, len);
297         else if (!strcasecmp(data, "context") && chan->data)
298                 locked_copy_string(chan, buf, chan->context, len);
299         else if (!strcasecmp(data, "userfield") && chan->data)
300                 locked_copy_string(chan, buf, chan->userfield, len);
301         else if (!strcasecmp(data, "channame") && chan->data)
302                 locked_copy_string(chan, buf, chan->name, len);
303         else if (!strcasecmp(data, "linkedid")) {
304                 ast_channel_lock(chan);
305                 if (ast_strlen_zero(chan->linkedid)) {
306                         /* fall back on the channel's uniqueid if linkedid is unset */
307                         ast_copy_string(buf, chan->uniqueid, len);
308                 }
309                 else {
310                         ast_copy_string(buf, chan->linkedid, len);
311                 }
312                 ast_channel_unlock(chan);
313         } else if (!strcasecmp(data, "peer")) {
314                 struct ast_channel *p;
315                 ast_channel_lock(chan);
316                 p = ast_bridged_channel(chan);
317                 if (p || chan->tech || chan->cdr) /* dummy channel? if so, we hid the peer name in the language */
318                         ast_copy_string(buf, (p ? p->name : ""), len);
319                 else {
320                         /* a dummy channel can still pass along bridged peer info via
321                            the BRIDGEPEER variable */
322                         const char *pname = pbx_builtin_getvar_helper(chan, "BRIDGEPEER");
323                         if (!ast_strlen_zero(pname))
324                                 ast_copy_string(buf, pname, len); /* a horrible kludge, but... how else? */
325                         else
326                                 buf[0] = 0;
327                 }
328                 ast_channel_unlock(chan);
329         } else if (!strcasecmp(data, "uniqueid")) {
330                 locked_copy_string(chan, buf, chan->uniqueid, len);
331         } else if (!strcasecmp(data, "transfercapability"))
332                 locked_copy_string(chan, buf, transfercapability_table[chan->transfercapability & 0x1f], len);
333         else if (!strcasecmp(data, "callgroup")) {
334                 char groupbuf[256];
335                 locked_copy_string(chan, buf,  ast_print_group(groupbuf, sizeof(groupbuf), chan->callgroup), len);
336         } else if (!strcasecmp(data, "amaflags")) {
337                 char amabuf[256];
338                 snprintf(amabuf,sizeof(amabuf), "%d", chan->amaflags);
339                 locked_copy_string(chan, buf, amabuf, len);
340         } else if (!chan->tech || !chan->tech->func_channel_read || chan->tech->func_channel_read(chan, function, data, buf, len)) {
341                 ast_log(LOG_WARNING, "Unknown or unavailable item requested: '%s'\n", data);
342                 ret = -1;
343         }
344
345         return ret;
346 }
347
348 static int func_channel_write(struct ast_channel *chan, const char *function,
349                               char *data, const char *value)
350 {
351         int ret = 0;
352         signed char gainset;
353
354         if (!strcasecmp(data, "language"))
355                 locked_string_field_set(chan, language, value);
356         else if (!strcasecmp(data, "parkinglot"))
357                 locked_string_field_set(chan, parkinglot, value);
358         else if (!strcasecmp(data, "musicclass"))
359                 locked_string_field_set(chan, musicclass, value);
360         else if (!strcasecmp(data, "accountcode"))
361                 locked_string_field_set(chan, accountcode, value);
362         else if (!strcasecmp(data, "userfield"))
363                 locked_string_field_set(chan, userfield, value);
364         else if (!strcasecmp(data, "amaflags")) {
365                 ast_channel_lock(chan);
366                 if(isdigit(*value)) {
367                         sscanf(value, "%30d", &chan->amaflags);
368                 } else if (!strcasecmp(value,"OMIT")){
369                         chan->amaflags = 1;
370                 } else if (!strcasecmp(value,"BILLING")){
371                         chan->amaflags = 2;
372                 } else if (!strcasecmp(value,"DOCUMENTATION")){
373                         chan->amaflags = 3;
374                 }
375                 ast_channel_unlock(chan);
376         } else if (!strcasecmp(data, "peeraccount"))
377                 locked_string_field_set(chan, peeraccount, value);
378         else if (!strcasecmp(data, "hangupsource"))
379                 /* XXX - should we be forcing this here? */
380                 ast_set_hangupsource(chan, value, 0);
381 #ifdef CHANNEL_TRACE
382         else if (!strcasecmp(data, "trace")) {
383                 ast_channel_lock(chan);
384                 if (ast_true(value)) 
385                         ret = ast_channel_trace_enable(chan);
386                 else if (ast_false(value))
387                         ret = ast_channel_trace_disable(chan);
388                 else {
389                         ret = -1;
390                         ast_log(LOG_WARNING, "Invalid value for CHANNEL(trace).");
391                 }
392                 ast_channel_unlock(chan);
393         }
394 #endif
395         else if (!strcasecmp(data, "tonezone")) {
396                 struct ast_tone_zone *new_zone;
397                 if (!(new_zone = ast_get_indication_zone(value))) {
398                         ast_log(LOG_ERROR, "Unknown country code '%s' for tonezone. Check indications.conf for available country codes.\n", value);
399                         ret = -1;       
400                 } else {
401                         ast_channel_lock(chan);
402                         if (chan->zone) {
403                                 chan->zone = ast_tone_zone_unref(chan->zone);
404                         }
405                         chan->zone = ast_tone_zone_ref(new_zone);
406                         ast_channel_unlock(chan);
407                         new_zone = ast_tone_zone_unref(new_zone);
408                 }
409         } else if (!strcasecmp(data, "callgroup"))
410                 chan->callgroup = ast_get_group(value);
411         else if (!strcasecmp(data, "txgain")) {
412                 sscanf(value, "%4hhd", &gainset);
413                 ast_channel_setoption(chan, AST_OPTION_TXGAIN, &gainset, sizeof(gainset), 0);
414         } else if (!strcasecmp(data, "rxgain")) {
415                 sscanf(value, "%4hhd", &gainset);
416                 ast_channel_setoption(chan, AST_OPTION_RXGAIN, &gainset, sizeof(gainset), 0);
417         } else if (!strcasecmp(data, "transfercapability")) {
418                 unsigned short i;
419                 for (i = 0; i < 0x20; i++) {
420                         if (!strcasecmp(transfercapability_table[i], value) && strcmp(value, "UNK")) {
421                                 chan->transfercapability = i;
422                                 break;
423                         }
424                 }
425         } else if (!chan->tech->func_channel_write
426                  || chan->tech->func_channel_write(chan, function, data, value)) {
427                 ast_log(LOG_WARNING, "Unknown or unavailable item requested: '%s'\n",
428                                 data);
429                 ret = -1;
430         }
431
432         return ret;
433 }
434
435 static struct ast_custom_function channel_function = {
436         .name = "CHANNEL",
437         .read = func_channel_read,
438         .write = func_channel_write,
439 };
440
441 static int func_channels_read(struct ast_channel *chan, const char *function, char *data, char *buf, size_t maxlen)
442 {
443         struct ast_channel *c = NULL;
444         regex_t re;
445         int res;
446         size_t buflen = 0;
447         struct ast_channel_iterator *iter;
448
449         buf[0] = '\0';
450
451         if (!ast_strlen_zero(data)) {
452                 if ((res = regcomp(&re, data, REG_EXTENDED | REG_ICASE | REG_NOSUB))) {
453                         regerror(res, &re, buf, maxlen);
454                         ast_log(LOG_WARNING, "Error compiling regular expression for %s(%s): %s\n", function, data, buf);
455                         return -1;
456                 }
457         }
458
459         if (!(iter = ast_channel_iterator_all_new(0))) {
460                 if (!ast_strlen_zero(data)) {
461                         regfree(&re);
462                 }
463                 return -1;
464         }
465
466         while ((c = ast_channel_iterator_next(iter))) {
467                 ast_channel_lock(c);
468                 if (ast_strlen_zero(data) || regexec(&re, c->name, 0, NULL, 0) == 0) {
469                         size_t namelen = strlen(c->name);
470                         if (buflen + namelen + (ast_strlen_zero(buf) ? 0 : 1) + 1 < maxlen) {
471                                 if (!ast_strlen_zero(buf)) {
472                                         strcat(buf, " ");
473                                         buflen++;
474                                 }
475                                 strcat(buf, c->name);
476                                 buflen += namelen;
477                         } else {
478                                 ast_log(LOG_WARNING, "Number of channels exceeds the available buffer space.  Output will be truncated!\n");
479                         }
480                 }
481                 ast_channel_unlock(c);
482                 c = ast_channel_unref(c);
483         }
484
485         ast_channel_iterator_destroy(iter);
486
487         if (!ast_strlen_zero(data)) {
488                 regfree(&re);
489         }
490
491         return 0;
492 }
493
494 static struct ast_custom_function channels_function = {
495         .name = "CHANNELS",
496         .read = func_channels_read,
497 };
498
499 static int unload_module(void)
500 {
501         int res = 0;
502         
503         res |= ast_custom_function_unregister(&channel_function);
504         res |= ast_custom_function_unregister(&channels_function);
505         
506         return res;
507 }
508
509 static int load_module(void)
510 {
511         int res = 0;
512         
513         res |= ast_custom_function_register(&channel_function);
514         res |= ast_custom_function_register(&channels_function);
515         
516         return res;
517 }
518
519 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Channel information dialplan functions");