Merge changes dealing with support for Digium phones.

Presence support has been added. This is accomplished by
allowing for presence hints in addition to device state
hints. A dialplan function called PRESENCE_STATE has been
added to allow for setting and reading presence. Presence
can be transmitted to Digium phones using custom XML
elements in a PIDF presence document.

Voicemail has new APIs that allow for moving, removing,
forwarding, and playing messages. Messages have had a new
unique message ID added to them so that the APIs will work
reliably. The state of a voicemail mailbox can be obtained
using an API that allows one to get a snapshot of the mailbox.
A voicemail Dialplan App called VoiceMailPlayMsg has been
added to be able to play back a specific message.

Configuration hooks have been added. Configuration hooks
allow for a piece of code to be executed when a specific
configuration file is loaded by a specific module. This is
useful for modules that are dependent on the configuration
of other modules.

chan_sip now has a public method that allows for a custom
SIP INFO request to be sent mid-dialog. Digium phones use
this in order to display progress bars when files are played.

Messaging support has been expanded a bit. The main
visible difference is the addition of an AMI action
MessageSend.

Finally, a ParkingLots manager action has been added in order
to get a list of parking lots.



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

1 files changed, 154 insertions, 0 deletions

diff --git a/include/asterisk/presencestate.h b/include/asterisk/presencestate.h
new file mode 100644
index 000000000..dbbe5dcab
--- /dev/null
+++ b/include/asterisk/presencestate.h
@@ -0,0 +1,154 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2011, Digium, Inc.
+ *
+ * David Vossel <dvossel@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.
+ */
+
+/*! \file
+ * \brief Presence state management
+ */
+
+#ifndef _ASTERISK_PRESSTATE_H
+#define _ASTERISK_PRESSTATE_H
+
+enum ast_presence_state {
+	AST_PRESENCE_NOT_SET = 0,
+	AST_PRESENCE_UNAVAILABLE,
+	AST_PRESENCE_AVAILABLE,
+	AST_PRESENCE_AWAY,
+	AST_PRESENCE_XA,
+	AST_PRESENCE_CHAT,
+	AST_PRESENCE_DND,
+	/* This is not something that a user can
+	 * set his presence to. Rather, this is returned
+	 * to indicate that presence is in some invalid
+	 * state
+	 */
+	AST_PRESENCE_INVALID,
+};
+
+/*! \brief Presence state provider call back */
+typedef enum ast_presence_state (*ast_presence_state_prov_cb_type)(const char *data, char **subtype, char **message);
+
+/*!
+ * \brief Convert presence state to text string for output
+ *
+ * \param state Current presence state
+ */
+const char *ast_presence_state2str(enum ast_presence_state state);
+
+/*!
+ * \brief Convert presence state from text to integer value
+ *
+ * \param val The text representing the presence state.  Valid values are anything
+ *        that comes after AST_PRESENCE_ in one of the defined values.
+ *
+ * \return The AST_PRESENCE_ integer value
+ */
+enum ast_presence_state ast_presence_state_val(const char *val);
+
+/*!
+ * \brief Asks a presence state provider for the current presence state.
+ *
+ * \param presence_provider, The presence provider to retrieve the state from.
+ * \param subtype, The output paramenter to store the subtype string in. Must be freed if returned
+ * \param message, The output paramenter to store the message string in. Must be freed if returned
+ *
+ * \retval presence state value on success,
+ * \retval -1 on failure.
+ */
+enum ast_presence_state ast_presence_state(const char *presence_provider, char **subtype, char **message);
+
+/*!
+ * \brief Asks a presence state provider for the current presence state, bypassing the event cache
+ *
+ * \details Some presence state providers may perform transformations on presence data when it is
+ * requested (such as a base64 decode). In such instances, use of the event cache is not suitable
+ * and should be bypassed.
+ *
+ * \param presence_provider, The presence provider to retrieve the state from.
+ * \param subtype, The output paramenter to store the subtype string in. Must be freed if returned
+ * \param message, The output paramenter to store the message string in. Must be freed if returned
+ *
+ * \retval presence state value on success,
+ * \retval -1 on failure.
+ */
+enum ast_presence_state ast_presence_state_nocache(const char *presence_provider, char **subtype, char **message);
+
+/*!
+ * \brief Notify the world that a presence provider state changed.
+ *
+ * \param state the new presence state
+ * \param subtype the new presence subtype
+ * \param message the new presence message
+ * \param fmt Presence entity whose state has changed
+ *
+ * The new state of the entity will be sent off to any subscribers
+ * of the presence state. It will also be stored in the internal event
+ * cache.
+ *
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_presence_state_changed(enum ast_presence_state state,
+		const char *subtype,
+		const char *message,
+		const char *fmt, ...)
+	__attribute__((format(printf, 4, 5)));
+
+/*!
+ * \brief Notify the world that a presence provider state changed.
+ *
+ * \param state the new presence state
+ * \param subtype the new presence subtype
+ * \param message the new presence message
+ * \param presence_provider Presence entity whose state has changed
+ *
+ * The new state of the entity will be sent off to any subscribers
+ * of the presence state. It will also be stored in the internal event
+ * cache.
+ *
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_presence_state_changed_literal(enum ast_presence_state state,
+		const char *subtype,
+		const char *message,
+		const char *presence_provider);
+
+/*!
+ * \brief Add presence state provider
+ *
+ * \param label to use in hint, like label:object
+ * \param callback Callback
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_presence_state_prov_add(const char *label, ast_presence_state_prov_cb_type callback);
+
+/*!
+ * \brief Remove presence state provider
+ *
+ * \param label to use in hint, like label:object
+ *
+ * \retval -1 on failure
+ * \retval 0 on success
+ */
+int ast_presence_state_prov_del(const char *label);
+
+int ast_presence_state_engine_init(void);
+#endif
+