Asterisk - The Open Source Telephony Project  21.4.1
res_aeap.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 API
21  */
22 
23 #ifndef AST_RES_AEAP_H
24 #define AST_RES_AEAP_H
25 
26 #include <stdint.h>
27 
28 struct ao2_container;
29 struct ast_sorcery;
30 struct ast_variable;
31 
33 struct ast_aeap_message;
34 
35 #define AEAP_CONFIG_CLIENT "client"
36 
37 /*!
38  * \brief Retrieve the AEAP sorcery object
39  *
40  * \returns the AEAP sorcery object
41  */
42 struct ast_sorcery *ast_aeap_sorcery(void);
43 
44 /*!
45  * \brief Retrieve a listing of all client configuration objects by protocol.
46  *
47  * \note Caller is responsible for the returned container's reference.
48  *
49  * \param protocol An optional protocol to filter on (if NULL returns all client configs)
50  *
51  * \returns A container of client configuration objects
52  */
53 struct ao2_container *ast_aeap_client_configs_get(const char *protocol);
54 
55 /*!
56  * \brief Retrieve codec capabilities from the configuration
57  *
58  * \param cfg A configuration object
59  *
60  * \returns The configuration's codec capabilities
61  */
63 
64 /*!
65  * \brief Check a given protocol against that in an Asterisk external application configuration
66  *
67  * \param cfg A configuration object
68  * \param protocol The protocol to check
69  *
70  * \returns True if the configuration's protocol matches, false otherwise
71  */
73  const char *protocol);
74 
75 /*!
76  * \brief Retrieve a list of custom configuration fields
77  *
78  * \param id configuration id/sorcery lookup key
79  *
80  * \returns variables, or NULL on error
81  */
82 struct ast_variable *ast_aeap_custom_fields_get(const char *id);
83 
84 /*!
85  * \brief An Asterisk external application object
86  *
87  * Connects to an external application, sending and receiving data, and
88  * dispatches received data to registered handlers.
89  */
90 struct ast_aeap;
91 
92 /*!
93  * \brief Event raised when a message is received
94  *
95  * \param aeap An Asterisk external application object
96  * \param message The received message
97  * \param obj Associated user object
98  *
99  * \returns 0 on if message handled, otherwise non-zero
100  */
101 typedef int (*ast_aeap_on_message)(struct ast_aeap *aeap, struct ast_aeap_message *message, void *obj);
102 
103 /*!
104  * \brief An Asterisk external application message handler
105  *
106  * Used to register message handlers with an AEAP object.
107  */
109  /*! The handler name */
110  const char *name;
111  /*! Callback triggered when on a name match */
113 };
114 
115 /*!
116  * \brief Event raised when a sent message does not receive a reply within
117  * a specified time interval
118  *
119  * \param aeap An Asterisk external application object
120  * \param message The message sent that received no response
121  * \param obj Associated user object
122  */
123 typedef void (*ast_aeap_on_timeout)(struct ast_aeap *aeap, struct ast_aeap_message *message, void *obj);
124 
125 /*!
126  * \brief Callback to cleanup a user object
127  *
128  * \param obj The user object
129  */
130 typedef void (*ast_aeap_user_obj_cleanup)(void *obj);
131 
132 /*!
133  * \brief Supported Asterisk external application data types
134  */
136  AST_AEAP_DATA_TYPE_NONE,
137  AST_AEAP_DATA_TYPE_BINARY,
138  AST_AEAP_DATA_TYPE_STRING,
139 };
140 
141 /*!
142  * \brief Callbacks and other parameters used by an Asterisk external application object
143  */
145  /*!
146  * If true pass along error messages to the implementation.
147  * Otherwise log it only, and consider it handled.
148  */
149  unsigned int emit_error;
150 
151  /*! The message type used for communication */
153 
154  /*! Response handlers array */
156  /*! The number of response handlers */
158 
159  /*! Request handlers array */
161  /*! The number of request handlers */
163 
164  /*!
165  * \brief Raised when binary data is received
166  *
167  * \param aeap An Asterisk external application object
168  * \param buf The buffer containing binary data
169  * \param size The size of the buffer
170  */
171  void (*on_binary)(struct ast_aeap *aeap, const void *buf, intmax_t size);
172 
173  /*!
174  * \brief Raised when string data is received
175  *
176  * \param aeap An Asterisk external application object
177  * \param buf The buffer containing string data
178  * \param size The size/length of the string
179  */
180  void (*on_string)(struct ast_aeap *aeap, const char *buf, intmax_t size);
181 
182  /*!
183  * \brief Raised when an error occurs during reading
184  *
185  * \note This is an AEAP transport level read error event
186  *
187  * \note When this event is triggered the client has also
188  * been disconnected.
189  *
190  * \param aeap An Asterisk external application object
191  */
192  void (*on_error)(struct ast_aeap *aeap);
193 };
194 
195 /*!
196  * \brief Create an Asterisk external application object
197  *
198  * \param type The type of underlying transport
199  * \param params Callbacks and other parameters to use
200  *
201  * \returns A new ao2 reference counted aeap object, or NULL on error
202  */
203 struct ast_aeap *ast_aeap_create(const char *type, const struct ast_aeap_params *params);
204 
205 /*!
206  * \brief Create an Asterisk external application object by sorcery id
207  *
208  * \param id The sorcery id to lookup
209  * \param params Callbacks and other parameters to use
210  *
211  * \returns A new ao2 reference counted aeap object, or NULL on error
212  */
213 struct ast_aeap *ast_aeap_create_by_id(const char *id, const struct ast_aeap_params *params);
214 
215 /*!
216  * \brief Connect to an external application
217  *
218  * \param aeap An Asterisk external application object
219  * \param url The url to connect to
220  * \param protocol A protocol to use
221  * \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
222  *
223  * \returns 0 if able to connect, -1 on error
224  */
225 int ast_aeap_connect(struct ast_aeap *aeap, const char *url, const char *protocol, int timeout);
226 
227 /*!
228  * \brief Create and connect to an Asterisk external application by sorcery id
229  *
230  * \param id The sorcery id to lookup
231  * \param params Callbacks and other parameters to use
232  * \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
233  *
234  * \returns A new ao2 reference counted aeap object, or NULL on error
235  */
236 struct ast_aeap *ast_aeap_create_and_connect_by_id(const char *id,
237  const struct ast_aeap_params *params, int timeout);
238 
239 /*!
240  * \brief Create and connect to an Asterisk external application
241  *
242  * \param type The type of client connection to make
243  * \param params Callbacks and other parameters to use
244  * \param url The url to connect to
245  * \param protocol A protocol to use
246  * \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
247  *
248  * \returns A new ao2 reference counted aeap object, or NULL on error
249  */
250 struct ast_aeap *ast_aeap_create_and_connect(const char *type,
251  const struct ast_aeap_params *params, const char *url, const char *protocol, int timeout);
252 
253 /*!
254  * \brief Disconnect an Asterisk external application object
255  *
256  * \note Depending on the underlying transport this call may block
257  *
258  * \param aeap An Asterisk external application object
259  *
260  * \returns 0 on success, -1 on error
261  */
262 int ast_aeap_disconnect(struct ast_aeap *aeap);
263 
264 /*!
265  * \brief Register a user data object
266  *
267  * \note The "cleanup" is called on un-register, if one is specified
268  *
269  * \param aeap An Asterisk external application object
270  * \param id The look up id for the object
271  * \param obj The user object to register
272  * \param cleanup Optional user object clean up callback
273  *
274  * \returns 0 on success, -1 on error
275  */
276 int ast_aeap_user_data_register(struct ast_aeap *aeap, const char *id, void *obj,
278 
279 /*!
280  * \brief Un-register a user data object
281  *
282  * \note If specified on register, the "cleanup" callback is called during unregister.
283  *
284  * \param aeap An Asterisk external application object
285  * \param id The look up id for the object
286  */
287 void ast_aeap_user_data_unregister(struct ast_aeap *aeap, const char *id);
288 
289 /*!
290  * \brief Retrieve a registered user data object by its id
291  *
292  * \note Depending on how it was registered the returned user data object's lifetime
293  * may be managed by the given "aeap" object. If it was registered with a cleanup
294  * handler that [potentially] frees it the caller of this function must ensure
295  * it's done using the returned object before it's unregistered.
296  *
297  * \param aeap An Asterisk external application object
298  * \param id The look up id for the object
299  *
300  * \returns A user data object
301  */
302 void *ast_aeap_user_data_object_by_id(struct ast_aeap *aeap, const char *id);
303 
304 /*!
305  * \brief Send a binary data to an external application
306  *
307  * \param aeap An Asterisk external application object
308  * \param buf Binary data to send
309  * \param size The size of the binary data
310  *
311  * \returns 0 on success, -1 on error
312  */
313 int ast_aeap_send_binary(struct ast_aeap *aeap, const void *buf, uintmax_t size);
314 
315 /*!
316  * \brief Send a message to an external application
317  *
318  * \note "Steals" the given message reference, thus callers are not required to un-ref
319  * the message object after calling this function.
320  *
321  * \param aeap An Asterisk external application object
322  * \param msg The message to send
323  *
324  * \returns 0 on success, -1 on error
325  */
326 int ast_aeap_send_msg(struct ast_aeap *aeap, struct ast_aeap_message *msg);
327 
328 /*!
329  * \brief Parameters to be used when sending a transaction based message
330  */
332  /*! The message to send */
334  /*! The amount of time (in milliseconds) to wait for a received message */
335  int timeout;
336  /*! Optional callback raised when no message is received in an allotted time */
338  /*! Whether or not to block the current thread, and wait for a received message */
339  int wait;
340  /*!
341  * Optional user object to pass to handlers. User is responsible for object's lifetime
342  * unless an obj_cleanup callback is specified that handles its cleanup (e.g. freeing
343  * of memory).
344  */
345  void *obj;
346  /*!
347  * Optional user object cleanup callback. If specified, called upon "this" param's
348  * destruction (including on error).
349  */
351 };
352 
353 /*!
354  * \brief Send a transaction based message to an external application using the given parameters
355  *
356  * \note "Steals" the given message reference, thus callers are not required to un-ref
357  * the message object after calling this function.
358  *
359  * \note Also handles cleaning up the user object if the obj_cleanup callback
360  * is specified in "params".
361  *
362  * \param aeap An Asterisk external application object
363  * \param params (optional) Additional parameters to consider when sending. Heap allocation
364  * not required.
365  *
366  * \returns 0 on success, -1 on error
367  */
368 int ast_aeap_send_msg_tsx(struct ast_aeap *aeap, struct ast_aeap_tsx_params *params);
369 
370 #endif /* AST_RES_AEAP_H */
void(* on_binary)(struct ast_aeap *aeap, const void *buf, intmax_t size)
Raised when binary data is received.
Definition: res_aeap.h:171
Callbacks and other parameters used by an Asterisk external application object.
Definition: res_aeap.h:144
void ast_aeap_user_data_unregister(struct ast_aeap *aeap, const char *id)
Un-register a user data object.
Definition: aeap.c:169
void(* on_string)(struct ast_aeap *aeap, const char *buf, intmax_t size)
Raised when string data is received.
Definition: res_aeap.h:180
unsigned int emit_error
Definition: res_aeap.h:149
int ast_aeap_client_config_has_protocol(const struct ast_aeap_client_config *cfg, const char *protocol)
Check a given protocol against that in an Asterisk external application configuration.
Definition: res_aeap.c:136
const struct ast_aeap_message_handler * request_handlers
Definition: res_aeap.h:160
void(* ast_aeap_user_obj_cleanup)(void *obj)
Callback to cleanup a user object.
Definition: res_aeap.h:130
Structure for variables, used for configurations and for channel variables.
int(* ast_aeap_on_message)(struct ast_aeap *aeap, struct ast_aeap_message *message, void *obj)
Event raised when a message is received.
Definition: res_aeap.h:101
Full structure for sorcery.
Definition: sorcery.c:230
uintmax_t request_handlers_size
Definition: res_aeap.h:162
const struct ast_aeap_message_type * msg_type
Definition: res_aeap.h:152
int ast_aeap_send_msg_tsx(struct ast_aeap *aeap, struct ast_aeap_tsx_params *params)
Send a transaction based message to an external application using the given parameters.
Definition: aeap.c:464
struct ast_sorcery * ast_aeap_sorcery(void)
Retrieve the AEAP sorcery object.
Definition: res_aeap.c:67
void * ast_aeap_user_data_object_by_id(struct ast_aeap *aeap, const char *id)
Retrieve a registered user data object by its id.
Definition: aeap.c:174
Parameters to be used when sending a transaction based message.
Definition: res_aeap.h:331
struct ast_aeap * ast_aeap_create(const char *type, const struct ast_aeap_params *params)
Create an Asterisk external application object.
Definition: aeap.c:88
static void cleanup(void)
Clean up any old apps that we don't need any more.
Definition: res_stasis.c:327
ast_aeap_user_obj_cleanup obj_cleanup
Definition: res_aeap.h:350
int ast_aeap_send_msg(struct ast_aeap *aeap, struct ast_aeap_message *msg)
Send a message to an external application.
Definition: aeap.c:439
int ast_aeap_connect(struct ast_aeap *aeap, const char *url, const char *protocol, int timeout)
Connect to an external application.
Definition: aeap.c:338
ast_aeap_on_timeout on_timeout
Definition: res_aeap.h:337
int ast_aeap_disconnect(struct ast_aeap *aeap)
Disconnect an Asterisk external application object.
Definition: aeap.c:381
struct ast_aeap * ast_aeap_create_by_id(const char *id, const struct ast_aeap_params *params)
Create an Asterisk external application object by sorcery id.
Definition: res_aeap.c:317
const struct ast_aeap_params * params
Definition: aeap.c:49
struct ast_aeap * ast_aeap_create_and_connect(const char *type, const struct ast_aeap_params *params, const char *url, const char *protocol, int timeout)
Create and connect to an Asterisk external application.
Definition: aeap.c:363
struct ast_aeap * ast_aeap_create_and_connect_by_id(const char *id, const struct ast_aeap_params *params, int timeout)
Create and connect to an Asterisk external application by sorcery id.
Definition: res_aeap.c:322
struct ast_variable * ast_aeap_custom_fields_get(const char *id)
Retrieve a list of custom configuration fields.
Definition: res_aeap.c:328
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
int ast_aeap_user_data_register(struct ast_aeap *aeap, const char *id, void *obj, ast_aeap_user_obj_cleanup cleanup)
Register a user data object.
Definition: aeap.c:150
void(* on_error)(struct ast_aeap *aeap)
Raised when an error occurs during reading.
Definition: res_aeap.h:192
Asterisk external application base message.
An Asterisk external application message handler.
Definition: res_aeap.h:108
void(* ast_aeap_on_timeout)(struct ast_aeap *aeap, struct ast_aeap_message *message, void *obj)
Event raised when a sent message does not receive a reply within a specified time interval...
Definition: res_aeap.h:123
AST_AEAP_DATA_TYPE
Supported Asterisk external application data types.
Definition: res_aeap.h:135
Message type virtual method table.
struct ast_aeap_message * msg
Definition: res_aeap.h:333
const struct ast_aeap_message_handler * response_handlers
Definition: res_aeap.h:155
Generic container type.
const struct ast_format_cap * ast_aeap_client_config_codecs(const struct ast_aeap_client_config *cfg)
Retrieve codec capabilities from the configuration.
Definition: res_aeap.c:131
struct ao2_container * ast_aeap_client_configs_get(const char *protocol)
Retrieve a listing of all client configuration objects by protocol.
Definition: res_aeap.c:142
uintmax_t response_handlers_size
Definition: res_aeap.h:157
int ast_aeap_send_binary(struct ast_aeap *aeap, const void *buf, uintmax_t size)
Send a binary data to an external application.
Definition: aeap.c:434
Definition: aeap.c:47
ast_aeap_on_message on_message
Definition: res_aeap.h:112