Asterisk - The Open Source Telephony Project  GIT-master-e8cda4b
message.h
Go to the documentation of this file.
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 or another interface and potentially
29  * sent back out through a message technology that has been registered
30  * through this API.
31  */
32 
33 #ifndef __AST_MESSAGE_H__
34 #define __AST_MESSAGE_H__
35 
36 #if defined(__cplusplus) || defined(c_plusplus)
37 extern "C" {
38 #endif
39 
40 /*!
41  * \brief A text message.
42  *
43  * This is an opaque type that represents a text message.
44  */
45 struct ast_msg;
46 
47 /*!
48  * \brief A message technology
49  *
50  * A message technology is capable of transmitting text messages.
51  */
52 struct ast_msg_tech {
53  /*!
54  * \brief Name of this message technology
55  *
56  * This is the name that comes at the beginning of a URI for messages
57  * that should be sent to this message technology implementation.
58  * For example, messages sent to "xmpp:rbryant@digium.com" would be
59  * passed to the ast_msg_tech with a name of "xmpp".
60  */
61  const char * const name;
62  /*!
63  * \brief Send a message.
64  *
65  * \param msg the message to send
66  * \param to the URI of where the message is being sent
67  * \param from the URI of where the message was sent from
68  *
69  * The fields of the ast_msg are guaranteed not to change during the
70  * duration of this function call.
71  *
72  * \retval 0 success
73  * \retval non-zero failure
74  */
75  int (* const msg_send)(const struct ast_msg *msg, const char *to, const char *from);
76 };
77 
78 /*!
79  * \brief Register a message technology
80  *
81  * \retval 0 success
82  * \retval non-zero failure
83  */
84 int ast_msg_tech_register(const struct ast_msg_tech *tech);
85 
86 /*!
87  * \brief Unregister a message technology.
88  *
89  * \retval 0 success
90  * \retval non-zero failure
91  */
92 int ast_msg_tech_unregister(const struct ast_msg_tech *tech);
93 
94 /*!
95  * \brief An external processor of received messages
96  * \since 12.5.0
97  */
99  /*!
100  * \brief Name of the message handler
101  */
102  const char *name;
103 
104  /*!
105  * \brief The function callback that will handle the message
106  *
107  * \param msg The message to handle
108  *
109  * \retval 0 The handler processed the message successfull
110  * \retval non-zero The handler passed or could not process the message
111  */
112  int (* const handle_msg)(struct ast_msg *msg);
113 
114  /*!
115  * \brief Return whether or not the message has a valid destination
116  *
117  * A message may be delivered to the dialplan and/or other locations,
118  * depending on whether or not other handlers have been registered. This
119  * function is called by the message core to determine if any handler can
120  * process a message.
121  *
122  * \param msg The message to inspect
123  *
124  * \retval 0 The message does not have a valid destination
125  * \retval 1 The message has a valid destination
126  */
127  int (* const has_destination)(const struct ast_msg *msg);
128 };
129 
130 /*!
131  * \brief Register a \c ast_msg_handler
132  * \since 12.5.0
133  *
134  * \param handler The handler to register
135  *
136  * \retval 0 Success
137  * \retval non-zero Error
138  */
140 
141 /*!
142  * \brief Unregister a \c ast_msg_handler
143  * \since 12.5.0
144  *
145  * \param handler The handler to unregister
146  *
147  * \retval 0 Success
148  * \retval non-zero Error
149  */
151 
152 /*!
153  * \brief Allocate a message.
154  *
155  * Allocate a message for the purposes of passing it into the Asterisk core
156  * to be routed through the dialplan. If ast_msg_queue() is not called, this
157  * message must be destroyed using ast_msg_destroy(). Otherwise, the message
158  * core code will take care of it.
159  *
160  * \return A message object. This function will return NULL if an allocation
161  * error occurs.
162  */
163 struct ast_msg *ast_msg_alloc(void);
164 
165 /*!
166  * \brief Destroy an ast_msg
167  *
168  * This should only be called on a message if it was not
169  * passed on to ast_msg_queue().
170  *
171  * \return NULL, always.
172  */
173 struct ast_msg *ast_msg_destroy(struct ast_msg *msg);
174 
175 /*!
176  * \brief Bump a msg's ref count
177  */
178 struct ast_msg *ast_msg_ref(struct ast_msg *msg);
179 
180 /*!
181  * \brief Set the 'to' URI of a message
182  *
183  * \retval 0 success
184  * \retval -1 failure
185  */
186 int __attribute__((format(printf, 2, 3)))
187  ast_msg_set_to(struct ast_msg *msg, const char *fmt, ...);
188 
189 /*!
190  * \brief Set the 'from' URI of a message
191  *
192  * \retval 0 success
193  * \retval -1 failure
194  */
195 int __attribute__((format(printf, 2, 3)))
196  ast_msg_set_from(struct ast_msg *msg, const char *fmt, ...);
197 
198 /*!
199  * \brief Set the 'body' text of a message (in UTF-8)
200  *
201  * \retval 0 success
202  * \retval -1 failure
203  */
204 int __attribute__((format(printf, 2, 3)))
205  ast_msg_set_body(struct ast_msg *msg, const char *fmt, ...);
206 
207 /*!
208  * \brief Set the dialplan context for this message
209  *
210  * \retval 0 success
211  * \retval -1 failure
212  */
213 int __attribute__((format(printf, 2, 3)))
214  ast_msg_set_context(struct ast_msg *msg, const char *fmt, ...);
215 
216 /*!
217  * \brief Set the dialplan extension for this message
218  *
219  * \retval 0 success
220  * \retval -1 failure
221  */
222 int __attribute__((format(printf, 2, 3)))
223  ast_msg_set_exten(struct ast_msg *msg, const char *fmt, ...);
224 
225 /*!
226  * \brief Set the technology associated with this message
227  *
228  * \since 12.5.0
229  *
230  * \retval 0 success
231  * \retval -1 failure
232  */
233 int __attribute__((format(printf, 2, 3)))
234  ast_msg_set_tech(struct ast_msg *msg, const char *fmt, ...);
235 
236 /*!
237  * \brief Set the technology's endpoint associated with this message
238  *
239  * \since 12.5.0
240  *
241  * \retval 0 success
242  * \retval -1 failure
243  */
244 int __attribute__((format(printf, 2, 3)))
245  ast_msg_set_endpoint(struct ast_msg *msg, const char *fmt, ...);
246 
247 /*!
248  * \brief Set a variable on the message going to the dialplan.
249  * \note Setting a variable that already exists overwrites the existing variable value
250  *
251  * \param msg
252  * \param name Name of variable to set
253  * \param value Value of variable to set
254  *
255  * \retval 0 success
256  * \retval -1 failure
257  */
258 int ast_msg_set_var(struct ast_msg *msg, const char *name, const char *value);
259 
260 /*!
261  * \brief Set a variable on the message being sent to a message tech directly.
262  * \note Setting a variable that already exists overwrites the existing variable value
263  *
264  * \param msg
265  * \param name Name of variable to set
266  * \param value Value of variable to set
267  *
268  * \retval 0 success
269  * \retval -1 failure
270  */
271 int ast_msg_set_var_outbound(struct ast_msg *msg, const char *name, const char *value);
272 
273 /*!
274  * \brief Get the specified variable on the message
275  * \note The return value is valid only as long as the ast_message is valid. Hold a reference
276  * to the message if you plan on storing the return value. Do re-set the same
277  * message var name while holding a pointer to the result of this function.
278  *
279  * \return The value associated with variable "name". NULL if variable not found.
280  */
281 const char *ast_msg_get_var(struct ast_msg *msg, const char *name);
282 
283 /*!
284  * \brief Get the body of a message.
285  * \note The return value is valid only as long as the ast_message is valid. Hold a reference
286  * to the message if you plan on storing the return value.
287  *
288  * \return The body of the messsage, encoded in UTF-8.
289  */
290 const char *ast_msg_get_body(const struct ast_msg *msg);
291 
292 /*!
293  * \brief Retrieve the source of this message
294  *
295  * \since 12.5.0
296  *
297  * \param msg The message to get the soure from
298  *
299  * \retval The source of the message
300  * \retval NULL or empty string if the message has no source
301  */
302 const char *ast_msg_get_from(const struct ast_msg *msg);
303 
304 /*!
305  * \brief Retrieve the destination of this message
306  *
307  * \since 12.5.0
308  *
309  * \param msg The message to get the destination from
310  *
311  * \retval The destination of the message
312  * \retval NULL or empty string if the message has no destination
313  */
314 const char *ast_msg_get_to(const struct ast_msg *msg);
315 
316 /*!
317  * \brief Retrieve the technology associated with this message
318  *
319  * \since 12.5.0
320  *
321  * \param msg The message to get the technology from
322  *
323  * \retval The technology of the message
324  * \retval NULL or empty string if the message has no associated technology
325  */
326 const char *ast_msg_get_tech(const struct ast_msg *msg);
327 
328 /*!
329  * \brief Retrieve the endpoint associated with this message
330  *
331  * \since 12.5.0
332  *
333  * \param msg The message to get the endpoint from
334  *
335  * \retval The endpoint associated with the message
336  * \retval NULL or empty string if the message has no associated endpoint
337  */
338 const char *ast_msg_get_endpoint(const struct ast_msg *msg);
339 
340 /*!
341  * \brief Determine if a particular message has a destination via some handler
342  *
343  * \since 12.5.0
344  *
345  * \param msg The message to check
346  *
347  * \retval 0 if the message has no handler that can find a destination
348  * \retval 1 if the message has a handler that can find a destination
349  */
350 int ast_msg_has_destination(const struct ast_msg *msg);
351 
352 /*!
353  * \brief Queue a message for routing through the dialplan.
354  *
355  * Regardless of the return value of this function, this funciton will take
356  * care of ensuring that the message object is properly destroyed when needed.
357  *
358  * \retval 0 message successfully queued
359  * \retval non-zero failure, message not sent to dialplan
360  */
361 int ast_msg_queue(struct ast_msg *msg);
362 
363 /*!
364  * \brief Send a msg directly to an endpoint.
365  *
366  * Regardless of the return value of this function, this funciton will take
367  * care of ensuring that the message object is properly destroyed when needed.
368  *
369  * \retval 0 message successfully queued to be sent out
370  * \retval non-zero failure, message not get sent out.
371  */
372 int ast_msg_send(struct ast_msg *msg, const char *to, const char *from);
373 
374 /*!
375  * \brief Opaque iterator for msg variables
376  */
377 struct ast_msg_var_iterator;
378 
379 /*!
380  * \brief Create a new message variable iterator
381  * \param msg A message whose variables are to be iterated over
382  *
383  * \return An opaque pointer to the new iterator
384  */
385 struct ast_msg_var_iterator *ast_msg_var_iterator_init(const struct ast_msg *msg);
386 
387 /*!
388  * \brief Get the next variable name and value that is set for sending outbound
389  * \param msg The message with the variables
390  * \param iter An iterator created with ast_msg_var_iterator_init
391  * \param name A pointer to the name result pointer
392  * \param value A pointer to the value result pointer
393  *
394  * \retval 0 No more entries
395  * \retval 1 Valid entry
396  */
397 int ast_msg_var_iterator_next(const struct ast_msg *msg, struct ast_msg_var_iterator *iter, const char **name, const char **value);
398 
399 /*!
400  * \brief Get the next variable name and value that was set on a received message
401  * \param msg The message with the variables
402  * \param iter An iterator created with ast_msg_var_iterator_init
403  * \param name A pointer to the name result pointer
404  * \param value A pointer to the value result pointer
405  *
406  * \retval 0 No more entries
407  * \retval 1 Valid entry
408  */
409 int ast_msg_var_iterator_next_received(const struct ast_msg *msg,
410  struct ast_msg_var_iterator *iter, const char **name, const char **value);
411 
412 /*!
413  * \brief Destroy a message variable iterator
414  * \param iter Iterator to be destroyed
415  */
416 void ast_msg_var_iterator_destroy(struct ast_msg_var_iterator *iter);
417 
418 /*!
419  * \brief Unref a message var from inside an iterator loop
420  */
421 void ast_msg_var_unref_current(struct ast_msg_var_iterator *iter);
422 
423 
424 /*! \defgroup ast_msg_data Enhanced Messaging
425  * @{
426  * \page Messaging Enhanced Messaging
427  *
428  * The basic messaging framework has a basic drawback... It can only pass
429  * a text string through the core. This causes several issues:
430  * \li Only a content type of text/plain can be passed.
431  * \li If a softmix bridge is used, the original sender identity is lost.
432  *
433  * The Enhanced Messaging framework allows attributes, such as "From", "To"
434  * and "Content-Type" to be attached to the message by the incoming channel
435  * tech which can then be used by the outgoing channel tech to construct
436  * the appropriate technology-specific outgoing message.
437  */
438 
439 /*!
440  * \brief Structure used to transport an enhanced message through the frame core
441  * \since 13.22.0
442  * \since 15.5.0
443  */
444 struct ast_msg_data;
445 
452 };
453 
460 };
461 
464  char *value;
465 };
466 
467 /*!
468  * \brief Allocates an ast_msg_data structure.
469  * \since 13.22.0
470  * \since 15.5.0
471  *
472  * \param source The source type of the message
473  * \param attributes A pointer to an array of ast_msg_data_attribute structures
474  * \param count The number of elements in the array
475  *
476  * \return Pointer to msg structure or NULL on allocation failure.
477  * Caller must call ast_free when done.
478  */
480  struct ast_msg_data_attribute attributes[], size_t count);
481 
482 /*!
483  * \brief Allocates an ast_msg_data structure.
484  * \since 13.35.0
485  * \since 16.12.0
486  * \since 17.6.0
487  *
488  * \param source The source type of the message
489  * \param to Where the message is sent to
490  * \param from Where the message is sent from
491  * \param content_type Content type of the body
492  * \param body The message body
493  *
494  * \return Pointer to msg structure or NULL on allocation failure.
495  * Caller must call ast_free when done.
496  */
498  const char *to, const char *from, const char *content_type, const char *body);
499 
500 /*!
501  * \brief Clone an ast_msg_data structure
502  * \since 13.22.0
503  * \since 15.5.0
504  *
505  * \param msg The message to clone
506  *
507  * \return New message structure or NULL if there was an allocation failure.
508  * Caller must call ast_free when done.
509  */
510 struct ast_msg_data *ast_msg_data_dup(struct ast_msg_data *msg);
511 
512 /*!
513  * \brief Get length of the structure
514  * \since 13.22.0
515  * \since 15.5.0
516  *
517  * \param msg Pointer to ast_msg_data structure
518  *
519  * \return The length of the structure itself plus the dynamically allocated attribute buffer.
520  */
521 size_t ast_msg_data_get_length(struct ast_msg_data *msg);
522 
523 /*!
524  * \brief Get "source type" from ast_msg_data
525  * \since 13.22.0
526  * \since 15.5.0
527  *
528  * \param msg Pointer to ast_msg_data structure
529  *
530  * \return The source type field.
531  */
533 
534 /*!
535  * \brief Get attribute from ast_msg_data
536  * \since 13.22.0
537  * \since 15.5.0
538  *
539  * \param msg Pointer to ast_msg_data structure
540  * \param attribute_type One of ast_msg_data_attribute_type
541  *
542  * \return The attribute or an empty string ("") if the attribute wasn't set.
543  */
544 const char *ast_msg_data_get_attribute(struct ast_msg_data *msg,
545  enum ast_msg_data_attribute_type attribute_type);
546 
547 /*!
548  * \brief Queue an AST_FRAME_TEXT_DATA frame containing an ast_msg_data structure
549  * \since 13.22.0
550  * \since 15.5.0
551  *
552  * \param channel The channel on which to queue the frame
553  * \param msg Pointer to ast_msg_data structure
554  *
555  * \retval -1 Error
556  * \retval 0 Success
557  */
558 int ast_msg_data_queue_frame(struct ast_channel *channel, struct ast_msg_data *msg);
559 
560 /*!
561  * @}
562  */
563 
564 #if defined(__cplusplus) || defined(c_plusplus)
565 }
566 #endif
567 
568 #endif /* __AST_MESSAGE_H__ */
size_t ast_msg_data_get_length(struct ast_msg_data *msg)
Get length of the structure.
Definition: message.c:1513
int ast_msg_handler_unregister(const struct ast_msg_handler *handler)
Unregister a ast_msg_handler.
Definition: message.c:1671
static const char type[]
Definition: chan_ooh323.c:109
Main Channel structure associated with a channel.
int ast_msg_set_tech(struct ast_msg *msg, const char *fmt,...)
Set the technology associated with this message.
Definition: message.c:509
const char * ast_msg_get_var(struct ast_msg *msg, const char *name)
Get the specified variable on the message.
Definition: message.c:620
enum ast_msg_data_source_type ast_msg_data_get_source_type(struct ast_msg_data *msg)
Get "source type" from ast_msg_data.
Definition: message.c:1523
const char * ast_msg_get_tech(const struct ast_msg *msg)
Retrieve the technology associated with this message.
Definition: message.c:546
int ast_msg_set_context(struct ast_msg *msg, const char *fmt,...)
Set the dialplan context for this message.
Definition: message.c:487
struct ast_msg_data * ast_msg_data_dup(struct ast_msg_data *msg)
Clone an ast_msg_data structure.
Definition: message.c:1495
const char * ast_msg_get_endpoint(const struct ast_msg *msg)
Retrieve the endpoint associated with this message.
Definition: message.c:551
int ast_msg_set_body(struct ast_msg *msg, const char *fmt,...)
Set the &#39;body&#39; text of a message (in UTF-8)
Definition: message.c:476
An external processor of received messages.
Definition: message.h:98
int ast_msg_handler_register(const struct ast_msg_handler *handler)
Register a ast_msg_handler.
Definition: message.c:1629
struct ast_msg * ast_msg_alloc(void)
Allocate a message.
Definition: message.c:418
const ast_string_field to
Definition: message.c:249
int ast_msg_var_iterator_next(const struct ast_msg *msg, struct ast_msg_var_iterator *iter, const char **name, const char **value)
Get the next variable name and value that is set for sending outbound.
Definition: message.c:689
const char *const name
Name of this message technology.
Definition: message.h:61
Structure used to transport a message through the frame core.
Definition: message.c:1406
int ast_msg_tech_register(const struct ast_msg_tech *tech)
Register a message technology.
Definition: message.c:1569
struct ast_msg_data * ast_msg_data_alloc(enum ast_msg_data_source_type source, struct ast_msg_data_attribute attributes[], size_t count)
Allocates an ast_msg_data structure.
Definition: message.c:1418
Definition: muted.c:95
int value
Definition: syslog.c:37
const char * ast_msg_get_body(const struct ast_msg *msg)
Get the body of a message.
Definition: message.c:531
int ast_msg_var_iterator_next_received(const struct ast_msg *msg, struct ast_msg_var_iterator *iter, const char **name, const char **value)
Get the next variable name and value that was set on a received message.
Definition: message.c:694
void ast_msg_var_iterator_destroy(struct ast_msg_var_iterator *iter)
Destroy a message variable iterator.
Definition: message.c:706
int ast_msg_set_to(struct ast_msg *msg, const char *fmt,...)
Set the &#39;to&#39; URI of a message.
Definition: message.c:454
const char * ast_msg_get_to(const struct ast_msg *msg)
Retrieve the destination of this message.
Definition: message.c:541
int ast_msg_send(struct ast_msg *msg, const char *to, const char *from)
Send a msg directly to an endpoint.
Definition: message.c:1369
enum ast_msg_data_source_type source
Definition: message.c:1409
void ast_msg_var_unref_current(struct ast_msg_var_iterator *iter)
Unref a message var from inside an iterator loop.
Definition: message.c:700
int ast_msg_set_var(struct ast_msg *msg, const char *name, const char *value)
Set a variable on the message going to the dialplan.
Definition: message.c:615
ast_msg_data_source_type
Definition: message.h:446
int ast_msg_queue(struct ast_msg *msg)
Queue a message for routing through the dialplan.
Definition: message.c:958
struct ast_msg * ast_msg_ref(struct ast_msg *msg)
Bump a msg&#39;s ref count.
Definition: message.c:442
int ast_msg_data_queue_frame(struct ast_channel *channel, struct ast_msg_data *msg)
Queue an AST_FRAME_TEXT_DATA frame containing an ast_msg_data structure.
Definition: message.c:1548
int ast_msg_tech_unregister(const struct ast_msg_tech *tech)
Unregister a message technology.
Definition: message.c:1610
const char * ast_msg_get_from(const struct ast_msg *msg)
Retrieve the source of this message.
Definition: message.c:536
const char * ast_msg_data_get_attribute(struct ast_msg_data *msg, enum ast_msg_data_attribute_type attribute_type)
Get attribute from ast_msg_data.
Definition: message.c:1533
A message technology.
Definition: message.h:52
const ast_string_field from
Definition: message.c:249
ast_msg_data_attribute_type
Definition: message.h:454
int ast_msg_set_exten(struct ast_msg *msg, const char *fmt,...)
Set the dialplan extension for this message.
Definition: message.c:498
int ast_msg_set_from(struct ast_msg *msg, const char *fmt,...)
Set the &#39;from&#39; URI of a message.
Definition: message.c:465
const char * name
Name of the message handler.
Definition: message.h:102
int ast_msg_set_endpoint(struct ast_msg *msg, const char *fmt,...)
Set the technology&#39;s endpoint associated with this message.
Definition: message.c:520
int ast_msg_has_destination(const struct ast_msg *msg)
Determine if a particular message has a destination via some handler.
Definition: message.c:937
struct ast_msg_data * ast_msg_data_alloc2(enum ast_msg_data_source_type source_type, const char *to, const char *from, const char *content_type, const char *body)
Allocates an ast_msg_data structure.
Definition: message.c:1469
int ast_msg_set_var_outbound(struct ast_msg *msg, const char *name, const char *value)
Set a variable on the message being sent to a message tech directly.
Definition: message.c:610
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59
int(*const msg_send)(const struct ast_msg *msg, const char *to, const char *from)
Send a message.
Definition: message.h:75
A message.
Definition: message.c:233
struct ast_msg * ast_msg_destroy(struct ast_msg *msg)
Destroy an ast_msg.
Definition: message.c:448
static snd_pcm_format_t format
Definition: chan_alsa.c:102
const ast_string_field tech
Definition: message.c:249
struct ast_msg_var_iterator * ast_msg_var_iterator_init(const struct ast_msg *msg)
Create a new message variable iterator.
Definition: message.c:644