<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/Hangup+Handlers">Hangup 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 (1)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-unchanged" >h2. Overview <br> <br></td></tr>
<tr><td class="diff-changed-lines" >Hangup handlers <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">allow attaching</span> <span class="diff-added-words"style="background-color: #dfd;">are</span> subroutines <span class="diff-added-words"style="background-color: #dfd;">attached</span> to a channel that will execute when that channel hangs up. Unlike the traditional [h extension|AST:Handling Special Extensions], hangup handlers follow the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">channel, so</span> <span class="diff-added-words"style="background-color: #dfd;">channel; so,</span> regardless of where in the dialplan a channel is executing, if that channel is hung up, the hangup handlers will be run. <br></td></tr>
<tr><td class="diff-unchanged" > <br>Multiple hangup handlers can be attached to a single channel. If multiple hangup handlers are attached to a channel, the hangup handlers will be executed in the order of most recently added first. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h2><a name="HangupHandlers-Overview"></a>Overview </h2>
<p>Hangup handlers are subroutines attached to a channel that will execute when that channel hangs up. Unlike the traditional <a href="/wiki/display/AST/Handling+Special+Extensions" title="Handling Special Extensions">h extension</a>, hangup handlers follow the channel; so, regardless of where in the dialplan a channel is executing, if that channel is hung up, the hangup handlers will be run.</p>
<p>Multiple hangup handlers can be attached to a single channel. If multiple hangup handlers are attached to a channel, the hangup handlers will be executed in the order of most recently added first.</p>
<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><b>NOTES</b><br /><ul>
<li>Please note that when the hangup handlers execute in relation to the h extension is not defined. They could execute before or after the h extension.</li>
<li>Call transfers, call pickup, and call parking can result in channels on both sides of a bridge containing hangup handlers.</li>
<li>Hangup handlers can be attached to any call leg using pre-dial routines.</li>
</ul>
</td></tr></table></div>
<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 hangup handlers are 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>Adding a hangup handler in the h extension or during a hangup handler execution is undefined behaviour.</li>
<li>As always, hangup handlers, like the h extension, need to execute quickly because they are in the hangup sequence path of the call leg. Specific channel driver protocols like ISDN and SIP may not be able to handle excessive delays completing the hangup sequence.</li>
</ul>
</td></tr></table></div>
<h2><a name="HangupHandlers-DialplanApplicationsandFunctions"></a>Dialplan Applications and Functions</h2>
<p>All manipulation of a channel's hangup handlers are done using the <a href="/wiki/display/AST/Asterisk+11+Function_CHANNEL" title="Asterisk 11 Function_CHANNEL">CHANNEL</a> function. All values manipulated for hangup handlers are write-only.</p>
<h3><a name="HangupHandlers-hanguphandlerpush"></a>hangup_handler_push</h3>
<p>Used to push a hangup handler onto a channel.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>same => n,Set(CHANNEL(hangup_handler_push)=[[context,]exten,]priority[(arg1[,...][,argN])]);
</pre>
</div></div>
<h3><a name="HangupHandlers-hanguphandlerpop"></a>hangup_handler_pop</h3>
<p>Used to pop a hangup handler off a channel. Optionally, a replacement hangup handler can be added to the channel.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>same => n,Set(CHANNEL(hangup_handler_pop)=[[[context,]exten,]priority[(arg1[,...][,argN])]]);
</pre>
</div></div>
<h3><a name="HangupHandlers-hanguphandlerwipe"></a>hangup_handler_wipe</h3>
<p>Remove all hangup handlers on the channel. Optionally, a new hangup handler can be pushed onto the channel.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>same => n,Set(CHANNEL(hangup_handler_wipe)=[[[context,]exten,]priority[(arg1[,...][,argN])]]);
</pre>
</div></div>
<h3><a name="HangupHandlers-Examples"></a>Examples</h3>
<h5><a name="HangupHandlers-Addinghanguphandlerstoachannel"></a>Adding hangup handlers to a channel</h5>
<p>In this example, three hangup handlers are added to a channel: hdlr3, hdlr2, and hdlr1. When the channel is hung up, they will be executed in the order of most recently added first - so hdlr1 will execute first, followed by hdlr2, then hdlr3.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">; Some dialplan extension
same => n,Set(CHANNEL(hangup_handler_push)=hdlr3,s,1(args));
same => n,Set(CHANNEL(hangup_handler_push)=hdlr2,s,1(args));
same => n,Set(CHANNEL(hangup_handler_push)=hdlr1,s,1(args));
; Continuing in some dialplan extension
[hdlr1]
exten => s,1,Verbose(0, Executed First)
same => n,Return()
[hdlr2]
exten => s,1,Verbose(0, Executed Second)
same => n,Return()
[hdlr3]
exten => s,1,Verbose(0, Executed Third)
same => n,Return()</pre>
</div></div>
<h5><a name="HangupHandlers-Removingandreplacinghanguphandlers"></a>Removing and replacing hangup handlers</h5>
<p>In this example, three hangup handlers are added to a channel: hdlr3, hdlr2, and hdlr1. Using the <a href="/wiki/display/AST/Asterisk+11+Function_CHANNEL" title="Asterisk 11 Function_CHANNEL">CHANNEL</a> function's <b>hangup_handler_pop</b> value, hdlr1 is removed from the stack of hangup handlers. Then, using the <b>hangup_handler_pop</b> value again, hdlr2 is replaced with hdlr4. When the channel is hung up, hdlr4 will be executed, followed by hdlr3.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">; Some dialplan extension
same => n,Set(CHANNEL(hangup_handler_push)=hdlr3,s,1(args));
same => n,Set(CHANNEL(hangup_handler_push)=hdlr2,s,1(args));
same => n,Set(CHANNEL(hangup_handler_push)=hdlr1,s,1(args));
; Remove hdlr1
same => n,Set(CHANNEL(hangup_handler_pop))
; Replace hdlr2 with hdlr4
same => n,Set(CHANNEL(hangup_handler_pop)=hdlr4,s,1(args));
; Continuing in some dialplan extension
[hdlr1]
exten => s,1,Verbose(0, Not Executed)
same => n,Return()
[hdlr2]
exten => s,1,Verbose(0, Not Executed)
same => n,Return()
[hdlr3]
exten => s,1,Verbose(0, Executed Second)
same => n,Return()
[hdlr4]
exten => s,1,Verbose(0, Executed First)
same => n,Return()</pre>
</div></div>
<h2><a name="HangupHandlers-CLICommands"></a>CLI Commands</h2>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Single channel</b></div><div class="preformattedContent panelContent">
<pre>core show hanguphandlers <chan>
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Output</b></div><div class="preformattedContent panelContent">
<pre>Channel Handler
<chan-name> <first handler to execute>
<second handler to execute>
<third handler to execute>
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>All channels</b></div><div class="preformattedContent panelContent">
<pre>core show hanguphandlers all
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Output</b></div><div class="preformattedContent panelContent">
<pre>Channel Handler
<chan1-name> <first handler to execute>
<second handler to execute>
<third handler to execute>
<chan2-name> <first handler to execute>
<chan3-name> <first handler to execute>
<second handler to execute>
</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/Hangup+Handlers">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=20189328&revisedVersion=4&originalVersion=3">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Hangup+Handlers?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>