<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+Design">Hangup Handlers Design</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~mjordan">Matt Jordan</a>
</h4>
<br/>
<h4>Changes (0)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="HangupHandlersDesign-Summary"></a>1. Summary</h1>
<p>Hangup handlers - Ability to attach subroutines to a channel that runs dialplan when the channel hangs up.</p>
<h1><a name="HangupHandlersDesign-Description"></a>2. Description</h1>
<p>Hangup handlers are an alternative to the h extension. They can be used in addition to the h extension. The idea is to attach a Gosub routine to a channel that will execute when the call hangs up. Whereas which h extension gets executed depends on the location of dialplan execution when the call hangs up, hangup handlers are attached to the call channel. You can attach multiple handlers that will execute in the order of most recently added first.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>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.</td></tr></table></div>
<p>Call transfers, call pickup, and call parking can result in channels on both sides of a bridge containing hangup handlers.</p>
<p>Hangup handlers can also be attached to any call leg because of pre-dial routines.</p>
<h2><a name="HangupHandlersDesign-Whenhanguphandlersareexecuted"></a>2.1. When hangup handlers are executed</h2>
<p>Any hangup handlers associated with a channel are always executed when the channel is hung up.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Adding a hangup handler in the h extension or during a hangup handler execution is undefined behavior.</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>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.</td></tr></table></div>
<h2><a name="HangupHandlersDesign-Manipulatinghanguphandlersonachannel"></a>2.2. Manipulating hangup handlers on a channel</h2>
<p>Hangup handlers pass the saved handler string to the Gosub application to execute. The syntax is intentionally the same as the Gosub application. If context or exten are not supplied then the current values from the channel pushing the hangup handler are inserted before storing on the hangup handler stack.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Push a hangup handler onto a channel</b></div><div class="preformattedContent panelContent">
<pre>same => n,Set(CHANNEL(hangup_handler_push)=[[context,]exten,]priority[(arg1[,...][,argN])]);
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Pop a hangup handler off a channel and optionally push a replacement</b></div><div class="preformattedContent panelContent">
<pre>same => n,Set(CHANNEL(hangup_handler_pop)=[[[context,]exten,]priority[(arg1[,...][,argN])]]);
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Pop all hangup handlers off a channel and optionally push a replacement</b></div><div class="preformattedContent panelContent">
<pre>same => n,Set(CHANNEL(hangup_handler_wipe)=[[[context,]exten,]priority[(arg1[,...][,argN])]]);
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Cascading hangup handlers</b></div><div class="preformattedContent panelContent">
<pre>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));
</pre>
</div></div>
<h2><a name="HangupHandlersDesign-AMIevents"></a>2.3. AMI events</h2>
<p>The hangup handler AMI events are output as part of the AMI dialplan permission class.</p>
<p>The AMI event HangupHandlerPush is generated whenever a hangup handler is pushed on the stack by the CHANNEL() function.<br/>
The AMI event HangupHandlerPop is generated whenever a hangup handler is popped off the stack by the CHANNEL() function.<br/>
The AMI event HangupHandlerRun is generated as a hangup handler is about to be executed.</p>
<h2><a name="HangupHandlersDesign-CLIcommands"></a>2.4. 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+Design">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=19726432&revisedVersion=7&originalVersion=6">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Hangup+Handlers+Design?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>