Asterisk - The Open Source Telephony Project GIT-master-0bf3178
res_aeap_message.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 2021, Sangoma Technologies Corporation
5 *
6 * Kevin Harwell <kharwell@sangoma.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 Asterisk External Application Protocol Message API
21 */
22
23#ifndef AST_AEAP_MESSAGE_H
24#define AST_AEAP_MESSAGE_H
25
26#include <stdint.h>
27
28#include "asterisk/res_aeap.h"
29
30struct ast_aeap_message;
31
32/*!
33 * \brief Message type virtual method table
34 */
36 /*! The size of the message implementation type. Used for allocations. */
37 size_t type_size;
38 /*! The name of this type */
39 const char *type_name;
40 /*! The type to serialize to, and de-serialize from */
42
43 /*!
44 * \brief Construct/Initialize a message object
45 *
46 * \param self The message object to initialize
47 * \param params Other optional parameter(s) to possibly use
48 *
49 * \returns 0 on success, -1 on error
50 */
51 int (*construct1)(struct ast_aeap_message *self, const void *params);
52
53 /*!
54 * \brief Construct/Initialize a message object
55 *
56 * \param self The message object to initialize
57 * \param msg_type The type of message (e.g. request or response)
58 * \param name The name of the message
59 * \param id The message id
60 * \param params Other optional parameter(s) to possibly use
61 *
62 * \returns 0 on success, -1 on error
63 */
64 int (*construct2)(struct ast_aeap_message *self, const char *msg_type, const char *name,
65 const char *id, const void *params);
66
67 /*!
68 * \brief Destruct/Cleanup object resources
69 *
70 * \param self The message object being destructed
71 */
72 void (*destruct)(struct ast_aeap_message *self);
73
74 /*!
75 * \brief Deserialize the given buffer into a message object
76 *
77 * \param self The message object to deserialize into
78 * \param buf The buffer to deserialize
79 * \param size The size/length of the buffer
80 *
81 * \returns 0 on success, -1 on error
82 */
83 int (*deserialize)(struct ast_aeap_message *self, const void *buf, intmax_t size);
84
85 /*!
86 * \brief Serialize the message object into byte/char buffer
87 *
88 * \param self The message object to serialize
89 * \param buf [out] The buffer to hold the "packed" data
90 * \param size [out] The size of the data written to the buffer
91 *
92 * \returns 0 on success, -1 on error
93 */
94 int (*serialize)(const struct ast_aeap_message *self, void **buf, intmax_t *size);
95
96 /*!
97 * \brief Retrieve a message id
98 *
99 * \param self The message object
100 *
101 * \returns The message id
102 */
103 const char *(*id)(const struct ast_aeap_message *self);
104
105 /*!
106 * \brief Set a message id.
107 *
108 * \param self The message object
109 * \param id The id to set
110 *
111 * \returns 0 on success, -1 on error
112 */
113 int (*id_set)(struct ast_aeap_message *self, const char *id);
114
115 /*!
116 * \brief Retrieve a message name
117 *
118 * \param self The message object
119 *
120 * \returns The message name
121 */
122 const char *(*name)(const struct ast_aeap_message *self);
123
124 /*!
125 * \brief Retrieve the core message data/body
126 *
127 * \param self This message object
128 */
129 void *(*data)(struct ast_aeap_message *self);
130
131 /*!
132 * \brief Retrieve whether or not this is a request message
133 *
134 * \param self The message object
135 *
136 * \returns True if message is a request, false otherwise
137 */
138 int (*is_request)(const struct ast_aeap_message *self);
139
140 /*!
141 * \brief Retrieve whether or not this is a response message
142 *
143 * \param self The message object
144 *
145 * \returns True if message is a response, false otherwise
146 */
147 int (*is_response)(const struct ast_aeap_message *self);
148
149 /*!
150 * \brief Retrieve the error message if it has one
151 *
152 * \param self The message object
153 *
154 * \returns The error message if available, or NULL
155 */
156 const char *(*error_msg)(const struct ast_aeap_message *self);
157
158 /*!
159 * \brief Set an error message
160 *
161 * \param self The message object
162 * \param error_msg The error message string to set
163 *
164 * \returns 0 on success, -1 on error
165 */
166 int (*error_msg_set)(struct ast_aeap_message *self, const char *error_msg);
167};
168
169/*!
170 * \brief Asterisk external application base message
171 */
173 /*! The type virtual table */
175};
176
177/*!
178 * \brief Retrieve the serial type a message type
179 *
180 * \param type A message type
181 *
182 * \returns The type's serial type
183 */
185
186/*!
187 * \brief Create an Asterisk external application message object
188 *
189 * \param type The type of message object to create
190 * \param params Any parameter(s) to pass to the type's constructor
191 *
192 * \returns An ao2 reference counted AEAP message object, or NULL on error
193 */
195 const void *params);
196
197/*!
198 * \brief Create an Asterisk external application message object
199 *
200 * \param type The type of message object to create
201 * \param msg_type The type of message (e.g. request or response)
202 * \param name The name of the message
203 * \param id The message id
204 * \param params Other optional parameter(s) to possibly use
205 *
206 * \returns An ao2 reference counted AEAP message object, or NULL on error
207 */
209 const char *msg_type, const char *name, const char *id, const void *params);
210
211/*!
212 * \brief Create an Asterisk external application request object
213 *
214 * \param type The type of message object to create
215 * \param name The name of the message
216 * \param id Optional id (if NULL an id is generated)
217 * \param params Other optional parameter(s) to possibly use
218 *
219 * \returns An ao2 reference counted AEAP request object, or NULL on error
220 */
222 const char *name, const char *id, const void *params);
223
224/*!
225 * \brief Create an Asterisk external application response object
226 *
227 * \param type The type of message object to create
228 * \param name The name of the message
229 * \param id Optional id
230 * \param params Other optional parameter(s) to possibly use
231 *
232 * \returns An ao2 reference counted AEAP response object, or NULL on error
233 */
235 const char *name, const char *id, const void *params);
236
237/*!
238 * \brief Create an Asterisk external application error response object
239 *
240 * \param type The type of message object to create
241 * \param name The name of the message
242 * \param id Optional id
243 * \param error_msg Error message to set
244 *
245 * \returns An ao2 reference counted AEAP response object, or NULL on error
246 */
248 const char *name, const char *id, const char *error_msg);
249
250/*!
251 * \brief Deserialize the given buffer into an Asterisk external application message object
252 *
253 * \param type The message type to create, and deserialize to
254 * \param buf The buffer to deserialize
255 * \param size The size/length of the buffer
256 *
257 * \returns An ao2 reference counted AEAP message object, or NULL on error
258 */
260 const void *buf, intmax_t size);
261
262/*!
263 * \brief Serialize the given message object into a byte/char buffer
264 *
265 * \param message The message object to serialize
266 * \param buf [out] The buffer to hold the "packed" data
267 * \param size [out] The size of the data written to the buffer
268 *
269 * \returns 0 on success, -1 on error
270 */
272 void **buf, intmax_t *size);
273
274/*!
275 * \brief Retrieve a message id
276 *
277 * \param message A message object
278 *
279 * \returns The message id, or an empty string
280 */
281const char *ast_aeap_message_id(const struct ast_aeap_message *message);
282
283/*!
284 * \brief Set a message id.
285 *
286 * \param message A message object
287 * \param id The id to set
288 *
289 * \returns 0 on success, -1 on error
290 */
291int ast_aeap_message_id_set(struct ast_aeap_message *message, const char *id);
292
293/*!
294 * \brief Generate an id, and set it for the message
295 *
296 * \param message A message object
297 *
298 * \returns the generated id on success, or NULL on error
299 */
301
302/*!
303 * \brief Retrieve a message name
304 *
305 * \param message A message object
306 *
307 * \returns The message name, or an empty string
308 */
309const char *ast_aeap_message_name(const struct ast_aeap_message *message);
310
311/*!
312 * \brief Check whether or not a message's name matches the given one
313 *
314 * \note Case insensitive
315 *
316 * \param message A message object
317 * \param name The name to check against
318 *
319 * \returns True if matched, false otherwise
320 */
321int ast_aeap_message_is_named(const struct ast_aeap_message *message, const char *name);
322
323/*!
324 * \brief Retrieve the core message data/body
325 *
326 * \param message A message object
327 */
329
330/*!
331 * \brief Retrieve whether or not this is a request message
332 *
333 * \param message A message object
334 *
335 * \returns True if the message is a request, false otherwise
336 */
338
339/*!
340 * \brief Retrieve whether or not this is a response message
341 *
342 * \param message A message object
343 *
344 * \returns True if the message is a response, false otherwise
345 */
347
348/*!
349 * \brief Retrieve the error message if it has one
350 *
351 * \param message A message object
352 *
353 * \returns The error message if available, or NULL
354 */
355const char *ast_aeap_message_error_msg(const struct ast_aeap_message *message);
356
357/*!
358 * \brief Set an error message.
359 *
360 * \param message A message object
361 * \param error_msg The error string to set
362 *
363 * \returns 0 on success, -1 on error
364 */
366 const char *error_msg);
367
368/*!
369 * \brief Asterisk external application JSON message type
370 */
372
373#endif /* AST_AEAP_MESSAGE_H */
static const char type[]
Definition: chan_ooh323.c:109
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static const char name[]
Definition: format_mp3.c:68
Asterisk External Application Protocol API.
AST_AEAP_DATA_TYPE
Supported Asterisk external application data types.
Definition: res_aeap.h:135
int ast_aeap_message_serialize(const struct ast_aeap_message *message, void **buf, intmax_t *size)
Serialize the given message object into a byte/char buffer.
struct ast_aeap_message * ast_aeap_message_create_error(const struct ast_aeap_message_type *type, const char *name, const char *id, const char *error_msg)
Create an Asterisk external application error response object.
int ast_aeap_message_is_request(const struct ast_aeap_message *message)
Retrieve whether or not this is a request message.
const char * ast_aeap_message_id(const struct ast_aeap_message *message)
Retrieve a message id.
int ast_aeap_message_is_response(const struct ast_aeap_message *message)
Retrieve whether or not this is a response message.
struct ast_aeap_message * ast_aeap_message_create_request(const struct ast_aeap_message_type *type, const char *name, const char *id, const void *params)
Create an Asterisk external application request object.
struct ast_aeap_message * ast_aeap_message_create2(const struct ast_aeap_message_type *type, const char *msg_type, const char *name, const char *id, const void *params)
Create an Asterisk external application message object.
const char * ast_aeap_message_id_generate(struct ast_aeap_message *message)
Generate an id, and set it for the message.
const char * ast_aeap_message_name(const struct ast_aeap_message *message)
Retrieve a message name.
int ast_aeap_message_error_msg_set(struct ast_aeap_message *message, const char *error_msg)
Set an error message.
const struct ast_aeap_message_type * ast_aeap_message_type_json
Asterisk external application JSON message type.
Definition: message_json.c:191
int ast_aeap_message_id_set(struct ast_aeap_message *message, const char *id)
Set a message id.
const char * ast_aeap_message_error_msg(const struct ast_aeap_message *message)
Retrieve the error message if it has one.
struct ast_aeap_message * ast_aeap_message_create_response(const struct ast_aeap_message_type *type, const char *name, const char *id, const void *params)
Create an Asterisk external application response object.
void * ast_aeap_message_data(struct ast_aeap_message *message)
Retrieve the core message data/body.
int ast_aeap_message_is_named(const struct ast_aeap_message *message, const char *name)
Check whether or not a message's name matches the given one.
struct ast_aeap_message * ast_aeap_message_deserialize(const struct ast_aeap_message_type *type, const void *buf, intmax_t size)
Deserialize the given buffer into an Asterisk external application message object.
struct ast_aeap_message * ast_aeap_message_create1(const struct ast_aeap_message_type *type, const void *params)
Create an Asterisk external application message object.
enum AST_AEAP_DATA_TYPE ast_aeap_message_serial_type(const struct ast_aeap_message_type *type)
Retrieve the serial type a message type.
Message type virtual method table.
int(* is_response)(const struct ast_aeap_message *self)
Retrieve whether or not this is a response message.
const char *(* name)(const struct ast_aeap_message *self)
Retrieve a message name.
int(* construct2)(struct ast_aeap_message *self, const char *msg_type, const char *name, const char *id, const void *params)
Construct/Initialize a message object.
int(* error_msg_set)(struct ast_aeap_message *self, const char *error_msg)
Set an error message.
int(* deserialize)(struct ast_aeap_message *self, const void *buf, intmax_t size)
Deserialize the given buffer into a message object.
enum AST_AEAP_DATA_TYPE serial_type
int(* serialize)(const struct ast_aeap_message *self, void **buf, intmax_t *size)
Serialize the message object into byte/char buffer.
void(* destruct)(struct ast_aeap_message *self)
Destruct/Cleanup object resources.
const char *(* id)(const struct ast_aeap_message *self)
Retrieve a message id.
int(* construct1)(struct ast_aeap_message *self, const void *params)
Construct/Initialize a message object.
int(* is_request)(const struct ast_aeap_message *self)
Retrieve whether or not this is a request message.
const char *(* error_msg)(const struct ast_aeap_message *self)
Retrieve the error message if it has one.
int(* id_set)(struct ast_aeap_message *self, const char *id)
Set a message id.
Asterisk external application base message.
const struct ast_aeap_message_type * type