ARI: Implement device state API

Created a data model and implemented functionality for an ARI device state
resource.  The following operations have been added that allow a user to
manipulate an ARI controlled device:

Create/Change the state of an ARI controlled device
PUT    /deviceStates/{deviceName}&{deviceState}

Retrieve all ARI controlled devices
GET    /deviceStates

Retrieve the current state of a device
GET    /deviceStates/{deviceName}

Destroy a device-state controlled by ARI
DELETE /deviceStates/{deviceName}

The ARI controlled device must begin with 'Stasis:'.  An example controlled
device name would be Stasis:Example.  A 'DeviceStateChanged' event has also
been added so that an application can subscribe and receive device change
events.  Any device state, ARI controlled or not, can be subscribed to.

While adding the event, the underlying subscription control mechanism was
refactored so that all current and future resource subscriptions would be
the same.  Each event resource must now register itself in order to be able
to properly handle [un]subscribes.

(issue ASTERISK-22838)
Reported by: Matt Jordan
Review: https://reviewboard.asterisk.org/r/3025/
........

Merged revisions 403134 from http://svn.asterisk.org/svn/asterisk/branches/12


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

3 files changed, 212 insertions, 0 deletions

diff --git a/include/asterisk/devicestate.h b/include/asterisk/devicestate.h
index a3267387f..565e01341 100644
--- a/include/asterisk/devicestate.h
+++ b/include/asterisk/devicestate.h
@@ -325,6 +325,15 @@ struct stasis_cache *ast_device_state_cache(void);
 struct stasis_message_type *ast_device_state_message_type(void);
 
 /*!
+ * \brief Clear the device from the stasis cache.
+ * \param The device to clear
+ * \retval 0 if successful
+ * \retval -1 nothing to clear
+ * \since 12
+ */
+int ast_device_state_clear_cache(const char *device);
+
+/*!
  * \brief Initialize the device state core
  * \retval 0 Success
  * \retval -1 Failure
diff --git a/include/asterisk/stasis_app.h b/include/asterisk/stasis_app.h
index 4ef55b193..0c22a6c30 100644
--- a/include/asterisk/stasis_app.h
+++ b/include/asterisk/stasis_app.h
@@ -111,6 +111,18 @@ void stasis_app_unregister(const char *app_name);
  */
 int stasis_app_send(const char *app_name, struct ast_json *message);
 
+/*! \brief Forward declare app */
+struct stasis_app;
+
+/*!
+ * \brief Retrieve an application's name
+ *
+ * \param app An application
+ *
+ * \return The name of the application.
+ */
+const char *stasis_app_name(const struct stasis_app *app);
+
 /*!
  * \brief Return the JSON representation of a Stasis application.
  *
@@ -121,6 +133,102 @@ int stasis_app_send(const char *app_name, struct ast_json *message);
  */
 struct ast_json *stasis_app_to_json(const char *app_name);
 
