Hangup handlers - Dialplan subroutines that run when the channel hangs up.

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.

(closes issue ASTERISK-19549)
Reported by: Mark Murawski
Tested by: rmudgett

Review: https://reviewboard.asterisk.org/r/2002/


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@369493 65c4cc65-6c06-0410-ace0-fbb531ad65f3

2 files changed, 86 insertions, 0 deletions

diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index 06be07b2a..4f2cc8849 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -731,6 +731,15 @@ enum ast_t38_state {
 	T38_STATE_NEGOTIATED,	/*!< T38 established */
 };
 
+/*! Hangup handler instance node. */
+struct ast_hangup_handler {
+	/*! Next hangup handler node. */
+	AST_LIST_ENTRY(ast_hangup_handler) node;
+	/*! Hangup handler arg string passed to the Gosub application */
+	char args[0];
+};
+
+AST_LIST_HEAD_NOLOCK(ast_hangup_handler_list, ast_hangup_handler);
 AST_LIST_HEAD_NOLOCK(ast_datastore_list, ast_datastore);
 AST_LIST_HEAD_NOLOCK(ast_autochan_list, ast_autochan);
 AST_LIST_HEAD_NOLOCK(ast_readq_list, ast_frame);
@@ -2198,6 +2207,17 @@ int ast_autoservice_start(struct ast_channel *chan);
 int ast_autoservice_stop(struct ast_channel *chan);
 
 /*!
+ * \brief Put chan into autoservice while hanging up peer.
+ * \since 11.0
+ *
+ * \param chan Chan to put into autoservice.
+ * \param peer Chan to run hangup handlers and hangup.
+ *
+ * \return Nothing
+ */
+void ast_autoservice_chan_hangup_peer(struct ast_channel *chan, struct ast_channel *peer);
+
+/*!
  * \brief Ignore certain frame types
  * \note Normally, we cache DTMF, IMAGE, HTML, TEXT, and CONTROL frames
  * while a channel is in autoservice and queue them up when taken out of
@@ -3748,6 +3768,7 @@ void ast_channel_whentohangup_set(struct ast_channel *chan, struct timeval *valu
 void ast_channel_varshead_set(struct ast_channel *chan, struct varshead *value);
 
 /* List getters */
+struct ast_hangup_handler_list *ast_channel_hangup_handlers(struct ast_channel *chan);
 struct ast_datastore_list *ast_channel_datastores(struct ast_channel *chan);
 struct ast_autochan_list *ast_channel_autochans(struct ast_channel *chan);
 struct ast_readq_list *ast_channel_readq(struct ast_channel *chan);
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index 2305f3910..bea7e5ebf 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -368,6 +368,71 @@ struct ast_pbx_args {
 enum ast_pbx_result ast_pbx_run_args(struct ast_channel *c, struct ast_pbx_args *args);
 
 /*!
+ * \brief Run the h exten from the given context.
+ * \since 11.0
+ *
+ * \param chan Channel to run the h exten on.
+ * \param context Context the h exten is in.
+ *
+ * \return Nothing
+ */
+void ast_pbx_h_exten_run(struct ast_channel *chan, const char *context);
+
+/*!
+ * \brief Run all hangup handlers on the channel.
+ * \since 11.0
+ *
+ * \param chan Channel to run the hangup handlers on.
+ *
+ * \note Absolutely _NO_ channel locks should be held before calling this function.
+ *
+ * \retval Zero if no hangup handlers run.
+ * \retval non-zero if hangup handlers were run.
+ */
+int ast_pbx_hangup_handler_run(struct ast_channel *chan);
+
+/*!
+ * \brief Init the hangup handler container on a channel.
+ * \since 11.0
+ *
+ * \param chan Channel to init the hangup handler container on.
+ *
+ * \return Nothing
+ */
+void ast_pbx_hangup_handler_init(struct ast_channel *chan);
+
+/*!
+ * \brief Destroy the hangup handler container on a channel.
+ * \since 11.0
+ *
+ * \param chan Channel to destroy the hangup handler container on.
+ *
+ * \return Nothing
+ */
+void ast_pbx_hangup_handler_destroy(struct ast_channel *chan);
+
+/*!
+ * \brief Pop the top of the channel hangup handler stack.
+ * \since 11.0
+ *
+ * \param chan Channel to push the hangup handler onto.
+ *
+ * \retval TRUE if a handler was popped off of the stack.
+ */
+int ast_pbx_hangup_handler_pop(struct ast_channel *chan);
+
+/*!
+ * \brief Push the given hangup handler onto the channel hangup handler stack.
+ * \since 11.0
+ *
+ * \param chan Channel to push the hangup handler onto.
+ * \param handler Gosub application parameter string.
+ *
+ * \return Nothing
+ */
+void ast_pbx_hangup_handler_push(struct ast_channel *chan, const char *handler);
+
+/*!
  * \brief Add and extension to an extension context.
  *
  * \param context context to add the extension to