Asterisk - The Open Source Telephony Project  21.4.1
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 
30 struct 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  */
281 const 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  */
291 int 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  */
309 const 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  */
321 int 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  */
355 const 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 */
enum AST_AEAP_DATA_TYPE ast_aeap_message_serial_type(const struct ast_aeap_message_type *type)
Retrieve the serial type a message type.
Asterisk External Application Protocol API.
int(* is_response)(const struct ast_aeap_message *self)
Retrieve whether or not this is a response message.
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.
void * ast_aeap_message_data(struct ast_aeap_message *message)
Retrieve the core message data/body.
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 ast_aeap_message_error_msg_set(struct ast_aeap_message *message, const char *error_msg)
Set an error message.
int(* construct1)(struct ast_aeap_message *self, const void *params)
Construct/Initialize a 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.
const char * ast_aeap_message_id(const struct ast_aeap_message *message)
Retrieve a message id.
const char * ast_aeap_message_name(const struct ast_aeap_message *message)
Retrieve a message name.
int(* is_request)(const struct ast_aeap_message *self)
Retrieve whether or not this is a request message.
int ast_aeap_message_is_request(const struct ast_aeap_message *message)
Retrieve whether or not this is a request message.
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.
int ast_aeap_message_id_set(struct ast_aeap_message *message, const char *id)
Set a message id.
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.
int(* error_msg_set)(struct ast_aeap_message *self, const char *error_msg)
Set an error message.
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.
int(* deserialize)(struct ast_aeap_message *self, const void *buf, intmax_t size)
Deserialize the given buffer into a message object.
Asterisk external application base message.
enum AST_AEAP_DATA_TYPE serial_type
void(* destruct)(struct ast_aeap_message *self)
Destruct/Cleanup object resources.
AST_AEAP_DATA_TYPE
Supported Asterisk external application data types.
Definition: res_aeap.h:135
Message type virtual method table.
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.
const char *(* error_msg)(const struct ast_aeap_message *self)
Retrieve the error message if it has one.
const char *(* id)(const struct ast_aeap_message *self)
Retrieve a message id.
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.
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.
int(* id_set)(struct ast_aeap_message *self, const char *id)
Set a message id.
const struct ast_aeap_message_type * ast_aeap_message_type_json
Asterisk external application JSON message type.
Definition: message_json.c:191
const struct ast_aeap_message_type * type
const char * ast_aeap_message_error_msg(const struct ast_aeap_message *message)
Retrieve the error message if it has one.
const char *(* name)(const struct ast_aeap_message *self)
Retrieve a message name.
int ast_aeap_message_is_response(const struct ast_aeap_message *message)
Retrieve whether or not this is a response message.
int(* serialize)(const struct ast_aeap_message *self, void **buf, intmax_t *size)
Serialize the message object into byte/char buffer.