31ed0b28a4e46291521b32736f2c655a190807c7
[asterisk/asterisk.git] / include / asterisk / message.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2010, Digium, Inc.
5  *
6  * Russell Bryant <russell@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 /*!
20  * \file
21  *
22  * \brief Out-of-call text message support
23  *
24  * \author Russell Bryant <russell@digium.com>
25  *
26  * The purpose of this API is to provide support for text messages that
27  * are not session based.  The messages are passed into the Asterisk core
28  * to be routed through the dialplan and potentially sent back out through
29  * a message technology that has been registered through this API.
30  */
31
32 #ifndef __AST_MESSAGE_H__
33 #define __AST_MESSAGE_H__
34
35 #if defined(__cplusplus) || defined(c_plusplus)
36 extern "C" {
37 #endif
38
39 /*!
40  * \brief A text message.
41  *
42  * This is an opaque type that represents a text message.
43  */
44 struct ast_msg;
45
46 /*!
47  * \brief A message technology
48  *
49  * A message technology is capable of transmitting text messages.
50  */
51 struct ast_msg_tech {
52         /*!
53          * \brief Name of this message technology
54          *
55          * This is the name that comes at the beginning of a URI for messages
56          * that should be sent to this message technology implementation.
57          * For example, messages sent to "xmpp:rbryant@digium.com" would be
58          * passed to the ast_msg_tech with a name of "xmpp".
59          */
60         const char * const name;
61         /*!
62          * \brief Send a message.
63          *
64          * \param msg the message to send
65          * \param to the URI of where the message is being sent
66          * \param from the URI of where the message was sent from
67          *
68          * The fields of the ast_msg are guaranteed not to change during the
69          * duration of this function call.
70          *
71          * \retval 0 success
72          * \retval non-zero failure
73          */
74         int (* const msg_send)(const struct ast_msg *msg, const char *to, const char *from);
75 };
76
77 /*!
78  * \brief Register a message technology
79  *
80  * \retval 0 success
81  * \retval non-zero failure
82  */
83 int ast_msg_tech_register(const struct ast_msg_tech *tech);
84
85 /*!
86  * \brief Unregister a message technology.
87  *
88  * \retval 0 success
89  * \retval non-zero failure
90  */
91 int ast_msg_tech_unregister(const struct ast_msg_tech *tech);
92
93 /*!
94  * \brief Allocate a message.
95  *
96  * Allocate a message for the purposes of passing it into the Asterisk core
97  * to be routed through the dialplan.  If ast_msg_queue() is not called, this
98  * message must be destroyed using ast_msg_destroy().  Otherwise, the message
99  * core code will take care of it.
100  *
101  * \return A message object. This function will return NULL if an allocation
102  *         error occurs.
103  */
104 struct ast_msg *ast_msg_alloc(void);
105
106 /*!
107  * \brief Destroy an ast_msg
108  *
109  * This should only be called on a message if it was not
110  * passed on to ast_msg_queue().
111  *
112  * \return NULL, always.
113  */
114 struct ast_msg *ast_msg_destroy(struct ast_msg *msg);
115
116 /*!
117  * \brief Bump a msg's ref count
118  */
119 struct ast_msg *ast_msg_ref(struct ast_msg *msg);
120
121 /*!
122  * \brief Set the 'to' URI of a message
123  *
124  * \retval 0 success
125  * \retval -1 failure
126  */
127 int __attribute__((format(printf, 2, 3)))
128                 ast_msg_set_to(struct ast_msg *msg, const char *fmt, ...);
129
130 /*!
131  * \brief Set the 'from' URI of a message
132  *
133  * \retval 0 success
134  * \retval -1 failure
135  */
136 int __attribute__((format(printf, 2, 3)))
137                 ast_msg_set_from(struct ast_msg *msg, const char *fmt, ...);
138
139 /*!
140  * \brief Set the 'body' text of a message (in UTF-8)
141  *
142  * \retval 0 success
143  * \retval -1 failure
144  */
145 int __attribute__((format(printf, 2, 3)))
146                 ast_msg_set_body(struct ast_msg *msg, const char *fmt, ...);
147
148 /*!
149  * \brief Set the dialplan context for this message
150  *
151  * \retval 0 success
152  * \retval -1 failure
153  */
154 int __attribute__((format(printf, 2, 3)))
155                 ast_msg_set_context(struct ast_msg *msg, const char *fmt, ...);
156
157 /*!
158  * \brief Set the dialplan extension for this message
159  *
160  * \retval 0 success
161  * \retval -1 failure
162  */
163 int __attribute__((format(printf, 2, 3)))
164                 ast_msg_set_exten(struct ast_msg *msg, const char *fmt, ...);
165         
166 /*!
167  * \brief Set a variable on the message going to the dialplan.
168  * \note Setting a variable that already exists overwrites the existing variable value
169  *
170  * \param name Name of variable to set
171  * \param value Value of variable to set
172  *
173  * \retval 0 success
174  * \retval -1 failure
175  */
176 int ast_msg_set_var(struct ast_msg *msg, const char *name, const char *value);
177
178 /*!
179  * \brief Set a variable on the message being sent to a message tech directly.
180  * \note Setting a variable that already exists overwrites the existing variable value
181  *
182  * \param name Name of variable to set
183  * \param value Value of variable to set
184  *
185  * \retval 0 success
186  * \retval -1 failure
187  */
188 int ast_msg_set_var_outbound(struct ast_msg *msg, const char *name, const char *value);
189
190 /*!
191  * \brief Get the specified variable on the message
192  * \note The return value is valid only as long as the ast_message is valid. Hold a reference
193  *       to the message if you plan on storing the return value. Do re-set the same
194  *       message var name while holding a pointer to the result of this function.
195  *
196  * \return The value associated with variable "name". NULL if variable not found.
197  */
198 const char *ast_msg_get_var(struct ast_msg *msg, const char *name);
199
200 /*!
201  * \brief Get the body of a message.
202  * \note The return value is valid only as long as the ast_message is valid. Hold a reference
203  *       to the message if you plan on storing the return value. 
204  *
205  * \return The body of the messsage, encoded in UTF-8.
206  */
207 const char *ast_msg_get_body(const struct ast_msg *msg);
208
209 /*!
210  * \brief Queue a message for routing through the dialplan.
211  *
212  * Regardless of the return value of this function, this funciton will take
213  * care of ensuring that the message object is properly destroyed when needed.
214  *
215  * \retval 0 message successfully queued
216  * \retval non-zero failure, message not sent to dialplan
217  */
218 int ast_msg_queue(struct ast_msg *msg);
219
220 /*!
221  * \brief Send a msg directly to an endpoint.
222  *
223  * Regardless of the return value of this function, this funciton will take
224  * care of ensuring that the message object is properly destroyed when needed.
225  *
226  * \retval 0 message successfully queued to be sent out
227  * \retval non-zero failure, message not get sent out.
228  */
229 int ast_msg_send(struct ast_msg *msg, const char *to, const char *from);
230
231 /*!
232  * \brief Opaque iterator for msg variables
233  */
234 struct ast_msg_var_iterator;
235
236 /*!
237  * \brief Create a new message variable iterator
238  * \param msg A message whose variables are to be iterated over
239  *
240  * \return An opaque pointer to the new iterator
241  */
242 struct ast_msg_var_iterator *ast_msg_var_iterator_init(const struct ast_msg *msg);
243
244 /*!
245  * \brief Get the next variable name and value that is set for sending outbound
246  * \param msg The message with the variables
247  * \param i An iterator created with ast_msg_var_iterator_init
248  * \param name A pointer to the name result pointer
249  * \param value A pointer to the value result pointer
250  *
251  * \retval 0 No more entries
252  * \retval 1 Valid entry
253  */
254 int ast_msg_var_iterator_next(const struct ast_msg *msg, struct ast_msg_var_iterator *i, const char **name, const char **value);
255
256 /*!
257  * \brief Destroy a message variable iterator
258  * \param i Iterator to be destroyed
259  */
260 void ast_msg_var_iterator_destroy(struct ast_msg_var_iterator *i);
261
262 /*!
263  * \brief Unref a message var from inside an iterator loop
264  */
265 void ast_msg_var_unref_current(struct ast_msg_var_iterator *i);
266
267 #if defined(__cplusplus) || defined(c_plusplus)
268 }
269 #endif
270
271 #endif /* __AST_MESSAGE_H__ */