<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2171/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>
Initial Pre-dial handlers page contents<br />
</div>
<br/>
<h4>Changes (2)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-added-lines" style="background-color: #dfd;">{numberedheadings} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h1. Summary <br> <br>Pre-dial - Ability to run dialplan on callee and caller channel right before actual Dial. <br> <br>h1. Description <br> <br>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. <br> <br>The 'B' option executes a dialplan Gosub on the caller channel before any callee channels are created. <br> <br>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. <br> <br>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, <br> <br>{noformat:title=Example 1} <br><SIP/foo-123> Dial(SIP/bar,,B(context,exten,priority)) <br><SIP/foo-123> Executing context,exten,priority <br><SIP/foo-123> calling SIP/bar-124 <br>{noformat} <br> <br>{noformat:title=Example 2} <br><SIP/foo-123> Dial(SIP/bar,,b(context,exten,priority)) <br><SIP/bar-124> Executing context,exten,priority <br><SIP/foo-123> calling SIP/bar-124 <br>{noformat} <br> <br>{noformat:title=Example 3} <br><SIP/foo-123> Dial(SIP/bar&SIP/baz,,b(context,exten,priority)) <br><SIP/bar-124> Executing context,exten,priority <br><SIP/baz-125> Executing context,exten,priority <br><SIP/foo-123> calling SIP/bar-124 <br><SIP/foo-123> calling SIP/baz-125 <br>{noformat} <br> <br>h1. Use cases <br> <br>h2. Pre-dial callee channels (Option 'b') <br> <br>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? <br> <br>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. <br> <br>{noformat:title=New way} <br>Dial(SIP/def,,b(context,exten,priority)) <br>{noformat} <br> <br>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. <br> <br>h2. Pre-dial caller channels (Option 'B') <br> <br>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. <br> <br>{noformat:title=Example} <br>exten => _X.,1,GotoIf($[${LOCK(foo)}=1]?:failed) <br>exten => _X.,n,do stuff <br>exten => _X.,n,Set(Is_Unlocked=${UNLOCK(foo)}) <br>exten => _X.,n,Dial(SIP/abc) <br>exten => _X.,n(failed),Hangup() <br>{noformat} <br> <br>With this above example, say SIP/123 and SIP/234 are running this dialplan. <br> <br># SIP/123 locks foo <br># SIP/123 unlocks foo <br># Due to some CPU load issue, SIP/123 takes its time getting to Dial(SIP/abc) and doesn't do it right away. <br># Meanwhile... SIP/234 zips right by, lock 'foo' is already unlocked <br># SIP/234 grabs the lock, does its thing and it gets to Dial(SIP/abc). <br># SIP/123 wakes up and finally gets to the Dial(). <br> <br>Now you have two channels dialing SIP/abc when there was supposed to be one. <br> <br>If your intention is to ensure that Dial(SIP/abc) is only done one at a time, you may have unexpected behavior lurking. <br> <br>{noformat:title=New way} <br>exten => _X.,1,GotoIf($[${LOCK(foo)}=1]?:failed) <br>exten => _X.,n,do stuff... <br>exten => _X.,n,Dial(SIP/abc,,B(unlock,s,1)) <br>exten => _X.,n,GotoIf($[${Is_Unlocked}=1]?already_unlocked:not_unlocked) <br>exten => _X.,n(not_unlocked),Set(Is_Unlocked=${UNLOCK(foo)}) <br>exten => _X.,n(already_unlocked),Do after dial stuff... <br>exten => _X.,n(failed),Hangup() <br> <br>[unlock] <br>exten => s,1,Set(Is_Unlocked=${UNLOCK(foo)}) <br>{noformat} <br> <br>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. <br> <br>{numberedheadings} <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.</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-Usecases"></a>3. Use cases</h1>
<h2><a name="Pre-dialhandlers-Predialcalleechannels%28Option%27b%27%29"></a>3.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>3.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=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>