« back to all changes in this revision
Viewing changes to doc/core-en_US.xml
- browse files at revision 51
- compare with another revision
- download diff
- download tarball
- view history from revision 51
- Committer: Bazaar Package Importer
- Author(s): Dave Walker (Daviey)
- Date: 2009-09-22 16:22:14 UTC
- mfrom: (1.2.4 upstream)
- Revision ID: james.westby@ubuntu.com-20090922162214-awce8id0lt9v51jb
Tags: 1:1.6.2.0~rc2-0ubuntu1
* New upstream version, upstream is now DFSG compliant.
- ilibc has been removed upstream.
- Music on Hold is now cc-by-sa.
- binary firmware iaxy.bin has been removed upstream.
* debian/rules: Santitised UPSTREAM variable for compatiability
with Ubuntu and other variants.
* debian/control: Removed Debian Vcs-Svn entry and replaced
with ubuntu-voip Vcs-Bzr, to reflect divergence in packages.
* patches/makefile_appdocs_dtd: Removed, merged upstream.
* patches/disable_moh: Previosly disabled, removed from pool.
* patches/ubuntu-banner: Ported debian-banner to display Ubuntu
centric bug report information.
* Refresh quilt patches
- files added:
- autoconf/libcurl.m4
- files removed:
- apps/.app_adsiprog.makeopts
- contrib/firmware
- contrib/firmware/iax
- files modified:
- .version
added
removed
doc/core-en_US.xml
1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE docs SYSTEM "appdocsxml.dtd">
3
<docs xmlns:xi="http://www.w3.org/2001/XInclude">
4
<application name="AgentLogin" language="en_US">
5
<synopsis>
6
Call agent login.
7
</synopsis>
8
<syntax>
9
<parameter name="AgentNo" />
10
<parameter name="options">
11
<optionlist>
12
<option name="s">
13
<para>silent login - do not announce the login ok segment after
14
agent logged on/off</para>
15
</option>
16
</optionlist>
17
</parameter>
18
</syntax>
19
<description>
20
<para>Asks the agent to login to the system. Always returns <literal>-1</literal>.
21
While logged in, the agent can receive calls and will hear a <literal>beep</literal>
22
when a new call comes in. The agent can dump the call by pressing the star key.</para>
23
</description>
24
<see-also>
25
<ref type="application">Queue</ref>
26
<ref type="application">AddQueueMember</ref>
27
<ref type="application">RemoveQueueMember</ref>
28
<ref type="application">PauseQueueMember</ref>
29
<ref type="application">UnpauseQueueMember</ref>
30
<ref type="function">AGENT</ref>
31
<ref type="filename">agents.conf</ref>
32
<ref type="filename">queues.conf</ref>
33
</see-also>
34
</application>
35
<application name="AgentMonitorOutgoing" language="en_US">
36
<synopsis>
37
Record agent's outgoing call.
38
</synopsis>
39
<syntax>
40
<parameter name="options">
41
<optionlist>
42
<option name="d">
43
<para>make the app return <literal>-1</literal> if there is an error condition.</para>
44
</option>
45
<option name="c">
46
<para>change the CDR so that the source of the call is
47
<literal>Agent/agent_id</literal></para>
48
</option>
49
<option name="n">
50
<para>don't generate the warnings when there is no callerid or the
51
agentid is not known. It's handy if you want to have one context
52
for agent and non-agent calls.</para>
53
</option>
54
</optionlist>
55
</parameter>
56
</syntax>
57
<description>
58
<para>Tries to figure out the id of the agent who is placing outgoing call based on
59
comparison of the callerid of the current interface and the global variable
60
placed by the AgentCallbackLogin application. That's why it should be used only
61
with the AgentCallbackLogin app. Uses the monitoring functions in chan_agent
62
instead of Monitor application. That has to be configured in the
63
<filename>agents.conf</filename> file.</para>
64
<para>Normally the app returns <literal>0</literal> unless the options are passed.</para>
65
</description>
66
<see-also>
67
<ref type="filename">agents.conf</ref>
68
</see-also>
69
</application>
70
<function name="AGENT" language="en_US">
71
<synopsis>
72
Gets information about an Agent
73
</synopsis>
74
<syntax argsep=":">
75
<parameter name="agentid" required="true" />
76
<parameter name="item">
77
<para>The valid items to retrieve are:</para>
78
<enumlist>
79
<enum name="status">
80
<para>(default) The status of the agent (LOGGEDIN | LOGGEDOUT)</para>
81
</enum>
82
<enum name="password">
83
<para>The password of the agent</para>
84
</enum>
85
<enum name="name">
86
<para>The name of the agent</para>
87
</enum>
88
<enum name="mohclass">
89
<para>MusicOnHold class</para>
90
</enum>
91
<enum name="exten">
92
<para>The callback extension for the Agent (AgentCallbackLogin)</para>
93
</enum>
94
<enum name="channel">
95
<para>The name of the active channel for the Agent (AgentLogin)</para>
96
</enum>
97
</enumlist>
98
</parameter>
99
</syntax>
100
<description />
101
</function>
102
<application name="DAHDISendKeypadFacility" language="en_US">
103
<synopsis>
104
Send digits out of band over a PRI.
105
</synopsis>
106
<syntax>
107
<parameter name="digits" required="true" />
108
</syntax>
109
<description>
110
<para>This application will send the given string of digits in a Keypad
111
Facility IE over the current channel.</para>
112
</description>
113
</application>
114
<application name="DAHDISendCallreroutingFacility" language="en_US">
115
<synopsis>
116
Send QSIG call rerouting facility over a PRI.
117
</synopsis>
118
<syntax argsep=",">
119
<parameter name="destination" required="true">
120
<para>Destination number.</para>
121
</parameter>
122
<parameter name="original">
123
<para>Original called number.</para>
124
</parameter>
125
<parameter name="reason">
126
<para>Diversion reason, if not specified defaults to <literal>unknown</literal></para>
127
</parameter>
128
</syntax>
129
<description>
130
<para>This application will send a Callrerouting Facility IE over the
131
current channel.</para>
132
</description>
133
</application>
134
<application name="DAHDIAcceptR2Call" language="en_US">
135
<synopsis>
136
Accept an R2 call if its not already accepted (you still need to answer it)
137
</synopsis>
138
<syntax>
139
<parameter name="charge" required="true">
140
<para>Yes or No.</para>
141
<para>Whether you want to accept the call with charge or without charge.</para>
142
</parameter>
143
</syntax>
144
<description>
145
<para>This application will Accept the R2 call either with charge or no charge.</para>
146
</description>
147
</application>
148
<application name="IAX2Provision" language="en_US">
149
<synopsis>
150
Provision a calling IAXy with a given template.
151
</synopsis>
152
<syntax>
153
<parameter name="template">
154
<para>If not specified, defaults to <literal>default</literal>.</para>
155
</parameter>
156
</syntax>
157
<description>
158
<para>Provisions the calling IAXy (assuming the calling entity is in fact an IAXy) with the
159
given <replaceable>template</replaceable>. Returns <literal>-1</literal> on error
160
or <literal>0</literal> on success.</para>
161
</description>
162
</application>
163
<function name="IAXPEER" language="en_US">
164
<synopsis>
165
Gets IAX peer information.
166
</synopsis>
167
<syntax>
168
<parameter name="peername" required="true">
169
<enumlist>
170
<enum name="CURRENTCHANNEL">
171
<para>If <replaceable>peername</replaceable> is specified to this value, return the IP address of the
172
endpoint of the current channel</para>
173
</enum>
174
</enumlist>
175
</parameter>
176
<parameter name="item">
177
<para>If <replaceable>peername</replaceable> is specified, valid items are:</para>
178
<enumlist>
179
<enum name="ip">
180
<para>(default) The IP address.</para>
181
</enum>
182
<enum name="status">
183
<para>The peer's status (if <literal>qualify=yes</literal>)</para>
184
</enum>
185
<enum name="mailbox">
186
<para>The configured mailbox.</para>
187
</enum>
188
<enum name="context">
189
<para>The configured context.</para>
190
</enum>
191
<enum name="expire">
192
<para>The epoch time of the next expire.</para>
193
</enum>
194
<enum name="dynamic">
195
<para>Is it dynamic? (yes/no).</para>
196
</enum>
197
<enum name="callerid_name">
198
<para>The configured Caller ID name.</para>
199
</enum>
200
<enum name="callerid_num">
201
<para>The configured Caller ID number.</para>
202
</enum>
203
<enum name="codecs">
204
<para>The configured codecs.</para>
205
</enum>
206
<enum name="codec[x]">
207
<para>Preferred codec index number <replaceable>x</replaceable> (beginning
208
with <literal>0</literal>)</para>
209
</enum>
210
</enumlist>
211
</parameter>
212
</syntax>
213
<description />
214
<see-also>
215
<ref type="function">SIPPEER</ref>
216
</see-also>
217
</function>
218
<function name="IAXVAR" language="en_US">
219
<synopsis>
220
Sets or retrieves a remote variable.
221
</synopsis>
222
<syntax>
223
<parameter name="varname" required="true" />
224
</syntax>
225
<description />
226
</function>
227
<application name="SIPDtmfMode" language="en_US">
228
<synopsis>
229
Change the dtmfmode for a SIP call.
230
</synopsis>
231
<syntax>
232
<parameter name="mode" required="true">
233
<enumlist>
234
<enum name="inband" />
235
<enum name="info" />
236
<enum name="rfc2833" />
237
</enumlist>
238
</parameter>
239
</syntax>
240
<description>
241
<para>Changes the dtmfmode for a SIP call.</para>
242
</description>
243
</application>
244
<application name="SIPAddHeader" language="en_US">
245
<synopsis>
246
Add a SIP header to the outbound call.
247
</synopsis>
248
<syntax argsep=":">
249
<parameter name="Header" required="true" />
250
<parameter name="Content" required="true" />
251
</syntax>
252
<description>
253
<para>Adds a header to a SIP call placed with DIAL.</para>
254
<para>Remember to use the X-header if you are adding non-standard SIP
255
headers, like <literal>X-Asterisk-Accountcode:</literal>. Use this with care.
256
Adding the wrong headers may jeopardize the SIP dialog.</para>
257
<para>Always returns <literal>0</literal>.</para>
258
</description>
259
</application>
260
<application name="SIPRemoveHeader" language="en_US">
261
<synopsis>
262
Remove SIP headers previously added with SIPAddHeader
263
</synopsis>
264
<syntax>
265
<parameter name="Header" required="false" />
266
</syntax>
267
<description>
268
<para>SIPRemoveHeader() allows you to remove headers which were previously
269
added with SIPAddHeader(). If no parameter is supplied, all previously added
270
headers will be removed. If a parameter is supplied, only the matching headers
271
will be removed.</para>
272
<para>For example you have added these 2 headers:</para>
273
<para>SIPAddHeader(P-Asserted-Identity: sip:foo@bar);</para>
274
<para>SIPAddHeader(P-Preferred-Identity: sip:bar@foo);</para>
275
<para></para>
276
<para>// remove all headers</para>
277
<para>SIPRemoveHeader();</para>
278
<para>// remove all P- headers</para>
279
<para>SIPRemoveHeader(P-);</para>
280
<para>// remove only the PAI header (note the : at the end)</para>
281
<para>SIPRemoveHeader(P-Asserted-Identity:);</para>
282
<para></para>
283
<para>Always returns <literal>0</literal>.</para>
284
</description>
285
</application>
286
<function name="SIP_HEADER" language="en_US">
287
<synopsis>
288
Gets the specified SIP header.
289
</synopsis>
290
<syntax>
291
<parameter name="name" required="true" />
292
<parameter name="number">
293
<para>If not specified, defaults to <literal>1</literal>.</para>
294
</parameter>
295
</syntax>
296
<description>
297
<para>Since there are several headers (such as Via) which can occur multiple
298
times, SIP_HEADER takes an optional second argument to specify which header with
299
that name to retrieve. Headers start at offset <literal>1</literal>.</para>
300
</description>
301
</function>
302
<function name="SIPPEER" language="en_US">
303
<synopsis>
304
Gets SIP peer information.
305
</synopsis>
306
<syntax>
307
<parameter name="peername" required="true" />
308
<parameter name="item">
309
<enumlist>
310
<enum name="ip">
311
<para>(default) The ip address.</para>
312
</enum>
313
<enum name="port">
314
<para>The port number.</para>
315
</enum>
316
<enum name="mailbox">
317
<para>The configured mailbox.</para>
318
</enum>
319
<enum name="context">
320
<para>The configured context.</para>
321
</enum>
322
<enum name="expire">
323
<para>The epoch time of the next expire.</para>
324
</enum>
325
<enum name="dynamic">
326
<para>Is it dynamic? (yes/no).</para>
327
</enum>
328
<enum name="callerid_name">
329
<para>The configured Caller ID name.</para>
330
</enum>
331
<enum name="callerid_num">
332
<para>The configured Caller ID number.</para>
333
</enum>
334
<enum name="callgroup">
335
<para>The configured Callgroup.</para>
336
</enum>
337
<enum name="pickupgroup">
338
<para>The configured Pickupgroup.</para>
339
</enum>
340
<enum name="codecs">
341
<para>The configured codecs.</para>
342
</enum>
343
<enum name="status">
344
<para>Status (if qualify=yes).</para>
345
</enum>
346
<enum name="regexten">
347
<para>Registration extension.</para>
348
</enum>
349
<enum name="limit">
350
<para>Call limit (call-limit).</para>
351
</enum>
352
<enum name="busylevel">
353
<para>Configured call level for signalling busy.</para>
354
</enum>
355
<enum name="curcalls">
356
<para>Current amount of calls. Only available if call-limit is set.</para>
357
</enum>
358
<enum name="language">
359
<para>Default language for peer.</para>
360
</enum>
361
<enum name="accountcode">
362
<para>Account code for this peer.</para>
363
</enum>
364
<enum name="useragent">
365
<para>Current user agent id for peer.</para>
366
</enum>
367
<enum name="chanvar[name]">
368
<para>A channel variable configured with setvar for this peer.</para>
369
</enum>
370
<enum name="codec[x]">
371
<para>Preferred codec index number <replaceable>x</replaceable> (beginning with zero).</para>
372
</enum>
373
</enumlist>
374
</parameter>
375
</syntax>
376
<description />
377
</function>
378
<function name="SIPCHANINFO" language="en_US">
379
<synopsis>
380
Gets the specified SIP parameter from the current channel.
381
</synopsis>
382
<syntax>
383
<parameter name="item" required="true">
384
<enumlist>
385
<enum name="peerip">
386
<para>The IP address of the peer.</para>
387
</enum>
388
<enum name="recvip">
389
<para>The source IP address of the peer.</para>
390
</enum>
391
<enum name="from">
392
<para>The URI from the <literal>From:</literal> header.</para>
393
</enum>
394
<enum name="uri">
395
<para>The URI from the <literal>Contact:</literal> header.</para>
396
</enum>
397
<enum name="useragent">
398
<para>The useragent.</para>
399
</enum>
400
<enum name="peername">
401
<para>The name of the peer.</para>
402
</enum>
403
<enum name="t38passthrough">
404
<para><literal>1</literal> if T38 is offered or enabled in this channel,
405
otherwise <literal>0</literal>.</para>
406
</enum>
407
</enumlist>
408
</parameter>
409
</syntax>
410
<description />
411
</function>
412
<function name="CHECKSIPDOMAIN" language="en_US">
413
<synopsis>
414
Checks if domain is a local domain.
415
</synopsis>
416
<syntax>
417
<parameter name="domain" required="true" />
418
</syntax>
419
<description>
420
<para>This function checks if the <replaceable>domain</replaceable> in the argument is configured
421
as a local SIP domain that this Asterisk server is configured to handle.
422
Returns the domain name if it is locally handled, otherwise an empty string.
423
Check the <literal>domain=</literal> configuration in <filename>sip.conf</filename>.</para>
424
</description>
425
</function>
426
<application name="ADSIProg" language="en_US">
427
<synopsis>
428
Load Asterisk ADSI Scripts into phone
429
</synopsis>
430
<syntax>
431
<parameter name="script" required="false">
432
<para>adsi script to use. If not given uses the default script <filename>asterisk.adsi</filename></para>
433
</parameter>
434
</syntax>
435
<description>
436
<para>This application programs an ADSI Phone with the given script</para>
437
</description>
438
<see-also>
439
<ref type="application">GetCPEID</ref>
440
<ref type="filename">adsi.conf</ref>
441
</see-also>
442
</application>
443
<application name="AlarmReceiver" language="en_US">
444
<synopsis>
445
Provide support for receiving alarm reports from a burglar or fire alarm panel.
446
</synopsis>
447
<syntax />
448
<description>
449
<para>This application should be called whenever there is an alarm panel calling in to dump its events.
450
The application will handshake with the alarm panel, and receive events, validate them, handshake them,
451
and store them until the panel hangs up. Once the panel hangs up, the application will run the system
452
command specified by the eventcmd setting in <filename>alarmreceiver.conf</filename> and pipe the
453
events to the standard input of the application.
454
The configuration file also contains settings for DTMF timing, and for the loudness of the
455
acknowledgement tones.</para>
456
<note><para>Only 1 signalling format is supported at this time: Ademco Contact ID.</para></note>
457
</description>
458
<see-also>
459
<ref type="filename">alarmreceiver.conf</ref>
460
</see-also>
461
</application>
462
<application name="AMD" language="en_US">
463
<synopsis>
464
Attempt to detect answering machines.
465
</synopsis>
466
<syntax>
467
<parameter name="initialSilence" required="false">
468
<para>Is maximum initial silence duration before greeting.</para>
469
<para>If this is exceeded set as MACHINE</para>
470
</parameter>
471
<parameter name="greeting" required="false">
472
<para>is the maximum length of a greeting.</para>
473
<para>If this is exceeded set as MACHINE</para>
474
</parameter>
475
<parameter name="afterGreetingSilence" required="false">
476
<para>Is the silence after detecting a greeting.</para>
477
<para>If this is exceeded set as HUMAN</para>
478
</parameter>
479
<parameter name="totalAnalysis Time" required="false">
480
<para>Is the maximum time allowed for the algorithm</para>
481
<para>to decide HUMAN or MACHINE</para>
482
</parameter>
483
<parameter name="miniumWordLength" required="false">
484
<para>Is the minimum duration of Voice considered to be a word</para>
485
</parameter>
486
<parameter name="betweenWordSilence" required="false">
487
<para>Is the minimum duration of silence after a word to
488
consider the audio that follows to be a new word</para>
489
</parameter>
490
<parameter name="maximumNumberOfWords" required="false">
491
<para>Is the maximum number of words in a greeting</para>
492
<para>If this is exceeded set as MACHINE</para>
493
</parameter>
494
<parameter name="silenceThreshold" required="false">
495
<para>How long do we consider silence</para>
496
</parameter>
497
<parameter name="maximumWordLength" required="false">
498
<para>Is the maximum duration of a word to accept.</para>
499
<para>If exceeded set as MACHINE</para>
500
</parameter>
501
</syntax>
502
<description>
503
<para>This application attempts to detect answering machines at the beginning
504
of outbound calls. Simply call this application after the call
505
has been answered (outbound only, of course).</para>
506
<para>When loaded, AMD reads amd.conf and uses the parameters specified as
507
default values. Those default values get overwritten when the calling AMD
508
with parameters.</para>
509
<para>This application sets the following channel variables:</para>
510
<variablelist>
511
<variable name="AMDSTATUS">
512
<para>This is the status of the answering machine detection</para>
513
<value name="MACHINE" />
514
<value name="HUMAN" />
515
<value name="NOTSURE" />
516
<value name="HANGUP" />
517
</variable>
518
<variable name="AMDCAUSE">
519
<para>Indicates the cause that led to the conclusion</para>
520
<value name="TOOLONG">
521
Total Time.
522
</value>
523
<value name="INITIALSILENCE">
524
Silence Duration - Initial Silence.
525
</value>
526
<value name="HUMAN">
527
Silence Duration - afterGreetingSilence.
528
</value>
529
<value name="LONGGREETING">
530
Voice Duration - Greeting.
531
</value>
532
<value name="MAXWORDLENGTH">
533
Word Count - maximum number of words.
534
</value>
535
</variable>
536
</variablelist>
537
</description>
538
<see-also>
539
<ref type="application">WaitForSilence</ref>
540
<ref type="application">WaitForNoise</ref>
541
</see-also>
542
</application>
543
544
<application name="Authenticate" language="en_US">
545
<synopsis>
546
Authenticate a user
547
</synopsis>
548
<syntax>
549
<parameter name="password" required="true">
550
<para>Password the user should know</para>
551
</parameter>
552
<parameter name="options" required="false">
553
<optionlist>
554
<option name="a">
555
<para>Set the channels' account code to the password that is entered</para>
556
</option>
557
<option name="d">
558
<para>Interpret the given path as database key, not a literal file</para>
559
</option>
560
<option name="m">
561
<para>Interpret the given path as a file which contains a list of account
562
codes and password hashes delimited with <literal>:</literal>, listed one per line in
563
the file. When one of the passwords is matched, the channel will have
564
its account code set to the corresponding account code in the file.</para>
565
</option>
566
<option name="r">
567
<para>Remove the database key upon successful entry (valid with <literal>d</literal> only)</para>
568
</option>
569
</optionlist>
570
</parameter>
571
<parameter name="maxdigits" required="false">
572
<para>maximum acceptable number of digits. Stops reading after
573
maxdigits have been entered (without requiring the user to press the <literal>#</literal> key).
574
Defaults to 0 - no limit - wait for the user press the <literal>#</literal> key.</para>
575
</parameter>
576
<parameter name="prompt" required="false">
577
<para>Override the agent-pass prompt file.</para>
578
</parameter>
579
</syntax>
580
<description>
581
<para>This application asks the caller to enter a given password in order to continue dialplan execution.</para>
582
<para>If the password begins with the <literal>/</literal> character,
583
it is interpreted as a file which contains a list of valid passwords, listed 1 password per line in the file.</para>
584
<para>When using a database key, the value associated with the key can be anything.</para>
585
<para>Users have three attempts to authenticate before the channel is hung up.</para>
586
</description>
587
<see-also>
588
<ref type="application">VMAuthenticate</ref>
589
<ref type="application">DISA</ref>
590
</see-also>
591
</application>
592
<application name="NoCDR" language="en_US">
593
<synopsis>
594
Tell Asterisk to not maintain a CDR for the current call
595
</synopsis>
596
<syntax />
597
<description>
598
<para>This application will tell Asterisk not to maintain a CDR for the current call.</para>
599
</description>
600
</application>
601
<application name="ChanIsAvail" language="en_US">
602
<synopsis>
603
Check channel availability
604
</synopsis>
605
<syntax>
606
<parameter name="Technology/Resource" required="true" argsep="&">
607
<argument name="Technology2/Resource2" multiple="true">
608
<para>Optional extra devices to check</para>
609
<para>If you need more then one enter them as
610
Technology2/Resource2&Technology3/Resourse3&.....</para>
611
</argument>
612
<para>Specification of the device(s) to check. These must be in the format of
613
<literal>Technology/Resource</literal>, where <replaceable>Technology</replaceable>
614
represents a particular channel driver, and <replaceable>Resource</replaceable>
615
represents a resource available to that particular channel driver.</para>
616
</parameter>
617
<parameter name="options" required="false">
618
<optionlist>
619
<option name="a">
620
<para>Check for all available channels, not only the first one</para>
621
</option>
622
<option name="s">
623
<para>Consider the channel unavailable if the channel is in use at all</para>
624
</option>
625
<option name="t" implies="s">
626
<para>Simply checks if specified channels exist in the channel list</para>
627
</option>
628
</optionlist>
629
</parameter>
630
</syntax>
631
<description>
632
<para>This application will check to see if any of the specified channels are available.</para>
633
<para>This application sets the following channel variables:</para>
634
<variablelist>
635
<variable name="AVAILCHAN">
636
<para>The name of the available channel, if one exists</para>
637
</variable>
638
<variable name="AVAILORIGCHAN">
639
<para>The canonical channel name that was used to create the channel</para>
640
</variable>
641
<variable name="AVAILSTATUS">
642
<para>The status code for the available channel</para>
643
</variable>
644
</variablelist>
645
</description>
646
</application>
647
<application name="ChannelRedirect" language="en_US">
648
<synopsis>
649
Redirects given channel to a dialplan target
650
</synopsis>
651
<syntax>
652
<parameter name="channel" required="true" />
653
<parameter name="context" required="false" />
654
<parameter name="extension" required="false" />
655
<parameter name="priority" required="true" />
656
</syntax>
657
<description>
658
<para>Sends the specified channel to the specified extension priority</para>
659
660
<para>This application sets the following channel variables upon completion</para>
661
<variablelist>
662
<variable name="CHANNELREDIRECT_STATUS">
663
<value name="NOCHANNEL" />
664
<value name="SUCCESS" />
665
<para>Are set to the result of the redirection</para>
666
</variable>
667
</variablelist>
668
</description>
669
</application>
670
<application name="ChanSpy" language="en_US">
671
<synopsis>
672
Listen to a channel, and optionally whisper into it.
673
</synopsis>
674
<syntax>
675
<parameter name="chanprefix" />
676
<parameter name="options">
677
<optionlist>
678
<option name="b">
679
<para>Only spy on channels involved in a bridged call.</para>
680
</option>
681
<option name="B">
682
<para>Instead of whispering on a single channel barge in on both
683
channels involved in the call.</para>
684
</option>
685
<option name="d">
686
<para>Override the typical numeric DTMF functionality and instead
687
use DTMF to switch between spy modes.</para>
688
<enumlist>
689
<enum name="4">
690
<para>spy mode</para>
691
</enum>
692
<enum name="5">
693
<para>whisper mode</para>
694
</enum>
695
<enum name="6">
696
<para>barge mode</para>
697
</enum>
698
</enumlist>
699
</option>
700
<option name="g">
701
<argument name="grp" required="true">
702
<para>Only spy on channels in which one or more of the groups
703
listed in <replaceable>grp</replaceable> matches one or more groups from the
704
<variable>SPYGROUP</variable> variable set on the channel to be spied upon.</para>
705
</argument>
706
<note><para>both <replaceable>grp</replaceable> and <variable>SPYGROUP</variable> can contain
707
either a single group or a colon-delimited list of groups, such
708
as <literal>sales:support:accounting</literal>.</para></note>
709
</option>
710
<option name="n" argsep="@">
711
<para>Say the name of the person being spied on if that person has recorded
712
his/her name. If a context is specified, then that voicemail context will
713
be searched when retrieving the name, otherwise the <literal>default</literal> context
714
be used when searching for the name (i.e. if SIP/1000 is the channel being
715
spied on and no mailbox is specified, then <literal>1000</literal> will be used when searching
716
for the name).</para>
717
<argument name="mailbox" />
718
<argument name="context" />
719
</option>
720
<option name="q">
721
<para>Don't play a beep when beginning to spy on a channel, or speak the
722
selected channel name.</para>
723
</option>
724
<option name="r">
725
<para>Record the session to the monitor spool directory. An optional base for the filename
726
may be specified. The default is <literal>chanspy</literal>.</para>
727
<argument name="basename" />
728
</option>
729
<option name="s">
730
<para>Skip the playback of the channel type (i.e. SIP, IAX, etc) when
731
speaking the selected channel name.</para>
732
</option>
733
<option name="v">
734
<argument name="value" />
735
<para>Adjust the initial volume in the range from <literal>-4</literal>
736
to <literal>4</literal>. A negative value refers to a quieter setting.</para>
737
</option>
738
<option name="w">
739
<para>Enable <literal>whisper</literal> mode, so the spying channel can talk to
740
the spied-on channel.</para>
741
</option>
742
<option name="W">
743
<para>Enable <literal>private whisper</literal> mode, so the spying channel can
744
talk to the spied-on channel but cannot listen to that channel.</para>
745
</option>
746
<option name="o">
747
<para>Only listen to audio coming from this channel.</para>
748
</option>
749
<option name="X">
750
<para>Allow the user to exit ChanSpy to a valid single digit
751
numeric extension in the current context or the context
752
specified by the <variable>SPY_EXIT_CONTEXT</variable> channel variable. The
753
name of the last channel that was spied on will be stored
754
in the <variable>SPY_CHANNEL</variable> variable.</para>
755
</option>
756
<option name="e">
757
<argument name="ext" required="true" />
758
<para>Enable <emphasis>enforced</emphasis> mode, so the spying channel can
759
only monitor extensions whose name is in the <replaceable>ext</replaceable> : delimited
760
list.</para>
761
</option>
762
</optionlist>
763
</parameter>
764
</syntax>
765
<description>
766
<para>This application is used to listen to the audio from an Asterisk channel. This includes the audio
767
coming in and "out of the channel being spied on. If the <literal>chanprefix</literal> parameter is specified,
768
only channels beginning with this string will be spied upon.</para>
769
<para>While spying, the following actions may be performed:</para>
770
<para> - Dialing <literal>#</literal> cycles the volume level.</para>
771
<para> - Dialing <literal>*</literal> will stop spying and look for another channel to spy on.</para>
772
<para> - Dialing a series of digits followed by <literal>#</literal> builds a channel name to append
773
to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing the digits '1234#'
774
while spying will begin spying on the channel 'Agent/1234'. Note that this feature will be overridden if the 'd' option
775
is used</para>
776
<note><para>The <replaceable>X</replaceable> option supersedes the three features above in that if a valid
777
single digit extension exists in the correct context ChanSpy will exit to it.
778
This also disables choosing a channel based on <literal>chanprefix</literal> and a digit sequence.</para></note>
779
</description>
780
<see-also>
781
<ref type="application">ExtenSpy</ref>
782
</see-also>
783
</application>
784
<application name="ExtenSpy" language="en_US">
785
<synopsis>
786
Listen to a channel, and optionally whisper into it.
787
</synopsis>
788
<syntax>
789
<parameter name="exten" required="true" argsep="@">
790
<argument name="exten" required="true">
791
<para>Specify extension.</para>
792
</argument>
793
<argument name="context">
794
<para>Optionally specify a context, defaults to <literal>default</literal>.</para>
795
</argument>
796
</parameter>
797
<parameter name="options">
798
<optionlist>
799
<option name="b">
800
<para>Only spy on channels involved in a bridged call.</para>
801
</option>
802
<option name="B">
803
<para>Instead of whispering on a single channel barge in on both
804
channels involved in the call.</para>
805
</option>
806
<option name="d">
807
<para>Override the typical numeric DTMF functionality and instead
808
use DTMF to switch between spy modes.</para>
809
<enumlist>
810
<enum name="4">
811
<para>spy mode</para>
812
</enum>
813
<enum name="5">
814
<para>whisper mode</para>
815
</enum>
816
<enum name="6">
817
<para>barge mode</para>
818
</enum>
819
</enumlist>
820
</option>
821
<option name="g">
822
<argument name="grp" required="true">
823
<para>Only spy on channels in which one or more of the groups
824
listed in <replaceable>grp</replaceable> matches one or more groups from the
825
<variable>SPYGROUP</variable> variable set on the channel to be spied upon.</para>
826
</argument>
827
<note><para>both <replaceable>grp</replaceable> and <variable>SPYGROUP</variable> can contain
828
either a single group or a colon-delimited list of groups, such
829
as <literal>sales:support:accounting</literal>.</para></note>
830
</option>
831
<option name="n" argsep="@">
832
<para>Say the name of the person being spied on if that person has recorded
833
his/her name. If a context is specified, then that voicemail context will
834
be searched when retrieving the name, otherwise the <literal>default</literal> context
835
be used when searching for the name (i.e. if SIP/1000 is the channel being
836
spied on and no mailbox is specified, then <literal>1000</literal> will be used when searching
837
for the name).</para>
838
<argument name="mailbox" />
839
<argument name="context" />
840
</option>
841
<option name="q">
842
<para>Don't play a beep when beginning to spy on a channel, or speak the
843
selected channel name.</para>
844
</option>
845
<option name="r">
846
<para>Record the session to the monitor spool directory. An optional base for the filename
847
may be specified. The default is <literal>chanspy</literal>.</para>
848
<argument name="basename" />
849
</option>
850
<option name="s">
851
<para>Skip the playback of the channel type (i.e. SIP, IAX, etc) when
852
speaking the selected channel name.</para>
853
</option>
854
<option name="v">
855
<argument name="value" />
856
<para>Adjust the initial volume in the range from <literal>-4</literal>
857
to <literal>4</literal>. A negative value refers to a quieter setting.</para>
858
</option>
859
<option name="w">
860
<para>Enable <literal>whisper</literal> mode, so the spying channel can talk to
861
the spied-on channel.</para>
862
</option>
863
<option name="W">
864
<para>Enable <literal>private whisper</literal> mode, so the spying channel can
865
talk to the spied-on channel but cannot listen to that channel.</para>
866
</option>
867
<option name="o">
868
<para>Only listen to audio coming from this channel.</para>
869
</option>
870
<option name="X">
871
<para>Allow the user to exit ChanSpy to a valid single digit
872
numeric extension in the current context or the context
873
specified by the <variable>SPY_EXIT_CONTEXT</variable> channel variable. The
874
name of the last channel that was spied on will be stored
875
in the <variable>SPY_CHANNEL</variable> variable.</para>
876
</option>
877
<option name="e">
878
<argument name="ext" required="true" />
879
<para>Enable <emphasis>enforced</emphasis> mode, so the spying channel can
880
only monitor extensions whose name is in the <replaceable>ext</replaceable> : delimited
881
list.</para>
882
</option>
883
</optionlist>
884
</parameter>
885
</syntax>
886
<description>
887
<para>This application is used to listen to the audio from an Asterisk channel. This includes
888
the audio coming in and out of the channel being spied on. Only channels created by outgoing calls for the
889
specified extension will be selected for spying. If the optional context is not supplied,
890
the current channel's context will be used.</para>
891
<para>While spying, the following actions may be performed:</para>
892
<para> - Dialing <literal>#</literal> cycles the volume level.</para>
893
<para> - Dialing <literal>*</literal> will stop spying and look for another channel to spy on.</para>
894
<note><para>The <replaceable>X</replaceable> option supersedes the three features above in that if a valid
895
single digit extension exists in the correct context ChanSpy will exit to it.
896
This also disables choosing a channel based on <literal>chanprefix</literal> and a digit sequence.</para></note>
897
</description>
898
<see-also>
899
<ref type="application">ChanSpy</ref>
900
</see-also>
901
</application>
902
903
<application name="ConfBridge" language="en_US">
904
<synopsis>
905
Conference bridge application.
906
</synopsis>
907
<syntax>
908
<parameter name="confno">
909
<para>The conference number</para>
910
</parameter>
911
<parameter name="options">
912
<optionlist>
913
<option name="a">
914
<para>Set admin mode.</para>
915
</option>
916
<option name="A">
917
<para>Set marked mode.</para>
918
</option>
919
<option name="c">
920
<para>Announce user(s) count on joining a conference.</para>
921
</option>
922
<option name="m">
923
<para>Set initially muted.</para>
924
</option>
925
<option name="M" hasparams="optional">
926
<para>Enable music on hold when the conference has a single caller. Optionally,
927
specify a musiconhold class to use. If one is not provided, it will use the
928
channel's currently set music class, or <literal>default</literal>.</para>
929
<argument name="class" required="true" />
930
</option>
931
<option name="1">
932
<para>Do not play message when first person enters</para>
933
</option>
934
<option name="s">
935
<para>Present menu (user or admin) when <literal>*</literal> is received
936
(send to menu).</para>
937
</option>
938
<option name="w">
939
<para>Wait until the marked user enters the conference.</para>
940
</option>
941
<option name="q">
942
<para>Quiet mode (don't play enter/leave sounds).</para>
943
</option>
944
</optionlist>
945
</parameter>
946
</syntax>
947
<description>
948
<para>Enters the user into a specified conference bridge. The user can exit the conference by hangup only.</para>
949
<para>The join sound can be set using the <literal>CONFBRIDGE_JOIN_SOUND</literal> variable and the leave sound can be set using the <literal>CONFBRIDGE_LEAVE_SOUND</literal> variable. These can be unique to the caller.</para>
950
</description>
951
</application>
952
<application name="ControlPlayback" language="en_US">
953
<synopsis>
954
Play a file with fast forward and rewind.
955
</synopsis>
956
<syntax>
957
<parameter name="filename" required="true" />
958
<parameter name="skipms">
959
<para>This is number of milliseconds to skip when rewinding or
960
fast-forwarding.</para>
961
</parameter>
962
<parameter name="ff">
963
<para>Fast-forward when this DTMF digit is received. (defaults to <literal>#</literal>)</para>
964
</parameter>
965
<parameter name="rew">
966
<para>Rewind when this DTMF digit is received. (defaults to <literal>*</literal>)</para>
967
</parameter>
968
<parameter name="stop">
969
<para>Stop playback when this DTMF digit is received.</para>
970
</parameter>
971
<parameter name="pause">
972
<para>Pause playback when this DTMF digit is received.</para>
973
</parameter>
974
<parameter name="restart">
975
<para>Restart playback when this DTMF digit is received.</para>
976
</parameter>
977
<parameter name="options">
978
<optionlist>
979
<option name="o">
980
<argument name="time" required="true">
981
<para>Start at <replaceable>time</replaceable> ms from the
982
beginning of the file.</para>
983
</argument>
984
</option>
985
</optionlist>
986
</parameter>
987
</syntax>
988
<description>
989
<para>This application will play back the given <replaceable>filename</replaceable>.</para>
990
<para>It sets the following channel variables upon completion:</para>
991
<variablelist>
992
<variable name="CPLAYBACKSTATUS">
993
<para>Contains the status of the attempt as a text string</para>
994
<value name="SUCCESS" />
995
<value name="USERSTOPPED" />
996
<value name="ERROR" />
997
</variable>
998
<variable name="CPLAYBACKOFFSET">
999
<para>Contains the offset in ms into the file where playback
1000
was at when it stopped. <literal>-1</literal> is end of file.</para>
1001
</variable>
1002
<variable name="CPLAYBACKSTOPKEY">
1003
<para>If the playback is stopped by the user this variable contains
1004
the key that was pressed.</para>
1005
</variable>
1006
</variablelist>
1007
</description>
1008
</application>
1009
<application name="DAHDIBarge" language="en_US">
1010
<synopsis>
1011
Barge in (monitor) DAHDI channel.
1012
</synopsis>
1013
<syntax>
1014
<parameter name="channel">
1015
<para>Channel to barge.</para>
1016
</parameter>
1017
</syntax>
1018
<description>
1019
<para>Barges in on a specified DAHDI <replaceable>channel</replaceable> or prompts
1020
if one is not specified. Returns <literal>-1</literal> when caller user hangs
1021
up and is independent of the state of the channel being monitored.
1022
</para>
1023
</description>
1024
</application>
1025
<application name="DAHDIRAS" language="en_US">
1026
<synopsis>
1027
Executes DAHDI ISDN RAS application.
1028
</synopsis>
1029
<syntax>
1030
<parameter name="args" required="true">
1031
<para>A list of parameters to pass to the pppd daemon,
1032
separated by <literal>,</literal> characters.</para>
1033
</parameter>
1034
</syntax>
1035
<description>
1036
<para>Executes a RAS server using pppd on the given channel.
1037
The channel must be a clear channel (i.e. PRI source) and a DAHDI
1038
channel to be able to use this function (No modem emulation is included).</para>
1039
<para>Your pppd must be patched to be DAHDI aware.</para>
1040
</description>
1041
</application>
1042
1043
<application name="DAHDIScan" language="en_US">
1044
<synopsis>
1045
Scan DAHDI channels to monitor calls.
1046
</synopsis>
1047
<syntax>
1048
<parameter name="group">
1049
<para>Limit scanning to a channel <replaceable>group</replaceable> by setting this option.</para>
1050
</parameter>
1051
</syntax>
1052
<description>
1053
<para>Allows a call center manager to monitor DAHDI channels in a
1054
convenient way. Use <literal>#</literal> to select the next channel and use <literal>*</literal> to exit.</para>
1055
</description>
1056
</application>
1057
<application name="DBdel" language="en_US">
1058
<synopsis>
1059
Delete a key from the asterisk database.
1060
</synopsis>
1061
<syntax argsep="/">
1062
<parameter name="family" required="true" />
1063
<parameter name="key" required="true" />
1064
</syntax>
1065
<description>
1066
<para>This application will delete a <replaceable>key</replaceable> from the Asterisk
1067
database.</para>
1068
<note><para>This application has been DEPRECATED in favor of the DB_DELETE function.</para></note>
1069
</description>
1070
<see-also>
1071
<ref type="function">DB_DELETE</ref>
1072
<ref type="application">DBdeltree</ref>
1073
<ref type="function">DB</ref>
1074
</see-also>
1075
</application>
1076
<application name="DBdeltree" language="en_US">
1077
<synopsis>
1078
Delete a family or keytree from the asterisk database.
1079
</synopsis>
1080
<syntax argsep="/">
1081
<parameter name="family" required="true" />
1082
<parameter name="keytree" />
1083
</syntax>
1084
<description>
1085
<para>This application will delete a <replaceable>family</replaceable> or <replaceable>keytree</replaceable>
1086
from the Asterisk database.</para>
1087
</description>
1088
<see-also>
1089
<ref type="function">DB_DELETE</ref>
1090
<ref type="application">DBdel</ref>
1091
<ref type="function">DB</ref>
1092
</see-also>
1093
</application>
1094
<application name="Dial" language="en_US">
1095
<synopsis>
1096
Attempt to connect to another device or endpoint and bridge the call.
1097
</synopsis>
1098
<syntax>
1099
<parameter name="Technology/Resource" required="true" argsep="&">
1100
<argument name="Technology/Resource" required="true">
1101
<para>Specification of the device(s) to dial. These must be in the format of
1102
<literal>Technology/Resource</literal>, where <replaceable>Technology</replaceable>
1103
represents a particular channel driver, and <replaceable>Resource</replaceable>
1104
represents a resource available to that particular channel driver.</para>
1105
</argument>
1106
<argument name="Technology2/Resource2" required="false" multiple="true">
1107
<para>Optional extra devices to dial in parallel</para>
1108
<para>If you need more then one enter them as
1109
Technology2/Resource2&Technology3/Resourse3&.....</para>
1110
</argument>
1111
</parameter>
1112
<parameter name="timeout" required="false">
1113
<para>Specifies the number of seconds we attempt to dial the specified devices</para>
1114
<para>If not specified, this defaults to 136 years.</para>
1115
</parameter>
1116
<parameter name="options" required="false">
1117
<optionlist>
1118
<option name="A">
1119
<argument name="x" required="true">
1120
<para>The file to play to the called party</para>
1121
</argument>
1122
<para>Play an announcement to the called party, where <replaceable>x</replaceable> is the prompt to be played</para>
1123
</option>
1124
<option name="C">
1125
<para>Reset the call detail record (CDR) for this call.</para>
1126
</option>
1127
<option name="c">
1128
<para>If the Dial() application cancels this call, always set the flag to tell the channel
1129
driver that the call is answered elsewhere.</para>
1130
</option>
1131
<option name="d">
1132
<para>Allow the calling user to dial a 1 digit extension while waiting for
1133
a call to be answered. Exit to that extension if it exists in the
1134
current context, or the context defined in the <variable>EXITCONTEXT</variable> variable,
1135
if it exists.</para>
1136
</option>
1137
<option name="D" argsep=":">
1138
<argument name="called" />
1139
<argument name="calling" />
1140
<para>Send the specified DTMF strings <emphasis>after</emphasis> the called
1141
party has answered, but before the call gets bridged. The
1142
<replaceable>called</replaceable> DTMF string is sent to the called party, and the
1143
<replaceable>calling</replaceable> DTMF string is sent to the calling party. Both arguments
1144
can be used alone.</para>
1145
</option>
1146
<option name="e">
1147
<para>Execute the <literal>h</literal> extension for peer after the call ends</para>
1148
</option>
1149
<option name="f">
1150
<para>Force the callerid of the <emphasis>calling</emphasis> channel to be set as the
1151
extension associated with the channel using a dialplan <literal>hint</literal>.
1152
For example, some PSTNs do not allow CallerID to be set to anything
1153
other than the number assigned to the caller.</para>
1154
</option>
1155
<option name="F" argsep="^">
1156
<argument name="context" required="false" />
1157
<argument name="exten" required="false" />
1158
<argument name="priority" required="true" />
1159
<para>When the caller hangs up, transfer the called party
1160
to the specified destination and continue execution at that location.</para>
1161
</option>
1162
<option name="g">
1163
<para>Proceed with dialplan execution at the next priority in the current extension if the
1164
destination channel hangs up.</para>
1165
</option>
1166
<option name="G" argsep="^">
1167
<argument name="context" required="false" />
1168
<argument name="exten" required="false" />
1169
<argument name="priority" required="true" />
1170
<para>If the call is answered, transfer the calling party to
1171
the specified <replaceable>priority</replaceable> and the called party to the specified
1172
<replaceable>priority</replaceable> plus one.</para>
1173
<note>
1174
<para>You cannot use any additional action post answer options in conjunction with this option.</para>
1175
</note>
1176
</option>
1177
<option name="h">
1178
<para>Allow the called party to hang up by sending the <literal>*</literal> DTMF digit.</para>
1179
</option>
1180
<option name="H">
1181
<para>Allow the calling party to hang up by hitting the <literal>*</literal> DTMF digit.</para>
1182
</option>
1183
<option name="i">
1184
<para>Asterisk will ignore any forwarding requests it may receive on this dial attempt.</para>
1185
</option>
1186
<option name="k">
1187
<para>Allow the called party to enable parking of the call by sending
1188
the DTMF sequence defined for call parking in <filename>features.conf</filename>.</para>
1189
</option>
1190
<option name="K">
1191
<para>Allow the calling party to enable parking of the call by sending
1192
the DTMF sequence defined for call parking in <filename>features.conf</filename>.</para>
1193
</option>
1194
<option name="L" argsep=":">
1195
<argument name="x" required="true">
1196
<para>Maximum call time, in milliseconds</para>
1197
</argument>
1198
<argument name="y">
1199
<para>Warning time, in milliseconds</para>
1200
</argument>
1201
<argument name="z">
1202
<para>Repeat time, in milliseconds</para>
1203
</argument>
1204
<para>Limit the call to <replaceable>x</replaceable> milliseconds. Play a warning when <replaceable>y</replaceable> milliseconds are
1205
left. Repeat the warning every <replaceable>z</replaceable> milliseconds until time expires.</para>
1206
<para>This option is affected by the following variables:</para>
1207
<variablelist>
1208
<variable name="LIMIT_PLAYAUDIO_CALLER">
1209
<value name="yes" default="true" />
1210
<value name="no" />
1211
<para>If set, this variable causes Asterisk to play the prompts to the caller.</para>
1212
</variable>
1213
<variable name="LIMIT_PLAYAUDIO_CALLEE">
1214
<value name="yes" />
1215
<value name="no" default="true"/>
1216
<para>If set, this variable causes Asterisk to play the prompts to the callee.</para>
1217
</variable>
1218
<variable name="LIMIT_TIMEOUT_FILE">
1219
<value name="filename"/>
1220
<para>If specified, <replaceable>filename</replaceable> specifies the sound prompt to play when the timeout is reached.
1221
If not set, the time remaining will be announced.</para>
1222
</variable>
1223
<variable name="LIMIT_CONNECT_FILE">
1224
<value name="filename"/>
1225
<para>If specified, <replaceable>filename</replaceable> specifies the sound prompt to play when the call begins.
1226
If not set, the time remaining will be announced.</para>
1227
</variable>
1228
<variable name="LIMIT_WARNING_FILE">
1229
<value name="filename"/>
1230
<para>If specified, <replaceable>filename</replaceable> specifies the sound prompt to play as
1231
a warning when time <replaceable>x</replaceable> is reached. If not set, the time remaining will be announced.</para>
1232
</variable>
1233
</variablelist>
1234
</option>
1235
<option name="m">
1236
<argument name="class" required="false"/>
1237
<para>Provide hold music to the calling party until a requested
1238
channel answers. A specific music on hold <replaceable>class</replaceable>
1239
(as defined in <filename>musiconhold.conf</filename>) can be specified.</para>
1240
</option>
1241
<option name="M" argsep="^">
1242
<argument name="macro" required="true">
1243
<para>Name of the macro that should be executed.</para>
1244
</argument>
1245
<argument name="arg" multiple="true">
1246
<para>Macro arguments</para>
1247
</argument>
1248
<para>Execute the specified <replaceable>macro</replaceable> for the <emphasis>called</emphasis> channel
1249
before connecting to the calling channel. Arguments can be specified to the Macro
1250
using <literal>^</literal> as a delimiter. The macro can set the variable
1251
<variable>MACRO_RESULT</variable> to specify the following actions after the macro is
1252
finished executing:</para>
1253
<variablelist>
1254
<variable name="MACRO_RESULT">
1255
<para>If set, this action will be taken after the macro finished executing.</para>
1256
<value name="ABORT">
1257
Hangup both legs of the call
1258
</value>
1259
<value name="CONGESTION">
1260
Behave as if line congestion was encountered
1261
</value>
1262
<value name="BUSY">
1263
Behave as if a busy signal was encountered
1264
</value>
1265
<value name="CONTINUE">
1266
Hangup the called party and allow the calling party to continue dialplan execution at the next priority
1267
</value>
1268
<!-- TODO: Fix this syntax up, once we've figured out how to specify the GOTO syntax -->
1269
<value name="GOTO:<context>^<exten>^<priority>">
1270
Transfer the call to the specified destination.
1271
</value>
1272
</variable>
1273
</variablelist>
1274
<note>
1275
<para>You cannot use any additional action post answer options in conjunction
1276
with this option. Also, pbx services are not run on the peer (called) channel,
1277
so you will not be able to set timeouts via the TIMEOUT() function in this macro.</para>
1278
</note>
1279
<warning><para>Be aware of the limitations that macros have, specifically with regards to use of
1280
the <literal>WaitExten</literal> application. For more information, see the documentation for
1281
Macro()</para></warning>
1282
</option>
1283
<option name="n">
1284
<para>This option is a modifier for the call screening/privacy mode. (See the
1285
<literal>p</literal> and <literal>P</literal> options.) It specifies
1286
that no introductions are to be saved in the <directory>priv-callerintros</directory>
1287
directory.</para>
1288
</option>
1289
<option name="N">
1290
<para>This option is a modifier for the call screening/privacy mode. It specifies
1291
that if Caller*ID is present, do not screen the call.</para>
1292
</option>
1293
<option name="o">
1294
<para>Specify that the Caller*ID that was present on the <emphasis>calling</emphasis> channel
1295
be set as the Caller*ID on the <emphasis>called</emphasis> channel. This was the
1296
behavior of Asterisk 1.0 and earlier.</para>
1297
</option>
1298
<option name="O">
1299
<argument name="mode">
1300
<para>With <replaceable>mode</replaceable> either not specified or set to <literal>1</literal>,
1301
the originator hanging up will cause the phone to ring back immediately.</para>
1302
<para>With <replaceable>mode</replaceable> set to <literal>2</literal>, when the operator
1303
flashes the trunk, it will ring their phone back.</para>
1304
</argument>
1305
<para>Enables <emphasis>operator services</emphasis> mode. This option only
1306
works when bridging a DAHDI channel to another DAHDI channel
1307
only. if specified on non-DAHDI interfaces, it will be ignored.
1308
When the destination answers (presumably an operator services
1309
station), the originator no longer has control of their line.
1310
They may hang up, but the switch will not release their line
1311
until the destination party (the operator) hangs up.</para>
1312
</option>
1313
<option name="p">
1314
<para>This option enables screening mode. This is basically Privacy mode
1315
without memory.</para>
1316
</option>
1317
<option name="P">
1318
<argument name="x" />
1319
<para>Enable privacy mode. Use <replaceable>x</replaceable> as the family/key in the AstDB database if
1320
it is provided. The current extension is used if a database family/key is not specified.</para>
1321
</option>
1322
<option name="r">
1323
<para>Indicate ringing to the calling party, even if the called party isn't actually ringing. Pass no audio to the calling
1324
party until the called channel has answered.</para>
1325
</option>
1326
<option name="S">
1327
<argument name="x" required="true" />
1328
<para>Hang up the call <replaceable>x</replaceable> seconds <emphasis>after</emphasis> the called party has
1329
answered the call.</para>
1330
</option>
1331
<option name="t">
1332
<para>Allow the called party to transfer the calling party by sending the
1333
DTMF sequence defined in <filename>features.conf</filename>.</para>
1334
</option>
1335
<option name="T">
1336
<para>Allow the calling party to transfer the called party by sending the
1337
DTMF sequence defined in <filename>features.conf</filename>.</para>
1338
</option>
1339
<option name="U" argsep="^">
1340
<argument name="x" required="true">
1341
<para>Name of the subroutine to execute via Gosub</para>
1342
</argument>
1343
<argument name="arg" multiple="true" required="false">
1344
<para>Arguments for the Gosub routine</para>
1345
</argument>
1346
<para>Execute via Gosub the routine <replaceable>x</replaceable> for the <emphasis>called</emphasis> channel before connecting
1347
to the calling channel. Arguments can be specified to the Gosub
1348
using <literal>^</literal> as a delimiter. The Gosub routine can set the variable
1349
<variable>GOSUB_RESULT</variable> to specify the following actions after the Gosub returns.</para>
1350
<variablelist>
1351
<variable name="GOSUB_RESULT">
1352
<value name="ABORT">
1353
Hangup both legs of the call.
1354
</value>
1355
<value name="CONGESTION">
1356
Behave as if line congestion was encountered.
1357
</value>
1358
<value name="BUSY">
1359
Behave as if a busy signal was encountered.
1360
</value>
1361
<value name="CONTINUE">
1362
Hangup the called party and allow the calling party
1363
to continue dialplan execution at the next priority.
1364
</value>
1365
<!-- TODO: Fix this syntax up, once we've figured out how to specify the GOTO syntax -->
1366
<value name="GOTO:<context>^<exten>^<priority>">
1367
Transfer the call to the specified priority. Optionally, an extension, or
1368
extension and priority can be specified.
1369
</value>
1370
</variable>
1371
</variablelist>
1372
<note>
1373
<para>You cannot use any additional action post answer options in conjunction
1374
with this option. Also, pbx services are not run on the peer (called) channel,
1375
so you will not be able to set timeouts via the TIMEOUT() function in this routine.</para>
1376
</note>
1377
</option>
1378
<option name="w">
1379
<para>Allow the called party to enable recording of the call by sending
1380
the DTMF sequence defined for one-touch recording in <filename>features.conf</filename>.</para>
1381
</option>
1382
<option name="W">
1383
<para>Allow the calling party to enable recording of the call by sending
1384
the DTMF sequence defined for one-touch recording in <filename>features.conf</filename>.</para>
1385
</option>
1386
<option name="x">
1387
<para>Allow the called party to enable recording of the call by sending
1388
the DTMF sequence defined for one-touch automixmonitor in <filename>features.conf</filename>.</para>
1389
</option>
1390
<option name="X">
1391
<para>Allow the calling party to enable recording of the call by sending
1392
the DTMF sequence defined for one-touch automixmonitor in <filename>features.conf</filename>.</para>
1393
</option>
1394
</optionlist>
1395
</parameter>
1396
<parameter name="URL">
1397
<para>The optional URL will be sent to the called party if the channel driver supports it.</para>
1398
</parameter>
1399
</syntax>
1400
<description>
1401
<para>This application will place calls to one or more specified channels. As soon
1402
as one of the requested channels answers, the originating channel will be
1403
answered, if it has not already been answered. These two channels will then
1404
be active in a bridged call. All other channels that were requested will then
1405
be hung up.</para>
1406
1407
<para>Unless there is a timeout specified, the Dial application will wait
1408
indefinitely until one of the called channels answers, the user hangs up, or
1409
if all of the called channels are busy or unavailable. Dialplan executing will
1410
continue if no requested channels can be called, or if the timeout expires.
1411
This application will report normal termination if the originating channel
1412
hangs up, or if the call is bridged and either of the parties in the bridge
1413
ends the call.</para>
1414
1415
<para>If the <variable>OUTBOUND_GROUP</variable> variable is set, all peer channels created by this
1416
application will be put into that group (as in Set(GROUP()=...).
1417
If the <variable>OUTBOUND_GROUP_ONCE</variable> variable is set, all peer channels created by this
1418
application will be put into that group (as in Set(GROUP()=...). Unlike OUTBOUND_GROUP,
1419
however, the variable will be unset after use.</para>
1420
1421
<para>This application sets the following channel variables:</para>
1422
<variablelist>
1423
<variable name="DIALEDTIME">
1424
<para>This is the time from dialing a channel until when it is disconnected.</para>
1425
</variable>
1426
<variable name="ANSWEREDTIME">
1427
<para>This is the amount of time for actual call.</para>
1428
</variable>
1429
<variable name="DIALSTATUS">
1430
<para>This is the status of the call</para>
1431
<value name="CHANUNAVAIL" />
1432
<value name="CONGESTION" />
1433
<value name="NOANSWER" />
1434
<value name="BUSY" />
1435
<value name="ANSWER" />
1436
<value name="CANCEL" />
1437
<value name="DONTCALL">
1438
For the Privacy and Screening Modes.
1439
Will be set if the called party chooses to send the calling party to the 'Go Away' script.
1440
</value>
1441
<value name="TORTURE">
1442
For the Privacy and Screening Modes.
1443
Will be set if the called party chooses to send the calling party to the 'torture' script.
1444
</value>
1445
<value name="INVALIDARGS" />
1446
</variable>
1447
</variablelist>
1448
</description>
1449
</application>
1450
<application name="RetryDial" language="en_US">
1451
<synopsis>
1452
Place a call, retrying on failure allowing an optional exit extension.
1453
</synopsis>
1454
<syntax>
1455
<parameter name="announce" required="true">
1456
<para>Filename of sound that will be played when no channel can be reached</para>
1457
</parameter>
1458
<parameter name="sleep" required="true">
1459
<para>Number of seconds to wait after a dial attempt failed before a new attempt is made</para>
1460
</parameter>
1461
<parameter name="retries" required="true">
1462
<para>Number of retries</para>
1463
<para>When this is reached flow will continue at the next priority in the dialplan</para>
1464
</parameter>
1465
<parameter name="dialargs" required="true">
1466
<para>Same format as arguments provided to the Dial application</para>
1467
</parameter>
1468
</syntax>
1469
<description>
1470
<para>This application will attempt to place a call using the normal Dial application.
1471
If no channel can be reached, the <replaceable>announce</replaceable> file will be played.
1472
Then, it will wait <replaceable>sleep</replaceable> number of seconds before retrying the call.
1473
After <replaceable>retries</replaceable> number of attempts, the calling channel will continue at the next priority in the dialplan.
1474
If the <replaceable>retries</replaceable> setting is set to 0, this application will retry endlessly.
1475
While waiting to retry a call, a 1 digit extension may be dialed. If that
1476
extension exists in either the context defined in <variable>EXITCONTEXT</variable> or the current
1477
one, The call will jump to that extension immediately.
1478
The <replaceable>dialargs</replaceable> are specified in the same format that arguments are provided
1479
to the Dial application.</para>
1480
</description>
1481
</application>
1482
<application name="Dictate" language="en_US">
1483
<synopsis>
1484
Virtual Dictation Machine.
1485
</synopsis>
1486
<syntax>
1487
<parameter name="base_dir" />
1488
<parameter name="filename" />
1489
</syntax>
1490
<description>
1491
<para>Start dictation machine using optional <replaceable>base_dir</replaceable> for files.</para>
1492
</description>
1493
</application>
1494
<application name="Pickup" language="en_US">
1495
<synopsis>
1496
Directed extension call pickup.
1497
</synopsis>
1498
<syntax argsep="&">
1499
<parameter name="ext" argsep="@" required="true">
1500
<argument name="extension" required="true"/>
1501
<argument name="context" />
1502
</parameter>
1503
<parameter name="ext2" argsep="@" multiple="true">
1504
<argument name="extension2" required="true"/>
1505
<argument name="context2"/>
1506
</parameter>
1507
</syntax>
1508
<description>
1509
<para>This application can pickup any ringing channel that is calling
1510
the specified <replaceable>extension</replaceable>. If no <replaceable>context</replaceable>
1511
is specified, the current context will be used. If you use the special string <literal>PICKUPMARK</literal>
1512
for the context parameter, for example 10@PICKUPMARK, this application
1513
tries to find a channel which has defined a <variable>PICKUPMARK</variable>
1514
channel variable with the same value as <replaceable>extension</replaceable>
1515
(in this example, <literal>10</literal>). When no parameter is specified, the application
1516
will pickup a channel matching the pickup group of the active channel.</para>
1517
</description>
1518
</application>
1519
<application name="PickupChan" language="en_US">
1520
<synopsis>
1521
Pickup a ringing channel.
1522
</synopsis>
1523
<syntax>
1524
<parameter name="channel" required="true" />
1525
<parameter name="channel2" multiple="true" />
1526
</syntax>
1527
<description>
1528
<para>This will pickup a specified <replaceable>channel</replaceable> if ringing.</para>
1529
</description>
1530
</application>
1531
<application name="Directory" language="en_US">
1532
<synopsis>
1533
Provide directory of voicemail extensions.
1534
</synopsis>
1535
<syntax>
1536
<parameter name="vm-context">
1537
<para>This is the context within voicemail.conf to use for the Directory. If not specified and
1538
<literal>searchcontexts=no</literal> in <filename>voicemail.conf</filename>, then <literal>default</literal>
1539
will be assumed.</para>
1540
</parameter>
1541
<parameter name="dial-context" required="false">
1542
<para>This is the dialplan context to use when looking for an
1543
extension that the user has selected, or when jumping to the
1544
<literal>o</literal> or <literal>a</literal> extension.</para>
1545
</parameter>
1546
<parameter name="options" required="false">
1547
<optionlist>
1548
<option name="e">
1549
<para>In addition to the name, also read the extension number to the
1550
caller before presenting dialing options.</para>
1551
</option>
1552
<option name="f">
1553
<para>Allow the caller to enter the first name of a user in the
1554
directory instead of using the last name. If specified, the
1555
optional number argument will be used for the number of
1556
characters the user should enter.</para>
1557
<argument name="n" required="true" />
1558
</option>
1559
<option name="l">
1560
<para>Allow the caller to enter the last name of a user in the
1561
directory. This is the default. If specified, the
1562
optional number argument will be used for the number of
1563
characters the user should enter.</para>
1564
<argument name="n" required="true" />
1565
</option>
1566
<option name="b">
1567
<para> Allow the caller to enter either the first or the last name
1568
of a user in the directory. If specified, the optional number
1569
argument will be used for the number of characters the user should enter.</para>
1570
<argument name="n" required="true" />
1571
</option>
1572
<option name="m">
1573
<para>Instead of reading each name sequentially and asking for
1574
confirmation, create a menu of up to 8 names.</para>
1575
</option>
1576
<option name="p">
1577
<para>Pause for n milliseconds after the digits are typed. This is
1578
helpful for people with cellphones, who are not holding the
1579
receiver to their ear while entering DTMF.</para>
1580
<argument name="n" required="true" />
1581
</option>
1582
</optionlist>
1583
<note><para>Only one of the <replaceable>f</replaceable>, <replaceable>l</replaceable>, or <replaceable>b</replaceable>
1584
options may be specified. <emphasis>If more than one is specified</emphasis>, then Directory will act as
1585
if <replaceable>b</replaceable> was specified. The number
1586
of characters for the user to type defaults to <literal>3</literal>.</para></note>
1587
</parameter>
1588
</syntax>
1589
<description>
1590
<para>This application will present the calling channel with a directory of extensions from which they can search
1591
by name. The list of names and corresponding extensions is retrieved from the
1592
voicemail configuration file, <filename>voicemail.conf</filename>.</para>
1593
<para>This application will immediately exit if one of the following DTMF digits are
1594
received and the extension to jump to exists:</para>
1595
<para><literal>0</literal> - Jump to the 'o' extension, if it exists.</para>
1596
<para><literal>*</literal> - Jump to the 'a' extension, if it exists.</para>
1597
</description>
1598
</application>
1599
1600
<application name="DISA" language="en_US">
1601
<synopsis>
1602
Direct Inward System Access.
1603
</synopsis>
1604
<syntax>
1605
<parameter name="passcode|filename" required="true">
1606
<para>If you need to present a DISA dialtone without entering a password,
1607
simply set <replaceable>passcode</replaceable> to <literal>no-password</literal></para>
1608
<para>You may specified a <replaceable>filename</replaceable> instead of a
1609
<replaceable>passcode</replaceable>, this filename must contain individual passcodes</para>
1610
</parameter>
1611
<parameter name="context">
1612
<para>Specifies the dialplan context in which the user-entered extension
1613
will be matched. If no context is specified, the DISA application defaults
1614
to the <literal>disa</literal> context. Presumably a normal system will have a special
1615
context set up for DISA use with some or a lot of restrictions.</para>
1616
</parameter>
1617
<parameter name="cid">
1618
<para>Specifies a new (different) callerid to be used for this call.</para>
1619
</parameter>
1620
<parameter name="mailbox" argsep="@">
1621
<para>Will cause a stutter-dialtone (indication <emphasis>dialrecall</emphasis>)
1622
to be used, if the specified mailbox contains any new messages.</para>
1623
<argument name="mailbox" required="true" />
1624
<argument name="context" required="false" />
1625
</parameter>
1626
<parameter name="options">
1627
<optionlist>
1628
<option name="n">
1629
<para>The DISA application will not answer initially.</para>
1630
</option>
1631
<option name="p">
1632
<para>The extension entered will be considered complete when a <literal>#</literal>
1633
is entered.</para>
1634
</option>
1635
</optionlist>
1636
</parameter>
1637
</syntax>
1638
<description>
1639
<para>The DISA, Direct Inward System Access, application allows someone from
1640
outside the telephone switch (PBX) to obtain an <emphasis>internal</emphasis> system
1641
dialtone and to place calls from it as if they were placing a call from
1642
within the switch.
1643
DISA plays a dialtone. The user enters their numeric passcode, followed by
1644
the pound sign <literal>#</literal>. If the passcode is correct, the user is then given
1645
system dialtone within <replaceable>context</replaceable> on which a call may be placed.
1646
If the user enters an invalid extension and extension <literal>i</literal> exists in the specified
1647
<replaceable>context</replaceable>, it will be used.
1648
</para>
1649
<para>Be aware that using this may compromise the security of your PBX.</para>
1650
<para>The arguments to this application (in <filename>extensions.conf</filename>) allow either
1651
specification of a single global <replaceable>passcode</replaceable> (that everyone uses), or
1652
individual passcodes contained in a file (<replaceable>filename</replaceable>).</para>
1653
<para>The file that contains the passcodes (if used) allows a complete
1654
specification of all of the same arguments available on the command
1655
line, with the sole exception of the options. The file may contain blank
1656
lines, or comments starting with <literal>#</literal> or <literal>;</literal>.</para>
1657
</description>
1658
<see-also>
1659
<ref type="application">Authenticate</ref>
1660
<ref type="application">VMAuthenticate</ref>
1661
</see-also>
1662
</application>
1663
<application name="DumpChan" language="en_US">
1664
<synopsis>
1665
Dump Info About The Calling Channel.
1666
</synopsis>
1667
<syntax>
1668
<parameter name="level">
1669
<para>Minimun verbose level</para>
1670
</parameter>
1671
</syntax>
1672
<description>
1673
<para>Displays information on channel and listing of all channel
1674
variables. If <replaceable>level</replaceable> is specified, output is only
1675
displayed when the verbose level is currently set to that number
1676
or greater.</para>
1677
</description>
1678
<see-also>
1679
<ref type="application">NoOp</ref>
1680
<ref type="application">Verbose</ref>
1681
</see-also>
1682
</application>
1683
<application name="Echo" language="en_US">
1684
<synopsis>
1685
Echo audio, video, DTMF back to the calling party
1686
</synopsis>
1687
<syntax />
1688
<description>
1689
<para>Echos back any audio, video or DTMF frames read from the calling
1690
channel back to itself. Note: If '#' detected application exits</para>
1691
</description>
1692
</application>
1693
<application name="Exec" language="en_US">
1694
<synopsis>
1695
Executes dialplan application.
1696
</synopsis>
1697
<syntax>
1698
<parameter name="appname" required="true" hasparams="true">
1699
<para>Application name and arguments of the dialplan application to execute.</para>
1700
<argument name="arguments" required="true" />
1701
</parameter>
1702
</syntax>
1703
<description>
1704
<para>Allows an arbitrary application to be invoked even when not
1705
hard coded into the dialplan. If the underlying application
1706
terminates the dialplan, or if the application cannot be found,
1707
Exec will terminate the dialplan.</para>
1708
<para>To invoke external applications, see the application System.
1709
If you would like to catch any error instead, see TryExec.</para>
1710
</description>
1711
</application>
1712
<application name="TryExec" language="en_US">
1713
<synopsis>
1714
Executes dialplan application, always returning.
1715
</synopsis>
1716
<syntax>
1717
<parameter name="appname" required="true" hasparams="true">
1718
<argument name="arguments" required="true" />
1719
</parameter>
1720
</syntax>
1721
<description>
1722
<para>Allows an arbitrary application to be invoked even when not
1723
hard coded into the dialplan. To invoke external applications
1724
see the application System. Always returns to the dialplan.
1725
The channel variable TRYSTATUS will be set to one of:
1726
</para>
1727
<variablelist>
1728
<variable name="TRYSTATUS">
1729
<value name="SUCCESS">
1730
If the application returned zero.
1731
</value>
1732
<value name="FAILED">
1733
If the application returned non-zero.
1734
</value>
1735
<value name="NOAPP">
1736
If the application was not found or was not specified.
1737
</value>
1738
</variable>
1739
</variablelist>
1740
</description>
1741
</application>
1742
<application name="ExecIf" language="en_US">
1743
<synopsis>
1744
Executes dialplan application, conditionally.
1745
</synopsis>
1746
<syntax argsep="?">
1747
<parameter name="expression" required="true" />
1748
<parameter name="execapp" required="true" argsep=":">
1749
<argument name="appiftrue" required="true" hasparams="true">
1750
<argument name="args" required="true" />
1751
</argument>
1752
<argument name="appiffalse" required="false" hasparams="true">
1753
<argument name="args" required="true" />
1754
</argument>
1755
</parameter>
1756
</syntax>
1757
<description>
1758
<para>If <replaceable>expr</replaceable> is true, execute and return the
1759
result of <replaceable>appiftrue(args)</replaceable>.</para>
1760
<para>If <replaceable>expr</replaceable> is true, but <replaceable>appiftrue</replaceable> is not found,
1761
then the application will return a non-zero value.</para>
1762
</description>
1763
</application>
1764
<application name="SendFAX" language="en_US">
1765
<synopsis>
1766
Send a Fax
1767
</synopsis>
1768
<syntax>
1769
<parameter name="filename" required="true">
1770
<para>Filename of TIFF file to fax</para>
1771
</parameter>
1772
<parameter name="a" required="false">
1773
<para>Makes the application behave as the answering machine</para>
1774
<para>(Default behavior is as calling machine)</para>
1775
</parameter>
1776
</syntax>
1777
<description>
1778
<para>Send a given TIFF file to the channel as a FAX.</para>
1779
<para>This application sets the following channel variables:</para>
1780
<variablelist>
1781
<variable name="LOCALSTATIONID">
1782
<para>To identify itself to the remote end</para>
1783
</variable>
1784
<variable name="LOCALHEADERINFO">
1785
<para>To generate a header line on each page</para>
1786
</variable>
1787
<variable name="FAXSTATUS">
1788
<value name="SUCCESS"/>
1789
<value name="FAILED"/>
1790
</variable>
1791
<variable name="FAXERROR">
1792
<para>Cause of failure</para>
1793
</variable>
1794
<variable name="REMOTESTATIONID">
1795
<para>The CSID of the remote side</para>
1796
</variable>
1797
<variable name="FAXPAGES">
1798
<para>Number of pages sent</para>
1799
</variable>
1800
<variable name="FAXBITRATE">
1801
<para>Transmission rate</para>
1802
</variable>
1803
<variable name="FAXRESOLUTION">
1804
<para>Resolution of sent fax</para>
1805
</variable>
1806
</variablelist>
1807
</description>
1808
</application>
1809
<application name="ReceiveFAX" language="en_US">
1810
<synopsis>
1811
Receive a Fax
1812
</synopsis>
1813
<syntax>
1814
<parameter name="filename" required="true">
1815
<para>Filename of TIFF file save incoming fax</para>
1816
</parameter>
1817
<parameter name="c" required="false">
1818
<para>Makes the application behave as the calling machine</para>
1819
<para>(Default behavior is as answering machine)</para>
1820
</parameter>
1821
</syntax>
1822
<description>
1823
<para>Receives a FAX from the channel into the given filename
1824
overwriting the file if it already exists.</para>
1825
<para>File created will be in TIFF format.</para>
1826
1827
<para>This application sets the following channel variables:</para>
1828
<variablelist>
1829
<variable name="LOCALSTATIONID">
1830
<para>To identify itself to the remote end</para>
1831
</variable>
1832
<variable name="LOCALHEADERINFO">
1833
<para>To generate a header line on each page</para>
1834
</variable>
1835
<variable name="FAXSTATUS">
1836
<value name="SUCCESS"/>
1837
<value name="FAILED"/>
1838
</variable>
1839
<variable name="FAXERROR">
1840
<para>Cause of failure</para>
1841
</variable>
1842
<variable name="REMOTESTATIONID">
1843
<para>The CSID of the remote side</para>
1844
</variable>
1845
<variable name="FAXPAGES">
1846
<para>Number of pages sent</para>
1847
</variable>
1848
<variable name="FAXBITRATE">
1849
<para>Transmission rate</para>
1850
</variable>
1851
<variable name="FAXRESOLUTION">
1852
<para>Resolution of sent fax</para>
1853
</variable>
1854
</variablelist>
1855
</description>
1856
</application>
1857
1858
<application name="Festival" language="en_US">
1859
<synopsis>
1860
Say text to the user.
1861
</synopsis>
1862
<syntax>
1863
<parameter name="text" required="true" />
1864
<parameter name="intkeys" />
1865
</syntax>
1866
<description>
1867
<para>Connect to Festival, send the argument, get back the waveform, play it to the user,
1868
allowing any given interrupt keys to immediately terminate and return the value, or
1869
<literal>any</literal> to allow any number back (useful in dialplan).</para>
1870
</description>
1871
</application>
1872
<application name="Flash" language="en_US">
1873
<synopsis>
1874
Flashes a DAHDI Trunk.
1875
</synopsis>
1876
<syntax />
1877
<description>
1878
<para>Performs a flash on a DAHDI trunk. This can be used to access features
1879
provided on an incoming analogue circuit such as conference and call waiting.
1880
Use with SendDTMF() to perform external transfers.</para>
1881
</description>
1882
<see-also>
1883
<ref type="application">SendDTMF</ref>
1884
</see-also>
1885
</application>
1886
<application name="FollowMe" language="en_US">
1887
<synopsis>
1888
Find-Me/Follow-Me application.
1889
</synopsis>
1890
<syntax>
1891
<parameter name="followmeid" required="true" />
1892
<parameter name="options">
1893
<optionlist>
1894
<option name="s">
1895
<para>Playback the incoming status message prior to starting
1896
the follow-me step(s)</para>
1897
</option>
1898
<option name="a">
1899
<para>Record the caller's name so it can be announced to the
1900
callee on each step.</para>
1901
</option>
1902
<option name="n">
1903
<para>Playback the unreachable status message if we've run out
1904
of steps to reach the or the callee has elected not to be reachable.</para>
1905
</option>
1906
</optionlist>
1907
</parameter>
1908
</syntax>
1909
<description>
1910
<para>This application performs Find-Me/Follow-Me functionality for the caller
1911
as defined in the profile matching the <replaceable>followmeid</replaceable> parameter in
1912
<filename>followme.conf</filename>. If the specified <replaceable>followmeid</replaceable>
1913
profile doesn't exist in <filename>followme.conf</filename>, execution will be returned
1914
to the dialplan and call execution will continue at the next priority.</para>
1915
<para>Returns -1 on hangup.</para>
1916
</description>
1917
</application>
1918
<application name="ForkCDR" language="en_US">
1919
<synopsis>
1920
Forks the Call Data Record.
1921
</synopsis>
1922
<syntax>
1923
<parameter name="options">
1924
<optionlist>
1925
<option name="a">
1926
<para>Update the answer time on the NEW CDR just after it's been inited.
1927
The new CDR may have been answered already. The reset that forkcdr does
1928
will erase the answer time. This will bring it back, but the answer time
1929
will be a copy of the fork/start time. It will only do this if the initial
1930
cdr was indeed already answered.</para>
1931
</option>
1932
<option name="A">
1933
<para>Lock the original CDR against the answer time being updated. This
1934
will allow the disposition on the original CDR to remain the same.</para>
1935
</option>
1936
<option name="d">
1937
<para>Copy the disposition forward from the old cdr, after the init.</para>
1938
</option>
1939
<option name="D">
1940
<para>Clear the <literal>dstchannel</literal> on the new CDR after
1941
reset.</para>
1942
</option>
1943
<option name="e">
1944
<para>End the original CDR. Do this after all the neccessry data is copied
1945
from the original CDR to the new forked CDR.</para>
1946
</option>
1947
<option name="r">
1948
<para>Do <emphasis>NOT</emphasis> reset the new cdr.</para>
1949
</option>
1950
<option name="s(name=val)">
1951
<para>Set the CDR var <replaceable>name</replaceable> in the original CDR,
1952
with value <replaceable>val</replaceable>.</para>
1953
</option>
1954
<option name="T">
1955
<para>Mark the original CDR with a DONT_TOUCH flag. setvar, answer, and end
1956
cdr funcs will obey this flag; normally they don't honor the LOCKED flag
1957
set on the original CDR record.</para>
1958
<note><para>Using this flag may cause CDR's not to have their end times
1959
updated! It is suggested that if you specify this flag, you might wish
1960
to use the <literal>e</literal> flag as well!.</para></note>
1961
</option>
1962
<option name="v">
1963
<para>When the new CDR is forked, it gets a copy of the vars attached to
1964
the current CDR. The vars attached to the original CDR are removed unless
1965
this option is specified.</para>
1966
</option>
1967
</optionlist>
1968
</parameter>
1969
</syntax>
1970
<description>
1971
<para> Causes the Call Data Record to fork an additional cdr record starting from the time
1972
of the fork call. This new cdr record will be linked to end of the list of cdr records attached
1973
to the channel. The original CDR has a LOCKED flag set, which forces most cdr operations to skip
1974
it, except for the functions that set the answer and end times, which ignore the LOCKED flag. This
1975
allows all the cdr records in the channel to be 'ended' together when the channel is closed.</para>
1976
<para>The CDR() func (when setting CDR values) normally ignores the LOCKED flag also, but has options
1977
to vary its behavior. The 'T' option (described below), can override this behavior, but beware
1978
the risks.</para>
1979
<para>First, this app finds the last cdr record in the list, and makes a copy of it. This new copy
1980
will be the newly forked cdr record. Next, this new record is linked to the end of the cdr record list.
1981
Next, The new cdr record is RESET (unless you use an option to prevent this)</para>
1982
<para>This means that:</para>
1983
<para> 1. All flags are unset on the cdr record</para>
1984
<para> 2. the start, end, and answer times are all set to zero.</para>
1985
<para> 3. the billsec and duration fields are set to zero.</para>
1986
<para> 4. the start time is set to the current time.</para>
1987
<para> 5. the disposition is set to NULL.</para>
1988
<para>Next, unless you specified the <literal>v</literal> option, all variables will be removed from
1989
the original cdr record. Thus, the <literal>v</literal> option allows any CDR variables to be replicated
1990
to all new forked cdr records. Without the <literal>v</literal> option, the variables on the original
1991
are effectively moved to the new forked cdr record.</para>
1992
<para>Next, if the <literal>s</literal> option is set, the provided variable and value are set on the
1993
original cdr record.</para>
1994
<para>Next, if the <literal>a</literal> option is given, and the original cdr record has an answer time
1995
set, then the new forked cdr record will have its answer time set to its start time. If the old answer
1996
time were carried forward, the answer time would be earlier than the start time, giving strange
1997
duration and billsec times.</para>
1998
<para>If the <literal>d</literal> option was specified, the disposition is copied from
1999
the original cdr record to the new forked cdr. If the <literal>D</literal> option was specified,
2000
the destination channel field in the new forked CDR is erased. If the <literal>e</literal> option
2001
was specified, the 'end' time for the original cdr record is set to the current time. Future hang-up or
2002
ending events will not override this time stamp. If the <literal>A</literal> option is specified,
2003
the original cdr record will have it ANS_LOCKED flag set, which prevent future answer events from updating
2004
the original cdr record's disposition. Normally, an <literal>ANSWERED</literal> event would mark all cdr
2005
records in the chain as <literal>ANSWERED</literal>. If the <literal>T</literal> option is specified,
2006
the original cdr record will have its <literal>DONT_TOUCH</literal> flag set, which will force the
2007
cdr_answer, cdr_end, and cdr_setvar functions to leave that cdr record alone.</para>
2008
<para>And, last but not least, the original cdr record has its LOCKED flag set. Almost all internal
2009
CDR functions (except for the funcs that set the end, and answer times, and set a variable) will honor
2010
this flag and leave a LOCKED cdr record alone. This means that the newly created forked cdr record
2011
will be affected by events transpiring within Asterisk, with the previously noted exceptions.</para>
2012
</description>
2013
<see-also>
2014
<ref type="function">CDR</ref>
2015
<ref type="application">NoCDR</ref>
2016
<ref type="application">ResetCDR</ref>
2017
</see-also>
2018
</application>
2019
<application name="GetCPEID" language="en_US">
2020
<synopsis>
2021
Get ADSI CPE ID.
2022
</synopsis>
2023
<syntax />
2024
<description>
2025
<para>Obtains and displays ADSI CPE ID and other information in order
2026
to properly setup <filename>dahdi.conf</filename> for on-hook operations.</para>
2027
</description>
2028
</application>
2029
<application name="ICES" language="en_US">
2030
<synopsis>
2031
Encode and stream using 'ices'.
2032
</synopsis>
2033
<syntax>
2034
<parameter name="config" required="true">
2035
<para>ICES configuration file.</para>
2036
</parameter>
2037
</syntax>
2038
<description>
2039
<para>Streams to an icecast server using ices (available separately).
2040
A configuration file must be supplied for ices (see contrib/asterisk-ices.xml).</para>
2041
<note><para>ICES version 2 cient and server required.</para></note>
2042
</description>
2043
</application>
2044
2045
<application name="SendImage" language="en_US">
2046
<synopsis>
2047
Sends an image file.
2048
</synopsis>
2049
<syntax>
2050
<parameter name="filename" required="true">
2051
<para>Path of the filename (image) to send.</para>
2052
</parameter>
2053
</syntax>
2054
<description>
2055
<para>Send an image file on a channel supporting it.</para>
2056
<para>Result of transmission will be stored in <variable>SENDIMAGESTATUS</variable></para>
2057
<variablelist>
2058
<variable name="SENDIMAGESTATUS">
2059
<value name="SUCCESS">
2060
Transmission succeeded.
2061
</value>
2062
<value name="FAILURE">
2063
Transmission failed.
2064
</value>
2065
<value name="UNSUPPORTED">
2066
Image transmission not supported by channel.
2067
</value>
2068
</variable>
2069
</variablelist>
2070
</description>
2071
<see-also>
2072
<ref type="application">SendText</ref>
2073
<ref type="application">SendURL</ref>
2074
</see-also>
2075
</application>
2076
<application name="IVRDemo" language="en_US">
2077
<synopsis>
2078
IVR Demo Application.
2079
</synopsis>
2080
<syntax>
2081
<parameter name="filename" required="true" />
2082
</syntax>
2083
<description>
2084
<para>This is a skeleton application that shows you the basic structure to create your
2085
own asterisk applications and demonstrates the IVR demo.</para>
2086
</description>
2087
</application>
2088
<application name="JACK" language="en_US">
2089
<synopsis>
2090
Jack Audio Connection Kit
2091
</synopsis>
2092
<syntax>
2093
<parameter name="options" required="false">
2094
<optionlist>
2095
<option name="s">
2096
<argument name="name" required="true">
2097
<para>Connect to the specified jack server name</para>
2098
</argument>
2099
</option>
2100
<option name="i">
2101
<argument name="name" required="true">
2102
<para>Connect the output port that gets created to the specified jack input port</para>
2103
</argument>
2104
</option>
2105
<option name="o">
2106
<argument name="name" required="true">
2107
<para>Connect the input port that gets created to the specified jack output port</para>
2108
</argument>
2109
</option>
2110
<option name="c">
2111
<argument name="name" required="true">
2112
<para>By default, Asterisk will use the channel name for the jack client name.</para>
2113
<para>Use this option to specify a custom client name.</para>
2114
</argument>
2115
</option>
2116
</optionlist>
2117
</parameter>
2118
</syntax>
2119
<description>
2120
<para>When executing this application, two jack ports will be created;
2121
one input and one output. Other applications can be hooked up to
2122
these ports to access audio coming from, or being send to the channel.</para>
2123
</description>
2124
</application>
2125
<application name="Macro" language="en_US">
2126
<synopsis>
2127
Macro Implementation.
2128
</synopsis>
2129
<syntax>
2130
<parameter name="name" required="true">
2131
<para>The name of the macro</para>
2132
</parameter>
2133
<parameter name="args">
2134
<argument name="arg1" required="true" />
2135
<argument name="arg2" multiple="true" />
2136
</parameter>
2137
</syntax>
2138
<description>
2139
<para>Executes a macro using the context macro-<replaceable>name</replaceable>,
2140
jumping to the <literal>s</literal> extension of that context and executing each step,
2141
then returning when the steps end.</para>
2142
<para>The calling extension, context, and priority are stored in <variable>MACRO_EXTEN</variable>,
2143
<variable>MACRO_CONTEXT</variable> and <variable>MACRO_PRIORITY</variable> respectively. Arguments
2144
become <variable>ARG1</variable>, <variable>ARG2</variable>, etc in the macro context.</para>
2145
<para>If you Goto out of the Macro context, the Macro will terminate and control will be returned
2146
at the location of the Goto.</para>
2147
<para>If <variable>MACRO_OFFSET</variable> is set at termination, Macro will attempt to continue
2148
at priority MACRO_OFFSET + N + 1 if such a step exists, and N + 1 otherwise.</para>
2149
<warning><para>Because of the way Macro is implemented (it executes the priorities contained within
2150
it via sub-engine), and a fixed per-thread memory stack allowance, macros are limited to 7 levels
2151
of nesting (macro calling macro calling macro, etc.); It may be possible that stack-intensive
2152
applications in deeply nested macros could cause asterisk to crash earlier than this limit.
2153
It is advised that if you need to deeply nest macro calls, that you use the Gosub application
2154
(now allows arguments like a Macro) with explict Return() calls instead.</para></warning>
2155
<warning><para>Use of the application <literal>WaitExten</literal> within a macro will not function
2156
as expected. Please use the <literal>Read</literal> application in order to read DTMF from a channel
2157
currently executing a macro.</para></warning>
2158
</description>
2159
<see-also>
2160
<ref type="application">MacroExit</ref>
2161
<ref type="application">Goto</ref>
2162
<ref type="application">Gosub</ref>
2163
</see-also>
2164
</application>
2165
<application name="MacroIf" language="en_US">
2166
<synopsis>
2167
Conditional Macro implementation.
2168
</synopsis>
2169
<syntax argsep="?">
2170
<parameter name="expr" required="true" />
2171
<parameter name="destination" required="true" argsep=":">
2172
<argument name="macroiftrue" required="true">
2173
<argument name="macroiftrue" required="true" />
2174
<argument name="arg1" multiple="true" />
2175
</argument>
2176
<argument name="macroiffalse">
2177
<argument name="macroiffalse" required="true" />
2178
<argument name="arg1" multiple="true" />
2179
</argument>
2180
</parameter>
2181
</syntax>
2182
<description>
2183
<para>Executes macro defined in <replaceable>macroiftrue</replaceable> if
2184
<replaceable>expr</replaceable> is true (otherwise <replaceable>macroiffalse</replaceable>
2185
if provided)</para>
2186
<para>Arguments and return values as in application Macro()</para>
2187
<xi:include xpointer="xpointer(/docs/application[@name='Macro']/description/warning[2])" />
2188
</description>
2189
<see-also>
2190
<ref type="application">GotoIf</ref>
2191
<ref type="application">GosubIf</ref>
2192
<ref type="function">IF</ref>
2193
</see-also>
2194
</application>
2195
<application name="MacroExclusive" language="en_US">
2196
<synopsis>
2197
Exclusive Macro Implementation.
2198
</synopsis>
2199
<syntax>
2200
<parameter name="name" required="true">
2201
<para>The name of the macro</para>
2202
</parameter>
2203
<parameter name="arg1" />
2204
<parameter name="arg2" multiple="true" />
2205
</syntax>
2206
<description>
2207
<para>Executes macro defined in the context macro-<replaceable>name</replaceable>.
2208
Only one call at a time may run the macro. (we'll wait if another call is busy
2209
executing in the Macro)</para>
2210
<para>Arguments and return values as in application Macro()</para>
2211
<xi:include xpointer="xpointer(/docs/application[@name='Macro']/description/warning[2])" />
2212
</description>
2213
<see-also>
2214
<ref type="application">Macro</ref>
2215
</see-also>
2216
</application>
2217
<application name="MacroExit" language="en_US">
2218
<synopsis>
2219
Exit from Macro.
2220
</synopsis>
2221
<syntax />
2222
<description>
2223
<para>Causes the currently running macro to exit as if it had
2224
ended normally by running out of priorities to execute.
2225
If used outside a macro, will likely cause unexpected behavior.</para>
2226
</description>
2227
<see-also>
2228
<ref type="application">Macro</ref>
2229
</see-also>
2230
</application>
2231
<application name="MeetMe" language="en_US">
2232
<synopsis>
2233
MeetMe conference bridge.
2234
</synopsis>
2235
<syntax>
2236
<parameter name="confno">
2237
<para>The conference number</para>
2238
</parameter>
2239
<parameter name="options">
2240
<optionlist>
2241
<option name="a">
2242
<para>Set admin mode.</para>
2243
</option>
2244
<option name="A">
2245
<para>Set marked mode.</para>
2246
</option>
2247
<option name="b">
2248
<para>Run AGI script specified in <variable>MEETME_AGI_BACKGROUND</variable>
2249
Default: <literal>conf-background.agi</literal>.</para>
2250
<note><para>This does not work with non-DAHDI channels in the same
2251
conference).</para></note>
2252
</option>
2253
<option name="c">
2254
<para>Announce user(s) count on joining a conference.</para>
2255
</option>
2256
<option name="C">
2257
<para>Continue in dialplan when kicked out of conference.</para>
2258
</option>
2259
<option name="d">
2260
<para>Dynamically add conference.</para>
2261
</option>
2262
<option name="D">
2263
<para>Dynamically add conference, prompting for a PIN.</para>
2264
</option>
2265
<option name="e">
2266
<para>Select an empty conference.</para>
2267
</option>
2268
<option name="E">
2269
<para>Select an empty pinless conference.</para>
2270
</option>
2271
<option name="F">
2272
<para>Pass DTMF through the conference.</para>
2273
</option>
2274
<option name="i">
2275
<para>Announce user join/leave with review.</para>
2276
</option>
2277
<option name="I">
2278
<para>Announce user join/leave without review.</para>
2279
</option>
2280
<option name="l">
2281
<para>Set listen only mode (Listen only, no talking).</para>
2282
</option>
2283
<option name="m">
2284
<para>Set initially muted.</para>
2285
</option>
2286
<option name="M" hasparams="optional">
2287
<para>Enable music on hold when the conference has a single caller. Optionally,
2288
specify a musiconhold class to use. If one is not provided, it will use the
2289
channel's currently set music class, or <literal>default</literal>.</para>
2290
<argument name="class" required="true" />
2291
</option>
2292
<option name="o">
2293
<para>Set talker optimization - treats talkers who aren't speaking as
2294
being muted, meaning (a) No encode is done on transmission and (b)
2295
Received audio that is not registered as talking is omitted causing no
2296
buildup in background noise.</para>
2297
</option>
2298
<option name="p" hasparams="optional">
2299
<para>Allow user to exit the conference by pressing <literal>#</literal> (default)
2300
or any of the defined keys. If keys contain <literal>*</literal> this will override
2301
option <literal>s</literal>. The key used is set to channel variable
2302
<variable>MEETME_EXIT_KEY</variable>.</para>
2303
<argument name="keys" required="true" />
2304
</option>
2305
<option name="P">
2306
<para>Always prompt for the pin even if it is specified.</para>
2307
</option>
2308
<option name="q">
2309
<para>Quiet mode (don't play enter/leave sounds).</para>
2310
</option>
2311
<option name="r">
2312
<para>Record conference (records as <variable>MEETME_RECORDINGFILE</variable>
2313
using format <variable>MEETME_RECORDINGFORMAT</variable>. Default filename is
2314
<literal>meetme-conf-rec-${CONFNO}-${UNIQUEID}</literal> and the default format is
2315
wav.</para>
2316
</option>
2317
<option name="s">
2318
<para>Present menu (user or admin) when <literal>*</literal> is received
2319
(send to menu).</para>
2320
</option>
2321
<option name="t">
2322
<para>Set talk only mode. (Talk only, no listening).</para>
2323
</option>
2324
<option name="T">
2325
<para>Set talker detection (sent to manager interface and meetme list).</para>
2326
</option>
2327
<option name="W" hasparams="optional">
2328
<para>Wait until the marked user enters the conference.</para>
2329
<argument name="secs" required="true" />
2330
</option>
2331
<option name="x">
2332
<para>Close the conference when last marked user exits</para>
2333
</option>
2334
<option name="X">
2335
<para>Allow user to exit the conference by entering a valid single digit
2336
extension <variable>MEETME_EXIT_CONTEXT</variable> or the current context
2337
if that variable is not defined.</para>
2338
</option>
2339
<option name="1">
2340
<para>Do not play message when first person enters</para>
2341
</option>
2342
<option name="S">
2343
<para>Kick the user <replaceable>x</replaceable> seconds <emphasis>after</emphasis> he entered into
2344
the conference.</para>
2345
<argument name="x" required="true" />
2346
</option>
2347
<option name="L" argsep=":">
2348
<para>Limit the conference to <replaceable>x</replaceable> ms. Play a warning when
2349
<replaceable>y</replaceable> ms are left. Repeat the warning every <replaceable>z</replaceable> ms.
2350
The following special variables can be used with this option:</para>
2351
<variablelist>
2352
<variable name="CONF_LIMIT_TIMEOUT_FILE">
2353
<para>File to play when time is up.</para>
2354
</variable>
2355
<variable name="CONF_LIMIT_WARNING_FILE">
2356
<para>File to play as warning if <replaceable>y</replaceable> is defined. The
2357
default is to say the time remaining.</para>
2358
</variable>
2359
</variablelist>
2360
<argument name="x" />
2361
<argument name="y" />
2362
<argument name="z" />
2363
</option>
2364
</optionlist>
2365
</parameter>
2366
<parameter name="pin" />
2367
</syntax>
2368
<description>
2369
<para>Enters the user into a specified MeetMe conference. If the <replaceable>confno</replaceable>
2370
is omitted, the user will be prompted to enter one. User can exit the conference by hangup, or
2371
if the <literal>p</literal> option is specified, by pressing <literal>#</literal>.</para>
2372
<note><para>The DAHDI kernel modules and at least one hardware driver (or dahdi_dummy)
2373
must be present for conferencing to operate properly. In addition, the chan_dahdi channel driver
2374
must be loaded for the <literal>i</literal> and <literal>r</literal> options to operate at
2375
all.</para></note>
2376
</description>
2377
<see-also>
2378
<ref type="application">MeetMeCount</ref>
2379
<ref type="application">MeetMeAdmin</ref>
2380
<ref type="application">MeetMeChannelAdmin</ref>
2381
</see-also>
2382
</application>
2383
<application name="MeetMeCount" language="en_US">
2384
<synopsis>
2385
MeetMe participant count.
2386
</synopsis>
2387
<syntax>
2388
<parameter name="confno" required="true">
2389
<para>Conference number.</para>
2390
</parameter>
2391
<parameter name="var" />
2392
</syntax>
2393
<description>
2394
<para>Plays back the number of users in the specified MeetMe conference.
2395
If <replaceable>var</replaceable> is specified, playback will be skipped and the value
2396
will be returned in the variable. Upon application completion, MeetMeCount will hangup
2397
the channel, unless priority <literal>n+1</literal> exists, in which case priority progress will
2398
continue.</para>
2399
</description>
2400
<see-also>
2401
<ref type="application">MeetMe</ref>
2402
</see-also>
2403
</application>
2404
<application name="MeetMeAdmin" language="en_US">
2405
<synopsis>
2406
MeetMe conference administration.
2407
</synopsis>
2408
<syntax>
2409
<parameter name="confno" required="true" />
2410
<parameter name="command" required="true">
2411
<optionlist>
2412
<option name="e">
2413
<para>Eject last user that joined.</para>
2414
</option>
2415
<option name="E">
2416
<para>Extend conference end time, if scheduled.</para>
2417
</option>
2418
<option name="k">
2419
<para>Kick one user out of conference.</para>
2420
</option>
2421
<option name="K">
2422
<para>Kick all users out of conference.</para>
2423
</option>
2424
<option name="l">
2425
<para>Unlock conference.</para>
2426
</option>
2427
<option name="L">
2428
<para>Lock conference.</para>
2429
</option>
2430
<option name="m">
2431
<para>Unmute one user.</para>
2432
</option>
2433
<option name="M">
2434
<para>Mute one user.</para>
2435
</option>
2436
<option name="n">
2437
<para>Unmute all users in the conference.</para>
2438
</option>
2439
<option name="N">
2440
<para>Mute all non-admin users in the conference.</para>
2441
</option>
2442
<option name="r">
2443
<para>Reset one user's volume settings.</para>
2444
</option>
2445
<option name="R">
2446
<para>Reset all users volume settings.</para>
2447
</option>
2448
<option name="s">
2449
<para>Lower entire conference speaking volume.</para>
2450
</option>
2451
<option name="S">
2452
<para>Raise entire conference speaking volume.</para>
2453
</option>
2454
<option name="t">
2455
<para>Lower one user's talk volume.</para>
2456
</option>
2457
<option name="T">
2458
<para>Raise one user's talk volume.</para>
2459
</option>
2460
<option name="u">
2461
<para>Lower one user's listen volume.</para>
2462
</option>
2463
<option name="U">
2464
<para>Raise one user's listen volume.</para>
2465
</option>
2466
<option name="v">
2467
<para>Lower entire conference listening volume.</para>
2468
</option>
2469
<option name="V">
2470
<para>Raise entire conference listening volume.</para>
2471
</option>
2472
</optionlist>
2473
</parameter>
2474
<parameter name="user" />
2475
</syntax>
2476
<description>
2477
<para>Run admin <replaceable>command</replaceable> for conference <replaceable>confno</replaceable>.</para>
2478
<para>Will additionally set the variable <variable>MEETMEADMINSTATUS</variable> with one of
2479
the following values:</para>
2480
<variablelist>
2481
<variable name="MEETMEADMINSTATUS">
2482
<value name="NOPARSE">
2483
Invalid arguments.
2484
</value>
2485
<value name="NOTFOUND">
2486
User specified was not found.
2487
</value>
2488
<value name="FAILED">
2489
Another failure occurred.
2490
</value>
2491
<value name="OK">
2492
The operation was completed successfully.
2493
</value>
2494
</variable>
2495
</variablelist>
2496
</description>
2497
<see-also>
2498
<ref type="application">MeetMe</ref>
2499
</see-also>
2500
</application>
2501
<application name="MeetMeChannelAdmin" language="en_US">
2502
<synopsis>
2503
MeetMe conference Administration (channel specific).
2504
</synopsis>
2505
<syntax>
2506
<parameter name="channel" required="true" />
2507
<parameter name="command" required="true">
2508
<optionlist>
2509
<option name="k">
2510
<para>Kick the specified user out of the conference he is in.</para>
2511
</option>
2512
<option name="m">
2513
<para>Unmute the specified user.</para>
2514
</option>
2515
<option name="M">
2516
<para>Mute the specified user.</para>
2517
</option>
2518
</optionlist>
2519
</parameter>
2520
</syntax>
2521
<description>
2522
<para>Run admin <replaceable>command</replaceable> for a specific
2523
<replaceable>channel</replaceable> in any coference.</para>
2524
</description>
2525
</application>
2526
<application name="SLAStation" language="en_US">
2527
<synopsis>
2528
Shared Line Appearance Station.
2529
</synopsis>
2530
<syntax>
2531
<parameter name="station" required="true">
2532
<para>Station name</para>
2533
</parameter>
2534
</syntax>
2535
<description>
2536
<para>This application should be executed by an SLA station. The argument depends
2537
on how the call was initiated. If the phone was just taken off hook, then the argument
2538
<replaceable>station</replaceable> should be just the station name. If the call was
2539
initiated by pressing a line key, then the station name should be preceded by an underscore
2540
and the trunk name associated with that line button.</para>
2541
<para>For example: <literal>station1_line1</literal></para>
2542
<para>On exit, this application will set the variable <variable>SLASTATION_STATUS</variable> to
2543
one of the following values:</para>
2544
<variablelist>
2545
<variable name="SLASTATION_STATUS">
2546
<value name="FAILURE" />
2547
<value name="CONGESTION" />
2548
<value name="SUCCESS" />
2549
</variable>
2550
</variablelist>
2551
</description>
2552
</application>
2553
<application name="SLATrunk" language="en_US">
2554
<synopsis>
2555
Shared Line Appearance Trunk.
2556
</synopsis>
2557
<syntax>
2558
<parameter name="trunk" required="true">
2559
<para>Trunk name</para>
2560
</parameter>
2561
<parameter name="options">
2562
<optionlist>
2563
<option name="M" hasparams="optional">
2564
<para>Play back the specified MOH <replaceable>class</replaceable>
2565
instead of ringing</para>
2566
<argument name="class" required="true" />
2567
</option>
2568
</optionlist>
2569
</parameter>
2570
</syntax>
2571
<description>
2572
<para>This application should be executed by an SLA trunk on an inbound call. The channel calling
2573
this application should correspond to the SLA trunk with the name <replaceable>trunk</replaceable>
2574
that is being passed as an argument.</para>
2575
<para>On exit, this application will set the variable <variable>SLATRUNK_STATUS</variable> to
2576
one of the following values:</para>
2577
<variablelist>
2578
<variable name="SLATRUNK_STATUS">
2579
<value name="FAILURE" />
2580
<value name="SUCCESS" />
2581
<value name="UNANSWERED" />
2582
<value name="RINGTIMEOUT" />
2583
</variable>
2584
</variablelist>
2585
</description>
2586
</application>
2587
<application name="Milliwatt" language="en_US">
2588
<synopsis>
2589
Generate a Constant 1004Hz tone at 0dbm (mu-law).
2590
</synopsis>
2591
<syntax>
2592
<parameter name="options">
2593
<optionlist>
2594
<option name="o">
2595
<para>Generate the tone at 1000Hz like previous version.</para>
2596
</option>
2597
</optionlist>
2598
</parameter>
2599
</syntax>
2600
<description>
2601
<para>Previous versions of this application generated the tone at 1000Hz. If for
2602
some reason you would prefer that behavior, supply the <literal>o</literal> option to get the
2603
old behavior.</para>
2604
</description>
2605
</application>
2606
<application name="MinivmRecord" language="en_US">
2607
<synopsis>
2608
Receive Mini-Voicemail and forward via e-mail.
2609
</synopsis>
2610
<syntax>
2611
<parameter name="mailbox" required="true" argsep="@">
2612
<argument name="username" required="true">
2613
<para>Voicemail username</para>
2614
</argument>
2615
<argument name="domain" required="true">
2616
<para>Voicemail domain</para>
2617
</argument>
2618
</parameter>
2619
<parameter name="options" required="false">
2620
<optionlist>
2621
<option name="0">
2622
<para>Jump to the <literal>o</literal> extension in the current dialplan context.</para>
2623
</option>
2624
<option name="*">
2625
<para>Jump to the <literal>a</literal> extension in the current dialplan context.</para>
2626
</option>
2627
<option name="g">
2628
<argument name="gain">
2629
<para>Amount of gain to use</para>
2630
</argument>
2631
<para>Use the specified amount of gain when recording the voicemail message.
2632
The units are whole-number decibels (dB).</para>
2633
</option>
2634
</optionlist>
2635
</parameter>
2636
</syntax>
2637
<description>
2638
<para>This application is part of the Mini-Voicemail system, configured in <filename>minivm.conf</filename></para>
2639
<para>MiniVM records audio file in configured format and forwards message to e-mail and pager.</para>
2640
<para>If there's no user account for that address, a temporary account will be used with default options.</para>
2641
<para>The recorded file name and path will be stored in <variable>MVM_FILENAME</variable> and the duration
2642
of the message will be stored in <variable>MVM_DURATION</variable></para>
2643
<note><para>If the caller hangs up after the recording, the only way to send the message and clean up is to
2644
execute in the <literal>h</literal> extension. The application will exit if any of the following DTMF digits
2645
are received and the requested extension exist in the current context.</para></note>
2646
<variablelist>
2647
<variable name="MVM_RECORD_STATUS">
2648
<para>This is the status of the record operation</para>
2649
<value name="SUCCESS" />
2650
<value name="USEREXIT" />
2651
<value name="FAILED" />
2652
</variable>
2653
</variablelist>
2654
</description>
2655
</application>
2656
<application name="MinivmGreet" language="en_US">
2657
<synopsis>
2658
Play Mini-Voicemail prompts.
2659
</synopsis>
2660
<syntax>
2661
<parameter name="mailbox" required="true" argsep="@">
2662
<argument name="username" required="true">
2663
<para>Voicemail username</para>
2664
</argument>
2665
<argument name="domain" required="true">
2666
<para>Voicemail domain</para>
2667
</argument>
2668
</parameter>
2669
<parameter name="options" required="false">
2670
<optionlist>
2671
<option name="b">
2672
<para>Play the <literal>busy</literal> greeting to the calling party.</para>
2673
</option>
2674
<option name="s">
2675
<para>Skip the playback of instructions for leaving a message to the calling party.</para>
2676
</option>
2677
<option name="u">
2678
<para>Play the <literal>unavailable</literal> greeting.</para>
2679
</option>
2680
</optionlist>
2681
</parameter>
2682
</syntax>
2683
<description>
2684
<para>This application is part of the Mini-Voicemail system, configured in minivm.conf.</para>
2685
<para>MinivmGreet() plays default prompts or user specific prompts for an account.</para>
2686
<para>Busy and unavailable messages can be choosen, but will be overridden if a temporary
2687
message exists for the account.</para>
2688
<variablelist>
2689
<variable name="MVM_GREET_STATUS">
2690
<para>This is the status of the greeting playback.</para>
2691
<value name="SUCCESS" />
2692
<value name="USEREXIT" />
2693
<value name="FAILED" />
2694
</variable>
2695
</variablelist>
2696
</description>
2697
</application>
2698
<application name="MinivmNotify" language="en_US">
2699
<synopsis>
2700
Notify voicemail owner about new messages.
2701
</synopsis>
2702
<syntax>
2703
<parameter name="mailbox" required="true" argsep="@">
2704
<argument name="username" required="true">
2705
<para>Voicemail username</para>
2706
</argument>
2707
<argument name="domain" required="true">
2708
<para>Voicemail domain</para>
2709
</argument>
2710
</parameter>
2711
<parameter name="options" required="false">
2712
<optionlist>
2713
<option name="template">
2714
<para>E-mail template to use for voicemail notification</para>
2715
</option>
2716
</optionlist>
2717
</parameter>
2718
</syntax>
2719
<description>
2720
<para>This application is part of the Mini-Voicemail system, configured in minivm.conf.</para>
2721
<para>MiniVMnotify forwards messages about new voicemail to e-mail and pager. If there's no user
2722
account for that address, a temporary account will be used with default options (set in
2723
<filename>minivm.conf</filename>).</para>
2724
<para>If the channel variable <variable>MVM_COUNTER</variable> is set, this will be used in the message
2725
file name and available in the template for the message.</para>
2726
<para>If no template is given, the default email template will be used to send email and default pager
2727
template to send paging message (if the user account is configured with a paging address.</para>
2728
<variablelist>
2729
<variable name="MVM_NOTIFY_STATUS">
2730
<para>This is the status of the notification attempt</para>
2731
<value name="SUCCESS" />
2732
<value name="FAILED" />
2733
</variable>
2734
</variablelist>
2735
</description>
2736
</application>
2737
<application name="MinivmDelete" language="en_US">
2738
<synopsis>
2739
Delete Mini-Voicemail voicemail messages.
2740
</synopsis>
2741
<syntax>
2742
<parameter name="filename" required="true">
2743
<para>File to delete</para>
2744
</parameter>
2745
</syntax>
2746
<description>
2747
<para>This application is part of the Mini-Voicemail system, configured in <filename>minivm.conf</filename>.</para>
2748
<para>It deletes voicemail file set in MVM_FILENAME or given filename.</para>
2749
<variablelist>
2750
<variable name="MVM_DELETE_STATUS">
2751
<para>This is the status of the delete operation.</para>
2752
<value name="SUCCESS" />
2753
<value name="FAILED" />
2754
</variable>
2755
</variablelist>
2756
</description>
2757
</application>
2758
2759
<application name="MinivmAccMess" language="en_US">
2760
<synopsis>
2761
Record account specific messages.
2762
</synopsis>
2763
<syntax>
2764
<parameter name="mailbox" required="true" argsep="@">
2765
<argument name="username" required="true">
2766
<para>Voicemail username</para>
2767
</argument>
2768
<argument name="domain" required="true">
2769
<para>Voicemail domain</para>
2770
</argument>
2771
</parameter>
2772
<parameter name="options" required="false">
2773
<optionlist>
2774
<option name="u">
2775
<para>Record the <literal>unavailable</literal> greeting.</para>
2776
</option>
2777
<option name="b">
2778
<para>Record the <literal>busy</literal> greeting.</para>
2779
</option>
2780
<option name="t">
2781
<para>Record the temporary greeting.</para>
2782
</option>
2783
<option name="n">
2784
<para>Account name.</para>
2785
</option>
2786
</optionlist>
2787
</parameter>
2788
</syntax>
2789
<description>
2790
<para>This application is part of the Mini-Voicemail system, configured in <filename>minivm.conf</filename>.</para>
2791
<para>Use this application to record account specific audio/video messages for busy, unavailable
2792
and temporary messages.</para>
2793
<para>Account specific directories will be created if they do not exist.</para>
2794
<variablelist>
2795
<variable name="MVM_ACCMESS_STATUS">
2796
<para>This is the result of the attempt to record the specified greeting.</para>
2797
<para><literal>FAILED</literal> is set if the file can't be created.</para>
2798
<value name="SUCCESS" />
2799
<value name="FAILED" />
2800
</variable>
2801
</variablelist>
2802
</description>
2803
</application>
2804
<application name="MinivmMWI" language="en_US">
2805
<synopsis>
2806
Send Message Waiting Notification to subscriber(s) of mailbox.
2807
</synopsis>
2808
<syntax>
2809
<parameter name="mailbox" required="true" argsep="@">
2810
<argument name="username" required="true">
2811
<para>Voicemail username</para>
2812
</argument>
2813
<argument name="domain" required="true">
2814
<para>Voicemail domain</para>
2815
</argument>
2816
</parameter>
2817
<parameter name="urgent" required="true">
2818
<para>Number of urgent messages in mailbox.</para>
2819
</parameter>
2820
<parameter name="new" required="true">
2821
<para>Number of new messages in mailbox.</para>
2822
</parameter>
2823
<parameter name="old" required="true">
2824
<para>Number of old messages in mailbox.</para>
2825
</parameter>
2826
</syntax>
2827
<description>
2828
<para>This application is part of the Mini-Voicemail system, configured in <filename>minivm.conf</filename>.</para>
2829
<para>MinivmMWI is used to send message waiting indication to any devices whose channels have
2830
subscribed to the mailbox passed in the first parameter.</para>
2831
</description>
2832
</application>
2833
<application name="MixMonitor" language="en_US">
2834
<synopsis>
2835
Record a call and mix the audio during the recording. Use of StopMixMonitor is required
2836
to guarantee the audio file is available for processing during dialplan execution.
2837
</synopsis>
2838
<syntax>
2839
<parameter name="file" required="true" argsep=".">
2840
<argument name="filename" required="true">
2841
<para>If <replaceable>filename</replaceable> is an absolute path, uses that path, otherwise
2842
creates the file in the configured monitoring directory from <filename>asterisk.conf.</filename></para>
2843
</argument>
2844
<argument name="extension" required="true" />
2845
</parameter>
2846
<parameter name="options">
2847
<optionlist>
2848
<option name="a">
2849
<para>Append to the file instead of overwriting it.</para>
2850
</option>
2851
<option name="b">
2852
<para>Only save audio to the file while the channel is bridged.</para>
2853
<note><para>Does not include conferences or sounds played to each bridged party</para></note>
2854
<note><para>If you utilize this option inside a Local channel, you must make sure the Local
2855
channel is not optimized away. To do this, be sure to call your Local channel with the
2856
<literal>/n</literal> option. For example: Dial(Local/start@mycontext/n)</para></note>
2857
</option>
2858
<option name="v">
2859
<para>Adjust the <emphasis>heard</emphasis> volume by a factor of <replaceable>x</replaceable>
2860
(range <literal>-4</literal> to <literal>4</literal>)</para>
2861
<argument name="x" required="true" />
2862
</option>
2863
<option name="V">
2864
<para>Adjust the <emphasis>spoken</emphasis> volume by a factor
2865
of <replaceable>x</replaceable> (range <literal>-4</literal> to <literal>4</literal>)</para>
2866
<argument name="x" required="true" />
2867
</option>
2868
<option name="W">
2869
<para>Adjust both, <emphasis>heard and spoken</emphasis> volumes by a factor
2870
of <replaceable>x</replaceable> (range <literal>-4</literal> to <literal>4</literal>)</para>
2871
<argument name="x" required="true" />
2872
</option>
2873
</optionlist>
2874
</parameter>
2875
<parameter name="command">
2876
<para>Will be executed when the recording is over.</para>
2877
<para>Any strings matching <literal>^{X}</literal> will be unescaped to <variable>X</variable>.</para>
2878
<para>All variables will be evaluated at the time MixMonitor is called.</para>
2879
</parameter>
2880
</syntax>
2881
<description>
2882
<para>Records the audio on the current channel to the specified file.</para>
2883
<variablelist>
2884
<variable name="MIXMONITOR_FILENAME">
2885
<para>Will contain the filename used to record.</para>
2886
</variable>
2887
</variablelist>
2888
</description>
2889
<see-also>
2890
<ref type="application">Monitor</ref>
2891
<ref type="application">StopMixMonitor</ref>
2892
<ref type="application">PauseMonitor</ref>
2893
<ref type="application">UnpauseMonitor</ref>
2894
</see-also>
2895
</application>
2896
<application name="StopMixMonitor" language="en_US">
2897
<synopsis>
2898
Stop recording a call through MixMonitor, and free the recording's file handle.
2899
</synopsis>
2900
<syntax />
2901
<description>
2902
<para>Stops the audio recording that was started with a call to <literal>MixMonitor()</literal>
2903
on the current channel.</para>
2904
</description>
2905
<see-also>
2906
<ref type="application">MixMonitor</ref>
2907
</see-also>
2908
</application>
2909
2910
<application name="Morsecode" language="en_US">
2911
<synopsis>
2912
Plays morse code.
2913
</synopsis>
2914
<syntax>
2915
<parameter name="string" required="true">
2916
<para>String to playback as morse code to channel</para>
2917
</parameter>
2918
</syntax>
2919
<description>
2920
<para>Plays the Morse code equivalent of the passed string.</para>
2921
2922
<para>This application uses the following variables:</para>
2923
<variablelist>
2924
<variable name="MORSEDITLEN">
2925
<para>Use this value in (ms) for length of dit</para>
2926
</variable>
2927
<variable name="MORSETONE">
2928
<para>The pitch of the tone in (Hz), default is 800</para>
2929
</variable>
2930
</variablelist>
2931
</description>
2932
<see-also>
2933
<ref type="application">SayAlpha</ref>
2934
<ref type="application">SayPhonetic</ref>
2935
</see-also>
2936
</application>
2937
<application name="MP3Player" language="en_US">
2938
<synopsis>
2939
Play an MP3 file or stream.
2940
</synopsis>
2941
<syntax>
2942
<parameter name="Location" required="true">
2943
<para>Location of the file to be played.
2944
(argument passed to mpg123)</para>
2945
</parameter>
2946
</syntax>
2947
<description>
2948
<para>Executes mpg123 to play the given location, which typically would be a filename or a URL.
2949
User can exit by pressing any key on the dialpad, or by hanging up.</para>
2950
</description>
2951
</application>
2952
2953
<application name="NBScat" language="en_US">
2954
<synopsis>
2955
Play an NBS local stream.
2956
</synopsis>
2957
<syntax />
2958
<description>
2959
<para>Executes nbscat to listen to the local NBS stream.
2960
User can exit by pressing any key.</para>
2961
</description>
2962
</application>
2963
<application name="Originate" language="en_US">
2964
<synopsis>
2965
Originate a call.
2966
</synopsis>
2967
<syntax>
2968
<parameter name="tech_data" required="true">
2969
<para>Channel technology and data for creating the outbound channel.
2970
For example, SIP/1234.</para>
2971
</parameter>
2972
<parameter name="type" required="true">
2973
<para>This should be <literal>app</literal> or <literal>exten</literal>, depending on whether the outbound channel should be connected to an application or extension.</para>
2974
</parameter>
2975
<parameter name="arg1" required="true">
2976
<para>If the type is <literal>app</literal>, then this is the application name. If the type is <literal>exten</literal>, then this is the context that the channel will be sent to.</para>
2977
</parameter>
2978
<parameter name="arg2" required="false">
2979
<para>If the type is <literal>app</literal>, then this is the data passed as arguments to the application. If the type is <literal>exten</literal>, then this is the extension that the channel will be sent to.</para>
2980
</parameter>
2981
<parameter name="arg3" required="false">
2982
<para>If the type is <literal>exten</literal>, then this is the priority that the channel is sent to. If the type is <literal>app</literal>, then this parameter is ignored.</para>
2983
</parameter>
2984
</syntax>
2985
<description>
2986
<para>This application originates an outbound call and connects it to a specified extension or application. This application will block until the outgoing call fails or gets answered. At that point, this application will exit with the status variable set and dialplan processing will continue.</para>
2987
2988
<para>This application sets the following channel variable before exiting:</para>
2989
<variablelist>
2990
<variable name="ORIGINATE_STATUS">
2991
<para>This indicates the result of the call origination.</para>
2992
<value name="FAILED"/>
2993
<value name="SUCCESS"/>
2994
<value name="BUSY"/>
2995
<value name="CONGESTION"/>
2996
<value name="HANGUP"/>
2997
<value name="RINGING"/>
2998
<value name="UNKNOWN">
2999
In practice, you should never see this value. Please report it to the issue tracker if you ever see it.
3000
</value>
3001
</variable>
3002
</variablelist>
3003
</description>
3004
</application>
3005
<application name="Page" language="en_US">
3006
<synopsis>
3007
Page series of phones
3008
</synopsis>
3009
<syntax>
3010
<parameter name="Technology/Resource" required="true" argsep="&">
3011
<argument name="Technology/Resource" required="true">
3012
<para>Specification of the device(s) to dial. These must be in the format of
3013
<literal>Technology/Resource</literal>, where <replaceable>Technology</replaceable>
3014
represents a particular channel driver, and <replaceable>Resource</replaceable> represents a resource
3015
available to that particular channel driver.</para>
3016
</argument>
3017
<argument name="Technology2/Resource2" multiple="true">
3018
<para>Optional extra devices to dial inparallel</para>
3019
<para>If you need more then one enter them as Technology2/Resource2&
3020
Technology3/Resourse3&.....</para>
3021
</argument>
3022
</parameter>
3023
<parameter name="options">
3024
<optionlist>
3025
<option name="d">
3026
<para>Full duplex audio</para>
3027
</option>
3028
<option name="i">
3029
<para>Ignore attempts to forward the call</para>
3030
</option>
3031
<option name="q">
3032
<para>Quiet, do not play beep to caller</para>
3033
</option>
3034
<option name="r">
3035
<para>Record the page into a file (meetme option <literal>r</literal>)</para>
3036
</option>
3037
<option name="s">
3038
<para>Only dial a channel if its device state says that it is <literal>NOT_INUSE</literal></para>
3039
</option>
3040
</optionlist>
3041
</parameter>
3042
<parameter name="timeout">
3043
<para>Specify the length of time that the system will attempt to connect a call.
3044
After this duration, any intercom calls that have not been answered will be hung up by the
3045
system.</para>
3046
</parameter>
3047
</syntax>
3048
<description>
3049
<para>Places outbound calls to the given <replaceable>technology</replaceable>/<replaceable>resource</replaceable>
3050
and dumps them into a conference bridge as muted participants. The original
3051
caller is dumped into the conference as a speaker and the room is
3052
destroyed when the original callers leaves.</para>
3053
</description>
3054
<see-also>
3055
<ref type="application">MeetMe</ref>
3056
</see-also>
3057
</application>
3058
<application name="ParkAndAnnounce" language="en_US">
3059
<synopsis>
3060
Park and Announce.
3061
</synopsis>
3062
<syntax>
3063
<parameter name="announce_template" required="true" argsep=":">
3064
<argument name="announce" required="true">
3065
<para>Colon-separated list of files to announce. The word
3066
<literal>PARKED</literal> will be replaced by a say_digits of the extension in which
3067
the call is parked.</para>
3068
</argument>
3069
<argument name="announce1" multiple="true" />
3070
</parameter>
3071
<parameter name="timeout" required="true">
3072
<para>Time in seconds before the call returns into the return
3073
context.</para>
3074
</parameter>
3075
<parameter name="dial" required="true">
3076
<para>The app_dial style resource to call to make the
3077
announcement. Console/dsp calls the console.</para>
3078
</parameter>
3079
<parameter name="return_context">
3080
<para>The goto-style label to jump the call back into after
3081
timeout. Default <literal>priority+1</literal>.</para>
3082
</parameter>
3083
</syntax>
3084
<description>
3085
<para>Park a call into the parkinglot and announce the call to another channel.</para>
3086
<para>The variable <variable>PARKEDAT</variable> will contain the parking extension
3087
into which the call was placed. Use with the Local channel to allow the dialplan to make
3088
use of this information.</para>
3089
</description>
3090
<see-also>
3091
<ref type="application">Park</ref>
3092
<ref type="application">ParkedCall</ref>
3093
</see-also>
3094
</application>
3095
<application name="Playback" language="en_US">
3096
<synopsis>
3097
Play a file.
3098
</synopsis>
3099
<syntax>
3100
<parameter name="filenames" required="true" argsep="&">
3101
<argument name="filename" required="true" />
3102
<argument name="filename2" multiple="true" />
3103
</parameter>
3104
<parameter name="options">
3105
<para>Comma separated list of options</para>
3106
<optionlist>
3107
<option name="skip">
3108
<para>Do not play if not answered</para>
3109
</option>
3110
<option name="noanswer">
3111
<para>Playback without answering, otherwise the channel will
3112
be answered before the sound is played.</para>
3113
<note><para>Not all channel types support playing messages while still on hook.</para></note>
3114
</option>
3115
</optionlist>
3116
</parameter>
3117
</syntax>
3118
<description>
3119
<para>Plays back given filenames (do not put extension of wav/alaw etc).
3120
The playback command answer the channel if no options are specified.
3121
If the file is non-existant it will fail</para>
3122
<para>This application sets the following channel variable upon completion:</para>
3123
<variablelist>
3124
<variable name="PLAYBACKSTATUS">
3125
<para>The status of the playback attempt as a text string.</para>
3126
<value name="SUCCESS"/>
3127
<value name="FAILED"/>
3128
</variable>
3129
</variablelist>
3130
<para>See Also: Background (application) -- for playing sound files that are interruptible</para>
3131
<para>WaitExten (application) -- wait for digits from caller, optionally play music on hold</para>
3132
</description>
3133
</application>
3134
<application name="PlayTones" language="en_US">
3135
<synopsis>
3136
Play a tone list.
3137
</synopsis>
3138
<syntax>
3139
<parameter name="arg" required="true">
3140
<para>Arg is either the tone name defined in the <filename>indications.conf</filename>
3141
configuration file, or a directly specified list of frequencies and durations.</para>
3142
</parameter>
3143
</syntax>
3144
<description>
3145
<para>Plays a tone list. Execution will continue with the next step in the dialplan
3146
immediately while the tones continue to play.</para>
3147
<para>See the sample <filename>indications.conf</filename> for a description of the
3148
specification of a tonelist.</para>
3149
</description>
3150
<see-also>
3151
<ref type="application">StopPlayTones</ref>
3152
</see-also>
3153
</application>
3154
<application name="StopPlayTones" language="en_US">
3155
<synopsis>
3156
Stop playing a tone list.
3157
</synopsis>
3158
<syntax />
3159
<description>
3160
<para>Stop playing a tone list, initiated by PlayTones().</para>
3161
</description>
3162
<see-also>
3163
<ref type="application">PlayTones</ref>
3164
</see-also>
3165
</application>
3166
<application name="PrivacyManager" language="en_US">
3167
<synopsis>
3168
Require phone number to be entered, if no CallerID sent
3169
</synopsis>
3170
<syntax>
3171
<parameter name="maxretries">
3172
<para>Total tries caller is allowed to input a callerid. Defaults to <literal>3</literal>.</para>
3173
</parameter>
3174
<parameter name="minlength">
3175
<para>Minimum allowable digits in the input callerid number. Defaults to <literal>10</literal>.</para>
3176
</parameter>
3177
<parameter name="context">
3178
<para>Context to check the given callerid against patterns.</para>
3179
</parameter>
3180
</syntax>
3181
<description>
3182
<para>If no Caller*ID is sent, PrivacyManager answers the channel and asks
3183
the caller to enter their phone number. The caller is given
3184
<replaceable>maxretries</replaceable> attempts to do so. The application does
3185
<emphasis>nothing</emphasis> if Caller*ID was received on the channel.</para>
3186
<para>The application sets the following channel variable upon completion:</para>
3187
<variablelist>
3188
<variable name="PRIVACYMGRSTATUS">
3189
<para>The status of the privacy manager's attempt to collect a phone number from the user.</para>
3190
<value name="SUCCESS"/>
3191
<value name="FAILED"/>
3192
</variable>
3193
</variablelist>
3194
</description>
3195
<see-also>
3196
<ref type="application">Zapateller</ref>
3197
</see-also>
3198
</application>
3199
<application name="Queue" language="en_US">
3200
<synopsis>
3201
Queue a call for a call queue.
3202
</synopsis>
3203
<syntax>
3204
<parameter name="queuename" required="true" />
3205
<parameter name="options">
3206
<optionlist>
3207
<option name="C">
3208
<para>Mark all calls as "answered elsewhere" when cancelled.</para>
3209
</option>
3210
<option name="c">
3211
<para>Continue in the dialplan if the callee hangs up.</para>
3212
</option>
3213
<option name="d">
3214
<para>data-quality (modem) call (minimum delay).</para>
3215
</option>
3216
<option name="h">
3217
<para>Allow <emphasis>callee</emphasis> to hang up by pressing <literal>*</literal>.</para>
3218
</option>
3219
<option name="H">
3220
<para>Allow <emphasis>caller</emphasis> to hang up by pressing <literal>*</literal>.</para>
3221
</option>
3222
<option name="n">
3223
<para>No retries on the timeout; will exit this application and
3224
go to the next step.</para>
3225
</option>
3226
<option name="i">
3227
<para>Ignore call forward requests from queue members and do nothing
3228
when they are requested.</para>
3229
</option>
3230
<option name="r">
3231
<para>Ring instead of playing MOH. Periodic Announcements are still made, if applicable.</para>
3232
</option>
3233
<option name="t">
3234
<para>Allow the <emphasis>called</emphasis> user to transfer the calling user.</para>
3235
</option>
3236
<option name="T">
3237
<para>Allow the <emphasis>calling</emphasis> user to transfer the call.</para>
3238
</option>
3239
<option name="w">
3240
<para>Allow the <emphasis>called</emphasis> user to write the conversation to
3241
disk via Monitor.</para>
3242
</option>
3243
<option name="W">
3244
<para>Allow the <emphasis>calling</emphasis> user to write the conversation to
3245
disk via Monitor.</para>
3246
</option>
3247
<option name="k">
3248
<para>Allow the <emphasis>called</emphasis> party to enable parking of the call by sending
3249
the DTMF sequence defined for call parking in <filename>features.conf</filename>.</para>
3250
</option>
3251
<option name="K">
3252
<para>Allow the <emphasis>calling</emphasis> party to enable parking of the call by sending
3253
the DTMF sequence defined for call parking in <filename>features.conf</filename>.</para>
3254
</option>
3255
<option name="x">
3256
<para>Allow the <emphasis>called</emphasis> user to write the conversation
3257
to disk via MixMonitor.</para>
3258
</option>
3259
<option name="X">
3260
<para>Allow the <emphasis>calling</emphasis> user to write the conversation to
3261
disk via MixMonitor.</para>
3262
</option>
3263
</optionlist>
3264
</parameter>
3265
<parameter name="URL">
3266
<para><replaceable>URL</replaceable> will be sent to the called party if the channel supports it.</para>
3267
</parameter>
3268
<parameter name="announceoverride" />
3269
<parameter name="timeout">
3270
<para>Will cause the queue to fail out after a specified number of
3271
seconds, checked between each <filename>queues.conf</filename> <replaceable>timeout</replaceable> and
3272
<replaceable>retry</replaceable> cycle.</para>
3273
</parameter>
3274
<parameter name="AGI">
3275
<para>Will setup an AGI script to be executed on the calling party's channel once they are
3276
connected to a queue member.</para>
3277
</parameter>
3278
<parameter name="macro">
3279
<para>Will run a macro on the calling party's channel once they are connected to a queue member.</para>
3280
</parameter>
3281
<parameter name="gosub">
3282
<para>Will run a gosub on the calling party's channel once they are connected to a queue member.</para>
3283
</parameter>
3284
<parameter name="rule">
3285
<para>Will cause the queue's defaultrule to be overridden by the rule specified.</para>
3286
</parameter>
3287
</syntax>
3288
<description>
3289
<para>In addition to transferring the call, a call may be parked and then picked
3290
up by another user.</para>
3291
<para>This application will return to the dialplan if the queue does not exist, or
3292
any of the join options cause the caller to not enter the queue.</para>
3293
<para>This application sets the following channel variable upon completion:</para>
3294
<variablelist>
3295
<variable name="QUEUESTATUS">
3296
<para>The status of the call as a text string.</para>
3297
<value name="TIMEOUT" />
3298
<value name="FULL" />
3299
<value name="JOINEMPTY" />
3300
<value name="LEAVEEMPTY" />
3301
<value name="JOINUNAVAIL" />
3302
<value name="LEAVEUNAVAIL" />
3303
<value name="CONTINUE" />
3304
</variable>
3305
</variablelist>
3306
</description>
3307
<see-also>
3308
<ref type="application">AddQueueMember</ref>
3309
<ref type="application">RemoveQueueMember</ref>
3310
<ref type="application">PauseQueueMember</ref>
3311
<ref type="application">UnpauseQueueMember</ref>
3312
<ref type="application">AgentLogin</ref>
3313
<ref type="function">QUEUE_MEMBER_COUNT</ref>
3314
<ref type="function">QUEUE_MEMBER_LIST</ref>
3315
<ref type="function">QUEUE_WAITING_COUNT</ref>
3316
</see-also>
3317
</application>
3318
<application name="AddQueueMember" language="en_US">
3319
<synopsis>
3320
Dynamically adds queue members.
3321
</synopsis>
3322
<syntax>
3323
<parameter name="queuename" required="true" />
3324
<parameter name="interface" />
3325
<parameter name="penalty" />
3326
<parameter name="options" />
3327
<parameter name="membername" />
3328
<parameter name="stateinterface" />
3329
</syntax>
3330
<description>
3331
<para>Dynamically adds interface to an existing queue. If the interface is
3332
already in the queue it will return an error.</para>
3333
<para>This application sets the following channel variable upon completion:</para>
3334
<variablelist>
3335
<variable name="AQMSTATUS">
3336
<para>The status of the attempt to add a queue member as a text string.</para>
3337
<value name="ADDED" />
3338
<value name="MEMBERALREADY" />
3339
<value name="NOSUCHQUEUE" />
3340
</variable>
3341
</variablelist>
3342
</description>
3343
<see-also>
3344
<ref type="application">RemoveQueueMember</ref>
3345
<ref type="application">PauseQueueMember</ref>
3346
<ref type="application">UnpauseQueueMember</ref>
3347
<ref type="application">AgentLogin</ref>
3348
</see-also>
3349
</application>
3350
<application name="RemoveQueueMember" language="en_US">
3351
<synopsis>
3352
Dynamically removes queue members.
3353
</synopsis>
3354
<syntax>
3355
<parameter name="queuename" required="true" />
3356
<parameter name="interface" />
3357
<parameter name="options" />
3358
</syntax>
3359
<description>
3360
<para>If the interface is <emphasis>NOT</emphasis> in the queue it will return an error.</para>
3361
<para>This application sets the following channel variable upon completion:</para>
3362
<variablelist>
3363
<variable name="RQMSTATUS">
3364
<value name="REMOVED" />
3365
<value name="NOTINQUEUE" />
3366
<value name="NOSUCHQUEUE" />
3367
</variable>
3368
</variablelist>
3369
<para>Example: RemoveQueueMember(techsupport,SIP/3000)</para>
3370
</description>
3371
<see-also>
3372
<ref type="application">Queue</ref>
3373
<ref type="application">AddQueueMember</ref>
3374
<ref type="application">PauseQueueMember</ref>
3375
<ref type="application">UnpauseQueueMember</ref>
3376
</see-also>
3377
</application>
3378
<application name="PauseQueueMember" language="en_US">
3379
<synopsis>
3380
Pauses a queue member.
3381
</synopsis>
3382
<syntax>
3383
<parameter name="queuename" />
3384
<parameter name="interface" required="true" />
3385
<parameter name="options" />
3386
<parameter name="reason">
3387
<para>Is used to add extra information to the appropriate queue_log entries and manager events.</para>
3388
</parameter>
3389
</syntax>
3390
<description>
3391
<para>Pauses (blocks calls for) a queue member. The given interface will be paused in the given queue.
3392
This prevents any calls from being sent from the queue to the interface until it is
3393
unpaused with UnpauseQueueMember or the manager interface. If no queuename is given,
3394
the interface is paused in every queue it is a member of. The application will fail if the
3395
interface is not found.</para>
3396
<para>This application sets the following channel variable upon completion:</para>
3397
<variablelist>
3398
<variable name="PQMSTATUS">
3399
<para>The status of the attempt to pause a queue member as a text string.</para>
3400
<value name="PAUSED" />
3401
<value name="NOTFOUND" />
3402
</variable>
3403
</variablelist>
3404
<para>Example: PauseQueueMember(,SIP/3000)</para>
3405
</description>
3406
<see-also>
3407
<ref type="application">UnpauseQueueMember</ref>
3408
</see-also>
3409
</application>
3410
<application name="UnpauseQueueMember" language="en_US">
3411
<synopsis>
3412
Unpauses a queue member.
3413
</synopsis>
3414
<syntax>
3415
<parameter name="queuename" />
3416
<parameter name="interface" required="true" />
3417
<parameter name="options" />
3418
<parameter name="reason">
3419
<para>Is used to add extra information to the appropriate queue_log entries and manager events.</para>
3420
</parameter>
3421
</syntax>
3422
<description>
3423
<para>Unpauses (resumes calls to) a queue member. This is the counterpart to <literal>PauseQueueMember()</literal>
3424
and operates exactly the same way, except it unpauses instead of pausing the given interface.</para>
3425
<para>This application sets the following channel variable upon completion:</para>
3426
<variablelist>
3427
<variable name="UPQMSTATUS">
3428
<para>The status of the attempt to unpause a queue member as a text string.</para>
3429
<value name="UNPAUSED" />
3430
<value name="NOTFOUND" />
3431
</variable>
3432
</variablelist>
3433
<para>Example: UnpauseQueueMember(,SIP/3000)</para>
3434
</description>
3435
<see-also>
3436
<ref type="application">PauseQueueMember</ref>
3437
</see-also>
3438
</application>
3439
<application name="QueueLog" language="en_US">
3440
<synopsis>
3441
Writes to the queue_log file.
3442
</synopsis>
3443
<syntax>
3444
<parameter name="queuename" required="true" />
3445
<parameter name="uniqueid" required="true" />
3446
<parameter name="agent" required="true" />
3447
<parameter name="event" required="true" />
3448
<parameter name="additionalinfo" />
3449
</syntax>
3450
<description>
3451
<para>Allows you to write your own events into the queue log.</para>
3452
<para>Example: QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)</para>
3453
</description>
3454
<see-also>
3455
<ref type="application">Queue</ref>
3456
</see-also>
3457
</application>
3458
<function name="QUEUE_VARIABLES" language="en_US">
3459
<synopsis>
3460
Return Queue information in variables.
3461
</synopsis>
3462
<syntax>
3463
<parameter name="queuename" required="true">
3464
<enumlist>
3465
<enum name="QUEUEMAX">
3466
<para>Maxmimum number of calls allowed.</para>
3467
</enum>
3468
<enum name="QUEUESTRATEGY">
3469
<para>The strategy of the queue.</para>
3470
</enum>
3471
<enum name="QUEUECALLS">
3472
<para>Number of calls currently in the queue.</para>
3473
</enum>
3474
<enum name="QUEUEHOLDTIME">
3475
<para>Current average hold time.</para>
3476
</enum>
3477
<enum name="QUEUECOMPLETED">
3478
<para>Number of completed calls for the queue.</para>
3479
</enum>
3480
<enum name="QUEUEABANDONED">
3481
<para>Number of abandoned calls.</para>
3482
</enum>
3483
<enum name="QUEUESRVLEVEL">
3484
<para>Queue service level.</para>
3485
</enum>
3486
<enum name="QUEUESRVLEVELPERF">
3487
<para>Current service level performance.</para>
3488
</enum>
3489
</enumlist>
3490
</parameter>
3491
</syntax>
3492
<description>
3493
<para>Makes the following queue variables available.</para>
3494
<para>Returns <literal>0</literal> if queue is found and setqueuevar is defined, <literal>-1</literal> otherwise.</para>
3495
</description>
3496
</function>
3497
<function name="QUEUE_MEMBER" language="en_US">
3498
<synopsis>
3499
Count number of members answering a queue.
3500
</synopsis>
3501
<syntax>
3502
<parameter name="queuename" required="true" />
3503
<parameter name="option" required="true">
3504
<enumlist>
3505
<enum name="logged">
3506
<para>Returns the number of logged-in members for the specified queue.</para>
3507
</enum>
3508
<enum name="free">
3509
<para>Returns the number of logged-in members for the specified queue available to take a call.</para>
3510
</enum>
3511
<enum name="count">
3512
<para>Returns the total number of members for the specified queue.</para>
3513
</enum>
3514
</enumlist>
3515
</parameter>
3516
</syntax>
3517
<description>
3518
<para>Returns the number of members currently associated with the specified <replaceable>queuename</replaceable>.</para>
3519
</description>
3520
</function>
3521
<function name="QUEUE_MEMBER_COUNT" language="en_US">
3522
<synopsis>
3523
Count number of members answering a queue.
3524
</synopsis>
3525
<syntax>
3526
<parameter name="queuename" required="true" />
3527
</syntax>
3528
<description>
3529
<para>Returns the number of members currently associated with the specified <replaceable>queuename</replaceable>.</para>
3530
<warning><para>This function has been deprecated in favor of the <literal>QUEUE_MEMBER()</literal> function</para></warning>
3531
</description>
3532
<see-also>
3533
<ref type="function">QUEUE_MEMBER_LIST</ref>
3534
</see-also>
3535
</function>
3536
<function name="QUEUE_WAITING_COUNT" language="en_US">
3537
<synopsis>
3538
Count number of calls currently waiting in a queue.
3539
</synopsis>
3540
<syntax>
3541
<parameter name="queuename" />
3542
</syntax>
3543
<description>
3544
<para>Returns the number of callers currently waiting in the specified <replaceable>queuename</replaceable>.</para>
3545
</description>
3546
</function>
3547
<function name="QUEUE_MEMBER_LIST" language="en_US">
3548
<synopsis>
3549
Returns a list of interfaces on a queue.
3550
</synopsis>
3551
<syntax>
3552
<parameter name="queuename" required="true" />
3553
</syntax>
3554
<description>
3555
<para>Returns a comma-separated list of members associated with the specified <replaceable>queuename</replaceable>.</para>
3556
</description>
3557
<see-also>
3558
<ref type="function">QUEUE_MEMBER_COUNT</ref>
3559
</see-also>
3560
</function>
3561
<function name="QUEUE_MEMBER_PENALTY" language="en_US">
3562
<synopsis>
3563
Gets or sets queue members penalty.
3564
</synopsis>
3565
<syntax>
3566
<parameter name="queuename" required="true" />
3567
<parameter name="interface" required="true" />
3568
</syntax>
3569
<description>
3570
<para>Gets or sets queue members penalty.</para>
3571
</description>
3572
</function>
3573
3574
<application name="Read" language="en_US">
3575
<synopsis>
3576
Read a variable.
3577
</synopsis>
3578
<syntax>
3579
<parameter name="variable" required="true">
3580
<para>The input digits will be stored in the given <replaceable>variable</replaceable>
3581
name.</para>
3582
</parameter>
3583
<parameter name="filenames" argsep="&">
3584
<argument name="filename" required="true">
3585
<para>file(s) to play before reading digits or tone with option i</para>
3586
</argument>
3587
<argument name="filename2" multiple="true" />
3588
</parameter>
3589
<parameter name="maxdigits">
3590
<para>Maximum acceptable number of digits. Stops reading after
3591
<replaceable>maxdigits</replaceable> have been entered (without
3592
requiring the user to press the <literal>#</literal> key).</para>
3593
<para>Defaults to <literal>0</literal> - no limit - wait for the
3594
user press the <literal>#</literal> key. Any value below
3595
<literal>0</literal> means the same. Max accepted value is
3596
<literal>255</literal>.</para>
3597
</parameter>
3598
<parameter name="options">
3599
<optionlist>
3600
<option name="s">
3601
<para>to return immediately if the line is not up.</para>
3602
</option>
3603
<option name="i">
3604
<para>to play filename as an indication tone from your
3605
<filename>indications.conf</filename>.</para>
3606
</option>
3607
<option name="n">
3608
<para>to read digits even if the line is not up.</para>
3609
</option>
3610
</optionlist>
3611
</parameter>
3612
<parameter name="attempts">
3613
<para>If greater than <literal>1</literal>, that many
3614
<replaceable>attempts</replaceable> will be made in the
3615
event no data is entered.</para>
3616
</parameter>
3617
<parameter name="timeout">
3618
<para>The number of seconds to wait for a digit response. If greater
3619
than <literal>0</literal>, that value will override the default timeout.
3620
Can be floating point.</para>
3621
</parameter>
3622
</syntax>
3623
<description>
3624
<para>Reads a #-terminated string of digits a certain number of times from the
3625
user in to the given <replaceable>variable</replaceable>.</para>
3626
<para>This application sets the following channel variable upon completion:</para>
3627
<variablelist>
3628
<variable name="READSTATUS">
3629
<para>This is the status of the read operation.</para>
3630
<value name="OK" />
3631
<value name="ERROR" />
3632
<value name="HANGUP" />
3633
<value name="INTERRUPTED" />
3634
<value name="SKIPPED" />
3635
<value name="TIMEOUT" />
3636
</variable>
3637
</variablelist>
3638
</description>
3639
<see-also>
3640
<ref type="application">SendDTMF</ref>
3641
</see-also>
3642
</application>
3643
<application name="ReadExten" language="en_US">
3644
<synopsis>
3645
Read an extension into a variable.
3646
</synopsis>
3647
<syntax>
3648
<parameter name="variable" required="true" />
3649
<parameter name="filename">
3650
<para>File to play before reading digits or tone with option <literal>i</literal></para>
3651
</parameter>
3652
<parameter name="context">
3653
<para>Context in which to match extensions.</para>
3654
</parameter>
3655
<parameter name="option">
3656
<optionlist>
3657
<option name="s">
3658
<para>Return immediately if the channel is not answered.</para>
3659
</option>
3660
<option name="i">
3661
<para>Play <replaceable>filename</replaceable> as an indication tone from your
3662
<filename>indications.conf</filename></para>
3663
</option>
3664
<option name="n">
3665
<para>Read digits even if the channel is not answered.</para>
3666
</option>
3667
</optionlist>
3668
</parameter>
3669
<parameter name="timeout">
3670
<para>An integer number of seconds to wait for a digit response. If
3671
greater than <literal>0</literal>, that value will override the default timeout.</para>
3672
</parameter>
3673
</syntax>
3674
<description>
3675
<para>Reads a <literal>#</literal> terminated string of digits from the user into the given variable.</para>
3676
<para>Will set READEXTENSTATUS on exit with one of the following statuses:</para>
3677
<variablelist>
3678
<variable name="READEXTENSTATUS">
3679
<value name="OK">
3680
A valid extension exists in ${variable}.
3681
</value>
3682
<value name="TIMEOUT">
3683
No extension was entered in the specified time. Also sets ${variable} to "t".
3684
</value>
3685
<value name="INVALID">
3686
An invalid extension, ${INVALID_EXTEN}, was entered. Also sets ${variable} to "i".
3687
</value>
3688
<value name="SKIP">
3689
Line was not up and the option 's' was specified.
3690
</value>
3691
<value name="ERROR">
3692
Invalid arguments were passed.
3693
</value>
3694
</variable>
3695
</variablelist>
3696
</description>
3697
</application>
3698
<function name="VALID_EXTEN" language="en_US">
3699
<synopsis>
3700
Determine whether an extension exists or not.
3701
</synopsis>
3702
<syntax>
3703
<parameter name="context">
3704
<para>Defaults to the current context</para>
3705
</parameter>
3706
<parameter name="extension" required="true" />
3707
<parameter name="priority">
3708
<para>Priority defaults to <literal>1</literal>.</para>
3709
</parameter>
3710
</syntax>
3711
<description>
3712
<para>Returns a true value if the indicated <replaceable>context</replaceable>,
3713
<replaceable>extension</replaceable>, and <replaceable>priority</replaceable> exist.</para>
3714
</description>
3715
</function>
3716
<application name="ReadFile" language="en_US">
3717
<synopsis>
3718
Read the contents of a text file into a channel variable.
3719
</synopsis>
3720
<syntax argsep="=">
3721
<parameter name="varname" required="true">
3722
<para>Result stored here.</para>
3723
</parameter>
3724
<parameter name="fileparams" required="true">
3725
<argument name="file" required="true">
3726
<para>The name of the file to read.</para>
3727
</argument>
3728
<argument name="length" required="false">
3729
<para>Maximum number of characters to capture.</para>
3730
<para>If not specified defaults to max.</para>
3731
</argument>
3732
</parameter>
3733
</syntax>
3734
<description>
3735
<para>Read the contents of a text file into channel variable <replaceable>varname</replaceable></para>
3736
<warning><para>ReadFile has been deprecated in favor of Set(varname=${FILE(file,0,length)})</para></warning>
3737
</description>
3738
<see-also>
3739
<ref type="application">System</ref>
3740
<ref type="application">Read</ref>
3741
</see-also>
3742
</application>
3743
<application name="Record" language="en_US">
3744
<synopsis>
3745
Record to a file.
3746
</synopsis>
3747
<syntax>
3748
<parameter name="filename" required="true" argsep=".">
3749
<argument name="filename" required="true" />
3750
<argument name="format" required="true">
3751
<para>Is the format of the file type to be recorded (wav, gsm, etc).</para>
3752
</argument>
3753
</parameter>
3754
<parameter name="silence">
3755
<para>Is the number of seconds of silence to allow before returning.</para>
3756
</parameter>
3757
<parameter name="maxduration">
3758
<para>Is the maximum recording duration in seconds. If missing
3759
or 0 there is no maximum.</para>
3760
</parameter>
3761
<parameter name="options">
3762
<optionlist>
3763
<option name="a">
3764
<para>Append to existing recording rather than replacing.</para>
3765
</option>
3766
<option name="n">
3767
<para>Do not answer, but record anyway if line not yet answered.</para>
3768
</option>
3769
<option name="q">
3770
<para>quiet (do not play a beep tone).</para>
3771
</option>
3772
<option name="s">
3773
<para>skip recording if the line is not yet answered.</para>
3774
</option>
3775
<option name="t">
3776
<para>use alternate '*' terminator key (DTMF) instead of default '#'</para>
3777
</option>
3778
<option name="x">
3779
<para>Ignore all terminator keys (DTMF) and keep recording until hangup.</para>
3780
</option>
3781
<option name="k">
3782
<para>Keep recording if channel hangs up.</para>
3783
</option>
3784
</optionlist>
3785
</parameter>
3786
</syntax>
3787
<description>
3788
<para>If filename contains <literal>%d</literal>, these characters will be replaced with a number
3789
incremented by one each time the file is recorded.
3790
Use <astcli>core show file formats</astcli> to see the available formats on your system
3791
User can press <literal>#</literal> to terminate the recording and continue to the next priority.
3792
If the user hangs up during a recording, all data will be lost and the application will terminate.</para>
3793
<variablelist>
3794
<variable name="RECORDED_FILE">
3795
<para>Will be set to the final filename of the recording.</para>
3796
</variable>
3797
<variable name="RECORD_STATUS">
3798
<para>This is the final status of the command</para>
3799
<value name="DTMF">A terminating DTMF was received ('#' or '*', depending upon option 't')</value>
3800
<value name="SILENCE">The maximum silence occurred in the recording.</value>
3801
<value name="SKIP">The line was not yet answered and the 's' option was specified.</value>
3802
<value name="TIMEOUT">The maximum length was reached.</value>
3803
<value name="HANGUP">The channel was hung up.</value>
3804
<value name="ERROR">An unrecoverable error occurred, which resulted in a WARNING to the logs.</value>
3805
</variable>
3806
</variablelist>
3807
</description>
3808
</application>
3809
3810
<application name="SayUnixTime" language="en_US">
3811
<synopsis>
3812
Says a specified time in a custom format.
3813
</synopsis>
3814
<syntax>
3815
<parameter name="unixtime">
3816
<para>time, in seconds since Jan 1, 1970. May be negative. Defaults to now.</para>
3817
</parameter>
3818
<parameter name="timezone">
3819
<para>timezone, see <directory>/usr/share/zoneinfo</directory> for a list. Defaults to machine default.</para>
3820
</parameter>
3821
<parameter name="format">
3822
<para>a format the time is to be said in. See <filename>voicemail.conf</filename>.
3823
Defaults to <literal>ABdY "digits/at" IMp</literal></para>
3824
</parameter>
3825
</syntax>
3826
<description>
3827
<para>Uses some of the sound files stored in <directory>/var/lib/asterisk/sounds</directory> to construct a phrase
3828
saying the specified date and/or time in the specified format. </para>
3829
</description>
3830
<see-also>
3831
<ref type="function">STRFTIME</ref>
3832
<ref type="function">STRPTIME</ref>
3833
<ref type="function">IFTIME</ref>
3834
</see-also>
3835
</application>
3836
<application name="DateTime" language="en_US">
3837
<synopsis>
3838
Says a specified time in a custom format.
3839
</synopsis>
3840
<syntax>
3841
<parameter name="unixtime">
3842
<para>time, in seconds since Jan 1, 1970. May be negative. Defaults to now.</para>
3843
</parameter>
3844
<parameter name="timezone">
3845
<para>timezone, see <filename>/usr/share/zoneinfo</filename> for a list. Defaults to machine default.</para>
3846
</parameter>
3847
<parameter name="format">
3848
<para>a format the time is to be said in. See <filename>voicemail.conf</filename>.
3849
Defaults to <literal>ABdY "digits/at" IMp</literal></para>
3850
</parameter>
3851
</syntax>
3852
<description>
3853
<para>Say the date and time in a specified format.</para>
3854
</description>
3855
</application>
3856
3857
<application name="SendDTMF" language="en_US">
3858
<synopsis>
3859
Sends arbitrary DTMF digits
3860
</synopsis>
3861
<syntax>
3862
<parameter name="digits" required="true">
3863
<para>List of digits 0-9,*#,abcd</para>
3864
</parameter>
3865
<parameter name="timeout_ms" required="false">
3866
<para>Amount of time to wait in ms between tones. (defaults to .25s)</para>
3867
</parameter>
3868
<parameter name="duration_ms" required="false">
3869
<para>Duration of each digit</para>
3870
</parameter>
3871
</syntax>
3872
<description>
3873
<para>DTMF digits sent to a channel with half second pause</para>
3874
<para>It will pass all digits or terminate if it encounters an error.</para>
3875
</description>
3876
<see-also>
3877
<ref type="application">Read</ref>
3878
</see-also>
3879
</application>
3880
<application name="SendText" language="en_US">
3881
<synopsis>
3882
Send a Text Message.
3883
</synopsis>
3884
<syntax>
3885
<parameter name="text" required="true" />
3886
</syntax>
3887
<description>
3888
<para>Sends <replaceable>text</replaceable> to current channel (callee).</para>
3889
<para>Result of transmission will be stored in the <variable>SENDTEXTSTATUS</variable></para>
3890
<variablelist>
3891
<variable name="SENDTEXTSTATUS">
3892
<value name="SUCCESS">
3893
Transmission succeeded.
3894
</value>
3895
<value name="FAILURE">
3896
Transmission failed.
3897
</value>
3898
<value name="UNSUPPORTED">
3899
Text transmission not supported by channel.
3900
</value>
3901
</variable>
3902
</variablelist>
3903
<note><para>At this moment, text is supposed to be 7 bit ASCII in most channels.</para></note>
3904
</description>
3905
<see-also>
3906
<ref type="application">SendImage</ref>
3907
<ref type="application">SendURL</ref>
3908
</see-also>
3909
</application>
3910
<application name="SetCallerPres" language="en_US">
3911
<synopsis>
3912
Set CallerID Presentation.
3913
</synopsis>
3914
<syntax>
3915
<parameter name="presentation" required="true">
3916
<enumlist>
3917
<enum name="allowed_not_screened">
3918
<para>Presentation Allowed, Not Screened.</para>
3919
</enum>
3920
<enum name="allowed_passed_screen">
3921
<para>Presentation Allowed, Passed Screen.</para>
3922
</enum>
3923
<enum name="allowed_failed_screen">
3924
<para>Presentation Allowed, Failed Screen.</para>
3925
</enum>
3926
<enum name="allowed">
3927
<para>Presentation Allowed, Network Number.</para>
3928
</enum>
3929
<enum name="prohib_not_screened">
3930
<para>Presentation Prohibited, Not Screened.</para>
3931
</enum>
3932
<enum name="prohib_passed_screen">
3933
<para>Presentation Prohibited, Passed Screen.</para>
3934
</enum>
3935
<enum name="prohib_failed_screen">
3936
<para>Presentation Prohibited, Failed Screen.</para>
3937
</enum>
3938
<enum name="prohib">
3939
<para>Presentation Prohibited, Network Number.</para>
3940
</enum>
3941
<enum name="unavailable">
3942
<para>Number Unavailable.</para>
3943
</enum>
3944
</enumlist>
3945
</parameter>
3946
</syntax>
3947
<description>
3948
<para>Set Caller*ID presentation on a call.</para>
3949
</description>
3950
</application>
3951
<application name="Skel" language="en_US">
3952
<synopsis>
3953
Simple one line explaination.
3954
</synopsis>
3955
<syntax>
3956
<parameter name="dummy" required="true"/>
3957
<parameter name="options">
3958
<optionlist>
3959
<option name="a">
3960
<para>Option A.</para>
3961
</option>
3962
<option name="b">
3963
<para>Option B.</para>
3964
</option>
3965
<option name="c">
3966
<para>Option C.</para>
3967
</option>
3968
</optionlist>
3969
</parameter>
3970
</syntax>
3971
<description>
3972
<para>This application is a template to build other applications from.
3973
It shows you the basic structure to create your own Asterisk applications.</para>
3974
</description>
3975
</application>
3976
<application name="SMS" language="en_US">
3977
<synopsis>
3978
Communicates with SMS service centres and SMS capable analogue phones.
3979
</synopsis>
3980
<syntax>
3981
<parameter name="name" required="true">
3982
<para>The name of the queue used in <filename>/var/spool/asterisk/sms</filename></para>
3983
</parameter>
3984
<parameter name="options">
3985
<optionlist>
3986
<option name="a">
3987
<para>Answer, i.e. send initial FSK packet.</para>
3988
</option>
3989
<option name="s">
3990
<para>Act as service centre talking to a phone.</para>
3991
</option>
3992
<option name="t">
3993
<para>Use protocol 2 (default used is protocol 1).</para>
3994
</option>
3995
<option name="p">
3996
<para>Set the initial delay to N ms (default is <literal>300</literal>).
3997
addr and body are a deprecated format to send messages out.</para>
3998
</option>
3999
<option name="r">
4000
<para>Set the Status Report Request (SRR) bit.</para>
4001
</option>
4002
<option name="o">
4003
<para>The body should be coded as octets not 7-bit symbols.</para>
4004
</option>
4005
</optionlist>
4006
</parameter>
4007
<parameter name="addr" />
4008
<parameter name="body" />
4009
</syntax>
4010
<description>
4011
<para>SMS handles exchange of SMS data with a call to/from SMS capable phone or SMS PSTN service center.
4012
Can send and/or receive SMS messages. Works to ETSI ES 201 912; compatible with BT SMS PSTN service in
4013
UK and Telecom Italia in Italy.</para>
4014
<para>Typical usage is to use to handle calls from the SMS service centre CLI, or to set up a call using
4015
<literal>outgoing</literal> or manager interface to connect service centre to SMS().</para>
4016
<para>"Messages are processed as per text file message queues. smsq (a separate software) is a command to
4017
generate message queues and send messages.</para>
4018
<note><para>The protocol has tight delay bounds. Please use short frames and disable/keep short the
4019
jitter buffer on the ATA to make sure that respones (ACK etc.) are received in time.</para></note>
4020
</description>
4021
</application>
4022
<application name="SoftHangup" language="en_US">
4023
<synopsis>
4024
Hangs up the requested channel.
4025
</synopsis>
4026
<syntax>
4027
<parameter name="Technology/Resource" required="true" />
4028
<parameter name="options">
4029
<optionlist>
4030
<option name="a">
4031
<para>Hang up all channels on a specified device instead of a single resource</para>
4032
</option>
4033
</optionlist>
4034
</parameter>
4035
</syntax>
4036
<description>
4037
<para>Hangs up the requested channel. If there are no channels to
4038
hangup, the application will report it.</para>
4039
</description>
4040
</application>
4041
4042
<application name="SpeechCreate" language="en_US">
4043
<synopsis>
4044
Create a Speech Structure.
4045
</synopsis>
4046
<syntax>
4047
<parameter name="engine_name" required="true" />
4048
</syntax>
4049
<description>
4050
<para>This application creates information to be used by all the other applications.
4051
It must be called before doing any speech recognition activities such as activating a grammar.
4052
It takes the engine name to use as the argument, if not specified the default engine will be used.</para>
4053
</description>
4054
</application>
4055
<application name="SpeechActivateGrammar" language="en_US">
4056
<synopsis>
4057
Activate a grammar.
4058
</synopsis>
4059
<syntax>
4060
<parameter name="grammar_name" required="true" />
4061
</syntax>
4062
<description>
4063
<para>This activates the specified grammar to be recognized by the engine.
4064
A grammar tells the speech recognition engine what to recognize, and how to portray it back to you
4065
in the dialplan. The grammar name is the only argument to this application.</para>
4066
</description>
4067
</application>
4068
<application name="SpeechStart" language="en_US">
4069
<synopsis>
4070
Start recognizing voice in the audio stream.
4071
</synopsis>
4072
<syntax />
4073
<description>
4074
<para>Tell the speech recognition engine that it should start trying to get results from audio being
4075
fed to it.</para>
4076
</description>
4077
</application>
4078
<application name="SpeechBackground" language="en_US">
4079
<synopsis>
4080
Play a sound file and wait for speech to be recognized.
4081
</synopsis>
4082
<syntax>
4083
<parameter name="sound_file" required="true" />
4084
<parameter name="timeout">
4085
<para>Timeout integer in seconds. Note the timeout will only start
4086
once the sound file has stopped playing.</para>
4087
</parameter>
4088
<parameter name="options">
4089
<optionlist>
4090
<option name="n">
4091
<para>Don't answer the channel if it has not already been answered.</para>
4092
</option>
4093
</optionlist>
4094
</parameter>
4095
</syntax>
4096
<description>
4097
<para>This application plays a sound file and waits for the person to speak. Once they start speaking playback
4098
of the file stops, and silence is heard. Once they stop talking the processing sound is played to indicate
4099
the speech recognition engine is working. Once results are available the application returns and results
4100
(score and text) are available using dialplan functions.</para>
4101
<para>The first text and score are ${SPEECH_TEXT(0)} AND ${SPEECH_SCORE(0)} while the second are ${SPEECH_TEXT(1)}
4102
and ${SPEECH_SCORE(1)}.</para>
4103
<para>The first argument is the sound file and the second is the timeout integer in seconds.</para>
4104
4105
</description>
4106
</application>
4107
<application name="SpeechDeactivateGrammar" language="en_US">
4108
<synopsis>
4109
Deactivate a grammar.
4110
</synopsis>
4111
<syntax>
4112
<parameter name="grammar_name" required="true">
4113
<para>The grammar name to deactivate</para>
4114
</parameter>
4115
</syntax>
4116
<description>
4117
<para>This deactivates the specified grammar so that it is no longer recognized.</para>
4118
</description>
4119
</application>
4120
<application name="SpeechProcessingSound" language="en_US">
4121
<synopsis>
4122
Change background processing sound.
4123
</synopsis>
4124
<syntax>
4125
<parameter name="sound_file" required="true" />
4126
</syntax>
4127
<description>
4128
<para>This changes the processing sound that SpeechBackground plays back when the speech recognition engine is
4129
processing and working to get results.</para>
4130
</description>
4131
</application>
4132
<application name="SpeechDestroy" language="en_US">
4133
<synopsis>
4134
End speech recognition.
4135
</synopsis>
4136
<syntax />
4137
<description>
4138
<para>This destroys the information used by all the other speech recognition applications.
4139
If you call this application but end up wanting to recognize more speech, you must call SpeechCreate()
4140
again before calling any other application.</para>
4141
</description>
4142
</application>
4143
<application name="SpeechLoadGrammar" language="en_US">
4144
<synopsis>
4145
Load a grammar.
4146
</synopsis>
4147
<syntax>
4148
<parameter name="grammar_name" required="true" />
4149
<parameter name="path" required="true" />
4150
</syntax>
4151
<description>
4152
<para>Load a grammar only on the channel, not globally.</para>
4153
</description>
4154
</application>
4155
<application name="SpeechUnloadGrammar" language="en_US">
4156
<synopsis>
4157
Unload a grammar.
4158
</synopsis>
4159
<syntax>
4160
<parameter name="grammar_name" required="true" />
4161
</syntax>
4162
<description>
4163
<para>Unload a grammar.</para>
4164
</description>
4165
</application>
4166
<function name="SPEECH_SCORE" language="en_US">
4167
<synopsis>
4168
Gets the confidence score of a result.
4169
</synopsis>
4170
<syntax argsep="/">
4171
<parameter name="nbest_number" />
4172
<parameter name="result_number" required="true" />
4173
</syntax>
4174
<description>
4175
<para>Gets the confidence score of a result.</para>
4176
</description>
4177
</function>
4178
<function name="SPEECH_TEXT" language="en_US">
4179
<synopsis>
4180
Gets the recognized text of a result.
4181
</synopsis>
4182
<syntax argsep="/">
4183
<parameter name="nbest_number" />
4184
<parameter name="result_number" required="true" />
4185
</syntax>
4186
<description>
4187
<para>Gets the recognized text of a result.</para>
4188
</description>
4189
</function>
4190
<function name="SPEECH_GRAMMAR" language="en_US">
4191
<synopsis>
4192
Gets the matched grammar of a result if available.
4193
</synopsis>
4194
<syntax argsep="/">
4195
<parameter name="nbest_number" />
4196
<parameter name="result_number" required="true" />
4197
</syntax>
4198
<description>
4199
<para>Gets the matched grammar of a result if available.</para>
4200
</description>
4201
</function>
4202
<function name="SPEECH_ENGINE" language="en_US">
4203
<synopsis>
4204
Change a speech engine specific attribute.
4205
</synopsis>
4206
<syntax>
4207
<parameter name="name" required="true" />
4208
</syntax>
4209
<description>
4210
<para>Changes a speech engine specific attribute.</para>
4211
</description>
4212
</function>
4213
<function name="SPEECH_RESULTS_TYPE" language="en_US">
4214
<synopsis>
4215
Sets the type of results that will be returned.
4216
</synopsis>
4217
<syntax />
4218
<description>
4219
<para>Sets the type of results that will be returned. Valid options are normal or nbest.</para>
4220
</description>
4221
</function>
4222
<function name="SPEECH" language="en_US">
4223
<synopsis>
4224
Gets information about speech recognition results.
4225
</synopsis>
4226
<syntax>
4227
<parameter name="argument" required="true">
4228
<enumlist>
4229
<enum name="status">
4230
<para>Returns <literal>1</literal> upon speech object existing,
4231
or <literal>0</literal> if not</para>
4232
</enum>
4233
<enum name="spoke">
4234
<para>Returns <literal>1</literal> if spoker spoke,
4235
or <literal>0</literal> if not</para>
4236
</enum>
4237
<enum name="results">
4238
<para>Returns number of results that were recognized.</para>
4239
</enum>
4240
</enumlist>
4241
</parameter>
4242
</syntax>
4243
<description>
4244
<para>Gets information about speech recognition results.</para>
4245
</description>
4246
</function>
4247
<application name="Gosub" language="en_US">
4248
<synopsis>
4249
Jump to label, saving return address.
4250
</synopsis>
4251
<syntax>
4252
<parameter name="context" />
4253
<parameter name="exten" />
4254
<parameter name="priority" required="true" hasparams="optional">
4255
<argument name="arg1" multiple="true" required="true" />
4256
<argument name="argN" />
4257
</parameter>
4258
</syntax>
4259
<description>
4260
<para>Jumps to the label specified, saving the return address.</para>
4261
</description>
4262
<see-also>
4263
<ref type="application">GosubIf</ref>
4264
<ref type="application">Macro</ref>
4265
<ref type="application">Goto</ref>
4266
<ref type="application">Return</ref>
4267
<ref type="application">StackPop</ref>
4268
</see-also>
4269
</application>
4270
<application name="GosubIf" language="en_US">
4271
<synopsis>
4272
Conditionally jump to label, saving return address.
4273
</synopsis>
4274
<syntax argsep="?">
4275
<parameter name="condition" required="true" />
4276
<parameter name="destination" required="true" argsep=":">
4277
<argument name="labeliftrue" hasparams="optional">
4278
<argument name="arg1" required="true" multiple="true" />
4279
<argument name="argN" />
4280
</argument>
4281
<argument name="labeliffalse" hasparams="optional">
4282
<argument name="arg1" required="true" multiple="true" />
4283
<argument name="argN" />
4284
</argument>
4285
</parameter>
4286
</syntax>
4287
<description>
4288
<para>If the condition is true, then jump to labeliftrue. If false, jumps to
4289
labeliffalse, if specified. In either case, a jump saves the return point
4290
in the dialplan, to be returned to with a Return.</para>
4291
</description>
4292
<see-also>
4293
<ref type="application">Gosub</ref>
4294
<ref type="application">Return</ref>
4295
<ref type="application">MacroIf</ref>
4296
<ref type="function">IF</ref>
4297
<ref type="application">GotoIf</ref>
4298
</see-also>
4299
</application>
4300
<application name="Return" language="en_US">
4301
<synopsis>
4302
Return from gosub routine.
4303
</synopsis>
4304
<syntax>
4305
<parameter name="value">
4306
<para>Return value.</para>
4307
</parameter>
4308
</syntax>
4309
<description>
4310
<para>Jumps to the last label on the stack, removing it. The return <replaceable>value</replaceable>, if
4311
any, is saved in the channel variable <variable>GOSUB_RETVAL</variable>.</para>
4312
</description>
4313
<see-also>
4314
<ref type="application">Gosub</ref>
4315
<ref type="application">StackPop</ref>
4316
</see-also>
4317
</application>
4318
<application name="StackPop" language="en_US">
4319
<synopsis>
4320
Remove one address from gosub stack.
4321
</synopsis>
4322
<syntax />
4323
<description>
4324
<para>Removes last label on the stack, discarding it.</para>
4325
</description>
4326
<see-also>
4327
<ref type="application">Return</ref>
4328
<ref type="application">Gosub</ref>
4329
</see-also>
4330
</application>
4331
<function name="LOCAL" language="en_US">
4332
<synopsis>
4333
Manage variables local to the gosub stack frame.
4334
</synopsis>
4335
<syntax>
4336
<parameter name="varname" required="true" />
4337
</syntax>
4338
<description>
4339
<para>Read and write a variable local to the gosub stack frame, once we Return() it will be lost
4340
(or it will go back to whatever value it had before the Gosub()).</para>
4341
</description>
4342
<see-also>
4343
<ref type="application">Gosub</ref>
4344
<ref type="application">GosubIf</ref>
4345
<ref type="application">Return</ref>
4346
</see-also>
4347
</function>
4348
<function name="LOCAL_PEEK" language="en_US">
4349
<synopsis>
4350
Retrieve variables hidden by the local gosub stack frame.
4351
</synopsis>
4352
<syntax>
4353
<parameter name="n" required="true" />
4354
<parameter name="varname" required="true" />
4355
</syntax>
4356
<description>
4357
<para>Read a variable <replaceable>varname</replaceable> hidden by
4358
<replaceable>n</replaceable> levels of gosub stack frames. Note that ${LOCAL_PEEK(0,foo)}
4359
is the same as <variable>foo</variable>, since the value of <replaceable>n</replaceable>
4360
peeks under 0 levels of stack frames; in other words, 0 is the current level. If
4361
<replaceable>n</replaceable> exceeds the available number of stack frames, then an empty
4362
string is returned.</para>
4363
</description>
4364
<see-also>
4365
<ref type="application">Gosub</ref>
4366
<ref type="application">GosubIf</ref>
4367
<ref type="application">Return</ref>
4368
</see-also>
4369
</function>
4370
<application name="System" language="en_US">
4371
<synopsis>
4372
Execute a system command.
4373
</synopsis>
4374
<syntax>
4375
<parameter name="command" required="true">
4376
<para>Command to execute</para>
4377
</parameter>
4378
</syntax>
4379
<description>
4380
<para>Executes a command by using system(). If the command
4381
fails, the console should report a fallthrough.</para>
4382
<para>Result of execution is returned in the <variable>SYSTEMSTATUS</variable> channel variable:</para>
4383
<variablelist>
4384
<variable name="SYSTEMSTATUS">
4385
<value name="FAILURE">
4386
Could not execute the specified command.
4387
</value>
4388
<value name="SUCCESS">
4389
Specified command successfully executed.
4390
</value>
4391
</variable>
4392
</variablelist>
4393
</description>
4394
</application>
4395
<application name="TrySystem" language="en_US">
4396
<synopsis>
4397
Try executing a system command.
4398
</synopsis>
4399
<syntax>
4400
<parameter name="command" required="true">
4401
<para>Command to execute</para>
4402
</parameter>
4403
</syntax>
4404
<description>
4405
<para>Executes a command by using system().</para>
4406
<para>Result of execution is returned in the <variable>SYSTEMSTATUS</variable> channel variable:</para>
4407
<variablelist>
4408
<variable name="SYSTEMSTATUS">
4409
<value name="FAILURE">
4410
Could not execute the specified command.
4411
</value>
4412
<value name="SUCCESS">
4413
Specified command successfully executed.
4414
</value>
4415
<value name="APPERROR">
4416
Specified command successfully executed, but returned error code.
4417
</value>
4418
</variable>
4419
</variablelist>
4420
</description>
4421
</application>
4422
4423
<application name="BackgroundDetect" language="en_US">
4424
<synopsis>
4425
Background a file with talk detect.
4426
</synopsis>
4427
<syntax>
4428
<parameter name="filename" required="true" />
4429
<parameter name="sil">
4430
<para>If not specified, defaults to <literal>1000</literal>.</para>
4431
</parameter>
4432
<parameter name="min">
4433
<para>If not specified, defaults to <literal>100</literal>.</para>
4434
</parameter>
4435
<parameter name="max">
4436
<para>If not specified, defaults to <literal>infinity</literal>.</para>
4437
</parameter>
4438
<parameter name="analysistime">
4439
<para>If not specified, defaults to <literal>infinity</literal>.</para>
4440
</parameter>
4441
</syntax>
4442
<description>
4443
<para>Plays back <replaceable>filename</replaceable>, waiting for interruption from a given digit (the digit
4444
must start the beginning of a valid extension, or it will be ignored). During
4445
the playback of the file, audio is monitored in the receive direction, and if
4446
a period of non-silence which is greater than <replaceable>min</replaceable> ms yet less than
4447
<replaceable>max</replaceable> ms is followed by silence for at least <replaceable>sil</replaceable> ms,
4448
which occurs during the first <replaceable>analysistime</replaceable> ms, then the audio playback is
4449
aborted and processing jumps to the <replaceable>talk</replaceable> extension, if available.</para>
4450
</description>
4451
</application>
4452
<application name="TestServer" language="en_US">
4453
<synopsis>
4454
Execute Interface Test Server.
4455
</synopsis>
4456
<syntax />
4457
<description>
4458
<para>Perform test server function and write call report. Results stored in
4459
<filename>/var/log/asterisk/testreports/<testid>-server.txt</filename></para>
4460
</description>
4461
<see-also>
4462
<ref type="application">TestClient</ref>
4463
</see-also>
4464
</application>
4465
<application name="TestClient" language="en_US">
4466
<synopsis>
4467
Execute Interface Test Client.
4468
</synopsis>
4469
<syntax>
4470
<parameter name="testid" required="true">
4471
<para>An ID to identify this test.</para>
4472
</parameter>
4473
</syntax>
4474
<description>
4475
<para>Executes test client with given <replaceable>testid</replaceable>. Results stored in
4476
<filename>/var/log/asterisk/testreports/<testid>-client.txt</filename></para>
4477
</description>
4478
<see-also>
4479
<ref type="application">TestServer</ref>
4480
</see-also>
4481
</application>
4482
<application name="Transfer" language="en_US">
4483
<synopsis>
4484
Transfer caller to remote extension.
4485
</synopsis>
4486
<syntax>
4487
<parameter name="dest" required="true" argsep="/">
4488
<argument name="Tech" />
4489
<argument name="destination" required="true" />
4490
</parameter>
4491
</syntax>
4492
<description>
4493
<para>Requests the remote caller be transferred
4494
to a given destination. If TECH (SIP, IAX2, LOCAL etc) is used, only
4495
an incoming call with the same channel technology will be transfered.
4496
Note that for SIP, if you transfer before call is setup, a 302 redirect
4497
SIP message will be returned to the caller.</para>
4498
<para>The result of the application will be reported in the <variable>TRANSFERSTATUS</variable>
4499
channel variable:</para>
4500
<variablelist>
4501
<variable name="TRANSFERSTATUS">
4502
<value name="SUCCESS">
4503
Transfer succeeded.
4504
</value>
4505
<value name="FAILURE">
4506
Transfer failed.
4507
</value>
4508
<value name="UNSUPPORTED">
4509
Transfer unsupported by channel driver.
4510
</value>
4511
</variable>
4512
</variablelist>
4513
</description>
4514
</application>
4515
<application name="SendURL" language="en_US">
4516
<synopsis>
4517
Send a URL.
4518
</synopsis>
4519
<syntax>
4520
<parameter name="URL" required="true" />
4521
<parameter name="option">
4522
<optionlist>
4523
<option name="w">
4524
<para>Execution will wait for an acknowledgement that the
4525
URL has been loaded before continuing.</para>
4526
</option>
4527
</optionlist>
4528
</parameter>
4529
</syntax>
4530
<description>
4531
<para>Requests client go to <replaceable>URL</replaceable> (IAX2) or sends the
4532
URL to the client (other channels).</para>
4533
<para>Result is returned in the <variable>SENDURLSTATUS</variable> channel variable:</para>
4534
<variablelist>
4535
<variable name="SENDURLSTATUS">
4536
<value name="SUCCESS">
4537
URL successfully sent to client.
4538
</value>
4539
<value name="FAILURE">
4540
Failed to send URL.
4541
</value>
4542
<value name="NOLOAD">
4543
Client failed to load URL (wait enabled).
4544
</value>
4545
<value name="UNSUPPORTED">
4546
Channel does not support URL transport.
4547
</value>
4548
</variable>
4549
</variablelist>
4550
<para>SendURL continues normally if the URL was sent correctly or if the channel
4551
does not support HTML transport. Otherwise, the channel is hung up.</para>
4552
</description>
4553
<see-also>
4554
<ref type="application">SendImage</ref>
4555
<ref type="application">SendText</ref>
4556
</see-also>
4557
</application>
4558
<application name="UserEvent" language="en_US">
4559
<synopsis>
4560
Send an arbitrary event to the manager interface.
4561
</synopsis>
4562
<syntax>
4563
<parameter name="eventname" required="true" />
4564
<parameter name="body" />
4565
</syntax>
4566
<description>
4567
<para>Sends an arbitrary event to the manager interface, with an optional
4568
<replaceable>body</replaceable> representing additional arguments. The
4569
<replaceable>body</replaceable> may be specified as
4570
a <literal>|</literal> delimited list of headers. Each additional
4571
argument will be placed on a new line in the event. The format of the
4572
event will be:</para>
4573
<para> Event: UserEvent</para>
4574
<para> UserEvent: <specified event name></para>
4575
<para> [body]</para>
4576
<para>If no <replaceable>body</replaceable> is specified, only Event and UserEvent headers will be present.</para>
4577
</description>
4578
</application>
4579
<application name="Verbose" language="en_US">
4580
<synopsis>
4581
Send arbitrary text to verbose output.
4582
</synopsis>
4583
<syntax>
4584
<parameter name="level">
4585
<para>Must be an integer value. If not specified, defaults to 0.</para>
4586
</parameter>
4587
<parameter name="message" required="true">
4588
<para>Output text message.</para>
4589
</parameter>
4590
</syntax>
4591
<description>
4592
<para>Sends an arbitrary text message to verbose output.</para>
4593
</description>
4594
</application>
4595
<application name="Log" language="en_US">
4596
<synopsis>
4597
Send arbitrary text to a selected log level.
4598
</synopsis>
4599
<syntax>
4600
<parameter name="level">
4601
<para>Level must be one of <literal>ERROR</literal>, <literal>WARNING</literal>, <literal>NOTICE</literal>,
4602
<literal>DEBUG</literal>, <literal>VERBOSE</literal> or <literal>DTMF</literal>.</para>
4603
</parameter>
4604
<parameter name="message" required="true">
4605
<para>Output text message.</para>
4606
</parameter>
4607
</syntax>
4608
<description>
4609
<para>Sends an arbitrary text message to a selected log level.</para>
4610
</description>
4611
</application>
4612
<application name="VoiceMail" language="en_US">
4613
<synopsis>
4614
Leave a Voicemail message.
4615
</synopsis>
4616
<syntax>
4617
<parameter name="mailboxs" argsep="&" required="true">
4618
<argument name="mailbox1" argsep="@" required="true">
4619
<argument name="mailbox" required="true" />
4620
<argument name="context" />
4621
</argument>
4622
<argument name="mailbox2" argsep="@" multiple="true">
4623
<argument name="mailbox" required="true" />
4624
<argument name="context" />
4625
</argument>
4626
</parameter>
4627
<parameter name="options">
4628
<optionlist>
4629
<option name="b">
4630
<para>Play the <literal>busy</literal> greeting to the calling party.</para>
4631
</option>
4632
<option name="d">
4633
<argument name="c" />
4634
<para>Accept digits for a new extension in context <replaceable>c</replaceable>,
4635
if played during the greeting. Context defaults to the current context.</para>
4636
</option>
4637
<option name="g">
4638
<argument name="#" required="true" />
4639
<para>Use the specified amount of gain when recording the voicemail
4640
message. The units are whole-number decibels (dB). Only works on supported
4641
technologies, which is DAHDI only.</para>
4642
</option>
4643
<option name="s">
4644
<para>Skip the playback of instructions for leaving a message to the
4645
calling party.</para>
4646
</option>
4647
<option name="u">
4648
<para>Play the <literal>unavailable</literal> greeting.</para>
4649
</option>
4650
<option name="U">
4651
<para>Mark message as <literal>URGENT</literal>.</para>
4652
</option>
4653
<option name="P">
4654
<para>Mark message as <literal>PRIORITY</literal>.</para>
4655
</option>
4656
</optionlist>
4657
</parameter>
4658
</syntax>
4659
<description>
4660
<para>This application allows the calling party to leave a message for the specified
4661
list of mailboxes. When multiple mailboxes are specified, the greeting will be taken from
4662
the first mailbox specified. Dialplan execution will stop if the specified mailbox does not
4663
exist.</para>
4664
<para>The Voicemail application will exit if any of the following DTMF digits are received:</para>
4665
<enumlist>
4666
<enum name="0">
4667
<para>Jump to the <literal>o</literal> extension in the current dialplan context.</para>
4668
</enum>
4669
<enum name="*">
4670
<para>Jump to the <literal>a</literal> extension in the current dialplan context.</para>
4671
</enum>
4672
</enumlist>
4673
<para>This application will set the following channel variable upon completion:</para>
4674
<variablelist>
4675
<variable name="VMSTATUS">
4676
<para>This indicates the status of the execution of the VoiceMail application.</para>
4677
<value name="SUCCESS" />
4678
<value name="USEREXIT" />
4679
<value name="FAILED" />
4680
</variable>
4681
</variablelist>
4682
</description>
4683
</application>
4684
<application name="VoiceMailMain" language="en_US">
4685
<synopsis>
4686
Check Voicemail messages.
4687
</synopsis>
4688
<syntax>
4689
<parameter name="mailbox" required="true" argsep="@">
4690
<argument name="mailbox" />
4691
<argument name="context" />
4692
</parameter>
4693
<parameter name="options">
4694
<optionlist>
4695
<option name="p">
4696
<para>Consider the <replaceable>mailbox</replaceable> parameter as a prefix to
4697
the mailbox that is entered by the caller.</para>
4698
</option>
4699
<option name="g">
4700
<argument name="#" required="true" />
4701
<para>Use the specified amount of gain when recording a voicemail message.
4702
The units are whole-number decibels (dB).</para>
4703
</option>
4704
<option name="s">
4705
<para>Skip checking the passcode for the mailbox.</para>
4706
</option>
4707
<option name="a">
4708
<argument name="folder" required="true" />
4709
<para>Skip folder prompt and go directly to <replaceable>folder</replaceable> specified.
4710
Defaults to <literal>INBOX</literal>.</para>
4711
</option>
4712
</optionlist>
4713
</parameter>
4714
</syntax>
4715
<description>
4716
<para>This application allows the calling party to check voicemail messages. A specific
4717
<replaceable>mailbox</replaceable>, and optional corresponding <replaceable>context</replaceable>,
4718
may be specified. If a <replaceable>mailbox</replaceable> is not provided, the calling party will
4719
be prompted to enter one. If a <replaceable>context</replaceable> is not specified, the
4720
<literal>default</literal> context will be used.</para>
4721
</description>
4722
</application>
4723
<application name="MailboxExists" language="en_US">
4724
<synopsis>
4725
Check to see if Voicemail mailbox exists.
4726
</synopsis>
4727
<syntax>
4728
<parameter name="mailbox" required="true" argsep="@">
4729
<argument name="mailbox" required="true" />
4730
<argument name="context" />
4731
</parameter>
4732
<parameter name="options">
4733
<para>None options.</para>
4734
</parameter>
4735
</syntax>
4736
<description>
4737
<para>Check to see if the specified <replaceable>mailbox</replaceable> exists. If no voicemail
4738
<replaceable>context</replaceable> is specified, the <literal>default</literal> context
4739
will be used.</para>
4740
<para>This application will set the following channel variable upon completion:</para>
4741
<variablelist>
4742
<variable name="VMBOXEXISTSSTATUS">
4743
<para>This will contain the status of the execution of the MailboxExists application.
4744
Possible values include:</para>
4745
<value name="SUCCESS" />
4746
<value name="FAILED" />
4747
</variable>
4748
</variablelist>
4749
</description>
4750
</application>
4751
<application name="VMAuthenticate" language="en_US">
4752
<synopsis>
4753
Authenticate with Voicemail passwords.
4754
</synopsis>
4755
<syntax>
4756
<parameter name="mailbox" required="true" argsep="@">
4757
<argument name="mailbox" />
4758
<argument name="context" />
4759
</parameter>
4760
<parameter name="options">
4761
<optionlist>
4762
<option name="s">
4763
<para>Skip playing the initial prompts.</para>
4764
</option>
4765
</optionlist>
4766
</parameter>
4767
</syntax>
4768
<description>
4769
<para>This application behaves the same way as the Authenticate application, but the passwords
4770
are taken from <filename>voicemail.conf</filename>. If the <replaceable>mailbox</replaceable> is
4771
specified, only that mailbox's password will be considered valid. If the <replaceable>mailbox</replaceable>
4772
is not specified, the channel variable <variable>AUTH_MAILBOX</variable> will be set with the authenticated
4773
mailbox.</para>
4774
</description>
4775
</application>
4776
<function name="MAILBOX_EXISTS" language="en_US">
4777
<synopsis>
4778
Tell if a mailbox is configured.
4779
</synopsis>
4780
<syntax argsep="@">
4781
<parameter name="mailbox" required="true" />
4782
<parameter name="context" />
4783
</syntax>
4784
<description>
4785
<para>Returns a boolean of whether the corresponding <replaceable>mailbox</replaceable> exists.
4786
If <replaceable>context</replaceable> is not specified, defaults to the <literal>default</literal>
4787
context.</para>
4788
</description>
4789
</function>
4790
<application name="VoiceMail" language="en_US">
4791
<synopsis>
4792
Leave a Voicemail message.
4793
</synopsis>
4794
<syntax>
4795
<parameter name="mailboxs" argsep="&" required="true">
4796
<argument name="mailbox1" argsep="@" required="true">
4797
<argument name="mailbox" required="true" />
4798
<argument name="context" />
4799
</argument>
4800
<argument name="mailbox2" argsep="@" multiple="true">
4801
<argument name="mailbox" required="true" />
4802
<argument name="context" />
4803
</argument>
4804
</parameter>
4805
<parameter name="options">
4806
<optionlist>
4807
<option name="b">
4808
<para>Play the <literal>busy</literal> greeting to the calling party.</para>
4809
</option>
4810
<option name="d">
4811
<argument name="c" />
4812
<para>Accept digits for a new extension in context <replaceable>c</replaceable>,
4813
if played during the greeting. Context defaults to the current context.</para>
4814
</option>
4815
<option name="g">
4816
<argument name="#" required="true" />
4817
<para>Use the specified amount of gain when recording the voicemail
4818
message. The units are whole-number decibels (dB). Only works on supported
4819
technologies, which is DAHDI only.</para>
4820
</option>
4821
<option name="s">
4822
<para>Skip the playback of instructions for leaving a message to the
4823
calling party.</para>
4824
</option>
4825
<option name="u">
4826
<para>Play the <literal>unavailable</literal> greeting.</para>
4827
</option>
4828
<option name="U">
4829
<para>Mark message as <literal>URGENT</literal>.</para>
4830
</option>
4831
<option name="P">
4832
<para>Mark message as <literal>PRIORITY</literal>.</para>
4833
</option>
4834
</optionlist>
4835
</parameter>
4836
</syntax>
4837
<description>
4838
<para>This application allows the calling party to leave a message for the specified
4839
list of mailboxes. When multiple mailboxes are specified, the greeting will be taken from
4840
the first mailbox specified. Dialplan execution will stop if the specified mailbox does not
4841
exist.</para>
4842
<para>The Voicemail application will exit if any of the following DTMF digits are received:</para>
4843
<enumlist>
4844
<enum name="0">
4845
<para>Jump to the <literal>o</literal> extension in the current dialplan context.</para>
4846
</enum>
4847
<enum name="*">
4848
<para>Jump to the <literal>a</literal> extension in the current dialplan context.</para>
4849
</enum>
4850
</enumlist>
4851
<para>This application will set the following channel variable upon completion:</para>
4852
<variablelist>
4853
<variable name="VMSTATUS">
4854
<para>This indicates the status of the execution of the VoiceMail application.</para>
4855
<value name="SUCCESS" />
4856
<value name="USEREXIT" />
4857
<value name="FAILED" />
4858
</variable>
4859
</variablelist>
4860
</description>
4861
</application>
4862
<application name="VoiceMailMain" language="en_US">
4863
<synopsis>
4864
Check Voicemail messages.
4865
</synopsis>
4866
<syntax>
4867
<parameter name="mailbox" required="true" argsep="@">
4868
<argument name="mailbox" />
4869
<argument name="context" />
4870
</parameter>
4871
<parameter name="options">
4872
<optionlist>
4873
<option name="p">
4874
<para>Consider the <replaceable>mailbox</replaceable> parameter as a prefix to
4875
the mailbox that is entered by the caller.</para>
4876
</option>
4877
<option name="g">
4878
<argument name="#" required="true" />
4879
<para>Use the specified amount of gain when recording a voicemail message.
4880
The units are whole-number decibels (dB).</para>
4881
</option>
4882
<option name="s">
4883
<para>Skip checking the passcode for the mailbox.</para>
4884
</option>
4885
<option name="a">
4886
<argument name="folder" required="true" />
4887
<para>Skip folder prompt and go directly to <replaceable>folder</replaceable> specified.
4888
Defaults to <literal>INBOX</literal>.</para>
4889
</option>
4890
</optionlist>
4891
</parameter>
4892
</syntax>
4893
<description>
4894
<para>This application allows the calling party to check voicemail messages. A specific
4895
<replaceable>mailbox</replaceable>, and optional corresponding <replaceable>context</replaceable>,
4896
may be specified. If a <replaceable>mailbox</replaceable> is not provided, the calling party will
4897
be prompted to enter one. If a <replaceable>context</replaceable> is not specified, the
4898
<literal>default</literal> context will be used.</para>
4899
</description>
4900
</application>
4901
<application name="MailboxExists" language="en_US">
4902
<synopsis>
4903
Check to see if Voicemail mailbox exists.
4904
</synopsis>
4905
<syntax>
4906
<parameter name="mailbox" required="true" argsep="@">
4907
<argument name="mailbox" required="true" />
4908
<argument name="context" />
4909
</parameter>
4910
<parameter name="options">
4911
<para>None options.</para>
4912
</parameter>
4913
</syntax>
4914
<description>
4915
<para>Check to see if the specified <replaceable>mailbox</replaceable> exists. If no voicemail
4916
<replaceable>context</replaceable> is specified, the <literal>default</literal> context
4917
will be used.</para>
4918
<para>This application will set the following channel variable upon completion:</para>
4919
<variablelist>
4920
<variable name="VMBOXEXISTSSTATUS">
4921
<para>This will contain the status of the execution of the MailboxExists application.
4922
Possible values include:</para>
4923
<value name="SUCCESS" />
4924
<value name="FAILED" />
4925
</variable>
4926
</variablelist>
4927
</description>
4928
</application>
4929
<application name="VMAuthenticate" language="en_US">
4930
<synopsis>
4931
Authenticate with Voicemail passwords.
4932
</synopsis>
4933
<syntax>
4934
<parameter name="mailbox" required="true" argsep="@">
4935
<argument name="mailbox" />
4936
<argument name="context" />
4937
</parameter>
4938
<parameter name="options">
4939
<optionlist>
4940
<option name="s">
4941
<para>Skip playing the initial prompts.</para>
4942
</option>
4943
</optionlist>
4944
</parameter>
4945
</syntax>
4946
<description>
4947
<para>This application behaves the same way as the Authenticate application, but the passwords
4948
are taken from <filename>voicemail.conf</filename>. If the <replaceable>mailbox</replaceable> is
4949
specified, only that mailbox's password will be considered valid. If the <replaceable>mailbox</replaceable>
4950
is not specified, the channel variable <variable>AUTH_MAILBOX</variable> will be set with the authenticated
4951
mailbox.</para>
4952
</description>
4953
</application>
4954
<function name="MAILBOX_EXISTS" language="en_US">
4955
<synopsis>
4956
Tell if a mailbox is configured.
4957
</synopsis>
4958
<syntax argsep="@">
4959
<parameter name="mailbox" required="true" />
4960
<parameter name="context" />
4961
</syntax>
4962
<description>
4963
<para>Returns a boolean of whether the corresponding <replaceable>mailbox</replaceable> exists.
4964
If <replaceable>context</replaceable> is not specified, defaults to the <literal>default</literal>
4965
context.</para>
4966
</description>
4967
</function>
4968
<application name="VoiceMail" language="en_US">
4969
<synopsis>
4970
Leave a Voicemail message.
4971
</synopsis>
4972
<syntax>
4973
<parameter name="mailboxs" argsep="&" required="true">
4974
<argument name="mailbox1" argsep="@" required="true">
4975
<argument name="mailbox" required="true" />
4976
<argument name="context" />
4977
</argument>
4978
<argument name="mailbox2" argsep="@" multiple="true">
4979
<argument name="mailbox" required="true" />
4980
<argument name="context" />
4981
</argument>
4982
</parameter>
4983
<parameter name="options">
4984
<optionlist>
4985
<option name="b">
4986
<para>Play the <literal>busy</literal> greeting to the calling party.</para>
4987
</option>
4988
<option name="d">
4989
<argument name="c" />
4990
<para>Accept digits for a new extension in context <replaceable>c</replaceable>,
4991
if played during the greeting. Context defaults to the current context.</para>
4992
</option>
4993
<option name="g">
4994
<argument name="#" required="true" />
4995
<para>Use the specified amount of gain when recording the voicemail
4996
message. The units are whole-number decibels (dB). Only works on supported
4997
technologies, which is DAHDI only.</para>
4998
</option>
4999
<option name="s">
5000
<para>Skip the playback of instructions for leaving a message to the
5001
calling party.</para>
5002
</option>
5003
<option name="u">
5004
<para>Play the <literal>unavailable</literal> greeting.</para>
5005
</option>
5006
<option name="U">
5007
<para>Mark message as <literal>URGENT</literal>.</para>
5008
</option>
5009
<option name="P">
5010
<para>Mark message as <literal>PRIORITY</literal>.</para>
5011
</option>
5012
</optionlist>
5013
</parameter>
5014
</syntax>
5015
<description>
5016
<para>This application allows the calling party to leave a message for the specified
5017
list of mailboxes. When multiple mailboxes are specified, the greeting will be taken from
5018
the first mailbox specified. Dialplan execution will stop if the specified mailbox does not
5019
exist.</para>
5020
<para>The Voicemail application will exit if any of the following DTMF digits are received:</para>
5021
<enumlist>
5022
<enum name="0">
5023
<para>Jump to the <literal>o</literal> extension in the current dialplan context.</para>
5024
</enum>
5025
<enum name="*">
5026
<para>Jump to the <literal>a</literal> extension in the current dialplan context.</para>
5027
</enum>
5028
</enumlist>
5029
<para>This application will set the following channel variable upon completion:</para>
5030
<variablelist>
5031
<variable name="VMSTATUS">
5032
<para>This indicates the status of the execution of the VoiceMail application.</para>
5033
<value name="SUCCESS" />
5034
<value name="USEREXIT" />
5035
<value name="FAILED" />
5036
</variable>
5037
</variablelist>
5038
</description>
5039
</application>
5040
<application name="VoiceMailMain" language="en_US">
5041
<synopsis>
5042
Check Voicemail messages.
5043
</synopsis>
5044
<syntax>
5045
<parameter name="mailbox" required="true" argsep="@">
5046
<argument name="mailbox" />
5047
<argument name="context" />
5048
</parameter>
5049
<parameter name="options">
5050
<optionlist>
5051
<option name="p">
5052
<para>Consider the <replaceable>mailbox</replaceable> parameter as a prefix to
5053
the mailbox that is entered by the caller.</para>
5054
</option>
5055
<option name="g">
5056
<argument name="#" required="true" />
5057
<para>Use the specified amount of gain when recording a voicemail message.
5058
The units are whole-number decibels (dB).</para>
5059
</option>
5060
<option name="s">
5061
<para>Skip checking the passcode for the mailbox.</para>
5062
</option>
5063
<option name="a">
5064
<argument name="folder" required="true" />
5065
<para>Skip folder prompt and go directly to <replaceable>folder</replaceable> specified.
5066
Defaults to <literal>INBOX</literal>.</para>
5067
</option>
5068
</optionlist>
5069
</parameter>
5070
</syntax>
5071
<description>
5072
<para>This application allows the calling party to check voicemail messages. A specific
5073
<replaceable>mailbox</replaceable>, and optional corresponding <replaceable>context</replaceable>,
5074
may be specified. If a <replaceable>mailbox</replaceable> is not provided, the calling party will
5075
be prompted to enter one. If a <replaceable>context</replaceable> is not specified, the
5076
<literal>default</literal> context will be used.</para>
5077
</description>
5078
</application>
5079
<application name="MailboxExists" language="en_US">
5080
<synopsis>
5081
Check to see if Voicemail mailbox exists.
5082
</synopsis>
5083
<syntax>
5084
<parameter name="mailbox" required="true" argsep="@">
5085
<argument name="mailbox" required="true" />
5086
<argument name="context" />
5087
</parameter>
5088
<parameter name="options">
5089
<para>None options.</para>
5090
</parameter>
5091
</syntax>
5092
<description>
5093
<para>Check to see if the specified <replaceable>mailbox</replaceable> exists. If no voicemail
5094
<replaceable>context</replaceable> is specified, the <literal>default</literal> context
5095
will be used.</para>
5096
<para>This application will set the following channel variable upon completion:</para>
5097
<variablelist>
5098
<variable name="VMBOXEXISTSSTATUS">
5099
<para>This will contain the status of the execution of the MailboxExists application.
5100
Possible values include:</para>
5101
<value name="SUCCESS" />
5102
<value name="FAILED" />
5103
</variable>
5104
</variablelist>
5105
</description>
5106
</application>
5107
<application name="VMAuthenticate" language="en_US">
5108
<synopsis>
5109
Authenticate with Voicemail passwords.
5110
</synopsis>
5111
<syntax>
5112
<parameter name="mailbox" required="true" argsep="@">
5113
<argument name="mailbox" />
5114
<argument name="context" />
5115
</parameter>
5116
<parameter name="options">
5117
<optionlist>
5118
<option name="s">
5119
<para>Skip playing the initial prompts.</para>
5120
</option>
5121
</optionlist>
5122
</parameter>
5123
</syntax>
5124
<description>
5125
<para>This application behaves the same way as the Authenticate application, but the passwords
5126
are taken from <filename>voicemail.conf</filename>. If the <replaceable>mailbox</replaceable> is
5127
specified, only that mailbox's password will be considered valid. If the <replaceable>mailbox</replaceable>
5128
is not specified, the channel variable <variable>AUTH_MAILBOX</variable> will be set with the authenticated
5129
mailbox.</para>
5130
</description>
5131
</application>
5132
<function name="MAILBOX_EXISTS" language="en_US">
5133
<synopsis>
5134
Tell if a mailbox is configured.
5135
</synopsis>
5136
<syntax argsep="@">
5137
<parameter name="mailbox" required="true" />
5138
<parameter name="context" />
5139
</syntax>
5140
<description>
5141
<para>Returns a boolean of whether the corresponding <replaceable>mailbox</replaceable> exists.
5142
If <replaceable>context</replaceable> is not specified, defaults to the <literal>default</literal>
5143
context.</para>
5144
</description>
5145
</function>
5146
<application name="WaitForRing" language="en_US">
5147
<synopsis>
5148
Wait for Ring Application.
5149
</synopsis>
5150
<syntax>
5151
<parameter name="timeout" required="true" />
5152
</syntax>
5153
<description>
5154
<para>Returns <literal>0</literal> after waiting at least <replaceable>timeout</replaceable> seconds,
5155
and only after the next ring has completed. Returns <literal>0</literal> on success or
5156
<literal>-1</literal> on hangup.</para>
5157
</description>
5158
</application>
5159
<application name="WaitForSilence" language="en_US">
5160
<synopsis>
5161
Waits for a specified amount of silence.
5162
</synopsis>
5163
<syntax>
5164
<parameter name="silencerequired" required="true" />
5165
<parameter name="iterations">
5166
<para>If not specified, defaults to <literal>1</literal>.</para>
5167
</parameter>
5168
<parameter name="timeout">
5169
<para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para>
5170
</parameter>
5171
</syntax>
5172
<description>
5173
<para>Waits for up to <replaceable>silencerequired</replaceable> milliseconds of silence,
5174
<replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable>
5175
specified the number of seconds to return after, even if we do not receive the specified amount of silence.
5176
Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which
5177
is to wait indefinitely until silence is detected on the line. This is particularly useful for reverse-911-type
5178
call broadcast applications where you need to wait for an answering machine to complete its spiel before
5179
playing a message.</para>
5180
<para>Typically you will want to include two or more calls to WaitForSilence when dealing with an answering
5181
machine; first waiting for the spiel to finish, then waiting for the beep, etc.</para>
5182
<para>Examples:</para>
5183
<para>WaitForSilence(500,2) will wait for 1/2 second of silence, twice</para>
5184
<para>WaitForSilence(1000) will wait for 1 second of silence, once</para>
5185
<para>WaitForSilence(300,3,10) will wait for 300ms silence, 3 times, and returns after 10 sec, even if silence
5186
is not detected</para>
5187
<para>Sets the channel variable <variable>WAITSTATUS</variable> to one of these values:</para>
5188
<variablelist>
5189
<variable name="WAITSTATUS">
5190
<value name="SILENCE">
5191
if exited with silence detected.
5192
</value>
5193
<value name="TIMEOUT">
5194
if exited without silence detected after timeout.
5195
</value>
5196
</variable>
5197
</variablelist>
5198
</description>
5199
<see-also>
5200
<ref type="application">WaitForNoise</ref>
5201
</see-also>
5202
</application>
5203
<application name="WaitForNoise" language="en_US">
5204
<synopsis>
5205
Waits for a specified amount of noise.
5206
</synopsis>
5207
<syntax>
5208
<parameter name="noiserequired" required="true" />
5209
<parameter name="iterations">
5210
<para>If not specified, defaults to <literal>1</literal>.</para>
5211
</parameter>
5212
<parameter name="timeout">
5213
<para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para>
5214
</parameter>
5215
</syntax>
5216
<description>
5217
<para>Waits for up to <replaceable>noiserequired</replaceable> milliseconds of noise,
5218
<replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable>
5219
specified the number of seconds to return after, even if we do not receive the specified amount of noise.
5220
Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which
5221
is to wait indefinitely until noise is detected on the line.</para>
5222
</description>
5223
<see-also>
5224
<ref type="application">WaitForSilence</ref>
5225
</see-also>
5226
</application>
5227
<application name="WaitUntil" language="en_US">
5228
<synopsis>
5229
Wait (sleep) until the current time is the given epoch.
5230
</synopsis>
5231
<syntax>
5232
<parameter name="epoch" required="true" />
5233
</syntax>
5234
<description>
5235
<para>Waits until the given <replaceable>epoch</replaceable>.</para>
5236
<para>Sets <variable>WAITUNTILSTATUS</variable> to one of the following values:</para>
5237
<variablelist>
5238
<variable name="WAITUNTILSTATUS">
5239
<value name="OK">
5240
Wait succeeded.
5241
</value>
5242
<value name="FAILURE">
5243
Invalid argument.
5244
</value>
5245
<value name="HANGUP">
5246
Channel hungup before time elapsed.
5247
</value>
5248
<value name="PAST">
5249
Time specified had already past.
5250
</value>
5251
</variable>
5252
</variablelist>
5253
</description>
5254
</application>
5255
<application name="While" language="en_US">
5256
<synopsis>
5257
Start a while loop.
5258
</synopsis>
5259
<syntax>
5260
<parameter name="expr" required="true" />
5261
</syntax>
5262
<description>
5263
<para>Start a While Loop. Execution will return to this point when
5264
<literal>EndWhile()</literal> is called until expr is no longer true.</para>
5265
</description>
5266
<see-also>
5267
<ref type="application">EndWhile</ref>
5268
<ref type="application">ExitWhile</ref>
5269
<ref type="application">ContinueWhile</ref>
5270
</see-also>
5271
</application>
5272
<application name="EndWhile" language="en_US">
5273
<synopsis>
5274
End a while loop.
5275
</synopsis>
5276
<syntax />
5277
<description>
5278
<para>Return to the previous called <literal>While()</literal>.</para>
5279
</description>
5280
<see-also>
5281
<ref type="application">While</ref>
5282
<ref type="application">ExitWhile</ref>
5283
<ref type="application">ContinueWhile</ref>
5284
</see-also>
5285
</application>
5286
<application name="ExitWhile" language="en_US">
5287
<synopsis>
5288
End a While loop.
5289
</synopsis>
5290
<syntax />
5291
<description>
5292
<para>Exits a <literal>While()</literal> loop, whether or not the conditional has been satisfied.</para>
5293
</description>
5294
<see-also>
5295
<ref type="application">While</ref>
5296
<ref type="application">EndWhile</ref>
5297
<ref type="application">ContinueWhile</ref>
5298
</see-also>
5299
</application>
5300
<application name="ContinueWhile" language="en_US">
5301
<synopsis>
5302
Restart a While loop.
5303
</synopsis>
5304
<syntax />
5305
<description>
5306
<para>Returns to the top of the while loop and re-evaluates the conditional.</para>
5307
</description>
5308
<see-also>
5309
<ref type="application">While</ref>
5310
<ref type="application">EndWhile</ref>
5311
<ref type="application">ExitWhile</ref>
5312
</see-also>
5313
</application>
5314
<application name="Zapateller" language="en_US">
5315
<synopsis>
5316
Block telemarketers with SIT.
5317
</synopsis>
5318
<syntax>
5319
<parameter name="options" required="true">
5320
<para>Comma delimited list of options.</para>
5321
<optionlist>
5322
<option name="answer">
5323
<para>Causes the line to be answered before playing the tone.</para>
5324
</option>
5325
<option name="nocallerid">
5326
<para>Causes Zapateller to only play the tone if there is no
5327
callerid information available.</para>
5328
</option>
5329
</optionlist>
5330
</parameter>
5331
</syntax>
5332
<description>
5333
<para>Generates special information tone to block telemarketers from calling you.</para>
5334
<para>This application will set the following channel variable upon completion:</para>
5335
<variablelist>
5336
<variable name="ZAPATELLERSTATUS">
5337
<para>This will contain the last action accomplished by the
5338
Zapateller application. Possible values include:</para>
5339
<value name="NOTHING" />
5340
<value name="ANSWERED" />
5341
<value name="ZAPPED" />
5342
</variable>
5343
</variablelist>
5344
</description>
5345
</application>
5346
<function name="AES_ENCRYPT" language="en_US">
5347
<synopsis>
5348
Encrypt a string with AES given a 16 character key.
5349
</synopsis>
5350
<syntax>
5351
<parameter name="key" required="true">
5352
<para>AES Key</para>
5353
</parameter>
5354
<parameter name="string" required="true">
5355
<para>Input string</para>
5356
</parameter>
5357
</syntax>
5358
<description>
5359
<para>Returns an AES encrypted string encoded in base64.</para>
5360
</description>
5361
</function>
5362
<function name="AES_DECRYPT" language="en_US">
5363
<synopsis>
5364
Decrypt a string encoded in base64 with AES given a 16 character key.
5365
</synopsis>
5366
<syntax>
5367
<parameter name="key" required="true">
5368
<para>AES Key</para>
5369
</parameter>
5370
<parameter name="string" required="true">
5371
<para>Input string.</para>
5372
</parameter>
5373
</syntax>
5374
<description>
5375
<para>Returns the plain text string.</para>
5376
</description>
5377
</function>
5378
<function name = "AUDIOHOOK_INHERIT" language="en_US">
5379
<synopsis>
5380
Set whether an audiohook may be inherited to another channel
5381
</synopsis>
5382
<syntax>
5383
<parameter name="source" required="true">
5384
<para>The built-in sources in Asterisk are</para>
5385
<enumlist>
5386
<enum name="MixMonitor" />
5387
<enum name="Chanspy" />
5388
<enum name="Volume" />
5389
<enum name="Speex" />
5390
<enum name="JACK_HOOK" />
5391
</enumlist>
5392
<para>Note that the names are not case-sensitive</para>
5393
</parameter>
5394
</syntax>
5395
<description>
5396
<para>By enabling audiohook inheritance on the channel, you are giving
5397
permission for an audiohook to be inherited by a descendent channel.
5398
Inheritance may be be disabled at any point as well.</para>
5399
5400
<para>Example scenario:</para>
5401
<para>exten => 2000,1,MixMonitor(blah.wav)</para>
5402
<para>exten => 2000,n,Set(AUDIOHOOK_INHERIT(MixMonitor)=yes)</para>
5403
<para>exten => 2000,n,Dial(SIP/2000)</para>
5404
<para>
5405
</para>
5406
<para>exten => 4000,1,Dial(SIP/4000)</para>
5407
<para>
5408
</para>
5409
<para>exten => 5000,1,MixMonitor(blah2.wav)</para>
5410
<para>exten => 5000,n,Dial(SIP/5000)</para>
5411
<para>
5412
</para>
5413
<para>In this basic dialplan scenario, let's consider the following sample calls</para>
5414
<para>Call 1: Caller dials 2000. The person who answers then executes an attended</para>
5415
<para> transfer to 4000.</para>
5416
<para>Result: Since extension 2000 set MixMonitor to be inheritable, after the</para>
5417
<para> transfer to 4000 has completed, the call will continue to be recorded
5418
to blah.wav</para>
5419
<para>
5420
</para>
5421
<para>Call 2: Caller dials 5000. The person who answers then executes an attended</para>
5422
<para> transfer to 4000.</para>
5423
<para>Result: Since extension 5000 did not set MixMonitor to be inheritable, the</para>
5424
<para> recording will stop once the call has been transferred to 4000.</para>
5425
</description>
5426
</function>
5427
<function name="BASE64_ENCODE" language="en_US">
5428
<synopsis>
5429
Encode a string in base64.
5430
</synopsis>
5431
<syntax>
5432
<parameter name="string" required="true">
5433
<para>Input string</para>
5434
</parameter>
5435
</syntax>
5436
<description>
5437
<para>Returns the base64 string.</para>
5438
</description>
5439
</function>
5440
<function name="BASE64_DECODE" language="en_US">
5441
<synopsis>
5442
Decode a base64 string.
5443
</synopsis>
5444
<syntax>
5445
<parameter name="string" required="true">
5446
<para>Input string.</para>
5447
</parameter>
5448
</syntax>
5449
<description>
5450
<para>Returns the plain text string.</para>
5451
</description>
5452
</function>
5453
<function name="BLACKLIST" language="en_US">
5454
<synopsis>
5455
Check if the callerid is on the blacklist.
5456
</synopsis>
5457
<syntax />
5458
<description>
5459
<para>Uses astdb to check if the Caller*ID is in family <literal>blacklist</literal>.
5460
Returns <literal>1</literal> or <literal>0</literal>.</para>
5461
</description>
5462
<see-also>
5463
<ref type="function">DB</ref>
5464
</see-also>
5465
</function>
5466
5467
<function name="CALLERID" language="en_US">
5468
<synopsis>
5469
Gets or sets Caller*ID data on the channel.
5470
</synopsis>
5471
<syntax>
5472
<parameter name="datatype" required="true">
5473
<para>The allowable datatypes are:</para>
5474
<enumlist>
5475
<enum name="all" />
5476
<enum name="num" />
5477
<enum name="ANI" />
5478
<enum name="DNID" />
5479
<enum name="RDNIS" />
5480
<enum name="pres" />
5481
<enum name="ton" />
5482
</enumlist>
5483
</parameter>
5484
<parameter name="CID">
5485
<para>Optional Caller*ID</para>
5486
</parameter>
5487
</syntax>
5488
<description>
5489
<para>Gets or sets Caller*ID data on the channel. Uses channel callerid by default or optional
5490
callerid, if specified.</para>
5491
</description>
5492
</function>
5493
<function name="CALLERPRES" language="en_US">
5494
<synopsis>
5495
Gets or sets Caller*ID presentation on the channel.
5496
</synopsis>
5497
<syntax />
5498
<description>
5499
<para>Gets or sets Caller*ID presentation on the channel. The following values
5500
are valid:</para>
5501
<enumlist>
5502
<enum name="allowed_not_screened">
5503
<para>Presentation Allowed, Not Screened.</para>
5504
</enum>
5505
<enum name="allowed_passed_screen">
5506
<para>Presentation Allowed, Passed Screen.</para>
5507
</enum>
5508
<enum name="allowed_failed_screen">
5509
<para>Presentation Allowed, Failed Screen.</para>
5510
</enum>
5511
<enum name="allowed">
5512
<para>Presentation Allowed, Network Number.</para>
5513
</enum>
5514
<enum name="prohib_not_screened">
5515
<para>Presentation Prohibited, Not Screened.</para>
5516
</enum>
5517
<enum name="prohib_passed_screen">
5518
<para>Presentation Prohibited, Passed Screen.</para>
5519
</enum>
5520
<enum name="prohib_failed_screen">
5521
<para>Presentation Prohibited, Failed Screen.</para>
5522
</enum>
5523
<enum name="prohib">
5524
<para>Presentation Prohibited, Network Number.</para>
5525
</enum>
5526
<enum name="unavailable">
5527
<para>Number Unavailable.</para>
5528
</enum>
5529
</enumlist>
5530
</description>
5531
</function>
5532
<function name="CDR" language="en_US">
5533
<synopsis>
5534
Gets or sets a CDR variable.
5535
</synopsis>
5536
<syntax>
5537
<parameter name="name" required="true">
5538
<para>CDR field name:</para>
5539
<enumlist>
5540
<enum name="clid">
5541
<para>Caller ID.</para>
5542
</enum>
5543
<enum name="lastdata">
5544
<para>Last application arguments.</para>
5545
</enum>
5546
<enum name="disposition">
5547
<para>ANSWERED, NO ANSWER, BUSY.</para>
5548
</enum>
5549
<enum name="src">
5550
<para>Source.</para>
5551
</enum>
5552
<enum name="start">
5553
<para>Time the call started.</para>
5554
</enum>
5555
<enum name="amaflags">
5556
<para>DOCUMENTATION, BILL, IGNORE, etc.</para>
5557
</enum>
5558
<enum name="dst">
5559
<para>Destination.</para>
5560
</enum>
5561
<enum name="answer">
5562
<para>Time the call was answered.</para>
5563
</enum>
5564
<enum name="accountcode">
5565
<para>The channel's account code.</para>
5566
</enum>
5567
<enum name="dcontext">
5568
<para>Destination context.</para>
5569
</enum>
5570
<enum name="end">
5571
<para>Time the call ended.</para>
5572
</enum>
5573
<enum name="uniqueid">
5574
<para>The channel's unique id.</para>
5575
</enum>
5576
<enum name="dstchannel">
5577
<para>Destination channel.</para>
5578
</enum>
5579
<enum name="duration">
5580
<para>Duration of the call.</para>
5581
</enum>
5582
<enum name="userfield">
5583
<para>The channel's user specified field.</para>
5584
</enum>
5585
<enum name="lastapp">
5586
<para>Last application.</para>
5587
</enum>
5588
<enum name="billsec">
5589
<para>Duration of the call once it was answered.</para>
5590
</enum>
5591
<enum name="channel">
5592
<para>Channel name.</para>
5593
</enum>
5594
</enumlist>
5595
</parameter>
5596
<parameter name="options" required="false">
5597
<optionlist>
5598
<option name="l">
5599
<para>Uses the most recent CDR on a channel with multiple records</para>
5600
</option>
5601
<option name="r">
5602
<para>Searches the entire stack of CDRs on the channel.</para>
5603
</option>
5604
<option name="s">
5605
<para>Skips any CDR's that are marked 'LOCKED' due to forkCDR() calls.
5606
(on setting/writing CDR vars only)</para>
5607
</option>
5608
<option name="u">
5609
<para>Retrieves the raw, unprocessed value.</para>
5610
<para>For example, 'start', 'answer', and 'end' will be retrieved as epoch
5611
values, when the <literal>u</literal> option is passed, but formatted as YYYY-MM-DD HH:MM:SS
5612
otherwise. Similarly, disposition and amaflags will return their raw
5613
integral values.</para>
5614
</option>
5615
</optionlist>
5616
</parameter>
5617
</syntax>
5618
<description>
5619
<para>All of the CDR field names are read-only, except for <literal>accountcode</literal>,
5620
<literal>userfield</literal>, and <literal>amaflags</literal>. You may, however, supply
5621
a name not on the above list, and create your own variable, whose value can be changed
5622
with this function, and this variable will be stored on the cdr.</para>
5623
<note><para>For setting CDR values, the <literal>l</literal> flag does not apply to
5624
setting the <literal>accountcode</literal>, <literal>userfield</literal>, or
5625
<literal>amaflags</literal>.</para></note>
5626
<para>Raw values for <literal>disposition</literal>:</para>
5627
<enumlist>
5628
<enum name="1">
5629
<para>NO ANSWER</para>
5630
</enum>
5631
<enum name="2">
5632
<para>BUSY</para>
5633
</enum>
5634
<enum name="3">
5635
<para>FAILED</para>
5636
</enum>
5637
<enum name="4">
5638
<para>ANSWERED</para>
5639
</enum>
5640
</enumlist>
5641
<para>Raw values for <literal>amaflags</literal>:</para>
5642
<enumlist>
5643
<enum name="1">
5644
<para>OMIT</para>
5645
</enum>
5646
<enum name="2">
5647
<para>BILLING</para>
5648
</enum>
5649
<enum name="3">
5650
<para>DOCUMENTATION</para>
5651
</enum>
5652
</enumlist>
5653
<para>Example: exten => 1,1,Set(CDR(userfield)=test)</para>
5654
</description>
5655
</function>
5656
<function name="CHANNELS" language="en_US">
5657
<synopsis>
5658
Gets the list of channels, optionally filtering by a regular expression.
5659
</synopsis>
5660
<syntax>
5661
<parameter name="regular_expression" />
5662
</syntax>
5663
<description>
5664
<para>Gets the list of channels, optionally filtering by a <replaceable>regular_expression</replaceable>. If
5665
no argument is provided, all known channels are returned. The
5666
<replaceable>regular_expression</replaceable> must correspond to
5667
the POSIX.2 specification, as shown in <emphasis>regex(7)</emphasis>. The list returned
5668
will be space-delimited.</para>
5669
</description>
5670
</function>
5671
<function name="CHANNEL" language="en_US">
5672
<synopsis>
5673
Gets/sets various pieces of information about the channel.
5674
</synopsis>
5675
<syntax>
5676
<parameter name="item" required="true">
5677
<para>Standard items (provided by all channel technologies) are:</para>
5678
<enumlist>
5679
<enum name="audioreadformat">
5680
<para>R/O format currently being read.</para>
5681
</enum>
5682
<enum name="audionativeformat">
5683
<para>R/O format used natively for audio.</para>
5684
</enum>
5685
<enum name="audiowriteformat">
5686
<para>R/O format currently being written.</para>
5687
</enum>
5688
<enum name="callgroup">
5689
<para>R/W call groups for call pickup.</para>
5690
</enum>
5691
<enum name="channeltype">
5692
<para>R/O technology used for channel.</para>
5693
</enum>
5694
<enum name="language">
5695
<para>R/W language for sounds played.</para>
5696
</enum>
5697
<enum name="musicclass">
5698
<para>R/W class (from musiconhold.conf) for hold music.</para>
5699
</enum>
5700
<enum name="parkinglot">
5701
<para>R/W parkinglot for parking.</para>
5702
</enum>
5703
<enum name="rxgain">
5704
<para>R/W set rxgain level on channel drivers that support it.</para>
5705
</enum>
5706
<enum name="state">
5707
<para>R/O state for channel</para>
5708
</enum>
5709
<enum name="tonezone">
5710
<para>R/W zone for indications played</para>
5711
</enum>
5712
<enum name="transfercapability">
5713
<para>R/W ISDN Transfer Capability, one of:</para>
5714
<enumlist>
5715
<enum name="SPEECH" />
5716
<enum name="DIGITAL" />
5717
<enum name="RESTRICTED_DIGITAL" />
5718
<enum name="3K1AUDIO" />
5719
<enum name="DIGITAL_W_TONES" />
5720
<enum name="VIDEO" />
5721
</enumlist>
5722
</enum>
5723
<enum name="txgain">
5724
<para>R/W set txgain level on channel drivers that support it.</para>
5725
</enum>
5726
<enum name="videonativeformat">
5727
<para>R/O format used natively for video</para>
5728
</enum>
5729
<enum name="trace">
5730
<para>R/W whether or not context tracing is enabled, only available
5731
<emphasis>if CHANNEL_TRACE is defined</emphasis>.</para>
5732
</enum>
5733
</enumlist>
5734
<para><emphasis>chan_sip</emphasis> provides the following additional options:</para>
5735
<enumlist>
5736
<enum name="peerip">
5737
<para>R/O Get the IP address of the peer.</para>
5738
</enum>
5739
<enum name="recvip">
5740
<para>R/O Get the source IP address of the peer.</para>
5741
</enum>
5742
<enum name="from">
5743
<para>R/O Get the URI from the From: header.</para>
5744
</enum>
5745
<enum name="uri">
5746
<para>R/O Get the URI from the Contact: header.</para>
5747
</enum>
5748
<enum name="useragent">
5749
<para>R/O Get the useragent.</para>
5750
</enum>
5751
<enum name="peername">
5752
<para>R/O Get the name of the peer.</para>
5753
</enum>
5754
<enum name="t38passthrough">
5755
<para>R/O <literal>1</literal> if T38 is offered or enabled in this channel,
5756
otherwise <literal>0</literal></para>
5757
</enum>
5758
<enum name="rtpqos">
5759
<para>R/O Get QOS information about the RTP stream</para>
5760
<para> This option takes two additional arguments:</para>
5761
<para> Argument 1:</para>
5762
<para> <literal>audio</literal> Get data about the audio stream</para>
5763
<para> <literal>video</literal> Get data about the video stream</para>
5764
<para> <literal>text</literal> Get data about the text stream</para>
5765
<para> Argument 2:</para>
5766
<para> <literal>local_ssrc</literal> Local SSRC (stream ID)</para>
5767
<para> <literal>local_lostpackets</literal> Local lost packets</para>
5768
<para> <literal>local_jitter</literal> Local calculated jitter</para>
5769
<para> <literal>local_maxjitter</literal> Local calculated jitter (maximum)</para>
5770
<para> <literal>local_minjitter</literal> Local calculated jitter (minimum)</para>
5771
<para> <literal>local_normdevjitter</literal>Local calculated jitter (normal deviation)</para>
5772
<para> <literal>local_stdevjitter</literal> Local calculated jitter (standard deviation)</para>
5773
<para> <literal>local_count</literal> Number of received packets</para>
5774
<para> <literal>remote_ssrc</literal> Remote SSRC (stream ID)</para>
5775
<para> <literal>remote_lostpackets</literal>Remote lost packets</para>
5776
<para> <literal>remote_jitter</literal> Remote reported jitter</para>
5777
<para> <literal>remote_maxjitter</literal> Remote calculated jitter (maximum)</para>
5778
<para> <literal>remote_minjitter</literal> Remote calculated jitter (minimum)</para>
5779
<para> <literal>remote_normdevjitter</literal>Remote calculated jitter (normal deviation)</para>
5780
<para> <literal>remote_stdevjitter</literal>Remote calculated jitter (standard deviation)</para>
5781
<para> <literal>remote_count</literal> Number of transmitted packets</para>
5782
<para> <literal>remote_ssrc</literal> Remote SSRC (stream ID)</para>
5783
<para> <literal>remote_lostpackets</literal>Remote lost packets</para>
5784
<para> <literal>remote_jitter</literal> Remote reported jitter</para>
5785
<para> <literal>remote_maxjitter</literal> Remote calculated jitter (maximum)</para>
5786
<para> <literal>remote_minjitter</literal> Remote calculated jitter (minimum)</para>
5787
<para> <literal>remote_normdevjitter</literal>Remote calculated jitter (normal deviation)</para>
5788
<para> <literal>remote_stdevjitter</literal>Remote calculated jitter (standard deviation)</para>
5789
<para> <literal>remote_count</literal> Number of transmitted packets</para>
5790
<para> <literal>rtt</literal> Round trip time</para>
5791
<para> <literal>maxrtt</literal> Round trip time (maximum)</para>
5792
<para> <literal>minrtt</literal> Round trip time (minimum)</para>
5793
<para> <literal>normdevrtt</literal> Round trip time (normal deviation)</para>
5794
<para> <literal>stdevrtt</literal> Round trip time (standard deviation)</para>
5795
<para> <literal>all</literal> All statistics (in a form suited to logging,
5796
but not for parsing)</para>
5797
</enum>
5798
<enum name="rtpdest">
5799
<para>R/O Get remote RTP destination information.</para>
5800
<para> This option takes one additional argument:</para>
5801
<para> Argument 1:</para>
5802
<para> <literal>audio</literal> Get audio destination</para>
5803
<para> <literal>video</literal> Get video destination</para>
5804
</enum>
5805
</enumlist>
5806
<para><emphasis>chan_iax2</emphasis> provides the following additional options:</para>
5807
<enumlist>
5808
<enum name="osptoken">
5809
<para>R/W Get or set the OSP token information for a call.</para>
5810
</enum>
5811
<enum name="peerip">
5812
<para>R/O Get the peer's ip address.</para>
5813
</enum>
5814
<enum name="peername">
5815
<para>R/O Get the peer's username.</para>
5816
</enum>
5817
</enumlist>
5818
</parameter>
5819
</syntax>
5820
<description>
5821
<para>Gets/sets various pieces of information about the channel, additional <replaceable>item</replaceable> may
5822
be available from the channel driver; see its documentation for details. Any <replaceable>item</replaceable>
5823
requested that is not available on the current channel will return an empty string.</para>
5824
</description>
5825
</function>
5826
<function name="AST_CONFIG" language="en_US">
5827
<synopsis>
5828
Retrieve a variable from a configuration file.
5829
</synopsis>
5830
<syntax>
5831
<parameter name="config_file" required="true" />
5832
<parameter name="category" required="true" />
5833
<parameter name="variable_name" required="true" />
5834
</syntax>
5835
<description>
5836
<para>This function reads a variable from an Asterisk configuration file.</para>
5837
</description>
5838
</function>
5839
5840
<function name="SORT" language="en_US">
5841
<synopsis>
5842
Sorts a list of key/vals into a list of keys, based upon the vals.
5843
</synopsis>
5844
<syntax>
5845
<parameter name="keyval" required="true" argsep=":">
5846
<argument name="key1" required="true" />
5847
<argument name="val1" required="true" />
5848
</parameter>
5849
<parameter name="keyvaln" multiple="true" argsep=":">
5850
<argument name="key2" required="true" />
5851
<argument name="val2" required="true" />
5852
</parameter>
5853
</syntax>
5854
<description>
5855
<para>Takes a comma-separated list of keys and values, each separated by a colon, and returns a
5856
comma-separated list of the keys, sorted by their values. Values will be evaluated as
5857
floating-point numbers.</para>
5858
</description>
5859
</function>
5860
<function name="CUT" language="en_US">
5861
<synopsis>
5862
Slices and dices strings, based upon a named delimiter.
5863
</synopsis>
5864
<syntax>
5865
<parameter name="varname" required="true">
5866
<para>Variable you want cut</para>
5867
</parameter>
5868
<parameter name="char-delim" required="true">
5869
<para>Delimiter, defaults to <literal>-</literal></para>
5870
</parameter>
5871
<parameter name="range-spec" required="true">
5872
<para>Number of the field you want (1-based offset), may also be specified as a range (with <literal>-</literal>)
5873
or group of ranges and fields (with <literal>&</literal>)</para>
5874
</parameter>
5875
</syntax>
5876
<description>
5877
<para>Cut out information from a string (<replaceable>varname</replaceable>), based upon a named delimiter.</para>
5878
</description>
5879
</function>
5880
<function name="DB" language="en_US">
5881
<synopsis>
5882
Read from or write to the Asterisk database.
5883
</synopsis>
5884
<syntax argsep="/">
5885
<parameter name="family" required="true" />
5886
<parameter name="key" required="true" />
5887
</syntax>
5888
<description>
5889
<para>This function will read from or write a value to the Asterisk database. On a
5890
read, this function returns the corresponding value from the database, or blank
5891
if it does not exist. Reading a database value will also set the variable
5892
DB_RESULT. If you wish to find out if an entry exists, use the DB_EXISTS
5893
function.</para>
5894
</description>
5895
<see-also>
5896
<ref type="application">DBdel</ref>
5897
<ref type="function">DB_DELETE</ref>
5898
<ref type="application">DBdeltree</ref>
5899
<ref type="function">DB_EXISTS</ref>
5900
</see-also>
5901
</function>
5902
<function name="DB_EXISTS" language="en_US">
5903
<synopsis>
5904
Check to see if a key exists in the Asterisk database.
5905
</synopsis>
5906
<syntax argsep="/">
5907
<parameter name="family" required="true" />
5908
<parameter name="key" required="true" />
5909
</syntax>
5910
<description>
5911
<para>This function will check to see if a key exists in the Asterisk
5912
database. If it exists, the function will return <literal>1</literal>. If not,
5913
it will return <literal>0</literal>. Checking for existence of a database key will
5914
also set the variable DB_RESULT to the key's value if it exists.</para>
5915
</description>
5916
<see-also>
5917
<ref type="function">DB</ref>
5918
</see-also>
5919
</function>
5920
<function name="DB_DELETE" language="en_US">
5921
<synopsis>
5922
Return a value from the database and delete it.
5923
</synopsis>
5924
<syntax argsep="/">
5925
<parameter name="family" required="true" />
5926
<parameter name="key" required="true" />
5927
</syntax>
5928
<description>
5929
<para>This function will retrieve a value from the Asterisk database
5930
and then remove that key from the database. <variable>DB_RESULT</variable>
5931
will be set to the key's value if it exists.</para>
5932
</description>
5933
<see-also>
5934
<ref type="application">DBdel</ref>
5935
<ref type="function">DB</ref>
5936
<ref type="application">DBdeltree</ref>
5937
</see-also>
5938
</function>
5939
<function name="DEVICE_STATE" language="en_US">
5940
<synopsis>
5941
Get or Set a device state.
5942
</synopsis>
5943
<syntax>
5944
<parameter name="device" required="true" />
5945
</syntax>
5946
<description>
5947
<para>The DEVICE_STATE function can be used to retrieve the device state from any
5948
device state provider. For example:</para>
5949
<para>NoOp(SIP/mypeer has state ${DEVICE_STATE(SIP/mypeer)})</para>
5950
<para>NoOp(Conference number 1234 has state ${DEVICE_STATE(MeetMe:1234)})</para>
5951
<para>The DEVICE_STATE function can also be used to set custom device state from
5952
the dialplan. The <literal>Custom:</literal> prefix must be used. For example:</para>
5953
<para>Set(DEVICE_STATE(Custom:lamp1)=BUSY)</para>
5954
<para>Set(DEVICE_STATE(Custom:lamp2)=NOT_INUSE)</para>
5955
<para>You can subscribe to the status of a custom device state using a hint in
5956
the dialplan:</para>
5957
<para>exten => 1234,hint,Custom:lamp1</para>
5958
<para>The possible values for both uses of this function are:</para>
5959
<para>UNKNOWN | NOT_INUSE | INUSE | BUSY | INVALID | UNAVAILABLE | RINGING |
5960
RINGINUSE | ONHOLD</para>
5961
</description>
5962
</function>
5963
<function name="HINT" language="en_US">
5964
<synopsis>
5965
Get the devices set for a dialplan hint.
5966
</synopsis>
5967
<syntax>
5968
<parameter name="extension" required="true" argsep="@">
5969
<argument name="extension" required="true" />
5970
<argument name="context" />
5971
</parameter>
5972
<parameter name="options">
5973
<optionlist>
5974
<option name="n">
5975
<para>Retrieve name on the hint instead of list of devices.</para>
5976
</option>
5977
</optionlist>
5978
</parameter>
5979
</syntax>
5980
<description>
5981
<para>The HINT function can be used to retrieve the list of devices that are
5982
mapped to a dialplan hint. For example:</para>
5983
<para>NoOp(Hint for Extension 1234 is ${HINT(1234)})</para>
5984
</description>
5985
</function>
5986
<function name="DIALGROUP" language="en_US">
5987
<synopsis>
5988
Manages a group of users for dialing.
5989
</synopsis>
5990
<syntax>
5991
<parameter name="group" required="true" />
5992
<parameter name="op">
5993
<para>The operation name, possible values are:</para>
5994
<para><literal>add</literal> - add a channel name or interface (write-only)</para>
5995
<para><literal>del</literal> - remove a channel name or interface (write-only)</para>
5996
</parameter>
5997
</syntax>
5998
<description>
5999
<para>Presents an interface meant to be used in concert with the Dial
6000
application, by presenting a list of channels which should be dialled when
6001
referenced.</para>
6002
<para>When DIALGROUP is read from, the argument is interpreted as the particular
6003
<replaceable>group</replaceable> for which a dial should be attempted. When DIALGROUP is written to
6004
with no arguments, the entire list is replaced with the argument specified.</para>
6005
<para>Functionality is similar to a queue, except that when no interfaces are
6006
available, execution may continue in the dialplan. This is useful when
6007
you want certain people to be the first to answer any calls, with immediate
6008
fallback to a queue when the front line people are busy or unavailable, but
6009
you still want front line people to log in and out of that group, just like
6010
a queue.</para>
6011
<para>Example:</para>
6012
<para>exten => 1,1,Set(DIALGROUP(mygroup,add)=SIP/10)</para>
6013
<para>exten => 1,n,Set(DIALGROUP(mygroup,add)=SIP/20)</para>
6014
<para>exten => 1,n,Dial(${DIALGROUP(mygroup)})</para>
6015
</description>
6016
</function>
6017
<function name="DIALPLAN_EXISTS" language="en_US">
6018
<synopsis>
6019
Checks the existence of a dialplan target.
6020
</synopsis>
6021
<syntax>
6022
<parameter name="context" required="true" />
6023
<parameter name="extension" />
6024
<parameter name="priority" />
6025
</syntax>
6026
<description>
6027
<para>This function returns <literal>1</literal> if the target exits. Otherwise, it returns <literal>0</literal>.</para>
6028
</description>
6029
</function>
6030
6031
<function name="ENUMQUERY" language="en_US">
6032
<synopsis>
6033
Initiate an ENUM query.
6034
</synopsis>
6035
<syntax>
6036
<parameter name="number" required="true" />
6037
<parameter name="method-type">
6038
<para>If no <replaceable>method-type</replaceable> is given, the default will be
6039
<literal>sip</literal>.</para>
6040
</parameter>
6041
<parameter name="zone-suffix">
6042
<para>If no <replaceable>zone-suffix</replaceable> is given, the default will be
6043
<literal>e164.arpa</literal></para>
6044
</parameter>
6045
</syntax>
6046
<description>
6047
<para>This will do a ENUM lookup of the given phone number.</para>
6048
</description>
6049
</function>
6050
<function name="ENUMRESULT" language="en_US">
6051
<synopsis>
6052
Retrieve results from a ENUMQUERY.
6053
</synopsis>
6054
<syntax>
6055
<parameter name="id" required="true">
6056
<para>The identifier returned by the ENUMQUERY function.</para>
6057
</parameter>
6058
<parameter name="resultnum" required="true">
6059
<para>The number of the result that you want to retrieve.</para>
6060
<para>Results start at <literal>1</literal>. If this argument is specified
6061
as <literal>getnum</literal>, then it will return the total number of results
6062
that are available.</para>
6063
</parameter>
6064
</syntax>
6065
<description>
6066
<para>This function will retrieve results from a previous use
6067
of the ENUMQUERY function.</para>
6068
</description>
6069
</function>
6070
<function name="ENUMLOOKUP" language="en_US">
6071
<synopsis>
6072
General or specific querying of NAPTR records for ENUM or ENUM-like DNS pointers.
6073
</synopsis>
6074
<syntax>
6075
<parameter name="number" required="true" />
6076
<parameter name="method-type">
6077
<para>If no <replaceable>method-type</replaceable> is given, the default will be
6078
<literal>sip</literal>.</para>
6079
</parameter>
6080
<parameter name="options">
6081
<optionlist>
6082
<option name="c">
6083
<para>Returns an integer count of the number of NAPTRs of a certain RR type.</para>
6084
<para>Combination of <literal>c</literal> and Method-type of <literal>ALL</literal> will
6085
return a count of all NAPTRs for the record.</para>
6086
</option>
6087
<option name="u">
6088
<para>Returns the full URI and does not strip off the URI-scheme.</para>
6089
</option>
6090
<option name="s">
6091
<para>Triggers ISN specific rewriting.</para>
6092
</option>
6093
<option name="i">
6094
<para>Looks for branches into an Infrastructure ENUM tree.</para>
6095
</option>
6096
<option name="d">
6097
<para>for a direct DNS lookup without any flipping of digits.</para>
6098
</option>
6099
</optionlist>
6100
</parameter>
6101
<parameter name="record#">
6102
<para>If no <replaceable>record#</replaceable> is given,
6103
defaults to <literal>1</literal>.</para>
6104
</parameter>
6105
<parameter name="zone-suffix">
6106
<para>If no <replaceable>zone-suffix</replaceable> is given, the default will be
6107
<literal>e164.arpa</literal></para>
6108
</parameter>
6109
</syntax>
6110
<description>
6111
<para>For more information see <filename>doc/asterisk.pdf</filename>.</para>
6112
</description>
6113
</function>
6114
<function name="TXTCIDNAME" language="en_US">
6115
<synopsis>
6116
TXTCIDNAME looks up a caller name via DNS.
6117
</synopsis>
6118
<syntax>
6119
<parameter name="number" required="true" />
6120
<parameter name="zone-suffix">
6121
<para>If no <replaceable>zone-suffix</replaceable> is given, the default will be
6122
<literal>e164.arpa</literal></para>
6123
</parameter>
6124
</syntax>
6125
<description>
6126
<para>This function looks up the given phone number in DNS to retrieve
6127
the caller id name. The result will either be blank or be the value
6128
found in the TXT record in DNS.</para>
6129
</description>
6130
</function>
6131
<function name="ENV" language="en_US">
6132
<synopsis>
6133
Gets or sets the environment variable specified.
6134
</synopsis>
6135
<syntax>
6136
<parameter name="varname" required="true">
6137
<para>Environment variable name</para>
6138
</parameter>
6139
</syntax>
6140
<description>
6141
</description>
6142
</function>
6143
<function name="STAT" language="en_US">
6144
<synopsis>
6145
Does a check on the specified file.
6146
</synopsis>
6147
<syntax>
6148
<parameter name="flag" required="true">
6149
<para>Flag may be one of the following:</para>
6150
<para>d - Checks if the file is a directory.</para>
6151
<para>e - Checks if the file exists.</para>
6152
<para>f - Checks if the file is a regular file.</para>
6153
<para>m - Returns the file mode (in octal)</para>
6154
<para>s - Returns the size (in bytes) of the file</para>
6155
<para>A - Returns the epoch at which the file was last accessed.</para>
6156
<para>C - Returns the epoch at which the inode was last changed.</para>
6157
<para>M - Returns the epoch at which the file was last modified.</para>
6158
</parameter>
6159
<parameter name="filename" required="true" />
6160
</syntax>
6161
<description>
6162
</description>
6163
</function>
6164
<function name="FILE" language="en_US">
6165
<synopsis>
6166
Obtains the contents of a file.
6167
</synopsis>
6168
<syntax>
6169
<parameter name="filename" required="true" />
6170
<parameter name="offset" required="true">
6171
<para>Maybe specified as any number. If negative, <replaceable>offset</replaceable> specifies the number
6172
of bytes back from the end of the file.</para>
6173
</parameter>
6174
<parameter name="length" required="true">
6175
<para>If specified, will limit the length of the data read to that size. If negative,
6176
trims <replaceable>length</replaceable> bytes from the end of the file.</para>
6177
</parameter>
6178
</syntax>
6179
<description>
6180
</description>
6181
</function>
6182
<function name="EXTENSION_STATE" language="en_US">
6183
<synopsis>
6184
Get an extension's state.
6185
</synopsis>
6186
<syntax argsep="@">
6187
<parameter name="extension" required="true" />
6188
<parameter name="context">
6189
<para>If it is not specified defaults to <literal>default</literal>.</para>
6190
</parameter>
6191
</syntax>
6192
<description>
6193
<para>The EXTENSION_STATE function can be used to retrieve the state from any
6194
hinted extension. For example:</para>
6195
<para>NoOp(1234@default has state ${EXTENSION_STATE(1234)})</para>
6196
<para>NoOp(4567@home has state ${EXTENSION_STATE(4567@home)})</para>
6197
<para>The possible values returned by this function are:</para>
6198
<para>UNKNOWN | NOT_INUSE | INUSE | BUSY | INVALID | UNAVAILABLE | RINGING |
6199
RINGINUSE | HOLDINUSE | ONHOLD</para>
6200
</description>
6201
</function>
6202
<function name="GLOBAL" language="en_US">
6203
<synopsis>
6204
Gets or sets the global variable specified.
6205
</synopsis>
6206
<syntax>
6207
<parameter name="varname" required="true">
6208
<para>Global variable name</para>
6209
</parameter>
6210
</syntax>
6211
<description>
6212
<para>Set or get the value of a global variable specified in <replaceable>varname</replaceable></para>
6213
</description>
6214
</function>
6215
<function name="SHARED" language="en_US">
6216
<synopsis>
6217
Gets or sets the shared variable specified.
6218
</synopsis>
6219
<syntax>
6220
<parameter name="varname" required="true">
6221
<para>Variable name</para>
6222
</parameter>
6223
<parameter name="channel">
6224
<para>If not specified will default to current channel. It is the complete
6225
channel name: <literal>SIP/12-abcd1234</literal> or the prefix only <literal>SIP/12</literal>.</para>
6226
</parameter>
6227
</syntax>
6228
<description>
6229
<para>Implements a shared variable area, in which you may share variables between
6230
channels.</para>
6231
<para>The variables used in this space are separate from the general namespace of
6232
the channel and thus <variable>SHARED(foo)</variable> and <variable>foo</variable>
6233
represent two completely different variables, despite sharing the same name.</para>
6234
<para>Finally, realize that there is an inherent race between channels operating
6235
at the same time, fiddling with each others' internal variables, which is why
6236
this special variable namespace exists; it is to remind you that variables in
6237
the SHARED namespace may change at any time, without warning. You should
6238
therefore take special care to ensure that when using the SHARED namespace,
6239
you retrieve the variable and store it in a regular channel variable before
6240
using it in a set of calculations (or you might be surprised by the result).</para>
6241
</description>
6242
</function>
6243
6244
<function name="GROUP_COUNT" language="en_US">
6245
<synopsis>
6246
Counts the number of channels in the specified group.
6247
</synopsis>
6248
<syntax argsep="@">
6249
<parameter name="groupname">
6250
<para>Group name.</para>
6251
</parameter>
6252
<parameter name="category">
6253
<para>Category name</para>
6254
</parameter>
6255
</syntax>
6256
<description>
6257
<para>Calculates the group count for the specified group, or uses the
6258
channel's current group if not specifed (and non-empty).</para>
6259
</description>
6260
</function>
6261
<function name="GROUP_MATCH_COUNT" language="en_US">
6262
<synopsis>
6263
Counts the number of channels in the groups matching the specified pattern.
6264
</synopsis>
6265
<syntax argsep="@">
6266
<parameter name="groupmatch" required="true">
6267
<para>A standard regular expression used to match a group name.</para>
6268
</parameter>
6269
<parameter name="category">
6270
<para>Category name.</para>
6271
</parameter>
6272
</syntax>
6273
<description>
6274
<para>Calculates the group count for all groups that match the specified pattern.
6275
Uses standard regular expression matching (see regex(7)).</para>
6276
</description>
6277
</function>
6278
<function name="GROUP" language="en_US">
6279
<synopsis>
6280
Gets or sets the channel group.
6281
</synopsis>
6282
<syntax>
6283
<parameter name="category">
6284
<para>Category name.</para>
6285
</parameter>
6286
</syntax>
6287
<description>
6288
<para><replaceable>category</replaceable> can be employed for more fine grained group management. Each channel
6289
can only be member of exactly one group per <replaceable>category</replaceable>.</para>
6290
</description>
6291
</function>
6292
<function name="GROUP_LIST" language="en_US">
6293
<synopsis>
6294
Gets a list of the groups set on a channel.
6295
</synopsis>
6296
<syntax />
6297
<description>
6298
<para>Gets a list of the groups set on a channel.</para>
6299
</description>
6300
</function>
6301
6302
<function name="ICONV" language="en_US">
6303
<synopsis>
6304
Converts charsets of strings.
6305
</synopsis>
6306
<syntax>
6307
<parameter name="in-charset" required="true">
6308
<para>Input charset</para>
6309
</parameter>
6310
<parameter name="out-charset" required="true">
6311
<para>Output charset</para>
6312
</parameter>
6313
<parameter name="string" required="true">
6314
<para>String to convert, from <replaceable>in-charset</replaceable> to <replaceable>out-charset</replaceable></para>
6315
</parameter>
6316
</syntax>
6317
<description>
6318
<para>Converts string from <replaceable>in-charset</replaceable> into <replaceable>out-charset</replaceable>.
6319
For available charsets, use <literal>iconv -l</literal> on your shell command line.</para>
6320
<note><para>Due to limitations within the API, ICONV will not currently work with
6321
charsets with embedded NULLs. If found, the string will terminate.</para></note>
6322
</description>
6323
</function>
6324
<function name="LOCK" language="en_US">
6325
<synopsis>
6326
Attempt to obtain a named mutex.
6327
</synopsis>
6328
<syntax>
6329
<parameter name="lockname" required="true" />
6330
</syntax>
6331
<description>
6332
<para>Attempts to grab a named lock exclusively, and prevents other channels from
6333
obtaining the same lock. LOCK will wait for the lock to become available.
6334
Returns <literal>1</literal> if the lock was obtained or <literal>0</literal> on error.</para>
6335
<note><para>To avoid the possibility of a deadlock, LOCK will only attempt to
6336
obtain the lock for 3 seconds if the channel already has another lock.</para></note>
6337
</description>
6338
</function>
6339
<function name="TRYLOCK" language="en_US">
6340
<synopsis>
6341
Attempt to obtain a named mutex.
6342
</synopsis>
6343
<syntax>
6344
<parameter name="lockname" required="true" />
6345
</syntax>
6346
<description>
6347
<para>Attempts to grab a named lock exclusively, and prevents other channels
6348
from obtaining the same lock. Returns <literal>1</literal> if the lock was
6349
available or <literal>0</literal> otherwise.</para>
6350
</description>
6351
</function>
6352
<function name="UNLOCK" language="en_US">
6353
<synopsis>
6354
Unlocks a named mutex.
6355
</synopsis>
6356
<syntax>
6357
<parameter name="lockname" required="true" />
6358
</syntax>
6359
<description>
6360
<para>Unlocks a previously locked mutex. Returns <literal>1</literal> if the channel
6361
had a lock or <literal>0</literal> otherwise.</para>
6362
<note><para>It is generally unnecessary to unlock in a hangup routine, as any locks
6363
held are automatically freed when the channel is destroyed.</para></note>
6364
</description>
6365
</function>
6366
<function name="ISNULL" language="en_US">
6367
<synopsis>
6368
Check if a value is NULL.
6369
</synopsis>
6370
<syntax>
6371
<parameter name="data" required="true" />
6372
</syntax>
6373
<description>
6374
<para>Returns <literal>1</literal> if NULL or <literal>0</literal> otherwise.</para>
6375
</description>
6376
</function>
6377
<function name="SET" language="en_US">
6378
<synopsis>
6379
SET assigns a value to a channel variable.
6380
</synopsis>
6381
<syntax argsep="=">
6382
<parameter name="varname" required="true" />
6383
<parameter name="value" />
6384
</syntax>
6385
<description>
6386
</description>
6387
</function>
6388
<function name="EXISTS" language="en_US">
6389
<synopsis>
6390
Test the existence of a value.
6391
</synopsis>
6392
<syntax>
6393
<parameter name="data" required="true" />
6394
</syntax>
6395
<description>
6396
<para>Returns <literal>1</literal> if exists, <literal>0</literal> otherwise.</para>
6397
</description>
6398
</function>
6399
<function name="IF" language="en_US">
6400
<synopsis>
6401
Check for an expresion.
6402
</synopsis>
6403
<syntax argsep="?">
6404
<parameter name="expresion" required="true" />
6405
<parameter name="retvalue" argsep=":" required="true">
6406
<argument name="true" />
6407
<argument name="false" />
6408
</parameter>
6409
</syntax>
6410
<description>
6411
<para>Returns the data following <literal>?</literal> if true, else the data following <literal>:</literal></para>
6412
</description>
6413
</function>
6414
<function name="IFTIME" language="en_US">
6415
<synopsis>
6416
Temporal Conditional.
6417
</synopsis>
6418
<syntax argsep="?">
6419
<parameter name="timespec" required="true" />
6420
<parameter name="retvalue" required="true" argsep=":">
6421
<argument name="true" />
6422
<argument name="false" />
6423
</parameter>
6424
</syntax>
6425
<description>
6426
<para>Returns the data following <literal>?</literal> if true, else the data following <literal>:</literal></para>
6427
</description>
6428
</function>
6429
<function name="IMPORT" language="en_US">
6430
<synopsis>
6431
Retrieve the value of a variable from another channel.
6432
</synopsis>
6433
<syntax>
6434
<parameter name="channel" required="true" />
6435
<parameter name="variable" required="true" />
6436
</syntax>
6437
<description>
6438
</description>
6439
</function>
6440
<function name="MATH" language="en_US">
6441
<synopsis>
6442
Performs Mathematical Functions.
6443
</synopsis>
6444
<syntax>
6445
<parameter name="expression" required="true">
6446
<para>Is of the form:
6447
<replaceable>number1</replaceable><replaceable>op</replaceable><replaceable>number2</replaceable>
6448
where the possible values for <replaceable>op</replaceable>
6449
are:</para>
6450
<para>+,-,/,*,%,<<,>>,^,AND,OR,XOR,<,%gt;,>=,<=,== (and behave as their C equivalents)</para>
6451
</parameter>
6452
<parameter name="type">
6453
<para>Wanted type of result:</para>
6454
<para>f, float - float(default)</para>
6455
<para>i, int - integer</para>
6456
<para>h, hex - hex</para>
6457
<para>c, char - char</para>
6458
</parameter>
6459
</syntax>
6460
<description>
6461
<para>Performs mathematical functions based on two parameters and an operator. The returned
6462
value type is <replaceable>type</replaceable></para>
6463
<para>Example: Set(i=${MATH(123%16,int)}) - sets var i=11</para>
6464
</description>
6465
</function>
6466
<function name="MD5" language="en_US">
6467
<synopsis>
6468
Computes an MD5 digest.
6469
</synopsis>
6470
<syntax>
6471
<parameter name="data" required="true" />
6472
</syntax>
6473
<description>
6474
<para>Computes an MD5 digest.</para>
6475
</description>
6476
</function>
6477
<function name="IFMODULE" language="en_US">
6478
<synopsis>
6479
Checks if an Asterisk module is loaded in memory.
6480
</synopsis>
6481
<syntax>
6482
<parameter name="modulename.so" required="true">
6483
<para>Module name complete with <literal>.so</literal></para>
6484
</parameter>
6485
</syntax>
6486
<description>
6487
<para>Checks if a module is loaded. Use the full module name
6488
as shown by the list in <literal>module list</literal>.
6489
Returns <literal>1</literal> if module exists in memory, otherwise <literal>0</literal></para>
6490
</description>
6491
</function>
6492
<function name="ODBC_FETCH" language="en_US">
6493
<synopsis>
6494
Fetch a row from a multirow query.
6495
</synopsis>
6496
<syntax>
6497
<parameter name="result-id" required="true" />
6498
</syntax>
6499
<description>
6500
<para>For queries which are marked as mode=multirow, the original
6501
query returns a <replaceable>result-id</replaceable> from which results
6502
may be fetched. This function implements the actual fetch of the results.</para>
6503
<para>This also sets <variable>ODBC_FETCH_STATUS</variable>.</para>
6504
<variablelist>
6505
<variable name="ODBC_FETCH_STATUS">
6506
<value name="SUCESS">
6507
If rows are available.
6508
</value>
6509
<value name="FAILURE">
6510
If no rows are available.
6511
</value>
6512
</variable>
6513
</variablelist>
6514
</description>
6515
</function>
6516
<application name="ODBCFinish" language="en_US">
6517
<synopsis>
6518
Clear the resultset of a sucessful multirow query.
6519
</synopsis>
6520
<syntax>
6521
<parameter name="result-id" required="true" />
6522
</syntax>
6523
<description>
6524
<para>For queries which are marked as mode=multirow, this will clear
6525
any remaining rows of the specified resultset.</para>
6526
</description>
6527
</application>
6528
<function name="SQL_ESC" language="en_US">
6529
<synopsis>
6530
Escapes single ticks for use in SQL statements.
6531
</synopsis>
6532
<syntax>
6533
<parameter name="string" required="true" />
6534
</syntax>
6535
<description>
6536
<para>Used in SQL templates to escape data which may contain single ticks
6537
<literal>'</literal> which are otherwise used to delimit data.</para>
6538
<para>Example: SELECT foo FROM bar WHERE baz='${SQL_ESC(${ARG1})}'</para>
6539
</description>
6540
</function>
6541
<function name="RAND" language="en_US">
6542
<synopsis>
6543
Choose a random number in a range.
6544
</synopsis>
6545
<syntax>
6546
<parameter name="min" />
6547
<parameter name="max" />
6548
</syntax>
6549
<description>
6550
<para>Choose a random number between <replaceable>min</replaceable> and <replaceable>max</replaceable>.
6551
<replaceable>min</replaceable> defaults to <literal>0</literal>, if not specified, while <replaceable>max</replaceable> defaults
6552
to <literal>RAND_MAX</literal> (2147483647 on many systems).</para>
6553
<para>Example: Set(junky=${RAND(1,8)});
6554
Sets junky to a random number between 1 and 8, inclusive.</para>
6555
</description>
6556
</function>
6557
<function name="REALTIME" language="en_US">
6558
<synopsis>
6559
RealTime Read/Write Functions.
6560
</synopsis>
6561
<syntax>
6562
<parameter name="family" required="true" />
6563
<parameter name="fieldmatch" required="true" />
6564
<parameter name="value" />
6565
<parameter name="delim1|field">
6566
<para>Use <replaceable>delim1</replaceable> with <replaceable>delim2</replaceable> on
6567
read and <replaceable>field</replaceable> without <replaceable>delim2</replaceable> on
6568
write</para>
6569
<para>If we are reading and <replaceable>delim1</replaceable> is not specified, defaults
6570
to <literal>,</literal></para>
6571
</parameter>
6572
<parameter name="delim2">
6573
<para>Parameter only used when reading, if not specified defaults to <literal>=</literal></para>
6574
</parameter>
6575
</syntax>
6576
<description>
6577
<para>This function will read or write values from/to a RealTime repository.
6578
REALTIME(....) will read names/values from the repository, and
6579
REALTIME(....)= will write a new value/field to the repository. On a
6580
read, this function returns a delimited text string. The name/value
6581
pairs are delimited by <replaceable>delim1</replaceable>, and the name and value are delimited
6582
between each other with delim2.
6583
If there is no match, NULL will be returned by the function.
6584
On a write, this function will always return NULL.</para>
6585
</description>
6586
</function>
6587
<function name="REALTIME_STORE" language="en_US">
6588
<synopsis>
6589
RealTime Store Function.
6590
</synopsis>
6591
<syntax>
6592
<parameter name="family" required="true" />
6593
<parameter name="field1" required="true" />
6594
<parameter name="fieldN" required="true" multiple="true" />
6595
<parameter name="field30" required="true" />
6596
</syntax>
6597
<description>
6598
<para>This function will insert a new set of values into the RealTime repository.
6599
If RT engine provides an unique ID of the stored record, REALTIME_STORE(...)=..
6600
creates channel variable named RTSTOREID, which contains value of unique ID.
6601
Currently, a maximum of 30 field/value pairs is supported.</para>
6602
</description>
6603
</function>
6604
<function name="REALTIME_DESTROY" language="en_US">
6605
<synopsis>
6606
RealTime Destroy Function.
6607
</synopsis>
6608
<syntax>
6609
<parameter name="family" required="true" />
6610
<parameter name="fieldmatch" required="true" />
6611
<parameter name="value" />
6612
<parameter name="delim1" />
6613
<parameter name="delim2" />
6614
</syntax>
6615
<description>
6616
<para>This function acts in the same way as REALTIME(....) does, except that
6617
it destroys the matched record in the RT engine.</para>
6618
</description>
6619
</function>
6620
<function name="REALTIME_FIELD" language="en_US">
6621
<synopsis>
6622
RealTime query function.
6623
</synopsis>
6624
<syntax>
6625
<parameter name="family" required="true" />
6626
<parameter name="fieldmatch" required="true" />
6627
<parameter name="value" required="true" />
6628
<parameter name="fieldname" required="true" />
6629
</syntax>
6630
<description>
6631
<para>This function retrieves a single item, <replaceable>fieldname</replaceable>
6632
from the RT engine, where <replaceable>fieldmatch</replaceable> contains the value
6633
<replaceable>value</replaceable>. When written to, the REALTIME_FIELD() function
6634
performs identically to the REALTIME() function.</para>
6635
</description>
6636
</function>
6637
<function name="REALTIME_HASH" language="en_US">
6638
<synopsis>
6639
RealTime query function.
6640
</synopsis>
6641
<syntax>
6642
<parameter name="family" required="true" />
6643
<parameter name="fieldmatch" required="true" />
6644
<parameter name="value" required="true" />
6645
</syntax>
6646
<description>
6647
<para>This function retrieves a single record from the RT engine, where
6648
<replaceable>fieldmatch</replaceable> contains the value
6649
<replaceable>value</replaceable> and formats the output suitably, such that
6650
it can be assigned to the HASH() function. The HASH() function then provides
6651
a suitable method for retrieving each field value of the record.</para>
6652
</description>
6653
</function>
6654
<function name="SHA1" language="en_US">
6655
<synopsis>
6656
Computes a SHA1 digest.
6657
</synopsis>
6658
<syntax>
6659
<parameter name="data" required="true">
6660
<para>Input string</para>
6661
</parameter>
6662
</syntax>
6663
<description>
6664
<para>Generate a SHA1 digest via the SHA1 algorythm.</para>
6665
<para>Example: Set(sha1hash=${SHA1(junky)})</para>
6666
<para>Sets the asterisk variable sha1hash to the string <literal>60fa5675b9303eb62f99a9cd47f9f5837d18f9a0</literal>
6667
which is known as his hash</para>
6668
</description>
6669
</function>
6670
<function name="SHELL" language="en_US">
6671
<synopsis>
6672
Executes a command as if you were at a shell.
6673
</synopsis>
6674
<syntax>
6675
<parameter name="command" required="true">
6676
<para>This is the argument to the function, the command you want to pass to the shell.</para>
6677
</parameter>
6678
</syntax>
6679
<description>
6680
<para>Returns the value from a system command</para>
6681
<para>Example: <literal>Set(foo=${SHELL(echo \bar\)})</literal></para>
6682
<note><para>When using the SHELL() dialplan function, your \SHELL\ is /bin/sh,
6683
which may differ as to the underlying shell, depending upon your production
6684
platform. Also keep in mind that if you are using a common path, you should
6685
be mindful of race conditions that could result from two calls running
6686
SHELL() simultaneously.</para></note>
6687
</description>
6688
6689
</function>
6690
<function name="AGC" language="en_US">
6691
<synopsis>
6692
Apply automatic gain control to audio on a channel.
6693
</synopsis>
6694
<syntax>
6695
<parameter name="channeldirection" required="true">
6696
<para>This can be either <literal>rx</literal> or <literal>tx</literal></para>
6697
</parameter>
6698
</syntax>
6699
<description>
6700
<para>The AGC function will apply automatic gain control to the audio on the
6701
channel that it is executed on. Using <literal>rx</literal> for audio received
6702
and <literal>tx</literal> for audio transmitted to the channel. When using this
6703
function you set a target audio level. It is primarily intended for use with
6704
analog lines, but could be useful for other channels as well. The target volume
6705
is set with a number between <literal>1-32768</literal>. The larger the number
6706
the louder (more gain) the channel will receive.</para>
6707
<para>Examples:</para>
6708
<para>exten => 1,1,Set(AGC(rx)=8000)</para>
6709
<para>exten => 1,2,Set(AGC(tx)=off)</para>
6710
</description>
6711
</function>
6712
<function name="DENOISE" language="en_US">
6713
<synopsis>
6714
Apply noise reduction to audio on a channel.
6715
</synopsis>
6716
<syntax>
6717
<parameter name="channeldirection" required="true">
6718
<para>This can be either <literal>rx</literal> or <literal>tx</literal>
6719
the values that can be set to this are either <literal>on</literal> and
6720
<literal>off</literal></para>
6721
</parameter>
6722
</syntax>
6723
<description>
6724
<para>The DENOISE function will apply noise reduction to audio on the channel
6725
that it is executed on. It is very useful for noisy analog lines, especially
6726
when adjusting gains or using AGC. Use <literal>rx</literal> for audio received from the channel
6727
and <literal>tx</literal> to apply the filter to the audio being sent to the channel.</para>
6728
<para>Examples:</para>
6729
<para>exten => 1,1,Set(DENOISE(rx)=on)</para>
6730
<para>exten => 1,2,Set(DENOISE(tx)=off)</para>
6731
</description>
6732
</function>
6733
<function name="SPRINTF" language="en_US">
6734
<synopsis>
6735
Format a variable according to a format string.
6736
</synopsis>
6737
<syntax>
6738
<parameter name="format" required="true" />
6739
<parameter name="arg1" required="true" />
6740
<parameter name="arg2" multiple="true" />
6741
<parameter name="argN" />
6742
</syntax>
6743
<description>
6744
<para>Parses the format string specified and returns a string matching
6745
that format. Supports most options found in <emphasis>sprintf(3)</emphasis>.
6746
Returns a shortened string if a format specifier is not recognized.</para>
6747
</description>
6748
<see-also>
6749
<ref type="manpage">sprintf(3)</ref>
6750
</see-also>
6751
</function>
6752
<function name="FIELDQTY" language="en_US">
6753
<synopsis>
6754
Count the fields with an arbitrary delimiter
6755
</synopsis>
6756
<syntax>
6757
<parameter name="varname" required="true" />
6758
<parameter name="delim" required="true" />
6759
</syntax>
6760
<description>
6761
<para>The delimiter may be specified as a special or extended ASCII character, by encoding it. The characters
6762
<literal>\n</literal>, <literal>\r</literal>, and <literal>\t</literal> are all recognized as the newline,
6763
carriage return, and tab characters, respectively. Also, octal and hexadecimal specifications are recognized
6764
by the patterns <literal>\0nnn</literal> and <literal>\xHH</literal>, respectively. For example, if you wanted
6765
to encode a comma as the delimiter, you could use either <literal>\054</literal> or <literal>\x2C</literal>.</para>
6766
<para>Example: If ${example} contains <literal>ex-amp-le</literal>, then ${FIELDQTY(example,-)} returns 3.</para>
6767
</description>
6768
</function>
6769
<function name="LISTFILTER" language="en_US">
6770
<synopsis>Remove an item from a list, by name.</synopsis>
6771
<syntax>
6772
<parameter name="varname" required="true" />
6773
<parameter name="delim" required="true" default="," />
6774
<parameter name="value" required="true" />
6775
</syntax>
6776
<description>
6777
<para>Remove <replaceable>value</replaceable> from the list contained in the <replaceable>varname</replaceable>
6778
variable, where the list delimiter is specified by the <replaceable>delim</replaceable> parameter. This is
6779
very useful for removing a single channel name from a list of channels, for example.</para>
6780
</description>
6781
</function>
6782
<function name="FILTER" language="en_US">
6783
<synopsis>
6784
Filter the string to include only the allowed characters
6785
</synopsis>
6786
<syntax>
6787
<parameter name="allowed-chars" required="true" />
6788
<parameter name="string" required="true" />
6789
</syntax>
6790
<description>
6791
<para>Permits all characters listed in <replaceable>allowed-chars</replaceable>,
6792
filtering all others outs. In addition to literally listing the characters,
6793
you may also use ranges of characters (delimited by a <literal>-</literal></para>
6794
<para>Hexadecimal characters started with a <literal>\x</literal>(i.e. \x20)</para>
6795
<para>Octal characters started with a <literal>\0</literal> (i.e. \040)</para>
6796
<para>Also <literal>\t</literal>,<literal>\n</literal> and <literal>\r</literal> are recognized.</para>
6797
<note><para>If you want the <literal>-</literal> character it needs to be prefixed with a
6798
<literal>\</literal></para></note>
6799
</description>
6800
</function>
6801
<function name="REGEX" language="en_US">
6802
<synopsis>
6803
Check string against a regular expression.
6804
</synopsis>
6805
<syntax argsep=" ">
6806
<parameter name=""regular expression"" required="true" />
6807
<parameter name="string" required="true" />
6808
</syntax>
6809
<description>
6810
<para>Return <literal>1</literal> on regular expression match or <literal>0</literal> otherwise</para>
6811
<para>Please note that the space following the double quotes separating the
6812
regex from the data is optional and if present, is skipped. If a space is
6813
desired at the beginning of the data, then put two spaces there; the second
6814
will not be skipped.</para>
6815
</description>
6816
</function>
6817
<application name="ClearHash" language="en_US">
6818
<synopsis>
6819
Clear the keys from a specified hashname.
6820
</synopsis>
6821
<syntax>
6822
<parameter name="hashname" required="true" />
6823
</syntax>
6824
<description>
6825
<para>Clears all keys out of the specified <replaceable>hashname</replaceable>.</para>
6826
</description>
6827
</application>
6828
<function name="HASH" language="en_US">
6829
<synopsis>
6830
Implementation of a dialplan associative array
6831
</synopsis>
6832
<syntax>
6833
<parameter name="hashname" required="true" />
6834
<parameter name="hashkey" />
6835
</syntax>
6836
<description>
6837
<para>In two arguments mode, gets and sets values to corresponding keys within
6838
a named associative array. The single-argument mode will only work when assigned
6839
to from a function defined by func_odbc</para>
6840
</description>
6841
</function>
6842
<function name="HASHKEYS" language="en_US">
6843
<synopsis>
6844
Retrieve the keys of the HASH() function.
6845
</synopsis>
6846
<syntax>
6847
<parameter name="hashname" required="true" />
6848
</syntax>
6849
<description>
6850
<para>Returns a comma-delimited list of the current keys of the associative array
6851
defined by the HASH() function. Note that if you iterate over the keys of
6852
the result, adding keys during iteration will cause the result of the HASHKEYS()
6853
function to change.</para>
6854
</description>
6855
</function>
6856
<function name="KEYPADHASH" language="en_US">
6857
<synopsis>
6858
Hash the letters in string into equivalent keypad numbers.
6859
</synopsis>
6860
<syntax>
6861
<parameter name="string" required="true" />
6862
</syntax>
6863
<description>
6864
<para>Example: ${KEYPADHASH(Les)} returns "537"</para>
6865
</description>
6866
</function>
6867
<function name="ARRAY" language="en_US">
6868
<synopsis>
6869
Allows setting multiple variables at once.
6870
</synopsis>
6871
<syntax>
6872
<parameter name="var1" required="true" />
6873
<parameter name="var2" required="false" multiple="true" />
6874
<parameter name="varN" required="false" />
6875
</syntax>
6876
<description>
6877
<para>The comma-delimited list passed as a value to which the function is set will
6878
be interpreted as a set of values to which the comma-delimited list of
6879
variable names in the argument should be set.</para>
6880
<para>Example: Set(ARRAY(var1,var2)=1,2) will set var1 to 1 and var2 to 2</para>
6881
</description>
6882
</function>
6883
<function name="STRPTIME" language="en_US">
6884
<synopsis>
6885
Returns the epoch of the arbitrary date/time string structured as described by the format.
6886
</synopsis>
6887
<syntax>
6888
<parameter name="datetime" required="true" />
6889
<parameter name="timezone" required="true" />
6890
<parameter name="format" required="true" />
6891
</syntax>
6892
<description>
6893
<para>This is useful for converting a date into <literal>EPOCH</literal> time,
6894
possibly to pass to an application like SayUnixTime or to calculate the difference
6895
between the two date strings</para>
6896
<para>Example: ${STRPTIME(2006-03-01 07:30:35,America/Chicago,%Y-%m-%d %H:%M:%S)} returns 1141219835</para>
6897
</description>
6898
</function>
6899
<function name="STRFTIME" language="en_US">
6900
<synopsis>
6901
Returns the current date/time in the specified format.
6902
</synopsis>
6903
<syntax>
6904
<parameter name="epoch" />
6905
<parameter name="timezone" />
6906
<parameter name="format" />
6907
</syntax>
6908
<description>
6909
<para>STRFTIME supports all of the same formats as the underlying C function
6910
<emphasis>strftime(3)</emphasis>.
6911
It also supports the following format: <literal>%[n]q</literal> - fractions of a second,
6912
with leading zeros.</para>
6913
<para>Example: <literal>%3q</literal> will give milliseconds and <literal>%1q</literal>
6914
will give tenths of a second. The default is set at milliseconds (n=3).
6915
The common case is to use it in combination with %S, as in <literal>%S.%3q</literal>.</para>
6916
</description>
6917
<see-also>
6918
<ref type="manpage">strftime(3)</ref>
6919
</see-also>
6920
</function>
6921
<function name="EVAL" language="en_US">
6922
<synopsis>
6923
Evaluate stored variables
6924
</synopsis>
6925
<syntax>
6926
<parameter name="variable" required="true" />
6927
</syntax>
6928
<description>
6929
<para>Using EVAL basically causes a string to be evaluated twice.
6930
When a variable or expression is in the dialplan, it will be
6931
evaluated at runtime. However, if the results of the evaluation
6932
is in fact another variable or expression, using EVAL will have it
6933
evaluated a second time.</para>
6934
<para>Example: If the <variable>MYVAR</variable> contains
6935
<variable>OTHERVAR</variable>, then the result of ${EVAL(
6936
<variable>MYVAR</variable>)} in the dialplan will be the
6937
contents of <variable>OTHERVAR</variable>. Normally just
6938
putting <variable>MYVAR</variable> in the dialplan the result
6939
would be <variable>OTHERVAR</variable>.</para>
6940
</description>
6941
</function>
6942
<function name="TOUPPER" language="en_US">
6943
<synopsis>
6944
Convert string to all uppercase letters.
6945
</synopsis>
6946
<syntax>
6947
<parameter name="string" required="true" />
6948
</syntax>
6949
<description>
6950
<para>Example: ${TOUPPER(Example)} returns "EXAMPLE"</para>
6951
</description>
6952
</function>
6953
<function name="TOLOWER" language="en_US">
6954
<synopsis>
6955
Convert string to all lowercase letters.
6956
</synopsis>
6957
<syntax>
6958
<parameter name="string" required="true" />
6959
</syntax>
6960
<description>
6961
<para>Example: ${TOLOWER(Example)} returns "example"</para>
6962
</description>
6963
</function>
6964
<function name="LEN" language="en_US">
6965
<synopsis>
6966
Return the length of the string given.
6967
</synopsis>
6968
<syntax>
6969
<parameter name="string" required="true" />
6970
</syntax>
6971
<description>
6972
<para>Example: ${LEN(example)} returns 7</para>
6973
</description>
6974
</function>
6975
<function name="QUOTE" language="en_US">
6976
<synopsis>
6977
Quotes a given string, escaping embedded quotes as necessary
6978
</synopsis>
6979
<syntax>
6980
<parameter name="string" required="true" />
6981
</syntax>
6982
<description>
6983
<para>Example: ${QUOTE(ab"c"de)} will return "abcde"</para>
6984
</description>
6985
</function>
6986
<function name="TIMEOUT" language="en_US">
6987
<synopsis>
6988
Gets or sets timeouts on the channel. Timeout values are in seconds.
6989
</synopsis>
6990
<syntax>
6991
<parameter name="timeouttype" required="true">
6992
<para>The timeout that will be manipulated. The possible timeout types
6993
are: <literal>absolute</literal>, <literal>digit</literal> or
6994
<literal>response</literal></para>
6995
</parameter>
6996
</syntax>
6997
<description>
6998
<para>The timeouts that can be manipulated are:</para>
6999
<para><literal>absolute</literal>: The absolute maximum amount of time permitted for a call.
7000
Setting of 0 disables the timeout.</para>
7001
<para><literal>digit</literal>: The maximum amount of time permitted between digits when the
7002
user is typing in an extension. When this timeout expires,
7003
after the user has started to type in an extension, the
7004
extension will be considered complete, and will be
7005
interpreted. Note that if an extension typed in is valid,
7006
it will not have to timeout to be tested, so typically at
7007
the expiry of this timeout, the extension will be considered
7008
invalid (and thus control would be passed to the <literal>i</literal>
7009
extension, or if it doesn't exist the call would be
7010
terminated). The default timeout is 5 seconds.</para>
7011
<para><literal>response</literal>: The maximum amount of time permitted after falling through a
7012
series of priorities for a channel in which the user may
7013
begin typing an extension. If the user does not type an
7014
extension in this amount of time, control will pass to the
7015
<literal>t</literal> extension if it exists, and if not the call would be
7016
terminated. The default timeout is 10 seconds.</para>
7017
</description>
7018
</function>
7019
<function name="URIENCODE" language="en_US">
7020
<synopsis>
7021
Encodes a string to URI-safe encoding according to RFC 2396.
7022
</synopsis>
7023
<syntax>
7024
<parameter name="data" required="true">
7025
<para>Input string to be encoded.</para>
7026
</parameter>
7027
</syntax>
7028
<description>
7029
<para>Returns the encoded string defined in <replaceable>data</replaceable>.</para>
7030
</description>
7031
</function>
7032
<function name="URIDECODE" language="en_US">
7033
<synopsis>
7034
Decodes a URI-encoded string according to RFC 2396.
7035
</synopsis>
7036
<syntax>
7037
<parameter name="data" required="true">
7038
<para>Input string to be decoded.</para>
7039
</parameter>
7040
</syntax>
7041
<description>
7042
<para>Returns the decoded URI-encoded <replaceable>data</replaceable> string.</para>
7043
</description>
7044
</function>
7045
<function name="VERSION" language="en_US">
7046
<synopsis>
7047
Return the Version info for this Asterisk.
7048
</synopsis>
7049
<syntax>
7050
<parameter name="info">
7051
<para>The possible values are:</para>
7052
<enumlist>
7053
<enum name="ASTERISK_VERSION_NUM">
7054
<para>A string of digits is returned (right now fixed at 999999).</para>
7055
</enum>
7056
<enum name="BUILD_USER">
7057
<para>The string representing the user's name whose account
7058
was used to configure Asterisk, is returned.</para>
7059
</enum>
7060
<enum name="BUILD_HOSTNAME">
7061
<para>The string representing the name of the host on which Asterisk was configured, is returned.</para>
7062
</enum>
7063
<enum name="BUILD_MACHINE">
7064
<para>The string representing the type of machine on which Asterisk was configured, is returned.</para>
7065
</enum>
7066
<enum name="BUILD_OS">
7067
<para>The string representing the OS of the machine on which Asterisk was configured, is returned.</para>
7068
</enum>
7069
<enum name="BUILD_DATE">
7070
<para>The string representing the date on which Asterisk was configured, is returned.</para>
7071
</enum>
7072
<enum name="BUILD_KERNEL">
7073
<para>The string representing the kernel version of the machine on which Asterisk
7074
was configured, is returned.</para>
7075
</enum>
7076
</enumlist>
7077
</parameter>
7078
</syntax>
7079
<description>
7080
<para>If there are no arguments, return the version of Asterisk in this format: SVN-branch-1.4-r44830M</para>
7081
<para>Example: Set(junky=${VERSION()};</para>
7082
<para>Sets junky to the string <literal>SVN-branch-1.6-r74830M</literal>, or possibly, <literal>SVN-trunk-r45126M</literal>.</para>
7083
</description>
7084
</function>
7085
<function name="VMCOUNT" language="en_US">
7086
<synopsis>
7087
Count the voicemails in a specified mailbox.
7088
</synopsis>
7089
<syntax>
7090
<parameter name="vmbox" required="true" argsep="@">
7091
<argument name="vmbox" required="true" />
7092
<argument name="context" required="false">
7093
<para>If not specified, defaults to <literal>default</literal>.</para>
7094
</argument>
7095
</parameter>
7096
<parameter name="folder" required="false">
7097
<para>If not specified, defaults to <literal>INBOX</literal></para>
7098
</parameter>
7099
</syntax>
7100
<description>
7101
<para>Count the number of voicemails in a specified mailbox, you could also specify
7102
the <replaceable>context</replaceable> and the mailbox <replaceable>folder</replaceable>.</para>
7103
<para>Example: <literal>exten => s,1,Set(foo=${VMCOUNT(125)})</literal></para>
7104
</description>
7105
</function>
7106
<function name="VOLUME" language="en_US">
7107
<synopsis>
7108
Set the TX or RX volume of a channel.
7109
</synopsis>
7110
<syntax>
7111
<parameter name="direction" required="true">
7112
<para>Must be <literal>TX</literal> or <literal>RX</literal>.</para>
7113
</parameter>
7114
</syntax>
7115
<description>
7116
<para>The VOLUME function can be used to increase or decrease the <literal>tx</literal> or
7117
<literal>rx</literal> gain of any channel.</para>
7118
<para>For example:</para>
7119
<para>Set(VOLUME(TX)=3)</para>
7120
<para>Set(VOLUME(RX)=2)</para>
7121
</description>
7122
</function>
7123
<application name="Bridge" language="en_US">
7124
<synopsis>
7125
Bridge two channels.
7126
</synopsis>
7127
<syntax>
7128
<parameter name="channel" required="true">
7129
<para>The current channel is bridged to the specified <replaceable>channel</replaceable>.</para>
7130
</parameter>
7131
<parameter name="options">
7132
<optionlist>
7133
<option name="p">
7134
<para>Play a courtesy tone to <replaceable>channel</replaceable>.</para>
7135
</option>
7136
</optionlist>
7137
</parameter>
7138
</syntax>
7139
<description>
7140
<para>Allows the ability to bridge two channels via the dialplan.</para>
7141
<para>This application sets the following channel variable upon completion:</para>
7142
<variablelist>
7143
<variable name="BRIDGERESULT">
7144
<para>The result of the bridge attempt as a text string.</para>
7145
<value name="SUCCESS" />
7146
<value name="FAILURE" />
7147
<value name="LOOP" />
7148
<value name="NONEXISTENT" />
7149
<value name="INCOMPATIBLE" />
7150
</variable>
7151
</variablelist>
7152
</description>
7153
</application>
7154
<application name="ParkedCall" language="en_US">
7155
<synopsis>
7156
Answer a parked call.
7157
</synopsis>
7158
<syntax>
7159
<parameter name="exten" required="true" />
7160
</syntax>
7161
<description>
7162
<para>Used to connect to a parked call. This application is always
7163
registered internally and does not need to be explicitly added
7164
into the dialplan, although you should include the <literal>parkedcalls</literal>
7165
context. If no extension is provided, then the first available
7166
parked call will be acquired.</para>
7167
</description>
7168
<see-also>
7169
<ref type="application">Park</ref>
7170
<ref type="application">ParkAndAnnounce</ref>
7171
</see-also>
7172
</application>
7173
<application name="Park" language="en_US">
7174
<synopsis>
7175
Park yourself.
7176
</synopsis>
7177
<syntax>
7178
<parameter name="timeout">
7179
<para>A custom parking timeout for this parked call.</para>
7180
</parameter>
7181
<parameter name="return_context">
7182
<para>The context to return the call to after it times out.</para>
7183
</parameter>
7184
<parameter name="return_exten">
7185
<para>The extension to return the call to after it times out.</para>
7186
</parameter>
7187
<parameter name="return_priority">
7188
<para>The priority to return the call to after it times out.</para>
7189
</parameter>
7190
<parameter name="options">
7191
<para>A list of options for this parked call.</para>
7192
<optionlist>
7193
<option name="r">
7194
<para>Send ringing instead of MOH to the parked call.</para>
7195
</option>
7196
<option name="R">
7197
<para>Randomize the selection of a parking space.</para>
7198
</option>
7199
<option name="s">
7200
<para>Silence announcement of the parking space number.</para>
7201
</option>
7202
</optionlist>
7203
</parameter>
7204
</syntax>
7205
<description>
7206
<para>Used to park yourself (typically in combination with a supervised
7207
transfer to know the parking space). This application is always
7208
registered internally and does not need to be explicitly added
7209
into the dialplan, although you should include the <literal>parkedcalls</literal>
7210
context (or the context specified in <filename>features.conf</filename>).</para>
7211
<para>If you set the <variable>PARKINGEXTEN</variable> variable to an extension in your
7212
parking context, Park() will park the call on that extension, unless
7213
it already exists. In that case, execution will continue at next priority.</para>
7214
</description>
7215
<see-also>
7216
<ref type="application">ParkAndAnnounce</ref>
7217
<ref type="application">ParkedCall</ref>
7218
</see-also>
7219
</application>
7220
<application name="Answer" language="en_US">
7221
<synopsis>
7222
Answer a channel if ringing.
7223
</synopsis>
7224
<syntax>
7225
<parameter name="delay">
7226
<para>Asterisk will wait this number of milliseconds before returning to
7227
the dialplan after answering the call.</para>
7228
</parameter>
7229
<parameter name="nocdr">
7230
<para>Asterisk will send an answer signal to the calling phone, but will not
7231
set the disposition or answer time in the CDR for this call.</para>
7232
</parameter>
7233
</syntax>
7234
<description>
7235
<para>If the call has not been answered, this application will
7236
answer it. Otherwise, it has no effect on the call.</para>
7237
</description>
7238
<see-also>
7239
<ref type="application">Hangup</ref>
7240
</see-also>
7241
</application>
7242
<application name="BackGround" language="en_US">
7243
<synopsis>
7244
Play an audio file while waiting for digits of an extension to go to.
7245
</synopsis>
7246
<syntax>
7247
<parameter name="filenames" required="true" argsep="&">
7248
<argument name="filename1" required="true" />
7249
<argument name="filename2" multiple="true" />
7250
</parameter>
7251
<parameter name="options">
7252
<optionlist>
7253
<option name="s">
7254
<para>Causes the playback of the message to be skipped
7255
if the channel is not in the <literal>up</literal> state (i.e. it
7256
hasn't been answered yet). If this happens, the
7257
application will return immediately.</para>
7258
</option>
7259
<option name="n">
7260
<para>Don't answer the channel before playing the files.</para>
7261
</option>
7262
<option name="m">
7263
<para>Only break if a digit hit matches a one digit
7264
extension in the destination context.</para>
7265
</option>
7266
</optionlist>
7267
</parameter>
7268
<parameter name="langoverride">
7269
<para>Explicitly specifies which language to attempt to use for the requested sound files.</para>
7270
</parameter>
7271
<parameter name="context">
7272
<para>This is the dialplan context that this application will use when exiting
7273
to a dialed extension.</para>
7274
</parameter>
7275
</syntax>
7276
<description>
7277
<para>This application will play the given list of files <emphasis>(do not put extension)</emphasis>
7278
while waiting for an extension to be dialed by the calling channel. To continue waiting
7279
for digits after this application has finished playing files, the <literal>WaitExten</literal>
7280
application should be used.</para>
7281
<para>If one of the requested sound files does not exist, call processing will be terminated.</para>
7282
<para>This application sets the following channel variable upon completion:</para>
7283
<variablelist>
7284
<variable name="BACKGROUNDSTATUS">
7285
<para>The status of the background attempt as a text string.</para>
7286
<value name="SUCCESS" />
7287
<value name="FAILED" />
7288
</variable>
7289
</variablelist>
7290
</description>
7291
<see-also>
7292
<ref type="application">ControlPlayback</ref>
7293
<ref type="application">WaitExten</ref>
7294
<ref type="application">BackgroundDetect</ref>
7295
<ref type="function">TIMEOUT</ref>
7296
</see-also>
7297
</application>
7298
<application name="Busy" language="en_US">
7299
<synopsis>
7300
Indicate the Busy condition.
7301
</synopsis>
7302
<syntax>
7303
<parameter name="timeout">
7304
<para>If specified, the calling channel will be hung up after the specified number of seconds.
7305
Otherwise, this application will wait until the calling channel hangs up.</para>
7306
</parameter>
7307
</syntax>
7308
<description>
7309
<para>This application will indicate the busy condition to the calling channel.</para>
7310
</description>
7311
<see-also>
7312
<ref type="application">Congestion</ref>
7313
<ref type="application">Progess</ref>
7314
<ref type="application">Playtones</ref>
7315
<ref type="application">Hangup</ref>
7316
</see-also>
7317
</application>
7318
<application name="Congestion" language="en_US">
7319
<synopsis>
7320
Indicate the Congestion condition.
7321
</synopsis>
7322
<syntax>
7323
<parameter name="timeout">
7324
<para>If specified, the calling channel will be hung up after the specified number of seconds.
7325
Otherwise, this application will wait until the calling channel hangs up.</para>
7326
</parameter>
7327
</syntax>
7328
<description>
7329
<para>This application will indicate the congestion condition to the calling channel.</para>
7330
</description>
7331
<see-also>
7332
<ref type="application">Busy</ref>
7333
<ref type="application">Progess</ref>
7334
<ref type="application">Playtones</ref>
7335
<ref type="application">Hangup</ref>
7336
</see-also>
7337
</application>
7338
<application name="ExecIfTime" language="en_US">
7339
<synopsis>
7340
Conditional application execution based on the current time.
7341
</synopsis>
7342
<syntax argsep="?">
7343
<parameter name="day_condition" required="true">
7344
<argument name="times" required="true" />
7345
<argument name="weekdays" required="true" />
7346
<argument name="mdays" required="true" />
7347
<argument name="months" required="true" />
7348
<argument name="timezone" required="false" />
7349
</parameter>
7350
<parameter name="appname" required="true" hasparams="optional">
7351
<argument name="appargs" required="true" />
7352
</parameter>
7353
</syntax>
7354
<description>
7355
<para>This application will execute the specified dialplan application, with optional
7356
arguments, if the current time matches the given time specification.</para>
7357
</description>
7358
<see-also>
7359
<ref type="application">Exec</ref>
7360
<ref type="application">TryExec</ref>
7361
</see-also>
7362
</application>
7363
<application name="Goto" language="en_US">
7364
<synopsis>
7365
Jump to a particular priority, extension, or context.
7366
</synopsis>
7367
<syntax>
7368
<parameter name="context" />
7369
<parameter name="extensions" />
7370
<parameter name="priority" required="true" />
7371
</syntax>
7372
<description>
7373
<para>This application will set the current context, extension, and priority in the channel structure.
7374
After it completes, the pbx engine will continue dialplan execution at the specified location.
7375
If no specific <replaceable>extension</replaceable>, or <replaceable>extension</replaceable> and
7376
<replaceable>context</replaceable>, are specified, then this application will
7377
just set the specified <replaceable>priority</replaceable> of the current extension.</para>
7378
<para>At least a <replaceable>priority</replaceable> is required as an argument, or the goto will
7379
return a <literal>-1</literal>, and the channel and call will be terminated.</para>
7380
<para>If the location that is put into the channel information is bogus, and asterisk cannot
7381
find that location in the dialplan, then the execution engine will try to find and execute the code in
7382
the <literal>i</literal> (invalid) extension in the current context. If that does not exist, it will try to execute the
7383
<literal>h</literal> extension. If either or neither the <literal>h</literal> or <literal>i</literal> extensions
7384
have been defined, the channel is hung up, and the execution of instructions on the channel is terminated.
7385
What this means is that, for example, you specify a context that does not exist, then
7386
it will not be possible to find the <literal>h</literal> or <literal>i</literal> extensions,
7387
and the call will terminate!</para>
7388
</description>
7389
<see-also>
7390
<ref type="application">GotoIf</ref>
7391
<ref type="application">GotoIfTime</ref>
7392
<ref type="application">Gosub</ref>
7393
<ref type="application">Macro</ref>
7394
</see-also>
7395
</application>
7396
<application name="GotoIf" language="en_US">
7397
<synopsis>
7398
Conditional goto.
7399
</synopsis>
7400
<syntax argsep="?">
7401
<parameter name="condition" required="true" />
7402
<parameter name="destination" required="true" argsep=":">
7403
<argument name="labeliftrue">
7404
<para>Continue at <replaceable>labeliftrue</replaceable> if the condition is true.</para>
7405
</argument>
7406
<argument name="labeliffalse">
7407
<para>Continue at <replaceable>labeliffalse</replaceable> if the condition is false.</para>
7408
</argument>
7409
</parameter>
7410
</syntax>
7411
<description>
7412
<para>This application will set the current context, extension, and priority in the channel structure
7413
based on the evaluation of the given condition. After this application completes, the
7414
pbx engine will continue dialplan execution at the specified location in the dialplan.
7415
The labels are specified with the same syntax as used within the Goto application.
7416
If the label chosen by the condition is omitted, no jump is performed, and the execution passes to the
7417
next instruction. If the target location is bogus, and does not exist, the execution engine will try
7418
to find and execute the code in the <literal>i</literal> (invalid) extension in the current context.
7419
If that does not exist, it will try to execute the <literal>h</literal> extension.
7420
If either or neither the <literal>h</literal> or <literal>i</literal> extensions have been defined,
7421
the channel is hung up, and the execution of instructions on the channel is terminated.
7422
Remember that this command can set the current context, and if the context specified
7423
does not exist, then it will not be able to find any 'h' or 'i' extensions there, and
7424
the channel and call will both be terminated!.</para>
7425
</description>
7426
<see-also>
7427
<ref type="application">Goto</ref>
7428
<ref type="application">GotoIfTime</ref>
7429
<ref type="application">GosubIf</ref>
7430
<ref type="application">MacroIf</ref>
7431
</see-also>
7432
</application>
7433
<application name="GotoIfTime" language="en_US">
7434
<synopsis>
7435
Conditional Goto based on the current time.
7436
</synopsis>
7437
<syntax argsep="?">
7438
<parameter name="condition" required="true">
7439
<argument name="times" required="true" />
7440
<argument name="weekdays" required="true" />
7441
<argument name="mdays" required="true" />
7442
<argument name="months" required="true" />
7443
<argument name="timezone" required="false" />
7444
</parameter>
7445
<parameter name="destination" required="true" argsep=":">
7446
<argument name="labeliftrue" />
7447
<argument name="labeliffalse" />
7448
</parameter>
7449
</syntax>
7450
<description>
7451
<para>This application will set the context, extension, and priority in the channel structure
7452
based on the evaluation of the given time specification. After this application completes,
7453
the pbx engine will continue dialplan execution at the specified location in the dialplan.
7454
If the current time is within the given time specification, the channel will continue at
7455
<replaceable>labeliftrue</replaceable>. Otherwise the channel will continue at <replaceable>labeliffalse</replaceable>.
7456
If the label chosen by the condition is omitted, no jump is performed, and execution passes to the next
7457
instruction. If the target jump location is bogus, the same actions would be taken as for <literal>Goto</literal>.
7458
Further information on the time specification can be found in examples
7459
illustrating how to do time-based context includes in the dialplan.</para>
7460
</description>
7461
<see-also>
7462
<ref type="application">GotoIf</ref>
7463
<ref type="function">IFTIME</ref>
7464
</see-also>
7465
</application>
7466
<application name="ImportVar" language="en_US">
7467
<synopsis>
7468
Import a variable from a channel into a new variable.
7469
</synopsis>
7470
<syntax argsep="=">
7471
<parameter name="newvar" required="true" />
7472
<parameter name="vardata" required="true">
7473
<argument name="channelname" required="true" />
7474
<argument name="variable" required="true" />
7475
</parameter>
7476
</syntax>
7477
<description>
7478
<para>This application imports a <replaceable>variable</replaceable> from the specified
7479
<replaceable>channel</replaceable> (as opposed to the current one) and stores it as a variable
7480
(<replaceable>newvar</replaceable>) in the current channel (the channel that is calling this
7481
application). Variables created by this application have the same inheritance properties as those
7482
created with the <literal>Set</literal> application.</para>
7483
</description>
7484
<see-also>
7485
<ref type="application">Set</ref>
7486
</see-also>
7487
</application>
7488
<application name="Hangup" language="en_US">
7489
<synopsis>
7490
Hang up the calling channel.
7491
</synopsis>
7492
<syntax>
7493
<parameter name="causecode">
7494
<para>If a <replaceable>causecode</replaceable> is given the channel's
7495
hangup cause will be set to the given value.</para>
7496
</parameter>
7497
</syntax>
7498
<description>
7499
<para>This application will hang up the calling channel.</para>
7500
</description>
7501
<see-also>
7502
<ref type="application">Answer</ref>
7503
<ref type="application">Busy</ref>
7504
<ref type="application">Congestion</ref>
7505
</see-also>
7506
</application>
7507
<application name="Incomplete" language="en_US">
7508
<synopsis>
7509
Returns AST_PBX_INCOMPLETE value.
7510
</synopsis>
7511
<syntax>
7512
<parameter name="n">
7513
<para>If specified, then Incomplete will not attempt to answer the channel first.</para>
7514
<note><para>Most channel types need to be in Answer state in order to receive DTMF.</para></note>
7515
</parameter>
7516
</syntax>
7517
<description>
7518
<para>Signals the PBX routines that the previous matched extension is incomplete
7519
and that further input should be allowed before matching can be considered
7520
to be complete. Can be used within a pattern match when certain criteria warrants
7521
a longer match.</para>
7522
</description>
7523
</application>
7524
<application name="NoOp" language="en_US">
7525
<synopsis>
7526
Do Nothing (No Operation).
7527
</synopsis>
7528
<syntax>
7529
<parameter name="text">
7530
<para>Any text provided can be viewed at the Asterisk CLI.</para>
7531
</parameter>
7532
</syntax>
7533
<description>
7534
<para>This application does nothing. However, it is useful for debugging purposes.</para>
7535
<para>This method can be used to see the evaluations of variables or functions without having any effect.</para>
7536
</description>
7537
<see-also>
7538
<ref type="application">Verbose</ref>
7539
<ref type="application">Log</ref>
7540
</see-also>
7541
</application>
7542
<application name="Proceeding" language="en_US">
7543
<synopsis>
7544
Indicate proceeding.
7545
</synopsis>
7546
<syntax />
7547
<description>
7548
<para>This application will request that a proceeding message be provided to the calling channel.</para>
7549
</description>
7550
</application>
7551
<application name="Progress" language="en_US">
7552
<synopsis>
7553
Indicate progress.
7554
</synopsis>
7555
<syntax />
7556
<description>
7557
<para>This application will request that in-band progress information be provided to the calling channel.</para>
7558
</description>
7559
<see-also>
7560
<ref type="application">Busy</ref>
7561
<ref type="application">Congestion</ref>
7562
<ref type="application">Ringing</ref>
7563
<ref type="application">Playtones</ref>
7564
</see-also>
7565
</application>
7566
<application name="RaiseException" language="en_US">
7567
<synopsis>
7568
Handle an exceptional condition.
7569
</synopsis>
7570
<syntax>
7571
<parameter name="reason" required="true" />
7572
</syntax>
7573
<description>
7574
<para>This application will jump to the <literal>e</literal> extension in the current context, setting the
7575
dialplan function EXCEPTION(). If the <literal>e</literal> extension does not exist, the call will hangup.</para>
7576
</description>
7577
<see-also>
7578
<ref type="function">Exception</ref>
7579
</see-also>
7580
</application>
7581
<application name="ResetCDR" language="en_US">
7582
<synopsis>
7583
Resets the Call Data Record.
7584
</synopsis>
7585
<syntax>
7586
<parameter name="options">
7587
<optionlist>
7588
<option name="w">
7589
<para>Store the current CDR record before resetting it.</para>
7590
</option>
7591
<option name="a">
7592
<para>Store any stacked records.</para>
7593
</option>
7594
<option name="v">
7595
<para>Save CDR variables.</para>
7596
</option>
7597
<option name="e">
7598
<para>Enable CDR only (negate effects of NoCDR).</para>
7599
</option>
7600
</optionlist>
7601
</parameter>
7602
</syntax>
7603
<description>
7604
<para>This application causes the Call Data Record to be reset.</para>
7605
</description>
7606
<see-also>
7607
<ref type="application">ForkCDR</ref>
7608
<ref type="application">NoCDR</ref>
7609
</see-also>
7610
</application>
7611
<application name="Ringing" language="en_US">
7612
<synopsis>
7613
Indicate ringing tone.
7614
</synopsis>
7615
<syntax />
7616
<description>
7617
<para>This application will request that the channel indicate a ringing tone to the user.</para>
7618
</description>
7619
<see-also>
7620
<ref type="application">Busy</ref>
7621
<ref type="application">Congestion</ref>
7622
<ref type="application">Progress</ref>
7623
<ref type="application">Playtones</ref>
7624
</see-also>
7625
</application>
7626
<application name="SayAlpha" language="en_US">
7627
<synopsis>
7628
Say Alpha.
7629
</synopsis>
7630
<syntax>
7631
<parameter name="string" required="true" />
7632
</syntax>
7633
<description>
7634
<para>This application will play the sounds that correspond to the letters of the
7635
given <replaceable>string</replaceable>.</para>
7636
</description>
7637
<see-also>
7638
<ref type="application">SayDigits</ref>
7639
<ref type="application">SayNumber</ref>
7640
<ref type="application">SayPhonetic</ref>
7641
<ref type="function">CHANNEL</ref>
7642
</see-also>
7643
</application>
7644
<application name="SayDigits" language="en_US">
7645
<synopsis>
7646
Say Digits.
7647
</synopsis>
7648
<syntax>
7649
<parameter name="digits" required="true" />
7650
</syntax>
7651
<description>
7652
<para>This application will play the sounds that correspond to the digits of
7653
the given number. This will use the language that is currently set for the channel.</para>
7654
</description>
7655
<see-also>
7656
<ref type="application">SayAlpha</ref>
7657
<ref type="application">SayNumber</ref>
7658
<ref type="application">SayPhonetic</ref>
7659
<ref type="function">CHANNEL</ref>
7660
</see-also>
7661
</application>
7662
<application name="SayNumber" language="en_US">
7663
<synopsis>
7664
Say Number.
7665
</synopsis>
7666
<syntax>
7667
<parameter name="digits" required="true" />
7668
<parameter name="gender" />
7669
</syntax>
7670
<description>
7671
<para>This application will play the sounds that correspond to the given <replaceable>digits</replaceable>.
7672
Optionally, a <replaceable>gender</replaceable> may be specified. This will use the language that is currently
7673
set for the channel. See the LANGUAGE() function for more information on setting the language for the channel.</para>
7674
</description>
7675
<see-also>
7676
<ref type="application">SayAlpha</ref>
7677
<ref type="application">SayDigits</ref>
7678
<ref type="application">SayPhonetic</ref>
7679
<ref type="function">CHANNEL</ref>
7680
</see-also>
7681
</application>
7682
<application name="SayPhonetic" language="en_US">
7683
<synopsis>
7684
Say Phonetic.
7685
</synopsis>
7686
<syntax>
7687
<parameter name="string" required="true" />
7688
</syntax>
7689
<description>
7690
<para>This application will play the sounds from the phonetic alphabet that correspond to the
7691
letters in the given <replaceable>string</replaceable>.</para>
7692
</description>
7693
<see-also>
7694
<ref type="application">SayAlpha</ref>
7695
<ref type="application">SayDigits</ref>
7696
<ref type="application">SayNumber</ref>
7697
</see-also>
7698
</application>
7699
<application name="Set" language="en_US">
7700
<synopsis>
7701
Set channel variable or function value.
7702
</synopsis>
7703
<syntax argsep="=">
7704
<parameter name="name" required="true" />
7705
<parameter name="value" required="true" />
7706
</syntax>
7707
<description>
7708
<para>This function can be used to set the value of channel variables or dialplan functions.
7709
When setting variables, if the variable name is prefixed with <literal>_</literal>,
7710
the variable will be inherited into channels created from the current channel.
7711
If the variable name is prefixed with <literal>__</literal>, the variable will be
7712
inherited into channels created from the current channel and all children channels.</para>
7713
<note><para>If (and only if), in <filename>/etc/asterisk/asterisk.conf</filename>, you have
7714
a <literal>[compat]</literal> category, and you have <literal>app_set = 1.6</literal> under that,then
7715
the behavior of this app changes, and does not strip surrounding quotes from the right hand side as
7716
it did previously in 1.4. The <literal>app_set = 1.6</literal> is only inserted if <literal>make samples</literal>
7717
is executed, or if users insert this by hand into the <filename>asterisk.conf</filename> file.
7718
The advantages of not stripping out quoting, and not caring about the separator characters (comma and vertical bar)
7719
were sufficient to make these changes in 1.6. Confusion about how many backslashes would be needed to properly
7720
protect separators and quotes in various database access strings has been greatly
7721
reduced by these changes.</para></note>
7722
</description>
7723
<see-also>
7724
<ref type="application">MSet</ref>
7725
<ref type="function">GLOBAL</ref>
7726
<ref type="function">SET</ref>
7727
<ref type="function">ENV</ref>
7728
</see-also>
7729
</application>
7730
<application name="MSet" language="en_US">
7731
<synopsis>
7732
Set channel variable(s) or function value(s).
7733
</synopsis>
7734
<syntax>
7735
<parameter name="set1" required="true" argsep="=">
7736
<argument name="name1" required="true" />
7737
<argument name="value1" required="true" />
7738
</parameter>
7739
<parameter name="set2" multiple="true" argsep="=">
7740
<argument name="name2" required="true" />
7741
<argument name="value2" required="true" />
7742
</parameter>
7743
</syntax>
7744
<description>
7745
<para>This function can be used to set the value of channel variables or dialplan functions.
7746
When setting variables, if the variable name is prefixed with <literal>_</literal>,
7747
the variable will be inherited into channels created from the current channel
7748
If the variable name is prefixed with <literal>__</literal>, the variable will be
7749
inherited into channels created from the current channel and all children channels.
7750
MSet behaves in a similar fashion to the way Set worked in 1.2/1.4 and is thus
7751
prone to doing things that you may not expect. For example, it strips surrounding
7752
double-quotes from the right-hand side (value). If you need to put a separator
7753
character (comma or vert-bar), you will need to escape them by inserting a backslash
7754
before them. Avoid its use if possible.</para>
7755
</description>
7756
<see-also>
7757
<ref type="application">Set</ref>
7758
</see-also>
7759
</application>
7760
<application name="SetAMAFlags" language="en_US">
7761
<synopsis>
7762
Set the AMA Flags.
7763
</synopsis>
7764
<syntax>
7765
<parameter name="flag" />
7766
</syntax>
7767
<description>
7768
<para>This application will set the channel's AMA Flags for billing purposes.</para>
7769
</description>
7770
<see-also>
7771
<ref type="function">CDR</ref>
7772
</see-also>
7773
</application>
7774
<application name="Wait" language="en_US">
7775
<synopsis>
7776
Waits for some time.
7777
</synopsis>
7778
<syntax>
7779
<parameter name="seconds" required="true">
7780
<para>Can be passed with fractions of a second. For example, <literal>1.5</literal> will ask the
7781
application to wait for 1.5 seconds.</para>
7782
</parameter>
7783
</syntax>
7784
<description>
7785
<para>This application waits for a specified number of <replaceable>seconds</replaceable>.</para>
7786
</description>
7787
</application>
7788
<application name="WaitExten" language="en_US">
7789
<synopsis>
7790
Waits for an extension to be entered.
7791
</synopsis>
7792
<syntax>
7793
<parameter name="seconds">
7794
<para>Can be passed with fractions of a second. For example, <literal>1.5</literal> will ask the
7795
application to wait for 1.5 seconds.</para>
7796
</parameter>
7797
<parameter name="options">
7798
<optionlist>
7799
<option name="m">
7800
<para>Provide music on hold to the caller while waiting for an extension.</para>
7801
<argument name="x">
7802
<para>Specify the class for music on hold.</para>
7803
</argument>
7804
</option>
7805
</optionlist>
7806
</parameter>
7807
</syntax>
7808
<description>
7809
<para>This application waits for the user to enter a new extension for a specified number
7810
of <replaceable>seconds</replaceable>.</para>
7811
<xi:include xpointer="xpointer(/docs/application[@name='Macro']/description/warning[2])" />
7812
</description>
7813
<see-also>
7814
<ref type="application">Background</ref>
7815
<ref type="function">TIMEOUT</ref>
7816
</see-also>
7817
</application>
7818
<function name="EXCEPTION" language="en_US">
7819
<synopsis>
7820
Retrieve the details of the current dialplan exception.
7821
</synopsis>
7822
<syntax>
7823
<parameter name="field" required="true">
7824
<para>The following fields are available for retrieval:</para>
7825
<enumlist>
7826
<enum name="reason">
7827
<para>INVALID, ERROR, RESPONSETIMEOUT, ABSOLUTETIMEOUT, or custom
7828
value set by the RaiseException() application</para>
7829
</enum>
7830
<enum name="context">
7831
<para>The context executing when the exception occurred.</para>
7832
</enum>
7833
<enum name="exten">
7834
<para>The extension executing when the exception occurred.</para>
7835
</enum>
7836
<enum name="priority">
7837
<para>The numeric priority executing when the exception occurred.</para>
7838
</enum>
7839
</enumlist>
7840
</parameter>
7841
</syntax>
7842
<description>
7843
<para>Retrieve the details (specified <replaceable>field</replaceable>) of the current dialplan exception.</para>
7844
</description>
7845
<see-also>
7846
<ref type="application">RaiseException</ref>
7847
</see-also>
7848
</function>
7849
<agi name="answer" language="en_US">
7850
<synopsis>
7851
Answer channel
7852
</synopsis>
7853
<syntax />
7854
<description>
7855
<para>Answers channel if not already in answer state. Returns <literal>-1</literal> on
7856
channel failure, or <literal>0</literal> if successful.</para>
7857
</description>
7858
<see-also>
7859
<ref type="agi">hangup</ref>
7860
</see-also>
7861
</agi>
7862
<agi name="asyncagi break" language="en_US">
7863
<synopsis>
7864
Interrupts Async AGI
7865
</synopsis>
7866
<syntax />
7867
<description>
7868
<para>Interrupts expected flow of Async AGI commands and returns control to previous source
7869
(typically, the PBX dialplan).</para>
7870
</description>
7871
<see-also>
7872
<ref type="agi">hangup</ref>
7873
</see-also>
7874
</agi>
7875
<agi name="channel status" language="en_US">
7876
<synopsis>
7877
Returns status of the connected channel.
7878
</synopsis>
7879
<syntax>
7880
<parameter name="channelname" />
7881
</syntax>
7882
<description>
7883
<para>Returns the status of the specified <replaceable>channelname</replaceable>.
7884
If no channel name is given then returns the status of the current channel.</para>
7885
<para>Return values:</para>
7886
<enumlist>
7887
<enum name="0">
7888
<para>Channel is down and available.</para>
7889
</enum>
7890
<enum name="1">
7891
<para>Channel is down, but reserved.</para>
7892
</enum>
7893
<enum name="2">
7894
<para>Channel is off hook.</para>
7895
</enum>
7896
<enum name="3">
7897
<para>Digits (or equivalent) have been dialed.</para>
7898
</enum>
7899
<enum name="4">
7900
<para>Line is ringing.</para>
7901
</enum>
7902
<enum name="5">
7903
<para>Remote end is ringing.</para>
7904
</enum>
7905
<enum name="6">
7906
<para>Line is up.</para>
7907
</enum>
7908
<enum name="7">
7909
<para>Line is busy.</para>
7910
</enum>
7911
</enumlist>
7912
</description>
7913
</agi>
7914
<agi name="database del" language="en_US">
7915
<synopsis>
7916
Removes database key/value
7917
</synopsis>
7918
<syntax>
7919
<parameter name="family" required="true" />
7920
<parameter name="key" required="true" />
7921
</syntax>
7922
<description>
7923
<para>Deletes an entry in the Asterisk database for a given
7924
<replaceable>family</replaceable> and <replaceable>key</replaceable>.</para>
7925
<para>Returns <literal>1</literal> if successful, <literal>0</literal>
7926
otherwise.</para>
7927
</description>
7928
</agi>
7929
<agi name="database deltree" language="en_US">
7930
<synopsis>
7931
Removes database keytree/value
7932
</synopsis>
7933
<syntax>
7934
<parameter name="family" required="true" />
7935
<parameter name="keytree" />
7936
</syntax>
7937
<description>
7938
<para>Deletes a <replaceable>family</replaceable> or specific <replaceable>keytree</replaceable>
7939
within a <replaceable>family</replaceable> in the Asterisk database.</para>
7940
<para>Returns <literal>1</literal> if successful, <literal>0</literal> otherwise.</para>
7941
</description>
7942
</agi>
7943
<agi name="database get" language="en_US">
7944
<synopsis>
7945
Gets database value
7946
</synopsis>
7947
<syntax>
7948
<parameter name="family" required="true" />
7949
<parameter name="key" required="true" />
7950
</syntax>
7951
<description>
7952
<para>Retrieves an entry in the Asterisk database for a given <replaceable>family</replaceable>
7953
and <replaceable>key</replaceable>.</para>
7954
<para>Returns <literal>0</literal> if <replaceable>key</replaceable> is not set.
7955
Returns <literal>1</literal> if <replaceable>key</replaceable> is set and returns the variable
7956
in parenthesis.</para>
7957
<para>Example return code: 200 result=1 (testvariable)</para>
7958
</description>
7959
</agi>
7960
<agi name="database put" language="en_US">
7961
<synopsis>
7962
Adds/updates database value
7963
</synopsis>
7964
<syntax>
7965
<parameter name="family" required="true" />
7966
<parameter name="key" required="true" />
7967
<parameter name="value" required="true" />
7968
</syntax>
7969
<description>
7970
<para>Adds or updates an entry in the Asterisk database for a given
7971
<replaceable>family</replaceable>, <replaceable>key</replaceable>, and
7972
<replaceable>value</replaceable>.</para>
7973
<para>Returns <literal>1</literal> if successful, <literal>0</literal> otherwise.</para>
7974
</description>
7975
</agi>
7976
<agi name="exec" language="en_US">
7977
<synopsis>
7978
Executes a given Application
7979
</synopsis>
7980
<syntax>
7981
<parameter name="application" required="true" />
7982
<parameter name="options" required="true" />
7983
</syntax>
7984
<description>
7985
<para>Executes <replaceable>application</replaceable> with given
7986
<replaceable>options</replaceable>.</para>
7987
<para>Returns whatever the <replaceable>application</replaceable> returns, or
7988
<literal>-2</literal> on failure to find <replaceable>application</replaceable>.</para>
7989
</description>
7990
</agi>
7991
<agi name="get data" language="en_US">
7992
<synopsis>
7993
Prompts for DTMF on a channel
7994
</synopsis>
7995
<syntax>
7996
<parameter name="file" required="true" />
7997
<parameter name="timeout" />
7998
<parameter name="maxdigits" />
7999
</syntax>
8000
<description>
8001
<para>Stream the given <replaceable>file</replaceable>, and receive DTMF data.</para>
8002
<para>Returns the digits received from the channel at the other end.</para>
8003
</description>
8004
</agi>
8005
<agi name="get full variable" language="en_US">
8006
<synopsis>
8007
Evaluates a channel expression
8008
</synopsis>
8009
<syntax>
8010
<parameter name="variablename" required="true" />
8011
<parameter name="channel name" />
8012
</syntax>
8013
<description>
8014
<para>Returns <literal>0</literal> if <replaceable>variablename</replaceable> is not set
8015
or channel does not exist. Returns <literal>1</literal> if <replaceable>variablename</replaceable>
8016
is set and returns the variable in parenthesis. Understands complex variable names and builtin
8017
variables, unlike GET VARIABLE.</para>
8018
<para>Example return code: 200 result=1 (testvariable)</para>
8019
</description>
8020
</agi>
8021
<agi name="get option" language="en_US">
8022
<synopsis>
8023
Stream file, prompt for DTMF, with timeout.
8024
</synopsis>
8025
<syntax>
8026
<parameter name="filename" required="true" />
8027
<parameter name="escape_digits" required="true" />
8028
<parameter name="timeout" />
8029
</syntax>
8030
<description>
8031
<para>Behaves similar to STREAM FILE but used with a timeout option.</para>
8032
</description>
8033
<see-also>
8034
<ref type="agi">stream file</ref>
8035
</see-also>
8036
</agi>
8037
<agi name="get variable" language="en_US">
8038
<synopsis>
8039
Gets a channel variable.
8040
</synopsis>
8041
<syntax>
8042
<parameter name="variablename" required="true" />
8043
</syntax>
8044
<description>
8045
<para>Returns <literal>0</literal> if <replaceable>variablename</replaceable> is not set.
8046
Returns <literal>1</literal> if <replaceable>variablename</replaceable> is set and returns
8047
the variable in parentheses.</para>
8048
<para>Example return code: 200 result=1 (testvariable)</para>
8049
</description>
8050
</agi>
8051
<agi name="hangup" language="en_US">
8052
<synopsis>
8053
Hangup the current channel.
8054
</synopsis>
8055
<syntax>
8056
<parameter name="channelname" />
8057
</syntax>
8058
<description>
8059
<para>Hangs up the specified channel. If no channel name is given, hangs
8060
up the current channel</para>
8061
</description>
8062
</agi>
8063
<agi name="noop" language="en_US">
8064
<synopsis>
8065
Does nothing.
8066
</synopsis>
8067
<syntax />
8068
<description>
8069
<para>Does nothing.</para>
8070
</description>
8071
</agi>
8072
<agi name="set music" language="en_US">
8073
<synopsis>
8074
Enable/Disable Music on hold generator
8075
</synopsis>
8076
<syntax>
8077
<parameter required="true">
8078
<enumlist>
8079
<enum>
8080
<parameter name="on" literal="true" required="true" />
8081
</enum>
8082
<enum>
8083
<parameter name="off" literal="true" required="true" />
8084
</enum>
8085
</enumlist>
8086
</parameter>
8087
<parameter name="class" required="true" />
8088
</syntax>
8089
<description>
8090
<para>Enables/Disables the music on hold generator. If <replaceable>class</replaceable>
8091
is not specified, then the <literal>default</literal> music on hold class will be
8092
used.</para>
8093
<para>Always returns <literal>0</literal>.</para>
8094
</description>
8095
</agi>
8096
<application name="JabberSend" language="en_US">
8097
<synopsis>
8098
Send a Jabber Message
8099
</synopsis>
8100
<syntax>
8101
<parameter name="Jabber" required="true">
8102
<para>Client or transport Asterisk uses to connect to Jabber.</para>
8103
</parameter>
8104
<parameter name="JID" required="true">
8105
<para>XMPP/Jabber JID (Name) of recipient.</para>
8106
</parameter>
8107
<parameter name="Message" required="true">
8108
<para>Message to be sent to the buddy.</para>
8109
</parameter>
8110
</syntax>
8111
<description>
8112
<para>Allows user to send a message to a receipent via XMPP.</para>
8113
</description>
8114
</application>
8115
<application name="JabberStatus" language="en_US">
8116
<synopsis>
8117
Retrieve the status of a jabber list member
8118
</synopsis>
8119
<syntax>
8120
<parameter name="Jabber" required="true">
8121
<para>Client or transport Asterisk users to connect to Jabber.</para>
8122
</parameter>
8123
<parameter name="JID" required="true">
8124
<para>XMPP/Jabber JID (Name) of recipient.</para>
8125
</parameter>
8126
<parameter name="Variable" required="true">
8127
<para>Variable to store the status of requested user.</para>
8128
</parameter>
8129
</syntax>
8130
<description>
8131
<para>This application is deprecated. Please use the JABBER_STATUS() function instead.</para>
8132
<para>Retrieves the numeric status associated with the specified buddy <replaceable>JID</replaceable>.
8133
The return value in the <replaceable>Variable</replaceable>will be one of the following.</para>
8134
<enumlist>
8135
<enum name="1">
8136
<para>Online.</para>
8137
</enum>
8138
<enum name="2">
8139
<para>Chatty.</para>
8140
</enum>
8141
<enum name="3">
8142
<para>Away.</para>
8143
</enum>
8144
<enum name="4">
8145
<para>Extended Away.</para>
8146
</enum>
8147
<enum name="5">
8148
<para>Do Not Disturb.</para>
8149
</enum>
8150
<enum name="6">
8151
<para>Offline.</para>
8152
</enum>
8153
<enum name="7">
8154
<para>Not In Roster.</para>
8155
</enum>
8156
</enumlist>
8157
</description>
8158
</application>
8159
<function name="JABBER_STATUS" language="en_US">
8160
<synopsis>
8161
Retrieve the status of a jabber list member
8162
</synopsis>
8163
<syntax>
8164
<parameter name="sender" required="true">
8165
<para>XMPP/Jabber ID (Name) of sender.</para>
8166
</parameter>
8167
<parameter name="buddy" required="true">
8168
<para>XMPP/Jabber JID (Name) of recipient.</para>
8169
</parameter>
8170
<parameter name="resource">
8171
<para>Client or transport Asterisk users to connect to Jabber.</para>
8172
</parameter>
8173
</syntax>
8174
<description>
8175
<para>Retrieves the numeric status associated with the specified buddy <replaceable>JID</replaceable>.
8176
The return value will be one of the following.</para>
8177
<enumlist>
8178
<enum name="1">
8179
<para>Online.</para>
8180
</enum>
8181
<enum name="2">
8182
<para>Chatty.</para>
8183
</enum>
8184
<enum name="3">
8185
<para>Away.</para>
8186
</enum>
8187
<enum name="4">
8188
<para>Extended Away.</para>
8189
</enum>
8190
<enum name="5">
8191
<para>Do Not Disturb.</para>
8192
</enum>
8193
<enum name="6">
8194
<para>Offline.</para>
8195
</enum>
8196
<enum name="7">
8197
<para>Not In Roster.</para>
8198
</enum>
8199
</enumlist>
8200
</description>
8201
</function>
8202
<function name="ODBC" language="en_US">
8203
<synopsis>
8204
Controls ODBC transaction properties.
8205
</synopsis>
8206
<syntax>
8207
<parameter name="property" required="true">
8208
<enumlist>
8209
<enum name="transaction">
8210
<para>Gets or sets the active transaction ID. If set, and the transaction ID does not
8211
exist and a <replaceable>database name</replaceable> is specified as an argument, it will be created.</para>
8212
</enum>
8213
<enum name="forcecommit">
8214
<para>Controls whether a transaction will be automatically committed when the channel
8215
hangs up. Defaults to false. If a <replaceable>transaction ID</replaceable> is specified in the optional argument,
8216
the property will be applied to that ID, otherwise to the current active ID.</para>
8217
</enum>
8218
<enum name="isolation">
8219
<para>Controls the data isolation on uncommitted transactions. May be one of the
8220
following: <literal>read_committed</literal>, <literal>read_uncommitted</literal>,
8221
<literal>repeatable_read</literal>, or <literal>serializable</literal>. Defaults to the
8222
database setting in <filename>res_odbc.conf</filename> or <literal>read_committed</literal>
8223
if not specified. If a <replaceable>transaction ID</replaceable> is specified as an optional argument, it will be
8224
applied to that ID, otherwise the current active ID.</para>
8225
</enum>
8226
</enumlist>
8227
</parameter>
8228
<parameter name="argument" required="false" />
8229
</syntax>
8230
<description>
8231
<para>The ODBC() function allows setting several properties to influence how a connected
8232
database processes transactions.</para>
8233
</description>
8234
</function>
8235
<application name="ODBC_Commit" language="en_US">
8236
<synopsis>
8237
Commits a currently open database transaction.
8238
</synopsis>
8239
<syntax>
8240
<parameter name="transaction ID" required="no" />
8241
</syntax>
8242
<description>
8243
<para>Commits the database transaction specified by <replaceable>transaction ID</replaceable>
8244
or the current active transaction, if not specified.</para>
8245
</description>
8246
</application>
8247
<application name="ODBC_Rollback" language="en_US">
8248
<synopsis>
8249
Rollback a currently open database transaction.
8250
</synopsis>
8251
<syntax>
8252
<parameter name="transaction ID" required="no" />
8253
</syntax>
8254
<description>
8255
<para>Rolls back the database transaction specified by <replaceable>transaction ID</replaceable>
8256
or the current active transaction, if not specified.</para>
8257
</description>
8258
</application>
8259
</docs>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1