+/*!
+ * \brief Event source information and callbacks.
+ */
+struct stasis_app_event_source {
+	/*! \brief The scheme to match against on [un]subscribes */
+	const char *scheme;
+
+	/*!
+	 * \brief Find an event source data object by the given id/name.
+	 *
+	 * \param app Application
+	 * \param id A unique identifier to search on
+	 *
+	 * \return The data object associated with the id/name.
+	 */
+	void *(*find)(const struct stasis_app *app, const char *id);
+
+	/*!
+	 * \brief Subscribe an application to an event source.
+	 *
+	 * \param app Application
+	 * \param obj an event source data object
+	 *
+	 * \return 0 on success, failure code otherwise
+	 */
+	int (*subscribe)(struct stasis_app *app, void *obj);
+
+	/*!
+	 * \brief Cancel the subscription an app has to an event source.
+	 *
+	 * \param app Application
+	 * \param id a previously subscribed object id
+	 *
+	 * \return 0 on success, failure code otherwise
+	 */
+	int (*unsubscribe)(struct stasis_app *app, const char *id);
+
+	/*!
+	 * \brief Find an event source by the given id/name.
+	 *
+	 * \param app Application
+	 * \param id A unique identifier to check
+	 *
+	 * \return true if id is subscribed, false otherwise.
+	 */
+	int (*is_subscribed)(struct stasis_app *app, const char *id);
+
+	/*!
+	 * \brief Convert event source data to json
+	 *
+	 * \param app Application
+	 * \param id json object to fill
+	 */
+	void (*to_json)(const struct stasis_app *app, struct ast_json *json);
+
+	/*! Next item in the list */
+	AST_LIST_ENTRY(stasis_app_event_source) next;
+};
+
+/*!
+ * \brief Register an application event source.
+ *
+ * \param obj the event source to register
+ */
+void stasis_app_register_event_source(struct stasis_app_event_source *obj);
+
+/*!
+ * \brief Register core event sources.
+ */
+void stasis_app_register_event_sources(void);
+
+/*!
+ * \brief Checks to see if the given object is a core event source
+ *
+ * \note core event sources are currently only endpoint, bridge, and channel.
+ *
+ * \param obj event source object to check
+ *
+ * \return non-zero if core event source, otherwise 0 (false)
+
+ */
+int stasis_app_is_core_event_source(struct stasis_app_event_source *obj);
+
+/*!
+ * \brief Unregister an application event source.
+ *
+ * \param obj the event source to unregister
+ */
+void stasis_app_unregister_event_source(struct stasis_app_event_source *obj);
+
+/*!
+ * \brief Unregister core event sources.
+ */
+void stasis_app_unregister_event_sources(void);
+
+
 /*! \brief Return code for stasis_app_[un]subscribe */
 enum stasis_app_subscribe_res {
 	STASIS_ASR_OK,
diff --git a/include/asterisk/stasis_app_device_state.h b/include/asterisk/stasis_app_device_state.h
new file mode 100644
index 000000000..2bc521a04
--- /dev/null
+++ b/include/asterisk/stasis_app_device_state.h
@@ -0,0 +1,95 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2013, Digium, Inc.
+ *
+ * Kevin Harwell <kharwell@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+#ifndef _ASTERISK_STASIS_APP_DEVICE_STATE_H
+#define _ASTERISK_STASIS_APP_DEVICE_STATE_H
+
+/*! \file
+ *
+ * \brief Stasis Application Device State API. See \ref res_stasis "Stasis
+ * Application API" for detailed documentation.
+ *
+ * \author Kevin Harwell <kharwell@digium.com>
+ * \since 12
+ */
+
+#include "asterisk/app.h"
+#include "asterisk/stasis_app.h"
+
+/*! @{ */
+
+/*!
+ * \brief Convert device state to json.
+ *
+ * \param name the name of the device
+ * \param state the device state
+ * \return JSON representation.
+ * \return \c NULL on error.
+ */
+struct ast_json *stasis_app_device_state_to_json(
+	const char *name, enum ast_device_state state);
+
+/*!
+ * \brief Convert device states to json array.
+ *
+ * \return JSON representation.
+ * \return \c NULL on error.
+ */
+struct ast_json *stasis_app_device_states_to_json(void);
+
+/*! Stasis device state application result codes */
+enum stasis_device_state_result {
+	/*! Application controlled device state is okay */
+	STASIS_DEVICE_STATE_OK,
+	/*! The device name is not application controlled */
+	STASIS_DEVICE_STATE_NOT_CONTROLLED,
+	/*! The application controlled device name is missing */
+	STASIS_DEVICE_STATE_MISSING,
+	/*! The application controlled device is unknown */
+	STASIS_DEVICE_STATE_UNKNOWN,
+	/*! The application controlled device has subscribers */
+	STASIS_DEVICE_STATE_SUBSCRIBERS
+};
+
+/*!
+ * \brief Changes the state of a device controlled by ARI.
+ *
+ * \note The controlled device must be prefixed with 'Stasis:'.
+ * \note Implicitly creates the device state.
+ *
+ * \param name the name of the ARI controlled device
+ * \param value a valid device state value
+ *
+ * \return a stasis device state application result.
+ */
+enum stasis_device_state_result stasis_app_device_state_update(
+	const char *name, const char *value);
+
+/*!
+ * \brief Delete a device controlled by ARI.
+ *
+ * \param name the name of the ARI controlled device
+ *
+ * \returna stasis device state application result.
+ */
+enum stasis_device_state_result stasis_app_device_state_delete(
+	const char *name);
+
+/*! @} */
+
+#endif /* _ASTERISK_STASIS_APP_DEVICE_STATE_H */