Asterisk - The Open Source Telephony Project GIT-master-2de1a68
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
28struct ao2_container;
29struct ast_sorcery;
30struct ast_variable;
31
33struct 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 */
42struct 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 */
53struct 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 */
82struct 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 */
90struct 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 */
101typedef 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 */
123typedef 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 */
130typedef void (*ast_aeap_user_obj_cleanup)(void *obj);
131
132/*!
133 * \brief Supported Asterisk external application data types
134 */
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 */
203struct 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 */
213struct 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 */
225int 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 */
236struct 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 */
250struct 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 */
262int 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 */
276int 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 */
287void 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 */
302void *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 */
313int 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 */
326int 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 */
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 */
368int ast_aeap_send_msg_tsx(struct ast_aeap *aeap, struct ast_aeap_tsx_params *params);
369
370#endif /* AST_RES_AEAP_H */
static const char type[]
Definition: chan_ooh323.c:109
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static void * cleanup(void *unused)
Definition: pbx_realtime.c:124
int ast_aeap_disconnect(struct ast_aeap *aeap)
Disconnect an Asterisk external application object.
Definition: aeap.c:381
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_aeap * ast_aeap_create(const char *type, const struct ast_aeap_params *params)
Create an Asterisk external application object.
Definition: aeap.c:88
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
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
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
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
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
struct ast_variable * ast_aeap_custom_fields_get(const char *id)
Retrieve a list of custom configuration fields.
Definition: res_aeap.c:328
struct ast_sorcery * ast_aeap_sorcery(void)
Retrieve the AEAP sorcery object.
Definition: res_aeap.c:67
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
AST_AEAP_DATA_TYPE
Supported Asterisk external application data types.
Definition: res_aeap.h:135
@ AST_AEAP_DATA_TYPE_NONE
Definition: res_aeap.h:136
@ AST_AEAP_DATA_TYPE_BINARY
Definition: res_aeap.h:137
@ AST_AEAP_DATA_TYPE_STRING
Definition: res_aeap.h:138
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
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
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
void ast_aeap_user_data_unregister(struct ast_aeap *aeap, const char *id)
Un-register a user data object.
Definition: aeap.c:169
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
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
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
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
void(* ast_aeap_user_obj_cleanup)(void *obj)
Callback to cleanup a user object.
Definition: res_aeap.h:130
static char url[512]
Generic container type.
An Asterisk external application message handler.
Definition: res_aeap.h:108
ast_aeap_on_message on_message
Definition: res_aeap.h:112
Message type virtual method table.
Asterisk external application base message.
Callbacks and other parameters used by an Asterisk external application object.
Definition: res_aeap.h:144
const struct ast_aeap_message_type * msg_type
Definition: res_aeap.h:152
unsigned int emit_error
Definition: res_aeap.h:149
void(* on_string)(struct ast_aeap *aeap, const char *buf, intmax_t size)
Raised when string data is received.
Definition: res_aeap.h:180
uintmax_t response_handlers_size
Definition: res_aeap.h:157
void(* on_error)(struct ast_aeap *aeap)
Raised when an error occurs during reading.
Definition: res_aeap.h:192
uintmax_t request_handlers_size
Definition: res_aeap.h:162
const struct ast_aeap_message_handler * response_handlers
Definition: res_aeap.h:155
const struct ast_aeap_message_handler * request_handlers
Definition: res_aeap.h:160
void(* on_binary)(struct ast_aeap *aeap, const void *buf, intmax_t size)
Raised when binary data is received.
Definition: res_aeap.h:171
Parameters to be used when sending a transaction based message.
Definition: res_aeap.h:331
struct ast_aeap_message * msg
Definition: res_aeap.h:333
ast_aeap_user_obj_cleanup obj_cleanup
Definition: res_aeap.h:350
ast_aeap_on_timeout on_timeout
Definition: res_aeap.h:337
Definition: aeap.c:47
const struct ast_aeap_params * params
Definition: aeap.c:49
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
Full structure for sorcery.
Definition: sorcery.c:230
Structure for variables, used for configurations and for channel variables.