<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/~rmudgett">Richard Mudgett</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
Updated adding a hangup handler syntax and added a note about what context and exten are used if they are not supplied.<br />
</div>
<br/>
<h4>Changes (3)</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" > <br>{noformat:title=Add a hangup handler to a channel} <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">same => n,Set(CHANNEL(hangup_handler)=<Gosub-app-args>); <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">same => n,Set(CHANNEL(hangup_handler)=[[context,]exten,]priority[(arg1[,...][,argN])]); <br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The syntax is intentionally the same as the Gosub application. If context or exten are not supplied then the current values from the channel adding the hangup handler are inserted before saving. <br> <br></td></tr>
<tr><td class="diff-unchanged" >{noformat:title=Cascading hangup handlers} <br>same => n,Set(CHANNEL(hangup_handler)=hdlr3,s,1(args)); <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="Hanguphandlers-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="Hanguphandlers-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>
<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>Need to investigate CDR handling issues.</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. However, attaching a hangup handler to a channel using pre-dial does not necessarily mean it will get executed. If you attached a hangup handler to all outgoing legs of a Dial or FollowMe using the pre-dial feature, only the winning outgoing call leg will have its hangup handlers run. </p>
<p>The restriction on losing calls not having their hangup handlers executed may be removed. The call pickup scenario has the picked up ringing channel run its hangup handlers after the masquerade. Although, it would be easy to have that situation just discard those handlers instead.</p>
<h2><a name="Hanguphandlers-Whenhanguphandlersareexecuted"></a>2.1. When hangup handlers are executed</h2>
<p>Hangup handler execution will be evaluated under the following circumstances:</p>
<p>1) When the incoming call PBX reaches the end of dialplan. This is normal PBX thread termination.</p>
<p>2) When the bridge between a channel and its peer call leg is broken. The hangup handlers on both sides of the bridge will be evaluated for possible execution as appropriate for the circumstances of the bridge.</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="Hanguphandlers-Addhanguphandlerstoachannel"></a>2.2. Add hangup handlers to a channel</h2>
<p>Hangup handlers pass the saved handler string to the Gosub application to execute.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Add a hangup handler to a channel</b></div><div class="preformattedContent panelContent">
<pre>same => n,Set(CHANNEL(hangup_handler)=[[context,]exten,]priority[(arg1[,...][,argN])]);
</pre>
</div></div>
<p>The syntax is intentionally the same as the Gosub application. If context or exten are not supplied then the current values from the channel adding the hangup handler are inserted before saving.</p>
<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)=hdlr3,s,1(args));
same => n,Set(CHANNEL(hangup_handler)=hdlr2,s,1(args));
same => n,Set(CHANNEL(hangup_handler)=hdlr1,s,1(args));
</pre>
</div></div>
<h2><a name="Hanguphandlers-CLIcommands"></a>2.3. 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 channel <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><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 channels
</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=19726432&revisedVersion=2&originalVersion=1">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>