Thu Apr 28 2011 16:56:47

Asterisk developer's documentation


func_channel.c

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2006, Digium, Inc.
00005  *
00006  * See http://www.asterisk.org for more information about
00007  * the Asterisk project. Please do not directly contact
00008  * any of the maintainers of this project for assistance;
00009  * the project provides a web site, mailing lists and IRC
00010  * channels for your use.
00011  *
00012  * This program is free software, distributed under the terms of
00013  * the GNU General Public License Version 2. See the LICENSE file
00014  * at the top of the source tree.
00015  */
00016 
00017 /*! \file
00018  *
00019  * \brief Channel info dialplan functions
00020  *
00021  * \author Kevin P. Fleming <kpfleming@digium.com>
00022  * \author Ben Winslow
00023  * 
00024  * \ingroup functions
00025  */
00026 
00027 #include "asterisk.h"
00028 
00029 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 286115 $")
00030 
00031 #include <regex.h>
00032 
00033 #include "asterisk/module.h"
00034 #include "asterisk/channel.h"
00035 #include "asterisk/pbx.h"
00036 #include "asterisk/utils.h"
00037 #include "asterisk/app.h"
00038 #include "asterisk/indications.h"
00039 #include "asterisk/stringfields.h"
00040 
00041 /*** DOCUMENTATION
00042    <function name="CHANNELS" language="en_US">
00043       <synopsis>
00044          Gets the list of channels, optionally filtering by a regular expression.
00045       </synopsis>
00046       <syntax>
00047          <parameter name="regular_expression" />
00048       </syntax>
00049       <description>
00050          <para>Gets the list of channels, optionally filtering by a <replaceable>regular_expression</replaceable>. If
00051          no argument is provided, all known channels are returned. The
00052          <replaceable>regular_expression</replaceable> must correspond to
00053          the POSIX.2 specification, as shown in <emphasis>regex(7)</emphasis>. The list returned
00054          will be space-delimited.</para>
00055       </description>
00056    </function>
00057    <function name="CHANNEL" language="en_US">
00058       <synopsis>
00059          Gets/sets various pieces of information about the channel.
00060       </synopsis>
00061       <syntax>
00062          <parameter name="item" required="true">
00063             <para>Standard items (provided by all channel technologies) are:</para>
00064             <enumlist>
00065                <enum name="audioreadformat">
00066                   <para>R/O format currently being read.</para>
00067                </enum>
00068                <enum name="audionativeformat">
00069                   <para>R/O format used natively for audio.</para>
00070                </enum>
00071                <enum name="audiowriteformat">
00072                   <para>R/O format currently being written.</para>
00073                </enum>
00074                <enum name="callgroup">
00075                   <para>R/W call groups for call pickup.</para>
00076                </enum>
00077                <enum name="channeltype">
00078                   <para>R/O technology used for channel.</para>
00079                </enum>
00080                <enum name="language">
00081                   <para>R/W language for sounds played.</para>
00082                </enum>
00083                <enum name="musicclass">
00084                   <para>R/W class (from musiconhold.conf) for hold music.</para>
00085                </enum>
00086                <enum name="parkinglot">
00087                   <para>R/W parkinglot for parking.</para>
00088                </enum>
00089                <enum name="rxgain">
00090                   <para>R/W set rxgain level on channel drivers that support it.</para>
00091                </enum>
00092                <enum name="state">
00093                   <para>R/O state for channel</para>
00094                </enum>
00095                <enum name="tonezone">
00096                   <para>R/W zone for indications played</para>
00097                </enum>
00098                <enum name="transfercapability">
00099                   <para>R/W ISDN Transfer Capability, one of:</para>
00100                   <enumlist>
00101                      <enum name="SPEECH" />
00102                      <enum name="DIGITAL" />
00103                      <enum name="RESTRICTED_DIGITAL" />
00104                      <enum name="3K1AUDIO" />
00105                      <enum name="DIGITAL_W_TONES" />
00106                      <enum name="VIDEO" />
00107                   </enumlist>
00108                </enum>
00109                <enum name="txgain">
00110                   <para>R/W set txgain level on channel drivers that support it.</para>
00111                </enum>
00112                <enum name="videonativeformat">
00113                   <para>R/O format used natively for video</para>
00114                </enum>
00115                <enum name="trace">
00116                   <para>R/W whether or not context tracing is enabled, only available
00117                   <emphasis>if CHANNEL_TRACE is defined</emphasis>.</para>
00118                </enum>
00119             </enumlist>
00120             <para><emphasis>chan_sip</emphasis> provides the following additional options:</para>
00121             <enumlist>
00122                <enum name="peerip">
00123                   <para>R/O Get the IP address of the peer.</para>
00124                </enum>
00125                <enum name="recvip">
00126                   <para>R/O Get the source IP address of the peer.</para>
00127                </enum>
00128                <enum name="from">
00129                   <para>R/O Get the URI from the From: header.</para>
00130                </enum>
00131                <enum name="uri">
00132                   <para>R/O Get the URI from the Contact: header.</para>
00133                </enum>
00134                <enum name="useragent">
00135                   <para>R/O Get the useragent.</para>
00136                </enum>
00137                <enum name="peername">
00138                   <para>R/O Get the name of the peer.</para>
00139                </enum>
00140                <enum name="t38passthrough">
00141                   <para>R/O <literal>1</literal> if T38 is offered or enabled in this channel,
00142                   otherwise <literal>0</literal></para>
00143                </enum>
00144                <enum name="rtpqos">
00145                   <para>R/O Get QOS information about the RTP stream</para>
00146                   <para>    This option takes two additional arguments:</para>
00147                   <para>    Argument 1:</para>
00148                   <para>     <literal>audio</literal>             Get data about the audio stream</para>
00149                   <para>     <literal>video</literal>             Get data about the video stream</para>
00150                   <para>     <literal>text</literal>              Get data about the text stream</para>
00151                   <para>    Argument 2:</para>
00152                   <para>     <literal>local_ssrc</literal>        Local SSRC (stream ID)</para>
00153                   <para>     <literal>local_lostpackets</literal> Local lost packets</para>
00154                   <para>     <literal>local_jitter</literal>      Local calculated jitter</para>
00155                   <para>     <literal>local_maxjitter</literal>   Local calculated jitter (maximum)</para>
00156                   <para>     <literal>local_minjitter</literal>   Local calculated jitter (minimum)</para>
00157                   <para>     <literal>local_normdevjitter</literal>Local calculated jitter (normal deviation)</para>
00158                   <para>     <literal>local_stdevjitter</literal> Local calculated jitter (standard deviation)</para>
00159                   <para>     <literal>local_count</literal>       Number of received packets</para>
00160                   <para>     <literal>remote_ssrc</literal>       Remote SSRC (stream ID)</para>
00161                   <para>     <literal>remote_lostpackets</literal>Remote lost packets</para>
00162                   <para>     <literal>remote_jitter</literal>     Remote reported jitter</para>
00163                   <para>     <literal>remote_maxjitter</literal>  Remote calculated jitter (maximum)</para>
00164                   <para>     <literal>remote_minjitter</literal>  Remote calculated jitter (minimum)</para>
00165                   <para>     <literal>remote_normdevjitter</literal>Remote calculated jitter (normal deviation)</para>
00166                   <para>     <literal>remote_stdevjitter</literal>Remote calculated jitter (standard deviation)</para>
00167                   <para>     <literal>remote_count</literal>      Number of transmitted packets</para>
00168                   <para>     <literal>remote_ssrc</literal>       Remote SSRC (stream ID)</para>
00169                   <para>     <literal>remote_lostpackets</literal>Remote lost packets</para>
00170                   <para>     <literal>remote_jitter</literal>     Remote reported jitter</para>
00171                   <para>     <literal>remote_maxjitter</literal>  Remote calculated jitter (maximum)</para>
00172                   <para>     <literal>remote_minjitter</literal>  Remote calculated jitter (minimum)</para>
00173                   <para>     <literal>remote_normdevjitter</literal>Remote calculated jitter (normal deviation)</para>
00174                   <para>     <literal>remote_stdevjitter</literal>Remote calculated jitter (standard deviation)</para>
00175                   <para>     <literal>remote_count</literal>      Number of transmitted packets</para>
00176                   <para>     <literal>rtt</literal>               Round trip time</para>
00177                   <para>     <literal>maxrtt</literal>            Round trip time (maximum)</para>
00178                   <para>     <literal>minrtt</literal>            Round trip time (minimum)</para>
00179                   <para>     <literal>normdevrtt</literal>        Round trip time (normal deviation)</para>
00180                   <para>     <literal>stdevrtt</literal>          Round trip time (standard deviation)</para>
00181                   <para>     <literal>all</literal>               All statistics (in a form suited to logging,
00182                   but not for parsing)</para>
00183                </enum>
00184                <enum name="rtpdest">
00185                   <para>R/O Get remote RTP destination information.</para>
00186                   <para>   This option takes one additional argument:</para>
00187                   <para>    Argument 1:</para>
00188                   <para>     <literal>audio</literal>             Get audio destination</para>
00189                   <para>     <literal>video</literal>             Get video destination</para>
00190                   <para>     <literal>text</literal>              Get text destination</para>
00191                </enum>
00192             </enumlist>
00193             <para><emphasis>chan_iax2</emphasis> provides the following additional options:</para>
00194             <enumlist>
00195                <enum name="peerip">
00196                   <para>R/O Get the peer's ip address.</para>
00197                </enum>
00198                <enum name="peername">
00199                   <para>R/O Get the peer's username.</para>
00200                </enum>
00201             </enumlist>
00202          </parameter>
00203       </syntax>
00204       <description>
00205          <para>Gets/sets various pieces of information about the channel, additional <replaceable>item</replaceable> may
00206          be available from the channel driver; see its documentation for details. Any <replaceable>item</replaceable>
00207          requested that is not available on the current channel will return an empty string.</para>
00208       </description>
00209    </function>
00210  ***/
00211 
00212 #define locked_copy_string(chan, dest, source, len) \
00213    do { \
00214       ast_channel_lock(chan); \
00215       ast_copy_string(dest, source, len); \
00216       ast_channel_unlock(chan); \
00217    } while (0)
00218 #define locked_string_field_set(chan, field, source) \
00219    do { \
00220       ast_channel_lock(chan); \
00221       ast_string_field_set(chan, field, source); \
00222       ast_channel_unlock(chan); \
00223    } while (0)
00224 
00225 char *transfercapability_table[0x20] = {
00226    "SPEECH", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
00227    "DIGITAL", "RESTRICTED_DIGITAL", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
00228    "3K1AUDIO", "DIGITAL_W_TONES", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
00229    "VIDEO", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", };
00230 
00231 static int func_channel_read(struct ast_channel *chan, const char *function,
00232               char *data, char *buf, size_t len)
00233 {
00234    int ret = 0;
00235 
00236    if (!strcasecmp(data, "audionativeformat"))
00237       /* use the _multiple version when chan->nativeformats holds multiple formats */
00238       /* ast_getformatname_multiple(buf, len, chan->nativeformats & AST_FORMAT_AUDIO_MASK); */
00239       ast_copy_string(buf, ast_getformatname(chan->nativeformats & AST_FORMAT_AUDIO_MASK), len);
00240    else if (!strcasecmp(data, "videonativeformat"))
00241       /* use the _multiple version when chan->nativeformats holds multiple formats */
00242       /* ast_getformatname_multiple(buf, len, chan->nativeformats & AST_FORMAT_VIDEO_MASK); */
00243       ast_copy_string(buf, ast_getformatname(chan->nativeformats & AST_FORMAT_VIDEO_MASK), len);
00244    else if (!strcasecmp(data, "audioreadformat"))
00245       ast_copy_string(buf, ast_getformatname(chan->readformat), len);
00246    else if (!strcasecmp(data, "audiowriteformat"))
00247       ast_copy_string(buf, ast_getformatname(chan->writeformat), len);
00248 #ifdef CHANNEL_TRACE
00249    else if (!strcasecmp(data, "trace")) {
00250       ast_channel_lock(chan);
00251       ast_copy_string(buf, ast_channel_trace_is_enabled(chan) ? "1" : "0", len);
00252       ast_channel_unlock(chan);
00253    }
00254 #endif
00255    else if (!strcasecmp(data, "tonezone") && chan->zone)
00256       locked_copy_string(chan, buf, chan->zone->country, len);
00257    else if (!strcasecmp(data, "language"))
00258       locked_copy_string(chan, buf, chan->language, len);
00259    else if (!strcasecmp(data, "musicclass"))
00260       locked_copy_string(chan, buf, chan->musicclass, len);
00261    else if (!strcasecmp(data, "parkinglot"))
00262       locked_copy_string(chan, buf, chan->parkinglot, len);
00263    else if (!strcasecmp(data, "state"))
00264       locked_copy_string(chan, buf, ast_state2str(chan->_state), len);
00265    else if (!strcasecmp(data, "channeltype"))
00266       locked_copy_string(chan, buf, chan->tech->type, len);
00267    else if (!strcasecmp(data, "transfercapability"))
00268       locked_copy_string(chan, buf, transfercapability_table[chan->transfercapability & 0x1f], len);
00269    else if (!strcasecmp(data, "callgroup")) {
00270       char groupbuf[256];
00271       locked_copy_string(chan, buf,  ast_print_group(groupbuf, sizeof(groupbuf), chan->callgroup), len);
00272    } else if (!chan->tech->func_channel_read
00273        || chan->tech->func_channel_read(chan, function, data, buf, len)) {
00274       ast_log(LOG_WARNING, "Unknown or unavailable item requested: '%s'\n", data);
00275       ret = -1;
00276    }
00277 
00278    return ret;
00279 }
00280 
00281 static int func_channel_write_real(struct ast_channel *chan, const char *function,
00282                char *data, const char *value)
00283 {
00284    int ret = 0;
00285    signed char gainset;
00286 
00287    if (!strcasecmp(data, "language"))
00288       locked_string_field_set(chan, language, value);
00289    else if (!strcasecmp(data, "parkinglot"))
00290       locked_string_field_set(chan, parkinglot, value);
00291    else if (!strcasecmp(data, "musicclass"))
00292       locked_string_field_set(chan, musicclass, value);
00293 #ifdef CHANNEL_TRACE
00294    else if (!strcasecmp(data, "trace")) {
00295       ast_channel_lock(chan);
00296       if (ast_true(value)) 
00297          ret = ast_channel_trace_enable(chan);
00298       else if (ast_false(value)) 
00299          ret = ast_channel_trace_disable(chan);
00300       else {
00301          ret = -1;
00302          ast_log(LOG_WARNING, "Invalid value for CHANNEL(trace).");
00303       }
00304       ast_channel_unlock(chan);
00305    }
00306 #endif
00307    else if (!strcasecmp(data, "tonezone")) {
00308       struct ast_tone_zone *new_zone;
00309       if (!(new_zone = ast_get_indication_zone(value))) {
00310          ast_log(LOG_ERROR, "Unknown country code '%s' for tonezone. Check indications.conf for available country codes.\n", value);
00311          ret = -1;   
00312       } else {
00313          ast_channel_lock(chan);
00314          if (chan->zone) {
00315             chan->zone = ast_tone_zone_unref(chan->zone);
00316          }
00317          chan->zone = ast_tone_zone_ref(new_zone);
00318          ast_channel_unlock(chan);
00319          new_zone = ast_tone_zone_unref(new_zone);
00320       }
00321    } else if (!strcasecmp(data, "callgroup"))
00322       chan->callgroup = ast_get_group(value);
00323    else if (!strcasecmp(data, "txgain")) {
00324       sscanf(value, "%4hhd", &gainset);
00325       ast_channel_setoption(chan, AST_OPTION_TXGAIN, &gainset, sizeof(gainset), 0);
00326    } else if (!strcasecmp(data, "rxgain")) {
00327       sscanf(value, "%4hhd", &gainset);
00328       ast_channel_setoption(chan, AST_OPTION_RXGAIN, &gainset, sizeof(gainset), 0);
00329    } else if (!strcasecmp(data, "transfercapability")) {
00330       unsigned short i;
00331       for (i = 0; i < 0x20; i++) {
00332          if (!strcasecmp(transfercapability_table[i], value) && strcmp(value, "UNK")) {
00333             chan->transfercapability = i;
00334             break;
00335          }
00336       }
00337    } else if (!chan->tech->func_channel_write
00338        || chan->tech->func_channel_write(chan, function, data, value)) {
00339       ast_log(LOG_WARNING, "Unknown or unavailable item requested: '%s'\n",
00340             data);
00341       ret = -1;
00342    }
00343 
00344    return ret;
00345 }
00346 
00347 static int func_channel_write(struct ast_channel *chan, const char *function, char *data, const char *value)
00348 {
00349    int res;
00350    ast_chan_write_info_t write_info = {
00351       .version = AST_CHAN_WRITE_INFO_T_VERSION,
00352       .write_fn = func_channel_write_real,
00353       .chan = chan,
00354       .function = function,
00355       .data = data,
00356       .value = value,
00357    };
00358 
00359    res = func_channel_write_real(chan, function, data, value);
00360    ast_channel_setoption(chan, AST_OPTION_CHANNEL_WRITE, &write_info, sizeof(write_info), 0);
00361 
00362    return res;
00363 }
00364 
00365 static struct ast_custom_function channel_function = {
00366    .name = "CHANNEL",
00367    .read = func_channel_read,
00368    .write = func_channel_write,
00369 };
00370 
00371 static int func_channels_read(struct ast_channel *chan, const char *function, char *data, char *buf, size_t maxlen)
00372 {
00373    struct ast_channel *c = NULL;
00374    regex_t re;
00375    int res;
00376    size_t buflen = 0;
00377    
00378    buf[0] = '\0';
00379 
00380    if (!ast_strlen_zero(data)) {
00381       if ((res = regcomp(&re, data, REG_EXTENDED | REG_ICASE | REG_NOSUB))) {
00382          regerror(res, &re, buf, maxlen);
00383          ast_log(LOG_WARNING, "Error compiling regular expression for %s(%s): %s\n", function, data, buf);
00384          return -1;
00385       }
00386    }
00387 
00388    for (c = ast_channel_walk_locked(NULL); c; ast_channel_unlock(c), c = ast_channel_walk_locked(c)) {
00389       if (ast_strlen_zero(data) || regexec(&re, c->name, 0, NULL, 0) == 0) {
00390          size_t namelen = strlen(c->name);
00391          if (buflen + namelen + (ast_strlen_zero(buf) ? 0 : 1) + 1 < maxlen) {
00392             if (!ast_strlen_zero(buf)) {
00393                strcat(buf, " ");
00394                buflen++;
00395             }
00396             strcat(buf, c->name);
00397             buflen += namelen;
00398          } else {
00399             ast_log(LOG_WARNING, "Number of channels exceeds the available buffer space.  Output will be truncated!\n");
00400          }
00401       }
00402    }
00403 
00404    if (!ast_strlen_zero(data)) {
00405       regfree(&re);
00406    }
00407 
00408    return 0;
00409 }
00410 
00411 static struct ast_custom_function channels_function = {
00412    .name = "CHANNELS",
00413    .read = func_channels_read,
00414 };
00415 
00416 static int unload_module(void)
00417 {
00418    int res = 0;
00419    
00420    res |= ast_custom_function_unregister(&channel_function);
00421    res |= ast_custom_function_unregister(&channels_function);
00422    
00423    return res;
00424 }
00425 
00426 static int load_module(void)
00427 {
00428    int res = 0;
00429    
00430    res |= ast_custom_function_register(&channel_function);
00431    res |= ast_custom_function_register(&channels_function);
00432    
00433    return res;
00434 }
00435 
00436 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Channel information dialplan functions");