<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2172/18/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Pre-Dial+Handlers">Pre-Dial Handlers</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~mjordan">Matt Jordan</a>
</h4>
<br/>
<h4>Changes (3)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > <br>{warning:title=WARNINGS} <br></td></tr>
<tr><td class="diff-changed-lines" >* As pre-dial handlers are <span class="diff-added-words"style="background-color: #dfd;">implemented using [Gosub|AST:Asterisk 11 Application_Gosub]</span> subroutines, they must be terminated with a call to [Return|AST:Asterisk 11 Application_Return]. <br></td></tr>
<tr><td class="diff-unchanged" >* Taking actions in pre-dial handlers that would put the caller/callee channels into other applications will result in undefined behaviour. Pre-dial handlers should be short routines that do not impact the state that the dialling application assumes the channel will be in. <br>{warning} <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >h2. Syntax <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Handlers are invoked using the same nomenclature as other [Gosub|AST:Asterisk 11 Application_Gosub] routines. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Handlers are invoked using similar nomenclature as other options (*M*,*m*,*U*,*u*) in [Dial|AST:Asterisk 11 Application_Dial] or [FollowMe|AST:Asterisk 11 Application_FollowMe] that cause some portion of the dialplan to execute. <br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br>b([[context^]exten^]priority[(arg1[^...][^argN])]) <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h2><a name="Pre-DialHandlers-Overview"></a>Overview</h2>
<p>Pre-dial handlers allow you to execute a dialplan subroutine on a channel before a call is placed but after the application performing a dial action is invoked. This means that the handlers are executed after the creation of the caller/callee channels, but before any actions have been taken to actually dial the callee channels. You can execute a dialplan subroutine on the caller channel and on each callee channel dialled.</p>
<p>There are two ways in which a pre-dial handler can be invoked:</p>
<ul>
<li>The '<b>B</b>' option in an application executes a dialplan subroutine on the caller channel before any callee channels are created.</li>
<li>The '<b>b</b>' option in an application executes a dialplan subroutine on each callee channel after it is created but before the call is placed to the end-device.</li>
</ul>
<p>Pre-dial handlers are supported in the <a href="/wiki/display/AST/Asterisk+11+Application_Dial" title="Asterisk 11 Application_Dial">Dial</a> application and the <a href="/wiki/display/AST/Asterisk+11+Application_FollowMe" title="Asterisk 11 Application_FollowMe">FollowMe</a> application.</p>
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>WARNINGS</b><br /><ul>
<li>As pre-dial handlers are implemented using <a href="/wiki/display/AST/Asterisk+11+Application_Gosub" title="Asterisk 11 Application_Gosub">Gosub</a> subroutines, they must be terminated with a call to <a href="/wiki/display/AST/Asterisk+11+Application_Return" title="Asterisk 11 Application_Return">Return</a>.</li>
<li>Taking actions in pre-dial handlers that would put the caller/callee channels into other applications will result in undefined behaviour. Pre-dial handlers should be short routines that do not impact the state that the dialling application assumes the channel will be in.</li>
</ul>
</td></tr></table></div>
<h2><a name="Pre-DialHandlers-Syntax"></a>Syntax</h2>
<p>Handlers are invoked using similar nomenclature as other options (<b>M</b>,<b>m</b>,<b>U</b>,<b>u</b>) in <a href="/wiki/display/AST/Asterisk+11+Application_Dial" title="Asterisk 11 Application_Dial">Dial</a> or <a href="/wiki/display/AST/Asterisk+11+Application_FollowMe" title="Asterisk 11 Application_FollowMe">FollowMe</a> that cause some portion of the dialplan to execute.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>b([[context^]exten^]priority[(arg1[^...][^argN])])
B([[context^]exten^]priority[(arg1[^...][^argN])])
</pre>
</div></div>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>If context or exten are not supplied then the current values from the caller channel are used.</td></tr></table></div>
<h2><a name="Pre-DialHandlers-Examples"></a>Examples</h2>
<p>The examples illustrated below use the following channels:</p>
<ul>
<li><em>SIP/foo</em> is calls either <em>SIP/bar</em>, <em>SIP/baz</em>, or both</li>
<li><em>SIP/foo</em> is the caller</li>
<li><em>SIP/bar</em> is a callee</li>
<li><em>SIP/baz</em> is another callee</li>
</ul>
<h4><a name="Pre-DialHandlers-Example1Executingapredialhandleronthecallerchannel"></a>Example 1 - Executing a pre-dial handler on the caller channel</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">[default]
exten => s,1,NoOp()
same => n,Dial(SIP/bar,,B(default^caller_handler^1))
same => n,Hangup()
exten => caller_handler,1,NoOp()
same => n,Verbose(0, In caller pre-dial handler!)
same => n,Return()</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Example 1 CLI Output</b></div><div class="preformattedContent panelContent">
<pre><SIP/foo-123> Dial(SIP/bar,,B(default^caller_handler^1))
<SIP/foo-123> Executing default,caller_handler,1
<SIP/foo-123> In caller pre-dial handler!
<SIP/foo-123> calling SIP/bar-124
</pre>
</div></div>
<h4><a name="Pre-DialHandlers-Example2Executingapredialhandleronacalleechannel"></a>Example 2 - Executing a pre-dial handler on a callee channel</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">[default]
exten => s,1,NoOp()
same => n,Dial(SIP/bar,,b(default^callee_handler^1))
same => n,Hangup()
exten => callee_handler,1,NoOp()
same => n,Verbose(0, In callee pre-dial handler!)
same => n,Return()</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Example 2 CLI Output</b></div><div class="preformattedContent panelContent">
<pre><SIP/foo-123> Dial(SIP/bar,,b(default^callee_handler^1))
<SIP/bar-124> Executing default,callee_handler,1
<SIP/bar-124> In callee pre-dial handler!
<SIP/foo-123> calling SIP/bar-124
</pre>
</div></div>
<h4><a name="Pre-DialHandlers-Example3Executingapredialhandleronmultiplecalleechannels"></a>Example 3 - Executing a pre-dial handler on multiple callee channels</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">[default]
exten => s,1,NoOp()
same => n,Dial(SIP/bar&SIP/baz,,b(default^callee_handler^1))
same => n,Hangup()
exten => callee_handler,1,NoOp()
same => n,Verbose(0, In callee pre-dial handler!)
same => n,Return()</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Example 3 CLI Output</b></div><div class="preformattedContent panelContent">
<pre><SIP/foo-123> Dial(SIP/bar&SIP/baz,,b(default^callee_handler^1))
<SIP/bar-124> Executing default,callee_handler,1
<SIP/bar-124> In callee pre-dial handler!
<SIP/baz-125> Executing default,callee_handler,1
<SIP/baz-125> In callee pre-dial handler!
<SIP/foo-123> calling SIP/bar-124
<SIP/foo-123> calling SIP/baz-125
</pre>
</div></div>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/Pre-Dial+Handlers">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=20189344&revisedVersion=2&originalVersion=1">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Pre-Dial+Handlers?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>