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