From fddd385eb1b20c850e0d94e96a5951f52bc3c71f Mon Sep 17 00:00:00 2001
From: Olle Johansson <oej@edvina.net>
Date: Thu, 30 Nov 2006 17:15:54 +0000
Subject: [PATCH] Adding some generic docs on extension and device states -
watchers and providers
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@48139 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---
include/asterisk/doxyref.h | 1 +
main/devicestate.c | 45 +++++++++++++++++++++++++++++++++++++-
2 files changed, 45 insertions(+), 1 deletion(-)
diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h
index 5d6716fae0..dc5fd7bf48 100644
--- a/include/asterisk/doxyref.h
+++ b/include/asterisk/doxyref.h
@@ -67,6 +67,7 @@
*
* \arg \ref AstThreadStorage
* \arg \ref DataStores
+ * \arg \ref AstExtState
*
* \subsection model_txt Generic Model
* \verbinclude model.txt
diff --git a/main/devicestate.c b/main/devicestate.c
index 3f38930d17..0711a10021 100644
--- a/main/devicestate.c
+++ b/main/devicestate.c
@@ -20,8 +20,51 @@
*
* \brief Device state management
*
+ *
* \author Mark Spencer <markster@digium.com>
*/
+/*! \page AstExtState Extension and device states in Asterisk
+ *
+ * Asterisk has an internal system that reports states
+ * for an extension. By using the dialplan priority -1,
+ * also called a \b hint, a connection can be made from an
+ * extension to one or many devices. The state of the extension
+ * now depends on the combined state of the devices.
+ *
+ * The device state is basically based on the current calls.
+ * If the devicestate engine can find a call from or to the
+ * device, it's in use.
+ *
+ * Some channel drivers implement a callback function for
+ * a better level of reporting device states. The SIP channel
+ * has a complicated system for this, which is improved
+ * by adding call limits to the configuration.
+ *
+ * Functions that want to check the status of an extension
+ * register themself as a \b watcher.
+ * Watchers in this system can subscribe either to all extensions
+ * or just a specific extensions.
+ *
+ * For non-device related states, there's an API called
+ * devicestateproviders. This is an extendable system for
+ * delivering state information from outside sources or
+ * functions within Asterisk. Currently we have providers
+ * for app_meetme.c - the conference bridge - and call
+ * parking (metermaids).
+ *
+ * There are manly three subscribers to extension states
+ * within Asterisk:
+ * - AMI, the manager interface
+ * - app_queue.c - the Queue dialplan application
+ * - SIP subscriptions, a.k.a. "blinking lamps" or
+ * "buddy lists"
+ *
+ * None of these handle user states, like an IM presense
+ * system. res_jabber.c can subscribe and watch such states
+ * in jabber/xmpp based systems.
+ *
+ *
+ */
#include "asterisk.h"
@@ -69,7 +112,7 @@ static AST_LIST_HEAD_STATIC(devstate_provs, devstate_prov);
/*! \brief A device state watcher (callback) */
struct devstate_cb {
void *data;
- ast_devstate_cb_type callback;
+ ast_devstate_cb_type callback; /*!< Where to report when state changes */
AST_LIST_ENTRY(devstate_cb) list;
};
--
GitLab