Summary¶
Hangup handlers - Ability to attach subroutines to a channel that runs dialplan when the channel hangs up.
Description¶
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.
{note} 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.
Call transfers, call pickup, and call parking can result in channels on both sides of a bridge containing hangup handlers.
Hangup handlers can also be attached to any call leg because of pre-dial routines.
When hangup handlers are executed¶
Any hangup handlers associated with a channel are always executed when the channel is hung up.
{note} Adding a hangup handler in the h extension or during a hangup handler execution is undefined behavior.
{warning} 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.
Manipulating hangup handlers on a channel¶
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.
{noformat:title=Push a hangup handler onto a channel} same => n,Set(CHANNEL(hangup_handler_push)=[[context,]exten,]priority[(arg1[,...][,argN])]);
{noformat:title=Pop a hangup handler off a channel and optionally push a replacement}
same => n,Set(CHANNEL(hangup_handler_pop)=[[[context,]exten,]priority[(arg1[,...][,argN])]]);
{noformat:title=Cascading hangup handlers}
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));
AMI events¶
The hangup handler AMI events are output as part of the AMI dialplan permission class.
The AMI event HangupHandlerPush is generated whenever a hangup handler is pushed on the stack by the CHANNEL() function. The AMI event HangupHandlerPop is generated whenever a hangup handler is popped off the stack by the CHANNEL() function. The AMI event HangupHandlerRun is generated as a hangup handler is about to be executed.
CLI commands¶
{noformat:title=Single channel} core show hanguphandlers