<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/~rmudgett">Richard Mudgett</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
Added syntax section and a sentence about what context and exten are used if they are not supplied.<br />
</div>
<br/>
<h4>Changes (2)</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" >h1. Summary <br> <br></td></tr>
<tr><td class="diff-changed-lines" >Pre-dial - Ability to run dialplan on callee and caller channel right before actual Dial. <span class="diff-added-words"style="background-color: #dfd;"> Available on the Dial and FollowMe applications.</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>h1. Description <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h1. Syntax <br> <br>b([[context^]exten^]priority[(arg1[^...][^argN])]) <br>B([[context^]exten^]priority[(arg1[^...][^argN])]) <br> <br>The syntax is intentionally the same as the Gosub application. If context or exten are not supplied then the current values from the caller channel are used. <br> <br></td></tr>
<tr><td class="diff-unchanged" >h1. Use cases <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="Pre-dialhandlers-Summary"></a>1. Summary</h1>
<p>Pre-dial - Ability to run dialplan on callee and caller channel right before actual Dial. Available on the Dial and FollowMe applications.</p>
<h1><a name="Pre-dialhandlers-Description"></a>2. Description</h1>
<p>Pre-dial handlers allow you to execute a dialplan Gosub on a channel before a call is placed but after the Dial application is invoked. You can execute a dialplan Gosub on the caller channel and on each callee channel dialed.</p>
<p>The 'B' option executes a dialplan Gosub on the caller channel before any callee channels are created.</p>
<p>The 'b' option executes a dialplan Gosub on each callee channel after it is created but before the call is placed to the end-device.</p>
<p>Example execution sequences to show when things happen:<br/>
SIP/foo is calling SIP/bar<br/>
SIP/foo is the caller,<br/>
SIP/bar is the callee,<br/>
SIP/baz is another callee,</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Example 1</b></div><div class="preformattedContent panelContent">
<pre><SIP/foo-123> Dial(SIP/bar,,B(context^exten^priority))
<SIP/foo-123> Executing context,exten,priority
<SIP/foo-123> calling SIP/bar-124
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Example 2</b></div><div class="preformattedContent panelContent">
<pre><SIP/foo-123> Dial(SIP/bar,,b(context^exten^priority))
<SIP/bar-124> Executing context,exten,priority
<SIP/foo-123> calling SIP/bar-124
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Example 3</b></div><div class="preformattedContent panelContent">
<pre><SIP/foo-123> Dial(SIP/bar&SIP/baz,,b(context^exten^priority))
<SIP/bar-124> Executing context,exten,priority
<SIP/baz-125> Executing context,exten,priority
<SIP/foo-123> calling SIP/bar-124
<SIP/foo-123> calling SIP/baz-125
</pre>
</div></div>
<h1><a name="Pre-dialhandlers-Syntax"></a>3. Syntax</h1>
<p>b([<a href="/wiki/pages/createpage.action?spaceKey=AST&title=context&linkCreation=true&fromPageId=19008337" class="createlink">context^</a>exten^]priority[(arg1<span class="error">[^...]</span><span class="error">[^argN]</span>)])<br/>
B([<a href="/wiki/pages/createpage.action?spaceKey=AST&title=context&linkCreation=true&fromPageId=19008337" class="createlink">context^</a>exten^]priority[(arg1<span class="error">[^...]</span><span class="error">[^argN]</span>)])</p>
<p>The syntax is intentionally the same as the Gosub application. If context or exten are not supplied then the current values from the caller channel are used.</p>
<h1><a name="Pre-dialhandlers-Usecases"></a>4. Use cases</h1>
<h2><a name="Pre-dialhandlers-Predialcalleechannels%28Option%27b%27%29"></a>4.1. Pre-dial callee channels (Option 'b')</h2>
<p>Say SIP/abc is calling SIP/def. In the dialplan you have: Dial(SIP/def). When executed, SIP/def-123234 is created. But how can you tell that from dialplan?</p>
<p>You can use a pickup macro: M or U options to Dial(), but you have to wait till the called channel answers to know. The new pre-dial option 'b' to Dial(), will let you run dialplan on the newly created channel before the call is placed to the end-device.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>New way</b></div><div class="preformattedContent panelContent">
<pre>Dial(SIP/def,,b(context^exten^priority))
</pre>
</div></div>
<p>Dialplan will run on SIP/def-123234 and allow you to know right away what channel will be used, and you can set specific variables on that channel.</p>
<h2><a name="Pre-dialhandlers-Predialcallerchannels%28Option%27B%27%29"></a>4.2. Pre-dial caller channels (Option 'B')</h2>
<p>You can run dialplan on the caller channel right before the dial, which is a great place to do a last microsecond UNLOCK to ensure good channel behavior.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="preformattedContent panelContent">
<pre>exten => _X.,1,GotoIf($[${LOCK(foo)}=1]?:failed)
exten => _X.,n,do stuff
exten => _X.,n,Set(Is_Unlocked=${UNLOCK(foo)})
exten => _X.,n,Dial(SIP/abc)
exten => _X.,n(failed),Hangup()
</pre>
</div></div>
<p>With this above example, say SIP/123 and SIP/234 are running this dialplan.</p>
<ol>
<li>SIP/123 locks foo</li>
<li>SIP/123 unlocks foo</li>
<li>Due to some CPU load issue, SIP/123 takes its time getting to Dial(SIP/abc) and doesn't do it right away.</li>
<li>Meanwhile... SIP/234 zips right by, lock 'foo' is already unlocked</li>
<li>SIP/234 grabs the lock, does its thing and it gets to Dial(SIP/abc).</li>
<li>SIP/123 wakes up and finally gets to the Dial().</li>
</ol>
<p>Now you have two channels dialing SIP/abc when there was supposed to be one.</p>
<p>If your intention is to ensure that Dial(SIP/abc) is only done one at a time, you may have unexpected behavior lurking.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>New way</b></div><div class="preformattedContent panelContent">
<pre>exten => _X.,1,GotoIf($[${LOCK(foo)}=1]?:failed)
exten => _X.,n,do stuff...
exten => _X.,n,Dial(SIP/abc,,B(unlock^s^1))
exten => _X.,n,GotoIf($[${Is_Unlocked}=1]?already_unlocked:not_unlocked)
exten => _X.,n(not_unlocked),Set(Is_Unlocked=${UNLOCK(foo)})
exten => _X.,n(already_unlocked),Do after dial stuff...
exten => _X.,n(failed),Hangup()
[unlock]
exten => s,1,Set(Is_Unlocked=${UNLOCK(foo)})
</pre>
</div></div>
<p>Now, under no circumstances can this dialplan be run through and execute the Dial unless lock 'foo' is released. Obviously this doesn't ensure that you're not calling SIP/abc more than once (you would need more dialplan logic for that), but it will allow a dialplan coder to also put the Dial in the locked section to ensure tighter control.</p>
</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=19008337&revisedVersion=4&originalVersion=3">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>