func_channel: Add help text for undocumented CHANNEL function arguments
[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 /*** MODULEINFO
28         <support_level>core</support_level>
29  ***/
30
31 #include "asterisk.h"
32
33 ASTERISK_REGISTER_FILE()
34
35 #include <regex.h>
36 #include <ctype.h>
37
38 #include "asterisk/module.h"
39 #include "asterisk/channel.h"
40 #include "asterisk/bridge.h"
41 #include "asterisk/pbx.h"
42 #include "asterisk/utils.h"
43 #include "asterisk/app.h"
44 #include "asterisk/indications.h"
45 #include "asterisk/stringfields.h"
46 #include "asterisk/global_datastores.h"
47 #include "asterisk/bridge_basic.h"
48 #include "asterisk/bridge_after.h"
49 #include "asterisk/max_forwards.h"
50
51 /*** DOCUMENTATION
52         <function name="CHANNELS" language="en_US">
53                 <synopsis>
54                         Gets the list of channels, optionally filtering by a regular expression.
55                 </synopsis>
56                 <syntax>
57                         <parameter name="regular_expression" />
58                 </syntax>
59                 <description>
60                         <para>Gets the list of channels, optionally filtering by a <replaceable>regular_expression</replaceable>. If
61                         no argument is provided, all known channels are returned. The
62                         <replaceable>regular_expression</replaceable> must correspond to
63                         the POSIX.2 specification, as shown in <emphasis>regex(7)</emphasis>. The list returned
64                         will be space-delimited.</para>
65                 </description>
66         </function>
67         <function name="MASTER_CHANNEL" language="en_US">
68                 <synopsis>
69                         Gets or sets variables on the master channel
70                 </synopsis>
71                 <description>
72                         <para>Allows access to the channel which created the current channel, if any.  If the channel is already
73                         a master channel, then accesses local channel variables.</para>
74                 </description>
75         </function>
76         <function name="CHANNEL" language="en_US">
77                 <synopsis>
78                         Gets/sets various pieces of information about the channel.
79                 </synopsis>
80                 <syntax>
81                         <parameter name="item" required="true">
82                                 <para>Standard items (provided by all channel technologies) are:</para>
83                                 <enumlist>
84                                         <enum name="amaflags">
85                                                 <para>R/W the Automatic Message Accounting (AMA) flags on the channel.
86                                                 When read from a channel, the integer value will always be returned.
87                                                 When written to a channel, both the string format or integer value
88                                                 is accepted.</para>
89                                                 <enumlist>
90                                                         <enum name="1"><para><literal>OMIT</literal></para></enum>
91                                                         <enum name="2"><para><literal>BILLING</literal></para></enum>
92                                                         <enum name="3"><para><literal>DOCUMENTATION</literal></para></enum>
93                                                 </enumlist>
94                                         </enum>
95                                         <enum name="accountcode">
96                                                 <para>R/W the channel's account code.</para>
97                                         </enum>
98                                         <enum name="audioreadformat">
99                                                 <para>R/O format currently being read.</para>
100                                         </enum>
101                                         <enum name="audionativeformat">
102                                                 <para>R/O format used natively for audio.</para>
103                                         </enum>
104                                         <enum name="audiowriteformat">
105                                                 <para>R/O format currently being written.</para>
106                                         </enum>
107                                         <enum name="dtmf_features">
108                                                 <para>R/W The channel's DTMF bridge features.
109                                                 May include one or more of 'T' 'K' 'H' 'W' and 'X' in a similar manner to options
110                                                 in the <literal>Dial</literal> application. When setting it, the features string
111                                                 must be all upper case.</para>
112                                         </enum>
113                                         <enum name="callgroup">
114                                                 <para>R/W numeric call pickup groups that this channel is a member.</para>
115                                         </enum>
116                                         <enum name="pickupgroup">
117                                                 <para>R/W numeric call pickup groups this channel can pickup.</para>
118                                         </enum>
119                                         <enum name="namedcallgroup">
120                                                 <para>R/W named call pickup groups that this channel is a member.</para>
121                                         </enum>
122                                         <enum name="namedpickupgroup">
123                                                 <para>R/W named call pickup groups this channel can pickup.</para>
124                                         </enum>
125                                         <enum name="channeltype">
126                                                 <para>R/O technology used for channel.</para>
127                                         </enum>
128                                         <enum name="checkhangup">
129                                                 <para>R/O Whether the channel is hanging up (1/0)</para>
130                                         </enum>
131                                         <enum name="after_bridge_goto">
132                                                 <para>R/W the parseable goto string indicating where the channel is
133                                                 expected to return to in the PBX after exiting the next bridge it joins
134                                                 on the condition that it doesn't hang up. The parseable goto string uses
135                                                 the same syntax as the <literal>Goto</literal> application.</para>
136                                         </enum>
137                                         <enum name="hangup_handler_pop">
138                                                 <para>W/O Replace the most recently added hangup handler
139                                                 with a new hangup handler on the channel if supplied.  The
140                                                 assigned string is passed to the Gosub application when
141                                                 the channel is hung up.  Any optionally omitted context
142                                                 and exten are supplied by the channel pushing the handler
143                                                 before it is pushed.</para>
144                                         </enum>
145                                         <enum name="hangup_handler_push">
146                                                 <para>W/O Push a hangup handler onto the channel hangup
147                                                 handler stack.  The assigned string is passed to the
148                                                 Gosub application when the channel is hung up.  Any
149                                                 optionally omitted context and exten are supplied by the
150                                                 channel pushing the handler before it is pushed.</para>
151                                         </enum>
152                                         <enum name="hangup_handler_wipe">
153                                                 <para>W/O Wipe the entire hangup handler stack and replace
154                                                 with a new hangup handler on the channel if supplied.  The
155                                                 assigned string is passed to the Gosub application when
156                                                 the channel is hung up.  Any optionally omitted context
157                                                 and exten are supplied by the channel pushing the handler
158                                                 before it is pushed.</para>
159                                         </enum>
160                                         <enum name="onhold">
161                                                 <para>R/O Whether or not the channel is onhold. (1/0)</para>
162                                         </enum>
163                                         <enum name="language">
164                                                 <para>R/W language for sounds played.</para>
165                                         </enum>
166                                         <enum name="musicclass">
167                                                 <para>R/W class (from musiconhold.conf) for hold music.</para>
168                                         </enum>
169                                         <enum name="name">
170                                                 <para>The name of the channel</para>
171                                         </enum>
172                                         <enum name="parkinglot">
173                                                 <para>R/W parkinglot for parking.</para>
174                                         </enum>
175                                         <enum name="rxgain">
176                                                 <para>R/W set rxgain level on channel drivers that support it.</para>
177                                         </enum>
178                                         <enum name="secure_bridge_signaling">
179                                                 <para>Whether or not channels bridged to this channel require secure signaling (1/0)</para>
180                                         </enum>
181                                         <enum name="secure_bridge_media">
182                                                 <para>Whether or not channels bridged to this channel require secure media (1/0)</para>
183                                         </enum>
184                                         <enum name="state">
185                                                 <para>R/O state of the channel</para>
186                                         </enum>
187                                         <enum name="tonezone">
188                                                 <para>R/W zone for indications played</para>
189                                         </enum>
190                                         <enum name="transfercapability">
191                                                 <para>R/W ISDN Transfer Capability, one of:</para>
192                                                 <enumlist>
193                                                         <enum name="SPEECH" />
194                                                         <enum name="DIGITAL" />
195                                                         <enum name="RESTRICTED_DIGITAL" />
196                                                         <enum name="3K1AUDIO" />
197                                                         <enum name="DIGITAL_W_TONES" />
198                                                         <enum name="VIDEO" />
199                                                 </enumlist>
200                                         </enum>
201                                         <enum name="txgain">
202                                                 <para>R/W set txgain level on channel drivers that support it.</para>
203                                         </enum>
204                                         <enum name="videonativeformat">
205                                                 <para>R/O format used natively for video</para>
206                                         </enum>
207                                         <enum name="trace">
208                                                 <para>R/W whether or not context tracing is enabled, only available
209                                                 <emphasis>if CHANNEL_TRACE is defined</emphasis>.</para>
210                                         </enum>
211                                         <enum name="hangupsource">
212                                                 <para>R/W returns the channel responsible for hangup.</para>
213                                         </enum>
214                                         <enum name="appname">
215                                                 <para>R/O returns the internal application name.</para>
216                                         </enum>
217                                         <enum name="appdata">
218                                                 <para>R/O returns the application data if available.</para>
219                                         </enum>
220                                         <enum name="exten">
221                                                 <para>R/O returns the extension for an outbound channel.</para>
222                                         </enum>
223                                         <enum name="context">
224                                                 <para>R/O returns the context for an outbound channel.</para>
225                                         </enum>
226                                         <enum name="channame">
227                                                 <para>R/O returns the channel name for an outbound channel.</para>
228                                         </enum>
229                                         <enum name="uniqueid">
230                                                 <para>R/O returns the channel uniqueid.</para>
231                                         </enum>
232                                         <enum name="linkedid">
233                                                 <para>R/O returns the linkedid if available, otherwise returns the uniqueid.</para>
234                                         </enum>
235                                 </enumlist>
236                                 <para><emphasis>chan_sip</emphasis> provides the following additional options:</para>
237                                 <enumlist>
238                                         <enum name="peerip">
239                                                 <para>R/O Get the IP address of the peer.</para>
240                                         </enum>
241                                         <enum name="recvip">
242                                                 <para>R/O Get the source IP address of the peer.</para>
243                                         </enum>
244                                         <enum name="recvport">
245                                                 <para>R/O Get the source port of the peer.</para>
246                                         </enum>
247                                         <enum name="from">
248                                                 <para>R/O Get the URI from the From: header.</para>
249                                         </enum>
250                                         <enum name="uri">
251                                                 <para>R/O Get the URI from the Contact: header.</para>
252                                         </enum>
253                                         <enum name="useragent">
254                                                 <para>R/O Get the useragent.</para>
255                                         </enum>
256                                         <enum name="peername">
257                                                 <para>R/O Get the name of the peer.</para>
258                                         </enum>
259                                         <enum name="t38passthrough">
260                                                 <para>R/O <literal>1</literal> if T38 is offered or enabled in this channel,
261                                                 otherwise <literal>0</literal></para>
262                                         </enum>
263                                         <enum name="rtpqos">
264                                                 <para>R/O Get QOS information about the RTP stream</para>
265                                                 <para>    This option takes two additional arguments:</para>
266                                                 <para>    Argument 1:</para>
267                                                 <para>     <literal>audio</literal>             Get data about the audio stream</para>
268                                                 <para>     <literal>video</literal>             Get data about the video stream</para>
269                                                 <para>     <literal>text</literal>              Get data about the text stream</para>
270                                                 <para>    Argument 2:</para>
271                                                 <para>     <literal>local_ssrc</literal>        Local SSRC (stream ID)</para>
272                                                 <para>     <literal>local_lostpackets</literal> Local lost packets</para>
273                                                 <para>     <literal>local_jitter</literal>      Local calculated jitter</para>
274                                                 <para>     <literal>local_maxjitter</literal>   Local calculated jitter (maximum)</para>
275                                                 <para>     <literal>local_minjitter</literal>   Local calculated jitter (minimum)</para>
276                                                 <para>     <literal>local_normdevjitter</literal>Local calculated jitter (normal deviation)</para>
277                                                 <para>     <literal>local_stdevjitter</literal> Local calculated jitter (standard deviation)</para>
278                                                 <para>     <literal>local_count</literal>       Number of received packets</para>
279                                                 <para>     <literal>remote_ssrc</literal>       Remote SSRC (stream ID)</para>
280                                                 <para>     <literal>remote_lostpackets</literal>Remote lost packets</para>
281                                                 <para>     <literal>remote_jitter</literal>     Remote reported jitter</para>
282                                                 <para>     <literal>remote_maxjitter</literal>  Remote calculated jitter (maximum)</para>
283                                                 <para>     <literal>remote_minjitter</literal>  Remote calculated jitter (minimum)</para>
284                                                 <para>     <literal>remote_normdevjitter</literal>Remote calculated jitter (normal deviation)</para>
285                                                 <para>     <literal>remote_stdevjitter</literal>Remote calculated jitter (standard deviation)</para>
286                                                 <para>     <literal>remote_count</literal>      Number of transmitted packets</para>
287                                                 <para>     <literal>rtt</literal>               Round trip time</para>
288                                                 <para>     <literal>maxrtt</literal>            Round trip time (maximum)</para>
289                                                 <para>     <literal>minrtt</literal>            Round trip time (minimum)</para>
290                                                 <para>     <literal>normdevrtt</literal>        Round trip time (normal deviation)</para>
291                                                 <para>     <literal>stdevrtt</literal>          Round trip time (standard deviation)</para>
292                                                 <para>     <literal>all</literal>               All statistics (in a form suited to logging,
293                                                 but not for parsing)</para>
294                                         </enum>
295                                         <enum name="rtpdest">
296                                                 <para>R/O Get remote RTP destination information.</para>
297                                                 <para>   This option takes one additional argument:</para>
298                                                 <para>    Argument 1:</para>
299                                                 <para>     <literal>audio</literal>             Get audio destination</para>
300                                                 <para>     <literal>video</literal>             Get video destination</para>
301                                                 <para>     <literal>text</literal>              Get text destination</para>
302                                                 <para>   Defaults to <literal>audio</literal> if unspecified.</para>
303                                         </enum>
304                                         <enum name="rtpsource">
305                                                 <para>R/O Get source RTP destination information.</para>
306                                                 <para>   This option takes one additional argument:</para>
307                                                 <para>    Argument 1:</para>
308                                                 <para>     <literal>audio</literal>             Get audio destination</para>
309                                                 <para>     <literal>video</literal>             Get video destination</para>
310                                                 <para>     <literal>text</literal>              Get text destination</para>
311                                                 <para>   Defaults to <literal>audio</literal> if unspecified.</para>
312                                         </enum>
313                                 </enumlist>
314                                 <xi:include xpointer="xpointer(/docs/info[@name='PJSIPCHANNEL'])" />
315                                 <para><emphasis>chan_iax2</emphasis> provides the following additional options:</para>
316                                 <enumlist>
317                                         <enum name="osptoken">
318                                                 <para>R/O Get the peer's osptoken.</para>
319                                         </enum>
320                                         <enum name="peerip">
321                                                 <para>R/O Get the peer's ip address.</para>
322                                         </enum>
323                                         <enum name="peername">
324                                                 <para>R/O Get the peer's username.</para>
325                                         </enum>
326                                         <enum name="secure_signaling">
327                                                 <para>R/O Get the if the IAX channel is secured.</para>
328                                         </enum>
329                                         <enum name="secure_media">
330                                                 <para>R/O Get the if the IAX channel is secured.</para>
331                                         </enum>
332                                 </enumlist>
333                                 <para><emphasis>chan_dahdi</emphasis> provides the following additional options:</para>
334                                 <enumlist>
335                                         <enum name="dahdi_channel">
336                                                 <para>R/O DAHDI channel related to this channel.</para>
337                                         </enum>
338                                         <enum name="dahdi_span">
339                                                 <para>R/O DAHDI span related to this channel.</para>
340                                         </enum>
341                                         <enum name="dahdi_type">
342                                                 <para>R/O DAHDI channel type, one of:</para>
343                                                 <enumlist>
344                                                         <enum name="analog" />
345                                                         <enum name="mfc/r2" />
346                                                         <enum name="pri" />
347                                                         <enum name="pseudo" />
348                                                         <enum name="ss7" />
349                                                 </enumlist>
350                                         </enum>
351                                         <enum name="keypad_digits">
352                                                 <para>R/O PRI Keypad digits that came in with the SETUP message.</para>
353                                         </enum>
354                                         <enum name="reversecharge">
355                                                 <para>R/O PRI Reverse Charging Indication, one of:</para>
356                                                 <enumlist>
357                                                         <enum name="-1"> <para>None</para></enum>
358                                                         <enum name=" 1"> <para>Reverse Charging Requested</para></enum>
359                                                 </enumlist>
360                                         </enum>
361                                         <enum name="no_media_path">
362                                                 <para>R/O PRI Nonzero if the channel has no B channel.
363                                                 The channel is either on hold or a call waiting call.</para>
364                                         </enum>
365                                         <enum name="buffers">
366                                                 <para>W/O Change the channel's buffer policy (for the current call only)</para>
367                                                 <para>This option takes two arguments:</para>
368                                                 <para>  Number of buffers,</para>
369                                                 <para>  Buffer policy being one of:</para>
370                                                 <para>      <literal>full</literal></para>
371                                                 <para>      <literal>immediate</literal></para>
372                                                 <para>      <literal>half</literal></para>
373                                         </enum>
374                                         <enum name="echocan_mode">
375                                                 <para>W/O Change the configuration of the active echo
376                                                 canceller on the channel (if any), for the current call
377                                                 only.</para>
378                                                 <para>Possible values are:</para>
379                                                 <para>  <literal>on</literal>   Normal mode (the echo canceller is actually reinitalized)</para>
380                                                 <para>  <literal>off</literal>  Disabled</para>
381                                                 <para>  <literal>fax</literal>  FAX/data mode (NLP disabled if possible, otherwise
382                                                         completely disabled)</para>
383                                                 <para>  <literal>voice</literal>        Voice mode (returns from FAX mode, reverting the changes that were made)</para>
384                                         </enum>
385                                 </enumlist>
386                                 <para><emphasis>chan_ooh323</emphasis> provides the following additional options:</para>
387                                 <enumlist>
388                                         <enum name="faxdetect">
389                                                 <para>R/W Fax Detect</para>
390                                                 <para>Returns 0 or 1</para>
391                                                 <para>Write yes or no</para>
392                                         </enum>
393                                         <enum name="t38support">
394                                                 <para>R/W t38support</para>
395                                                 <para>Returns 0 or 1</para>
396                                                 <para>Write yes or no</para>
397                                         </enum>
398                                         <enum name="h323id_url">
399                                                 <para>R/0 Returns caller URL</para>
400                                         </enum>
401                                         <enum name="caller_h323id">
402                                                 <para>R/0 Returns caller h323id</para>
403                                         </enum>
404                                         <enum name="caller_dialeddigits">
405                                                 <para>R/0 Returns caller dialed digits</para>
406                                         </enum>
407                                         <enum name="caller_email">
408                                                 <para>R/0 Returns caller email</para>
409                                         </enum>
410                                         <enum name="callee_email">
411                                                 <para>R/0 Returns callee email</para>
412                                         </enum>
413                                         <enum name="callee_dialeddigits">
414                                                 <para>R/0 Returns callee dialed digits</para>
415                                         </enum>
416                                         <enum name="caller_url">
417                                                 <para>R/0 Returns caller URL</para>
418                                         </enum>
419                                         <enum name="max_forwards">
420                                                 <para>R/W Get or set the maximum number of call forwards for this channel.
421
422                                                 This number describes the number of times a call may be forwarded by this channel
423                                                 before the call fails. "Forwards" in this case refers to redirects by phones as well
424                                                 as calls to local channels.
425
426                                                 Note that this has no relation to the SIP Max-Forwards header.
427                                                 </para>
428                                         </enum>
429                                 </enumlist>
430                         </parameter>
431                 </syntax>
432                 <description>
433                         <para>Gets/sets various pieces of information about the channel, additional <replaceable>item</replaceable> may
434                         be available from the channel driver; see its documentation for details. Any <replaceable>item</replaceable>
435                         requested that is not available on the current channel will return an empty string.</para>
436                 </description>
437         </function>
438  ***/
439
440 #define locked_copy_string(chan, dest, source, len) \
441         do { \
442                 ast_channel_lock(chan); \
443                 ast_copy_string(dest, source, len); \
444                 ast_channel_unlock(chan); \
445         } while (0)
446 #define locked_string_field_set(chan, field, source) \
447         do { \
448                 ast_channel_lock(chan); \
449                 ast_channel_##field##_set(chan, source); \
450                 ast_channel_unlock(chan); \
451         } while (0)
452
453 static const char * const transfercapability_table[0x20] = {
454         "SPEECH", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
455         "DIGITAL", "RESTRICTED_DIGITAL", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
456         "3K1AUDIO", "DIGITAL_W_TONES", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK",
457         "VIDEO", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", "UNK", };
458
459 static int func_channel_read(struct ast_channel *chan, const char *function,
460                              char *data, char *buf, size_t len)
461 {
462         int ret = 0;
463         struct ast_format_cap *tmpcap;
464
465         if (!chan) {
466                 ast_log(LOG_WARNING, "No channel was provided to %s function.\n", function);
467                 return -1;
468         }
469
470         if (!strcasecmp(data, "audionativeformat")) {
471                 tmpcap = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
472                 if (tmpcap) {
473                         struct ast_str *codec_buf = ast_str_alloca(AST_FORMAT_CAP_NAMES_LEN);
474
475                         ast_channel_lock(chan);
476                         ast_format_cap_append_from_cap(tmpcap, ast_channel_nativeformats(chan), AST_MEDIA_TYPE_AUDIO);
477                         ast_channel_unlock(chan);
478                         ast_copy_string(buf, ast_format_cap_get_names(tmpcap, &codec_buf), len);
479                         ao2_ref(tmpcap, -1);
480                 }
481         } else if (!strcasecmp(data, "videonativeformat")) {
482                 tmpcap = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
483                 if (tmpcap) {
484                         struct ast_str *codec_buf = ast_str_alloca(AST_FORMAT_CAP_NAMES_LEN);
485
486                         ast_channel_lock(chan);
487                         ast_format_cap_append_from_cap(tmpcap, ast_channel_nativeformats(chan), AST_MEDIA_TYPE_VIDEO);
488                         ast_channel_unlock(chan);
489                         ast_copy_string(buf, ast_format_cap_get_names(tmpcap, &codec_buf), len);
490                         ao2_ref(tmpcap, -1);
491                 }
492         } else if (!strcasecmp(data, "audioreadformat")) {
493                 locked_copy_string(chan, buf, ast_format_get_name(ast_channel_readformat(chan)), len);
494         } else if (!strcasecmp(data, "audiowriteformat")) {
495                 locked_copy_string(chan, buf, ast_format_get_name(ast_channel_writeformat(chan)), len);
496 #ifdef CHANNEL_TRACE
497         } else if (!strcasecmp(data, "trace")) {
498                 locked_copy_string(chan, buf, ast_channel_trace_is_enabled(chan) ? "1" : "0", len);
499 #endif
500         } else if (!strcasecmp(data, "tonezone") && ast_channel_zone(chan)) {
501                 locked_copy_string(chan, buf, ast_channel_zone(chan)->country, len);
502         } else if (!strcasecmp(data, "dtmf_features")) {
503                 if (ast_bridge_features_ds_get_string(chan, buf, len)) {
504                         buf[0] = '\0';
505                 }
506         } else if (!strcasecmp(data, "language"))
507                 locked_copy_string(chan, buf, ast_channel_language(chan), len);
508         else if (!strcasecmp(data, "musicclass"))
509                 locked_copy_string(chan, buf, ast_channel_musicclass(chan), len);
510         else if (!strcasecmp(data, "name")) {
511                 locked_copy_string(chan, buf, ast_channel_name(chan), len);
512         } else if (!strcasecmp(data, "parkinglot"))
513                 locked_copy_string(chan, buf, ast_channel_parkinglot(chan), len);
514         else if (!strcasecmp(data, "state"))
515                 locked_copy_string(chan, buf, ast_state2str(ast_channel_state(chan)), len);
516         else if (!strcasecmp(data, "onhold")) {
517                 locked_copy_string(chan, buf,
518                         ast_channel_hold_state(chan) == AST_CONTROL_HOLD ? "1" : "0", len);
519         } else if (!strcasecmp(data, "channeltype"))
520                 locked_copy_string(chan, buf, ast_channel_tech(chan)->type, len);
521         else if (!strcasecmp(data, "accountcode"))
522                 locked_copy_string(chan, buf, ast_channel_accountcode(chan), len);
523         else if (!strcasecmp(data, "checkhangup")) {
524                 locked_copy_string(chan, buf, ast_check_hangup(chan) ? "1" : "0", len);
525         } else if (!strcasecmp(data, "peeraccount"))
526                 locked_copy_string(chan, buf, ast_channel_peeraccount(chan), len);
527         else if (!strcasecmp(data, "hangupsource"))
528                 locked_copy_string(chan, buf, ast_channel_hangupsource(chan), len);
529         else if (!strcasecmp(data, "appname") && ast_channel_appl(chan))
530                 locked_copy_string(chan, buf, ast_channel_appl(chan), len);
531         else if (!strcasecmp(data, "appdata") && ast_channel_data(chan))
532                 locked_copy_string(chan, buf, ast_channel_data(chan), len);
533         else if (!strcasecmp(data, "exten") && ast_channel_data(chan))
534                 locked_copy_string(chan, buf, ast_channel_exten(chan), len);
535         else if (!strcasecmp(data, "context") && ast_channel_data(chan))
536                 locked_copy_string(chan, buf, ast_channel_context(chan), len);
537         else if (!strcasecmp(data, "userfield") && ast_channel_data(chan))
538                 locked_copy_string(chan, buf, ast_channel_userfield(chan), len);
539         else if (!strcasecmp(data, "channame") && ast_channel_data(chan))
540                 locked_copy_string(chan, buf, ast_channel_name(chan), len);
541         else if (!strcasecmp(data, "linkedid")) {
542                 ast_channel_lock(chan);
543                 if (ast_strlen_zero(ast_channel_linkedid(chan))) {
544                         /* fall back on the channel's uniqueid if linkedid is unset */
545                         ast_copy_string(buf, ast_channel_uniqueid(chan), len);
546                 }
547                 else {
548                         ast_copy_string(buf, ast_channel_linkedid(chan), len);
549                 }
550                 ast_channel_unlock(chan);
551         } else if (!strcasecmp(data, "peer")) {
552                 struct ast_channel *peer;
553
554                 peer = ast_channel_bridge_peer(chan);
555                 if (peer) {
556                         /* Only real channels could have a bridge peer this way. */
557                         ast_channel_lock(peer);
558                         ast_copy_string(buf, ast_channel_name(peer), len);
559                         ast_channel_unlock(peer);
560                         ast_channel_unref(peer);
561                 } else {
562                         buf[0] = '\0';
563                         ast_channel_lock(chan);
564                         if (!ast_channel_tech(chan)) {
565                                 const char *pname;
566
567                                 /*
568                                  * A dummy channel can still pass along bridged peer info
569                                  * via the BRIDGEPEER variable.
570                                  *
571                                  * A horrible kludge, but... how else?
572                                  */
573                                 pname = pbx_builtin_getvar_helper(chan, "BRIDGEPEER");
574                                 if (!ast_strlen_zero(pname)) {
575                                         ast_copy_string(buf, pname, len);
576                                 }
577                         }
578                         ast_channel_unlock(chan);
579                 }
580         } else if (!strcasecmp(data, "uniqueid")) {
581                 locked_copy_string(chan, buf, ast_channel_uniqueid(chan), len);
582         } else if (!strcasecmp(data, "transfercapability")) {
583                 locked_copy_string(chan, buf, transfercapability_table[ast_channel_transfercapability(chan) & 0x1f], len);
584         } else if (!strcasecmp(data, "callgroup")) {
585                 char groupbuf[256];
586
587                 locked_copy_string(chan, buf,  ast_print_group(groupbuf, sizeof(groupbuf), ast_channel_callgroup(chan)), len);
588         } else if (!strcasecmp(data, "pickupgroup")) {
589                 char groupbuf[256];
590
591                 locked_copy_string(chan, buf,  ast_print_group(groupbuf, sizeof(groupbuf), ast_channel_pickupgroup(chan)), len);
592         } else if (!strcasecmp(data, "namedcallgroup")) {
593                 struct ast_str *tmp_str = ast_str_alloca(1024);
594
595                 locked_copy_string(chan, buf,  ast_print_namedgroups(&tmp_str, ast_channel_named_callgroups(chan)), len);
596         } else if (!strcasecmp(data, "namedpickupgroup")) {
597                 struct ast_str *tmp_str = ast_str_alloca(1024);
598
599                 locked_copy_string(chan, buf,  ast_print_namedgroups(&tmp_str, ast_channel_named_pickupgroups(chan)), len);
600         } else if (!strcasecmp(data, "after_bridge_goto")) {
601                 ast_bridge_read_after_goto(chan, buf, len);
602         } else if (!strcasecmp(data, "amaflags")) {
603                 ast_channel_lock(chan);
604                 snprintf(buf, len, "%u", ast_channel_amaflags(chan));
605                 ast_channel_unlock(chan);
606         } else if (!strncasecmp(data, "secure_bridge_", 14)) {
607                 struct ast_datastore *ds;
608
609                 buf[0] = '\0';
610                 ast_channel_lock(chan);
611                 if ((ds = ast_channel_datastore_find(chan, &secure_call_info, NULL))) {
612                         struct ast_secure_call_store *encrypt = ds->data;
613
614                         if (!strcasecmp(data, "secure_bridge_signaling")) {
615                                 snprintf(buf, len, "%s", encrypt->signaling ? "1" : "");
616                         } else if (!strcasecmp(data, "secure_bridge_media")) {
617                                 snprintf(buf, len, "%s", encrypt->media ? "1" : "");
618                         }
619                 }
620                 ast_channel_unlock(chan);
621         } else if (!strcasecmp(data, "max_forwards")) {
622                 ast_channel_lock(chan);
623                 snprintf(buf, len, "%d", ast_max_forwards_get(chan));
624                 ast_channel_unlock(chan);
625         } else if (!ast_channel_tech(chan) || !ast_channel_tech(chan)->func_channel_read || ast_channel_tech(chan)->func_channel_read(chan, function, data, buf, len)) {
626                 ast_log(LOG_WARNING, "Unknown or unavailable item requested: '%s'\n", data);
627                 ret = -1;
628         }
629
630         return ret;
631 }
632
633 static int func_channel_write_real(struct ast_channel *chan, const char *function,
634                               char *data, const char *value)
635 {
636         int ret = 0;
637         signed char gainset;
638
639         if (!strcasecmp(data, "language"))
640                 locked_string_field_set(chan, language, value);
641         else if (!strcasecmp(data, "parkinglot"))
642                 locked_string_field_set(chan, parkinglot, value);
643         else if (!strcasecmp(data, "musicclass"))
644                 locked_string_field_set(chan, musicclass, value);
645         else if (!strcasecmp(data, "accountcode"))
646                 locked_string_field_set(chan, accountcode, value);
647         else if (!strcasecmp(data, "userfield"))
648                 locked_string_field_set(chan, userfield, value);
649         else if (!strcasecmp(data, "after_bridge_goto")) {
650                 if (ast_strlen_zero(value)) {
651                         ast_bridge_discard_after_goto(chan);
652                 } else {
653                         ast_bridge_set_after_go_on(chan, ast_channel_context(chan), ast_channel_exten(chan), ast_channel_priority(chan), value);
654                 }
655         } else if (!strcasecmp(data, "amaflags")) {
656                 ast_channel_lock(chan);
657                 if (isdigit(*value)) {
658                         int amaflags;
659                         sscanf(value, "%30d", &amaflags);
660                         ast_channel_amaflags_set(chan, amaflags);
661                 } else if (!strcasecmp(value,"OMIT")){
662                         ast_channel_amaflags_set(chan, 1);
663                 } else if (!strcasecmp(value,"BILLING")){
664                         ast_channel_amaflags_set(chan, 2);
665                 } else if (!strcasecmp(value,"DOCUMENTATION")){
666                         ast_channel_amaflags_set(chan, 3);
667                 }
668                 ast_channel_unlock(chan);
669         } else if (!strcasecmp(data, "peeraccount"))
670                 locked_string_field_set(chan, peeraccount, value);
671         else if (!strcasecmp(data, "hangupsource"))
672                 /* XXX - should we be forcing this here? */
673                 ast_set_hangupsource(chan, value, 0);
674 #ifdef CHANNEL_TRACE
675         else if (!strcasecmp(data, "trace")) {
676                 ast_channel_lock(chan);
677                 if (ast_true(value))
678                         ret = ast_channel_trace_enable(chan);
679                 else if (ast_false(value))
680                         ret = ast_channel_trace_disable(chan);
681                 else {
682                         ret = -1;
683                         ast_log(LOG_WARNING, "Invalid value for CHANNEL(trace).\n");
684                 }
685                 ast_channel_unlock(chan);
686         }
687 #endif
688         else if (!strcasecmp(data, "tonezone")) {
689                 struct ast_tone_zone *new_zone;
690                 if (!(new_zone = ast_get_indication_zone(value))) {
691                         ast_log(LOG_ERROR, "Unknown country code '%s' for tonezone. Check indications.conf for available country codes.\n", value);
692                         ret = -1;
693                 } else {
694                         ast_channel_lock(chan);
695                         if (ast_channel_zone(chan)) {
696                                 ast_channel_zone_set(chan, ast_tone_zone_unref(ast_channel_zone(chan)));
697                         }
698                         ast_channel_zone_set(chan, ast_tone_zone_ref(new_zone));
699                         ast_channel_unlock(chan);
700                         new_zone = ast_tone_zone_unref(new_zone);
701                 }
702         } else if (!strcasecmp(data, "dtmf_features")) {
703                 ret = ast_bridge_features_ds_set_string(chan, value);
704         } else if (!strcasecmp(data, "callgroup")) {
705                 ast_channel_lock(chan);
706                 ast_channel_callgroup_set(chan, ast_get_group(value));
707                 ast_channel_unlock(chan);
708         } else if (!strcasecmp(data, "pickupgroup")) {
709                 ast_channel_lock(chan);
710                 ast_channel_pickupgroup_set(chan, ast_get_group(value));
711                 ast_channel_unlock(chan);
712         } else if (!strcasecmp(data, "namedcallgroup")) {
713                 struct ast_namedgroups *groups = ast_get_namedgroups(value);
714
715                 ast_channel_lock(chan);
716                 ast_channel_named_callgroups_set(chan, groups);
717                 ast_channel_unlock(chan);
718                 ast_unref_namedgroups(groups);
719         } else if (!strcasecmp(data, "namedpickupgroup")) {
720                 struct ast_namedgroups *groups = ast_get_namedgroups(value);
721
722                 ast_channel_lock(chan);
723                 ast_channel_named_pickupgroups_set(chan, groups);
724                 ast_channel_unlock(chan);
725                 ast_unref_namedgroups(groups);
726         } else if (!strcasecmp(data, "txgain")) {
727                 sscanf(value, "%4hhd", &gainset);
728                 ast_channel_setoption(chan, AST_OPTION_TXGAIN, &gainset, sizeof(gainset), 0);
729         } else if (!strcasecmp(data, "rxgain")) {
730                 sscanf(value, "%4hhd", &gainset);
731                 ast_channel_setoption(chan, AST_OPTION_RXGAIN, &gainset, sizeof(gainset), 0);
732         } else if (!strcasecmp(data, "transfercapability")) {
733                 unsigned short i;
734
735                 ast_channel_lock(chan);
736                 for (i = 0; i < 0x20; i++) {
737                         if (!strcasecmp(transfercapability_table[i], value) && strcmp(value, "UNK")) {
738                                 ast_channel_transfercapability_set(chan, i);
739                                 break;
740                         }
741                 }
742                 ast_channel_unlock(chan);
743         } else if (!strcasecmp(data, "hangup_handler_pop")) {
744                 /* Pop one hangup handler before pushing the new handler. */
745                 ast_pbx_hangup_handler_pop(chan);
746                 ast_pbx_hangup_handler_push(chan, value);
747         } else if (!strcasecmp(data, "hangup_handler_push")) {
748                 ast_pbx_hangup_handler_push(chan, value);
749         } else if (!strcasecmp(data, "hangup_handler_wipe")) {
750                 /* Pop all hangup handlers before pushing the new handler. */
751                 while (ast_pbx_hangup_handler_pop(chan)) {
752                 }
753                 ast_pbx_hangup_handler_push(chan, value);
754         } else if (!strncasecmp(data, "secure_bridge_", 14)) {
755                 struct ast_datastore *ds;
756                 struct ast_secure_call_store *store;
757
758                 if (!chan || !value) {
759                         return -1;
760                 }
761
762                 ast_channel_lock(chan);
763                 if (!(ds = ast_channel_datastore_find(chan, &secure_call_info, NULL))) {
764                         if (!(ds = ast_datastore_alloc(&secure_call_info, NULL))) {
765                                 ast_channel_unlock(chan);
766                                 return -1;
767                         }
768                         if (!(store = ast_calloc(1, sizeof(*store)))) {
769                                 ast_channel_unlock(chan);
770                                 ast_free(ds);
771                                 return -1;
772                         }
773                         ds->data = store;
774                         ast_channel_datastore_add(chan, ds);
775                 } else {
776                         store = ds->data;
777                 }
778
779                 if (!strcasecmp(data, "secure_bridge_signaling")) {
780                         store->signaling = ast_true(value) ? 1 : 0;
781                 } else if (!strcasecmp(data, "secure_bridge_media")) {
782                         store->media = ast_true(value) ? 1 : 0;
783                 }
784                 ast_channel_unlock(chan);
785         } else if (!strcasecmp(data, "max_forwards")) {
786                 int max_forwards;
787                 if (sscanf(value, "%d", &max_forwards) != 1) {
788                         ast_log(LOG_WARNING, "Unable to set max forwards to '%s'\n", value);
789                         ret = -1;
790                 } else {
791                         ast_channel_lock(chan);
792                         ret = ast_max_forwards_set(chan, max_forwards);
793                         ast_channel_unlock(chan);
794                 }
795         } else if (!ast_channel_tech(chan)->func_channel_write
796                  || ast_channel_tech(chan)->func_channel_write(chan, function, data, value)) {
797                 ast_log(LOG_WARNING, "Unknown or unavailable item requested: '%s'\n",
798                                 data);
799                 ret = -1;
800         }
801
802         return ret;
803 }
804
805 static int func_channel_write(struct ast_channel *chan, const char *function, char *data, const char *value)
806 {
807         int res;
808         ast_chan_write_info_t write_info = {
809                 .version = AST_CHAN_WRITE_INFO_T_VERSION,
810                 .write_fn = func_channel_write_real,
811                 .chan = chan,
812                 .function = function,
813                 .data = data,
814                 .value = value,
815         };
816
817         if (!chan) {
818                 ast_log(LOG_WARNING, "No channel was provided to %s function.\n", function);
819                 return -1;
820         }
821
822         res = func_channel_write_real(chan, function, data, value);
823         ast_channel_setoption(chan, AST_OPTION_CHANNEL_WRITE, &write_info, sizeof(write_info), 0);
824
825         return res;
826 }
827
828 static struct ast_custom_function channel_function = {
829         .name = "CHANNEL",
830         .read = func_channel_read,
831         .write = func_channel_write,
832 };
833
834 static int func_channels_read(struct ast_channel *chan, const char *function, char *data, char *buf, size_t maxlen)
835 {
836         struct ast_channel *c = NULL;
837         regex_t re;
838         int res;
839         size_t buflen = 0;
840         struct ast_channel_iterator *iter;
841
842         buf[0] = '\0';
843
844         if (!ast_strlen_zero(data)) {
845                 if ((res = regcomp(&re, data, REG_EXTENDED | REG_ICASE | REG_NOSUB))) {
846                         regerror(res, &re, buf, maxlen);
847                         ast_log(LOG_WARNING, "Error compiling regular expression for %s(%s): %s\n", function, data, buf);
848                         return -1;
849                 }
850         }
851
852         if (!(iter = ast_channel_iterator_all_new())) {
853                 if (!ast_strlen_zero(data)) {
854                         regfree(&re);
855                 }
856                 return -1;
857         }
858
859         while ((c = ast_channel_iterator_next(iter))) {
860                 ast_channel_lock(c);
861                 if (ast_strlen_zero(data) || regexec(&re, ast_channel_name(c), 0, NULL, 0) == 0) {
862                         size_t namelen = strlen(ast_channel_name(c));
863                         if (buflen + namelen + (ast_strlen_zero(buf) ? 0 : 1) + 1 < maxlen) {
864                                 if (!ast_strlen_zero(buf)) {
865                                         strcat(buf, " ");
866                                         buflen++;
867                                 }
868                                 strcat(buf, ast_channel_name(c));
869                                 buflen += namelen;
870                         } else {
871                                 ast_log(LOG_WARNING, "Number of channels exceeds the available buffer space.  Output will be truncated!\n");
872                         }
873                 }
874                 ast_channel_unlock(c);
875                 c = ast_channel_unref(c);
876         }
877
878         ast_channel_iterator_destroy(iter);
879
880         if (!ast_strlen_zero(data)) {
881                 regfree(&re);
882         }
883
884         return 0;
885 }
886
887 static struct ast_custom_function channels_function = {
888         .name = "CHANNELS",
889         .read = func_channels_read,
890 };
891
892 static int func_mchan_read(struct ast_channel *chan, const char *function,
893                              char *data, struct ast_str **buf, ssize_t len)
894 {
895         struct ast_channel *mchan;
896         char *template = ast_alloca(4 + strlen(data));
897
898         if (!chan) {
899                 ast_log(LOG_WARNING, "No channel was provided to %s function.\n", function);
900                 return -1;
901         }
902
903         mchan = ast_channel_get_by_name(ast_channel_linkedid(chan));
904         sprintf(template, "${%s}", data); /* SAFE */
905         ast_str_substitute_variables(buf, len, mchan ? mchan : chan, template);
906         if (mchan) {
907                 ast_channel_unref(mchan);
908         }
909         return 0;
910 }
911
912 static int func_mchan_write(struct ast_channel *chan, const char *function,
913                               char *data, const char *value)
914 {
915         struct ast_channel *mchan;
916
917         if (!chan) {
918                 ast_log(LOG_WARNING, "No channel was provided to %s function.\n", function);
919                 return -1;
920         }
921
922         mchan = ast_channel_get_by_name(ast_channel_linkedid(chan));
923         pbx_builtin_setvar_helper(mchan ? mchan : chan, data, value);
924         if (mchan) {
925                 ast_channel_unref(mchan);
926         }
927         return 0;
928 }
929
930 static struct ast_custom_function mchan_function = {
931         .name = "MASTER_CHANNEL",
932         .read2 = func_mchan_read,
933         .write = func_mchan_write,
934 };
935
936 static int unload_module(void)
937 {
938         int res = 0;
939
940         res |= ast_custom_function_unregister(&channel_function);
941         res |= ast_custom_function_unregister(&channels_function);
942         res |= ast_custom_function_unregister(&mchan_function);
943
944         return res;
945 }
946
947 static int load_module(void)
948 {
949         int res = 0;
950
951         res |= ast_custom_function_register(&channel_function);
952         res |= ast_custom_function_register(&channels_function);
953         res |= ast_custom_function_register(&mchan_function);
954
955         return res;
956 }
957
958 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Channel information dialplan functions");