<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/app_macro+Deprecation">app_macro Deprecation</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~kmoore">Kinsey Moore</a>
</h4>
<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;">h1. Macro Deprecation <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">These changes to Asterisk allow for the final deprecation of all usage of app_macro within Asterisk. There should now be app_stack based alternatives for every use case. Because of the way macros are implemented, they are limited to a nesting depth of 7. This is a result of its heavy usage of the stack when called recursively and the significant possibility of a crash when doing so. In addition, certain applications may not function as expected when called from within a macro call. <br> <br>h2. Call Completion Supplementary Services <br> <br>Starting with Asterisk 11, Call Completion Supplementary Services(CCSS) callback macro functionality has been deprecated in favor of an app_stack-based approach. Usage in channel driver configurations is nearly identical to that of the existing app_macro-based option. <br> <br>h3. Differences in Usage <br> <br>In channel configurations, 'cc_callback_sub' should be used instead of 'cc_callback_macro' and a complete location in the dialplan such as 'local,1234,1' should be provided instead of a macro context. Arguments and argument order have been preserved to make the change as smooth as possible. <br> <br>h3. Example <br> <br>Assuming a SIP configuration of the following: <br>{code} <br>[general] <br>limitonpeers=yes <br>udpbindaddr = 127.0.0.2 <br> <br>[alice] <br>type = friend <br>context = to-bob <br>host = 127.0.0.1 <br>qualify = no <br>insecure = invite <br>cc_agent_policy=generic <br>cc_monitor_policy=generic <br>cc_callback_sub=cc_test,s,1 <br>callcounter=yes <br> <br>[bob] <br>type = friend <br>fromuser = bob <br>context = bob-in <br>host = 127.0.0.1 <br>qualify = no <br>insecure = invite <br>cc_agent_policy=generic <br>cc_monitor_policy=generic <br>cc_callback_sub=cc_test,s,1 <br>callcounter=yes <br>{code} <br> <br>And dialplan: <br>{code} <br>[to-bob] <br>exten => 1234,1,NoOp <br>exten => 1234,n,Dial(SIP/bob) <br> <br>exten => 1235,1,Answer() <br>exten => 1235,n,CallCompletionRequest() <br> <br>[cc_test] <br>exten => s,1,NoOp(CCSS callback run for CCBS) <br>exten => s,n,Return <br>{code} <br> <br>h4. Events <br> <br>A call is made to bob. While this call is active, Alice attempts a call to Bob by dialing 1234, fails, and then requests CCBS by dialing 1235. Once Bob ends his call, Asterisk runs the callback (cc_test), calls Bob, and then calls Alice to complete the CCBS request. <br> <br>h2. Connected Line Information <br> <br>Starting with Asterisk 11, the use of a connected line information (CLI) callback macro for CLI interception and modification has been deprecated in favor of an app_stack-based approach. If both app_macro-based and app_stack-based callbacks have been defined, the app_stack-based callback will be run instead of the app_macro-based callbacks. To accomplish this deprecation, two new dialplan variables have been introduced: CONNECTED_LINE_SEND_SUB and CONNECTED_LINE_SEND_SUB_ARGS. If CONNECTED_LINE_SEND_SUB is set, it will override its equivalent macro-based callback. If neither CONNECTED_LINE_SEND_SUB nor its macro equivalents are set, connected line information will be passed along unmodified. <br> <br>h3. Differences in Usage <br> <br>The primary difference between the app_macro-based callbacks and the new app_stack-based callback is that there is only one variant of the app_stack-based callback where there were previously callee and caller variants of the macro callback. Caller and callee distinctions break down in transfer situations so the caller and callee variants were combined in the app_stack-based implementation. CONNECTED_LINE_SEND_SUB must be provided with a full dialplan location such as 'local,1234,1'. Otherwise, usage is identical to the deprecated app_macro-based callback. <br> <br>h3. Example <br> <br>Starting dialplan execution at 'test,100,1', the following is a working example of the app_stack-based CLI callback using local channels. <br>{code} <br>[test] <br>exten => 100,1,NoOp <br>exten => 100,n,Set(CONNECTED_LINE_SEND_SUB=callback,s,1) <br>exten => 100,n,Set(CONNECTED_LINE_SEND_SUB_ARGS=45,4) <br>exten => 100,n,Dial(local/101@test) <br>exten => 100,n,Hangup <br> <br>exten => 101,1,NoOp <br>exten => 101,n,Set(CONNECTEDLINE(name,i)="Company Name") <br>exten => 101,n,Set(CONNECTEDLINE(name-pres,i)=allowed) <br>exten => 101,n,Set(CONNECTEDLINE(num,i)=5551212) <br>exten => 101,n,Set(CONNECTEDLINE(num-pres)=allowed) <br>exten => 101,n,Answer <br>exten => 101,n,Echo() <br> <br>[callback] <br>; ARG1 is the prefix to add. <br>; ARG2 is the number of digits at the end to add the prefix to. <br>; When the subroutine ends the CONNECTEDLINE data is passed to the <br>; channel driver. <br>exten => s,1,NoOp() <br>exten => s,n,GotoIf($[${CONNECTEDLINE(number)} != 5551212]?end) <br>exten => s,n,NoOp(Running connected line subroutine with arg1: ${ARG1} and arg2: ${ARG2}) <br>exten => s,n,Set(NOPREFIX=${CONNECTEDLINE(number):-${ARG2}}) <br>exten => s,n,Set(CONNECTEDLINE(num,i)=${ARG1}${NOPREFIX}) <br>exten => s,(end),Return <br>{code} <br> <br>h2. Redirecting Information <br> <br>Starting with Asterisk 11, the use of a redirecting information (RI) callback macro for RI interception and modification has been deprecated in favor of an app_stack-based approach. If both app_macro-based and app_stack-based callbacks have been defined, the app_stack-based callback will be run instead of the app_macro-based callbacks. To accomplish this deprecation, two new dialplan variables have been introduced: REDIRECTING_SEND_SUB and REDIRECTING_SEND_SUB_ARGS. If REDIRECTING_SEND_SUB is set, it will override its equivalent macro-based callback. If neither REDIRECTING_SEND_SUB nor its macro equivalents are set, redirecting information will be passed along unmodified. <br> <br>h3. Differences in Usage <br> <br>The primary difference between the app_macro-based callbacks and the new app_stack-based callback is that there is only one variant of the app_stack-based callback where there were previously callee and caller variants of the macro callback. Caller and callee distinctions break down in transfer situations so the caller and callee variants were combined in the app_stack-based implementation. REDIRECTING_SEND_SUB must be provided with a full dialplan location such as 'local,1234,1'. Otherwise, usage is identical to the deprecated app_macro-based callback. <br> <br> <br>h3. Example <br> <br>Starting dialplan execution at 'test,100,1', the following is a working example of the app_stack-based RI callback using local channels. <br>{code} <br>[test] <br>exten => 100,1,NoOp <br>exten => 100,n,Set(REDIRECTING_SEND_SUB=callback,s,1) <br>exten => 100,n,Set(REDIRECTING_SEND_SUB_ARGS=45,4) <br>exten => 100,n,Dial(local/101@test) <br>exten => 100,n,Hangup <br> <br>exten => 101,1,NoOp <br>exten => 101,n,Set(REDIRECTING(to-num,i)=2000) <br>exten => 101,n,Set(REDIRECTING(to-num-pres)=allowed) <br>exten => 101,n,Set(REDIRECTING(from-num,i)=1000) <br>exten => 101,n,Set(REDIRECTING(from-num-pres,i)=allowed) <br>exten => 101,n,Set(REDIRECTING(count,i)=$[${REDIRECTING(count)} + 1]) <br>exten => 101,n,Set(REDIRECTING(reason,i)=cfu) <br>exten => 101,n,Answer <br>exten => 101,n,Echo() <br> <br>[callback] <br>; ARG1 is the prefix to add. <br>; ARG2 is the number of digits at the end to add the prefix to. <br>; When the subroutine ends the REDIRECTING data is passed to the <br>; channel driver. <br>exten => s,1,NoOp() <br>exten => s,n,GotoIf($[${REDIRECTING(to-num)} != 2000]?end) <br>exten => s,n,NoOp(Running caller redirecting subroutine with arg1: ${ARG1} and arg2: ${ARG2}) <br>exten => s,n,Set(NOPREFIX=${REDIRECTING(to-num):-${ARG2}}) <br>exten => s,n,Set(REDIRECTING(to-num,i)=${ARG1}${NOPREFIX}) <br>exten => s,(end),Return <br>{code} <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="app_macroDeprecation-MacroDeprecation"></a>Macro Deprecation</h1>
<p>These changes to Asterisk allow for the final deprecation of all usage of app_macro within Asterisk. There should now be app_stack based alternatives for every use case. Because of the way macros are implemented, they are limited to a nesting depth of 7. This is a result of its heavy usage of the stack when called recursively and the significant possibility of a crash when doing so. In addition, certain applications may not function as expected when called from within a macro call.</p>
<h2><a name="app_macroDeprecation-CallCompletionSupplementaryServices"></a>Call Completion Supplementary Services</h2>
<p>Starting with Asterisk 11, Call Completion Supplementary Services(CCSS) callback macro functionality has been deprecated in favor of an app_stack-based approach. Usage in channel driver configurations is nearly identical to that of the existing app_macro-based option.</p>
<h3><a name="app_macroDeprecation-DifferencesinUsage"></a>Differences in Usage</h3>
<p>In channel configurations, 'cc_callback_sub' should be used instead of 'cc_callback_macro' and a complete location in the dialplan such as 'local,1234,1' should be provided instead of a macro context. Arguments and argument order have been preserved to make the change as smooth as possible.</p>
<h3><a name="app_macroDeprecation-Example"></a>Example</h3>
<p>Assuming a SIP configuration of the following:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">[general]
limitonpeers=yes
udpbindaddr = 127.0.0.2
[alice]
type = friend
context = to-bob
host = 127.0.0.1
qualify = no
insecure = invite
cc_agent_policy=generic
cc_monitor_policy=generic
cc_callback_sub=cc_test,s,1
callcounter=yes
[bob]
type = friend
fromuser = bob
context = bob-in
host = 127.0.0.1
qualify = no
insecure = invite
cc_agent_policy=generic
cc_monitor_policy=generic
cc_callback_sub=cc_test,s,1
callcounter=yes</pre>
</div></div>
<p>And dialplan:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">[to-bob]
exten => 1234,1,NoOp
exten => 1234,n,Dial(SIP/bob)
exten => 1235,1,Answer()
exten => 1235,n,CallCompletionRequest()
[cc_test]
exten => s,1,NoOp(CCSS callback run for CCBS)
exten => s,n,Return</pre>
</div></div>
<h4><a name="app_macroDeprecation-Events"></a>Events</h4>
<p>A call is made to bob. While this call is active, Alice attempts a call to Bob by dialing 1234, fails, and then requests CCBS by dialing 1235. Once Bob ends his call, Asterisk runs the callback (cc_test), calls Bob, and then calls Alice to complete the CCBS request.</p>
<h2><a name="app_macroDeprecation-ConnectedLineInformation"></a>Connected Line Information</h2>
<p>Starting with Asterisk 11, the use of a connected line information (CLI) callback macro for CLI interception and modification has been deprecated in favor of an app_stack-based approach. If both app_macro-based and app_stack-based callbacks have been defined, the app_stack-based callback will be run instead of the app_macro-based callbacks. To accomplish this deprecation, two new dialplan variables have been introduced: CONNECTED_LINE_SEND_SUB and CONNECTED_LINE_SEND_SUB_ARGS. If CONNECTED_LINE_SEND_SUB is set, it will override its equivalent macro-based callback. If neither CONNECTED_LINE_SEND_SUB nor its macro equivalents are set, connected line information will be passed along unmodified.</p>
<h3><a name="app_macroDeprecation-DifferencesinUsage"></a>Differences in Usage</h3>
<p>The primary difference between the app_macro-based callbacks and the new app_stack-based callback is that there is only one variant of the app_stack-based callback where there were previously callee and caller variants of the macro callback. Caller and callee distinctions break down in transfer situations so the caller and callee variants were combined in the app_stack-based implementation. CONNECTED_LINE_SEND_SUB must be provided with a full dialplan location such as 'local,1234,1'. Otherwise, usage is identical to the deprecated app_macro-based callback.</p>
<h3><a name="app_macroDeprecation-Example"></a>Example</h3>
<p>Starting dialplan execution at 'test,100,1', the following is a working example of the app_stack-based CLI callback using local channels.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">[test]
exten => 100,1,NoOp
exten => 100,n,Set(CONNECTED_LINE_SEND_SUB=callback,s,1)
exten => 100,n,Set(CONNECTED_LINE_SEND_SUB_ARGS=45,4)
exten => 100,n,Dial(local/101@test)
exten => 100,n,Hangup
exten => 101,1,NoOp
exten => 101,n,Set(CONNECTEDLINE(name,i)="Company Name")
exten => 101,n,Set(CONNECTEDLINE(name-pres,i)=allowed)
exten => 101,n,Set(CONNECTEDLINE(num,i)=5551212)
exten => 101,n,Set(CONNECTEDLINE(num-pres)=allowed)
exten => 101,n,Answer
exten => 101,n,Echo()
[callback]
; ARG1 is the prefix to add.
; ARG2 is the number of digits at the end to add the prefix to.
; When the subroutine ends the CONNECTEDLINE data is passed to the
; channel driver.
exten => s,1,NoOp()
exten => s,n,GotoIf($[${CONNECTEDLINE(number)} != 5551212]?end)
exten => s,n,NoOp(Running connected line subroutine with arg1: ${ARG1} and arg2: ${ARG2})
exten => s,n,Set(NOPREFIX=${CONNECTEDLINE(number):-${ARG2}})
exten => s,n,Set(CONNECTEDLINE(num,i)=${ARG1}${NOPREFIX})
exten => s,(end),Return</pre>
</div></div>
<h2><a name="app_macroDeprecation-RedirectingInformation"></a>Redirecting Information</h2>
<p>Starting with Asterisk 11, the use of a redirecting information (RI) callback macro for RI interception and modification has been deprecated in favor of an app_stack-based approach. If both app_macro-based and app_stack-based callbacks have been defined, the app_stack-based callback will be run instead of the app_macro-based callbacks. To accomplish this deprecation, two new dialplan variables have been introduced: REDIRECTING_SEND_SUB and REDIRECTING_SEND_SUB_ARGS. If REDIRECTING_SEND_SUB is set, it will override its equivalent macro-based callback. If neither REDIRECTING_SEND_SUB nor its macro equivalents are set, redirecting information will be passed along unmodified.</p>
<h3><a name="app_macroDeprecation-DifferencesinUsage"></a>Differences in Usage</h3>
<p>The primary difference between the app_macro-based callbacks and the new app_stack-based callback is that there is only one variant of the app_stack-based callback where there were previously callee and caller variants of the macro callback. Caller and callee distinctions break down in transfer situations so the caller and callee variants were combined in the app_stack-based implementation. REDIRECTING_SEND_SUB must be provided with a full dialplan location such as 'local,1234,1'. Otherwise, usage is identical to the deprecated app_macro-based callback.</p>
<h3><a name="app_macroDeprecation-Example"></a>Example</h3>
<p>Starting dialplan execution at 'test,100,1', the following is a working example of the app_stack-based RI callback using local channels.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">[test]
exten => 100,1,NoOp
exten => 100,n,Set(REDIRECTING_SEND_SUB=callback,s,1)
exten => 100,n,Set(REDIRECTING_SEND_SUB_ARGS=45,4)
exten => 100,n,Dial(local/101@test)
exten => 100,n,Hangup
exten => 101,1,NoOp
exten => 101,n,Set(REDIRECTING(to-num,i)=2000)
exten => 101,n,Set(REDIRECTING(to-num-pres)=allowed)
exten => 101,n,Set(REDIRECTING(from-num,i)=1000)
exten => 101,n,Set(REDIRECTING(from-num-pres,i)=allowed)
exten => 101,n,Set(REDIRECTING(count,i)=$[${REDIRECTING(count)} + 1])
exten => 101,n,Set(REDIRECTING(reason,i)=cfu)
exten => 101,n,Answer
exten => 101,n,Echo()
[callback]
; ARG1 is the prefix to add.
; ARG2 is the number of digits at the end to add the prefix to.
; When the subroutine ends the REDIRECTING data is passed to the
; channel driver.
exten => s,1,NoOp()
exten => s,n,GotoIf($[${REDIRECTING(to-num)} != 2000]?end)
exten => s,n,NoOp(Running caller redirecting subroutine with arg1: ${ARG1} and arg2: ${ARG2})
exten => s,n,Set(NOPREFIX=${REDIRECTING(to-num):-${ARG2}})
exten => s,n,Set(REDIRECTING(to-num,i)=${ARG1}${NOPREFIX})
exten => s,(end),Return</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/app_macro+Deprecation">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=19008210&revisedVersion=3&originalVersion=2">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/app_macro+Deprecation?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>