[asterisk-dev] [Code Review] Hangup handlers - Dialplan subroutines that run when the channel hangs up.

[rmudgett]

-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviewboard.asterisk.org/r/2002/
-----------------------------------------------------------

Review request for Asterisk Developers.


Summary
-------

This feature originated with https://reviewboard.asterisk.org/r/1230/ by kobaz.

See
https://wiki.asterisk.org/wiki/display/AST/Asterisk+11+Projects
https://wiki.asterisk.org/wiki/display/AST/Hangup+handlers

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.  

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.  


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.  

Push a hangup handler onto a channel:
same => n,Set(CHANNEL(hangup_handler_push)=[[context,]exten,]priority[(arg1[,...][,argN])]);

Pop a hangup handler off a channel and optionally push a replacement:
same => n,Set(CHANNEL(hangup_handler_pop)=[[[context,]exten,]priority[(arg1[,...][,argN])]]);

Pop all hangup handlers off a channel and optionally push a replacement:
same => n,Set(CHANNEL(hangup_handler_replace)=[[[context,]exten,]priority[(arg1[,...][,argN])]]);

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

Single channel:
core show hanguphandlers <chan>

Output:
Channel       Handler
<chan-name>   <first handler to execute>
              <second handler to execute>
              <third handler to execute>

All channels:
core show hanguphandlers all

Output:
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>


This addresses bug ASTERISK-19549.
    https://issues.asterisk.org/jira/browse/ASTERISK-19549


Diffs
-----

  /trunk/.cleancount 369297 
  /trunk/apps/app_dial.c 369297 
  /trunk/apps/app_followme.c 369297 
  /trunk/apps/app_queue.c 369297 
  /trunk/channels/chan_local.c 369297 
  /trunk/configs/cdr.conf.sample 369297 
  /trunk/funcs/func_channel.c 369297 
  /trunk/include/asterisk/channel.h 369297 
  /trunk/include/asterisk/pbx.h 369297 
  /trunk/main/autoservice.c 369297 
  /trunk/main/channel.c 369297 
  /trunk/main/channel_internal_api.c 369297 
  /trunk/main/features.c 369297 
  /trunk/main/pbx.c 369297 

Diff: https://reviewboard.asterisk.org/r/2002/diff


Testing
-------

Attached hangup handlers to channels and done the following kinds of calls:
Simple A to B call.
DTMF attended transfer
DTMF blind transfer

Hangup handlers were executed when expected.


Thanks,

rmudgett

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20120623/935d8d6d/attachment-0001.htm>