CLI: Create ast_cli_completion_vector.
[asterisk/asterisk.git] / include / asterisk / presencestate.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2011, Digium, Inc.
5  *
6  * David Vossel <dvossel@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Presence state management
21  */
22
23 #ifndef _ASTERISK_PRESSTATE_H
24 #define _ASTERISK_PRESSTATE_H
25
26 enum ast_presence_state {
27         AST_PRESENCE_NOT_SET = 0,
28         AST_PRESENCE_UNAVAILABLE,
29         AST_PRESENCE_AVAILABLE,
30         AST_PRESENCE_AWAY,
31         AST_PRESENCE_XA,
32         AST_PRESENCE_CHAT,
33         AST_PRESENCE_DND,
34         /* This is not something that a user can
35          * set his presence to. Rather, this is returned
36          * to indicate that presence is in some invalid
37          * state
38          */
39         AST_PRESENCE_INVALID,
40 };
41
42 /*! \brief Presence state provider call back */
43 typedef enum ast_presence_state (*ast_presence_state_prov_cb_type)(const char *data, char **subtype, char **message);
44
45 /*!
46  * \brief Convert presence state to text string for output
47  *
48  * \param state Current presence state
49  */
50 const char *ast_presence_state2str(enum ast_presence_state state);
51
52 /*!
53  * \brief Convert presence state from text to integer value
54  *
55  * \param val The text representing the presence state.  Valid values are anything
56  *        that comes after AST_PRESENCE_ in one of the defined values.
57  *
58  * \return The AST_PRESENCE_ integer value
59  */
60 enum ast_presence_state ast_presence_state_val(const char *val);
61
62 /*!
63  * \brief Asks a presence state provider for the current presence state.
64  *
65  * \param presence_provider The presence provider to retrieve the state from.
66  * \param subtype The output paramenter to store the subtype string in. Must be freed if returned
67  * \param message The output paramenter to store the message string in. Must be freed if returned
68  *
69  * \retval presence state value on success,
70  * \retval -1 on failure.
71  */
72 enum ast_presence_state ast_presence_state(const char *presence_provider, char **subtype, char **message);
73
74 /*!
75  * \brief Asks a presence state provider for the current presence state, bypassing the event cache
76  *
77  * \details Some presence state providers may perform transformations on presence data when it is
78  * requested (such as a base64 decode). In such instances, use of the event cache is not suitable
79  * and should be bypassed.
80  *
81  * \param presence_provider The presence provider to retrieve the state from.
82  * \param subtype The output paramenter to store the subtype string in. Must be freed if returned
83  * \param message The output paramenter to store the message string in. Must be freed if returned
84  *
85  * \retval presence state value on success,
86  * \retval -1 on failure.
87  */
88 enum ast_presence_state ast_presence_state_nocache(const char *presence_provider, char **subtype, char **message);
89
90 /*!
91  * \brief Notify the world that a presence provider state changed.
92  *
93  * \param state the new presence state
94  * \param subtype the new presence subtype
95  * \param message the new presence message
96  * \param fmt Presence entity whose state has changed
97  *
98  * The new state of the entity will be sent off to any subscribers
99  * of the presence state. It will also be stored in the internal event
100  * cache.
101  *
102  * \retval 0 Success
103  * \retval -1 Failure
104  */
105 int ast_presence_state_changed(enum ast_presence_state state,
106                 const char *subtype,
107                 const char *message,
108                 const char *fmt, ...)
109         __attribute__((format(printf, 4, 5)));
110
111 /*!
112  * \brief Notify the world that a presence provider state changed.
113  *
114  * \param state the new presence state
115  * \param subtype the new presence subtype
116  * \param message the new presence message
117  * \param presence_provider Presence entity whose state has changed
118  *
119  * The new state of the entity will be sent off to any subscribers
120  * of the presence state. It will also be stored in the internal event
121  * cache.
122  *
123  * \retval 0 Success
124  * \retval -1 Failure
125  */
126 int ast_presence_state_changed_literal(enum ast_presence_state state,
127                 const char *subtype,
128                 const char *message,
129                 const char *presence_provider);
130
131 /*!
132  * \brief Add presence state provider
133  *
134  * \param label to use in hint, like label:object
135  * \param callback Callback
136  *
137  * \retval 0 success
138  * \retval -1 failure
139  */
140 int ast_presence_state_prov_add(const char *label, ast_presence_state_prov_cb_type callback);
141
142 /*!
143  * \brief Remove presence state provider
144  *
145  * \param label to use in hint, like label:object
146  *
147  * \retval -1 on failure
148  * \retval 0 on success
149  */
150 int ast_presence_state_prov_del(const char *label);
151
152 /*!
153  * \brief Get presence state message type
154  * \retval Stasis message type for presence state messages
155  * \since 12
156  */
157 struct stasis_message_type *ast_presence_state_message_type(void);
158
159 /*!
160  * \brief Get presence state topic
161  * \retval Stasis topic for presence state messages
162  * \since 12
163  */
164 struct stasis_topic *ast_presence_state_topic_all(void);
165
166 /*!
167  * \brief Get caching presence state topic
168  * \retval Caching Stasis topic for presence state messages
169  * \since 12
170  */
171 struct stasis_topic *ast_presence_state_topic_cached(void);
172
173 /*!
174  * \brief Backend cache for ast_presence_state_topic_cached()
175  * \retval Cache of \ref ast_presence_state_message.
176  * \since 12
177  */
178 struct stasis_cache *ast_presence_state_cache(void);
179
180 /*!
181  * \brief Stasis message payload representing a presence state update
182  * \since 12
183  */
184 struct ast_presence_state_message {
185                 AST_DECLARE_STRING_FIELDS(
186                         AST_STRING_FIELD(provider);     /*!< Provider that produced this presence state message */
187                         AST_STRING_FIELD(subtype);      /*!< Subtype associated with this presence state message */
188                         AST_STRING_FIELD(message);      /*!< The message to convey */
189                 );
190                 enum ast_presence_state state;          /*!< The state associated with this presence state message */
191 };
192
193 int ast_presence_state_engine_init(void);
194 #endif
195