Extend extension state callbacks to have more information.

Quote from review board:

This patch extends the extension state callbacks so that monitoring channels
(as chan_sip) get more information of the devices which are responsible for
an extension state change. The additional information is needed by chan_sip
to present names/numbers of the caller and callee in an early-state SIP
notification. Users of extenstion state callback not interested in the
additional information are not affected by the changes.

Motivation: to present the involved party's name/number in an early-state
nofification (used by the notified device as a pickup offer) one after another
so that a user can see which call he will pick up in an undirected pickup.
Such a pickup offer to a user shall indicate the same call (number/name-A calls
number/name-B) as the call which would be picked up when an undirected pickup
is executed.


Users interested in additional state info must use the new functions
ast_extension_state_add_extended() resp.
ast_extension_state_add_destroy_extended() to register an extended state
callback. When the callback is registered this way, an extra member
device_state_info of struct ast_state_cb_info is passed to the callback in
addition to the aggregated extension state. This container holds an object for
every device of the monitored extension hint consisting of the device name, the
device state and a channel reference to the channel which (presumably) caused
the device state.

The information is used by chan_sip for early-state notifications. When the
state of a device changes and the new state contains AST_EVENT_RINGING, an
early-state notification is sent to the subscribed devices with the
caller/callee names/numbers of the oldest ringing channel of the monitored
extension. The notified user may then invoke a direct pickup, which will pickup
exactly this channel.

Users of the old non-extended callbacks will only be called when the aggregated
state did change (same behavior as before). Users of the extended callback will
also be called when the state is unchanged but does contain AST_EVENT_RINGING.
That could be the case if two channels are ringing at one device and one of
them hangs up, so the aggregated state does not change. This way the monitoring
channel can create a new early-state notification with the now ringing
party-ids.

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

This contribution comes from Guenther Kelleter



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

1 files changed, 64 insertions, 0 deletions

diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index b1e820983..7e374345c 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -83,9 +83,16 @@ enum ast_state_cb_update_reason {
 	AST_HINT_UPDATE_PRESENCE = 2,
 };
 
+struct ast_device_state_info {
+	enum ast_device_state device_state;
+	struct ast_channel *causing_channel;
+	char device_name[1];
+};
+
 struct ast_state_cb_info {
 	enum ast_state_cb_update_reason reason;
 	enum ast_extension_states exten_state;
+	struct ao2_container *device_state_info; /* holds ast_device_state_info, must be referenced by callback if stored */
 	enum ast_presence_state presence_state;
 	const char *presence_subtype;
 	const char *presence_message;
@@ -483,6 +490,20 @@ enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devst
 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
 
 /*!
+ * \brief Uses hint and devicestate callback to get the extended state of an extension
+ * \since 11
+ *
+ * \param c this is not important
+ * \param context which context to look in
+ * \param exten which extension to get state
+ * \param[out] device_state_info ptr to an ao2_container with extended state info, must be unref'd after use.
+ *
+ * \return extension state as defined in the ast_extension_states enum
+ */
+int ast_extension_state_extended(struct ast_channel *c, const char *context, const char *exten,
+	struct ao2_container **device_state_info);
+
+/*!
  * \brief Uses hint and presence state callback to get the presence state of an extension
  *
  * \param c this is not important
@@ -531,6 +552,30 @@ int ast_extension_state_add_destroy(const char *context, const char *exten,
 	ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
 
 /*!
+ * \brief Registers an extended state change callback with destructor.
+ * \since 11
+ *
+ * \param context which context to look in
+ * \param exten which extension to get state
+ * \param change_cb callback to call if state changed
+ * \param destroy_cb callback to call when registration destroyed.
+ * \param data to pass to callback
+ *
+ * \note The change_cb is called if the state of an extension is changed.
+ * The extended state is passed to the callback in the device_state_info
+ * member of ast_state_cb_info.
+ *
+ * \note The destroy_cb is called when the registration is
+ * deleted so the registerer can release any associated
+ * resources.
+ *
+ * \retval -1 on failure
+ * \retval ID on success
+ */
+int ast_extension_state_add_destroy_extended(const char *context, const char *exten,
+	ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
+
+/*!
  * \brief Registers a state change callback
  *
  * \param context which context to look in
@@ -547,6 +592,25 @@ int ast_extension_state_add(const char *context, const char *exten,
 	ast_state_cb_type change_cb, void *data);
 
 /*!
+ * \brief Registers an extended state change callback
+ * \since 11
+ *
+ * \param context which context to look in
+ * \param exten which extension to get state
+ * \param change_cb callback to call if state changed
+ * \param data to pass to callback
+ *
+ * \note The change_cb is called if the state of an extension is changed.
+ * The extended state is passed to the callback in the device_state_info
+ * member of ast_state_cb_info.
+ *
+ * \retval -1 on failure
+ * \retval ID on success
+ */
+int ast_extension_state_add_extended(const char *context, const char *exten,
+	ast_state_cb_type change_cb, void *data);
+
+/*!
  * \brief Deletes a registered state change callback by ID
  *
  * \param id of the registered state callback to delete