Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Macros | Typedefs | Enumerations | Functions
res_aeap.h File Reference

Asterisk External Application Protocol API. More...

#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  ast_aeap_message_handler
 An Asterisk external application message handler. More...
 
struct  ast_aeap_params
 Callbacks and other parameters used by an Asterisk external application object. More...
 
struct  ast_aeap_tsx_params
 Parameters to be used when sending a transaction based message. More...
 

Macros

#define AEAP_CONFIG_CLIENT   "client"
 

Typedefs

typedef int(* ast_aeap_on_message) (struct ast_aeap *aeap, struct ast_aeap_message *message, void *obj)
 Event raised when a message is received. More...
 
typedef 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. More...
 
typedef void(* ast_aeap_user_obj_cleanup) (void *obj)
 Callback to cleanup a user object. More...
 

Enumerations

enum  AST_AEAP_DATA_TYPE { AST_AEAP_DATA_TYPE_NONE, AST_AEAP_DATA_TYPE_BINARY, AST_AEAP_DATA_TYPE_STRING }
 Supported Asterisk external application data types.
 

Functions

const struct ast_format_capast_aeap_client_config_codecs (const struct ast_aeap_client_config *cfg)
 Retrieve codec capabilities from the configuration. More...
 
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. More...
 
struct ao2_containerast_aeap_client_configs_get (const char *protocol)
 Retrieve a listing of all client configuration objects by protocol. More...
 
int ast_aeap_connect (struct ast_aeap *aeap, const char *url, const char *protocol, int timeout)
 Connect to an external application. More...
 
struct ast_aeapast_aeap_create (const char *type, const struct ast_aeap_params *params)
 Create an Asterisk external application object. More...
 
struct ast_aeapast_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. More...
 
struct ast_aeapast_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. More...
 
struct ast_aeapast_aeap_create_by_id (const char *id, const struct ast_aeap_params *params)
 Create an Asterisk external application object by sorcery id. More...
 
struct ast_variableast_aeap_custom_fields_get (const char *id)
 Retrieve a list of custom configuration fields. More...
 
int ast_aeap_disconnect (struct ast_aeap *aeap)
 Disconnect an Asterisk external application object. More...
 
int ast_aeap_send_binary (struct ast_aeap *aeap, const void *buf, uintmax_t size)
 Send a binary data to an external application. More...
 
int ast_aeap_send_msg (struct ast_aeap *aeap, struct ast_aeap_message *msg)
 Send a message to an external application. More...
 
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. More...
 
struct ast_sorceryast_aeap_sorcery (void)
 Retrieve the AEAP sorcery object. More...
 
void * ast_aeap_user_data_object_by_id (struct ast_aeap *aeap, const char *id)
 Retrieve a registered user data object by its id. More...
 
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. More...
 
void ast_aeap_user_data_unregister (struct ast_aeap *aeap, const char *id)
 Un-register a user data object. More...
 

Detailed Description

Asterisk External Application Protocol API.

Definition in file res_aeap.h.

Typedef Documentation

typedef int(* ast_aeap_on_message) (struct ast_aeap *aeap, struct ast_aeap_message *message, void *obj)

Event raised when a message is received.

Parameters
aeapAn Asterisk external application object
messageThe received message
objAssociated user object
Returns
0 on if message handled, otherwise non-zero

Definition at line 101 of file res_aeap.h.

typedef 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.

Parameters
aeapAn Asterisk external application object
messageThe message sent that received no response
objAssociated user object

Definition at line 123 of file res_aeap.h.

typedef void(* ast_aeap_user_obj_cleanup) (void *obj)

Callback to cleanup a user object.

Parameters
objThe user object

Definition at line 130 of file res_aeap.h.

Function Documentation

const struct ast_format_cap* ast_aeap_client_config_codecs ( const struct ast_aeap_client_config cfg)

Retrieve codec capabilities from the configuration.

Parameters
cfgA configuration object
Returns
The configuration's codec capabilities

Definition at line 131 of file res_aeap.c.

References ast_aeap_client_config::codecs.

132 {
133  return cfg->codecs;
134 }
struct ast_format_cap * codecs
Definition: res_aeap.c:81
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.

Parameters
cfgA configuration object
protocolThe protocol to check
Returns
True if the configuration's protocol matches, false otherwise

Definition at line 136 of file res_aeap.c.

References ast_aeap_client_config::protocol.

138 {
139  return !strcmp(protocol, cfg->protocol);
140 }
const ast_string_field protocol
Definition: res_aeap.c:79
struct ao2_container* ast_aeap_client_configs_get ( const char *  protocol)

Retrieve a listing of all client configuration objects by protocol.

Note
Caller is responsible for the returned container's reference.
Parameters
protocolAn optional protocol to filter on (if NULL returns all client configs)
Returns
A container of client configuration objects

Definition at line 142 of file res_aeap.c.

References AST_RETRIEVE_FLAG_ALL, AST_RETRIEVE_FLAG_MULTIPLE, ast_sorcery_retrieve_by_fields(), ast_variables_destroy(), and container.

143 {
144  struct ao2_container *container;
145  struct ast_variable *var;
146 
147  var = protocol ? ast_variable_new("protocol ==", protocol, "") : NULL;
148 
149  container = ast_sorcery_retrieve_by_fields(aeap_sorcery,
150  AEAP_CONFIG_CLIENT, AST_RETRIEVE_FLAG_MULTIPLE | AST_RETRIEVE_FLAG_ALL, var);
151 
153 
154  return container;
155 }
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262
Structure for variables, used for configurations and for channel variables.
Perform no matching, return all objects.
Definition: sorcery.h:123
Return all matching objects.
Definition: sorcery.h:120
struct ao2_container * container
Definition: res_fax.c:501
void * ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields)
Retrieve an object or multiple objects using specific fields.
Definition: sorcery.c:1897
Generic container type.
int ast_aeap_connect ( struct ast_aeap aeap,
const char *  url,
const char *  protocol,
int  timeout 
)

Connect to an external application.

Parameters
aeapAn Asterisk external application object
urlThe url to connect to
protocolA protocol to use
timeoutHow long (in milliseconds) to attempt to connect (-1 equals infinite)
Returns
0 if able to connect, -1 on error

Definition at line 338 of file aeap.c.

References ast_aeap_disconnect(), lock, ast_aeap::read_thread_id, SCOPED_AO2LOCK, and ast_aeap::transport.

Referenced by ast_aeap_create_and_connect().

339 {
340  SCOPED_AO2LOCK(lock, aeap);
341 
342  if (aeap_transport_is_connected(aeap->transport)) {
343  /* Should already be connected, so nothing to do */
344  return 0;
345  }
346 
347  if (aeap_transport_connect(aeap->transport, url, protocol, timeout)) {
348  aeap_error(aeap, NULL, "unable to connect transport");
349  return -1;
350  }
351 
352  if (ast_pthread_create_background(&aeap->read_thread_id, NULL,
353  aeap_receive, aeap)) {
354  aeap_error(aeap, NULL, "unable to start read thread: %s",
355  strerror(errno));
356  ast_aeap_disconnect(aeap);
357  return -1;
358  }
359 
360  return 0;
361 }
struct aeap_transport * transport
Definition: aeap.c:55
ast_mutex_t lock
int ast_aeap_disconnect(struct ast_aeap *aeap)
Disconnect an Asterisk external application object.
Definition: aeap.c:381
#define SCOPED_AO2LOCK(varname, obj)
scoped lock specialization for ao2 mutexes.
Definition: lock.h:604
pthread_t read_thread_id
Definition: aeap.c:57
struct ast_aeap* ast_aeap_create ( const char *  type,
const struct ast_aeap_params params 
)

Create an Asterisk external application object.

Parameters
typeThe type of underlying transport
paramsCallbacks and other parameters to use
Returns
A new ao2 reference counted aeap object, or NULL on error

Definition at line 88 of file aeap.c.

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ao2_ref, ast_aeap::params, ast_aeap::read_thread_id, ast_aeap::transactions, ast_aeap::transport, and ast_aeap::user_data.

Referenced by ast_aeap_create_and_connect().

90 {
91  struct ast_aeap *aeap;
92 
93  aeap = ao2_alloc(sizeof(*aeap), aeap_destructor);
94  if (!aeap) {
95  ast_log(LOG_ERROR, "AEAP: unable to create");
96  return NULL;
97  }
98 
99  aeap->params = params;
100  aeap->read_thread_id = AST_PTHREADT_NULL;
101 
102  aeap->user_data = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0, USER_DATA_BUCKETS,
103  aeap_user_data_hash_fn, NULL, aeap_user_data_cmp_fn);
104  if (!aeap->user_data) {
105  aeap_error(aeap, NULL, "unable to create user data container");
106  ao2_ref(aeap, -1);
107  return NULL;
108  }
109 
110  aeap->transactions = aeap_transactions_create();
111  if (!aeap->transactions) {
112  aeap_error(aeap, NULL, "unable to create transactions container");
113  ao2_ref(aeap, -1);
114  return NULL;
115  }
116 
117  aeap->transport = aeap_transport_create(transport_type);
118  if (!aeap->transport) {
119  aeap_error(aeap, NULL, "unable to create transport");
120  ao2_ref(aeap, -1);
121  return NULL;
122  }
123 
124  return aeap;
125 }
struct ao2_container * transactions
Definition: aeap.c:53
struct aeap_transport * transport
Definition: aeap.c:55
struct ao2_container * user_data
Definition: aeap.c:51
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
const struct ast_aeap_params * params
Definition: aeap.c:49
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Allocate and initialize a hash container with the desired number of buckets.
Definition: astobj2.h:1303
pthread_t read_thread_id
Definition: aeap.c:57
Definition: aeap.c:47
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.

Parameters
typeThe type of client connection to make
paramsCallbacks and other parameters to use
urlThe url to connect to
protocolA protocol to use
timeoutHow long (in milliseconds) to attempt to connect (-1 equals infinite)
Returns
A new ao2 reference counted aeap object, or NULL on error

Definition at line 363 of file aeap.c.

References ao2_ref, ast_aeap_connect(), and ast_aeap_create().

365 {
366  struct ast_aeap *aeap;
367 
368  aeap = ast_aeap_create(type, params);
369  if (!aeap) {
370  return NULL;
371  }
372 
373  if (ast_aeap_connect(aeap, url, protocol, timeout)) {
374  ao2_ref(aeap, -1);
375  return NULL;
376  }
377 
378  return aeap;
379 }
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_connect(struct ast_aeap *aeap, const char *url, const char *protocol, int timeout)
Connect to an external application.
Definition: aeap.c:338
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Definition: aeap.c:47
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.

Parameters
idThe sorcery id to lookup
paramsCallbacks and other parameters to use
timeoutHow long (in milliseconds) to attempt to connect (-1 equals infinite)
Returns
A new ao2 reference counted aeap object, or NULL on error

Definition at line 322 of file res_aeap.c.

324 {
325  return aeap_create(id, params, 1, timeout);
326 }
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.

Parameters
idThe sorcery id to lookup
paramsCallbacks and other parameters to use
Returns
A new ao2 reference counted aeap object, or NULL on error

Definition at line 317 of file res_aeap.c.

318 {
319  return aeap_create(id, params, 0, 0);
320 }
struct ast_variable* ast_aeap_custom_fields_get ( const char *  id)

Retrieve a list of custom configuration fields.

Parameters
idconfiguration id/sorcery lookup key
Returns
variables, or NULL on error

Definition at line 328 of file res_aeap.c.

References ao2_ref, and ast_sorcery_objectset_create.

329 {
330  struct ast_aeap_client_config *cfg;
331  struct ast_variable *vars;
332 
333  cfg = client_config_get(id);
334  if (!cfg) {
335  ast_log(LOG_WARNING, "AEAP: no client configuration '%s' to get fields\n", id);
336  return NULL;
337  }
338 
339  vars = ast_sorcery_objectset_create(aeap_sorcery, cfg);
340 
341  ao2_ref(cfg, -1);
342  return vars;
343 }
Structure for variables, used for configurations and for channel variables.
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define ast_sorcery_objectset_create(sorcery, object)
Create an object set (KVP list) for an object.
Definition: sorcery.h:1137
int ast_aeap_disconnect ( struct ast_aeap aeap)

Disconnect an Asterisk external application object.

Note
Depending on the underlying transport this call may block
Parameters
aeapAn Asterisk external application object
Returns
0 on success, -1 on error

Definition at line 381 of file aeap.c.

References ast_aeap::read_thread_id, and ast_aeap::transport.

Referenced by ast_aeap_connect().

382 {
383  ao2_lock(aeap);
384 
385  aeap_transport_disconnect(aeap->transport);
386 
387  if (aeap->read_thread_id != AST_PTHREADT_NULL) {
388  /*
389  * The read thread calls disconnect if an error occurs, so
390  * unlock the aeap before "joining" to avoid a deadlock.
391  */
392  ao2_unlock(aeap);
393  pthread_join(aeap->read_thread_id, NULL);
394  ao2_lock(aeap);
395 
396  aeap->read_thread_id = AST_PTHREADT_NULL;
397  }
398 
399  ao2_unlock(aeap);
400 
401  return 0;
402 }
struct aeap_transport * transport
Definition: aeap.c:55
pthread_t read_thread_id
Definition: aeap.c:57
int ast_aeap_send_binary ( struct ast_aeap aeap,
const void *  buf,
uintmax_t  size 
)

Send a binary data to an external application.

Parameters
aeapAn Asterisk external application object
bufBinary data to send
sizeThe size of the binary data
Returns
0 on success, -1 on error

Definition at line 434 of file aeap.c.

435 {
436  return aeap_send(aeap, buf, size, AST_AEAP_DATA_TYPE_BINARY);
437 }
int ast_aeap_send_msg ( struct ast_aeap aeap,
struct ast_aeap_message msg 
)

Send a message to an external application.

Note
"Steals" the given message reference, thus callers are not required to un-ref the message object after calling this function.
Parameters
aeapAn Asterisk external application object
msgThe message to send
Returns
0 on success, -1 on error

Definition at line 439 of file aeap.c.

References ao2_ref, ast_aeap_message_serialize(), ast_aeap_message_type::serial_type, and ast_aeap_message::type.

Referenced by ast_aeap_send_msg_tsx().

440 {
441  void *buf;
442  intmax_t size;
443  int res;
444 
445  if (!msg) {
446  aeap_error(aeap, NULL, "no message to send");
447  return -1;
448  }
449 
450  if (ast_aeap_message_serialize(msg, &buf, &size)) {
451  aeap_error(aeap, NULL, "unable to serialize outgoing message");
452  ao2_ref(msg, -1);
453  return -1;
454  }
455 
456  res = aeap_send(aeap, buf, size, msg->type->serial_type);
457 
458  ast_free(buf);
459  ao2_ref(msg, -1);
460 
461  return res;
462 }
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
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.
enum AST_AEAP_DATA_TYPE serial_type
const struct ast_aeap_message_type * type
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.

Note
"Steals" the given message reference, thus callers are not required to un-ref the message object after calling this function.
Also handles cleaning up the user object if the obj_cleanup callback is specified in "params".
Parameters
aeapAn Asterisk external application object
params(optional) Additional parameters to consider when sending. Heap allocation not required.
Returns
0 on success, -1 on error

Definition at line 464 of file aeap.c.

References ao2_bump, ao2_ref, ast_aeap_message_id(), ast_aeap_send_msg(), ast_aeap_tsx_params::msg, and ast_aeap::transactions.

465 {
466  struct aeap_transaction *tsx = NULL;
467  int res = 0;
468 
469  if (!params) {
470  return -1;
471  }
472 
473  if (!params->msg) {
474  aeap_transaction_params_cleanup(params);
475  aeap_error(aeap, NULL, "no message to send");
476  return -1;
477  }
478 
479  /* The transaction will take over params cleanup, which includes the msg reference */
480  tsx = aeap_transaction_create_and_add(aeap->transactions,
481  ast_aeap_message_id(params->msg), params, aeap);
482  if (!tsx) {
483  return -1;
484  }
485 
486  if (ast_aeap_send_msg(aeap, ao2_bump(params->msg))) {
487  aeap_transaction_end(tsx, -1); /* Removes container, and tsx ref */
488  return -1;
489  }
490 
491  if (aeap_transaction_start(tsx)) {
492  aeap_transaction_end(tsx, -1); /* Removes container, and tsx ref */
493  return -1;
494  }
495 
496  res = aeap_transaction_result(tsx);
497 
498  ao2_ref(tsx, -1);
499 
500  return res;
501 }
struct ao2_container * transactions
Definition: aeap.c:53
const char * ast_aeap_message_id(const struct ast_aeap_message *message)
Retrieve a message id.
#define ao2_bump(obj)
Bump refcount on an AO2 object by one, returning the object.
Definition: astobj2.h:480
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
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
struct ast_aeap_message * msg
Definition: res_aeap.h:333
struct ast_sorcery* ast_aeap_sorcery ( void  )

Retrieve the AEAP sorcery object.

Returns
the AEAP sorcery object

Definition at line 67 of file res_aeap.c.

67  {
68  return aeap_sorcery;
69 }
void* ast_aeap_user_data_object_by_id ( struct ast_aeap aeap,
const char *  id 
)

Retrieve a registered user data object by its id.

Note
Depending on how it was registered the returned user data object's lifetime may be managed by the given "aeap" object. If it was registered with a cleanup handler that [potentially] frees it the caller of this function must ensure it's done using the returned object before it's unregistered.
Parameters
aeapAn Asterisk external application object
idThe look up id for the object
Returns
A user data object

Definition at line 174 of file aeap.c.

References ao2_ref, aeap_user_data::obj, OBJ_SEARCH_KEY, and ast_aeap::user_data.

175 {
176  struct aeap_user_data *data;
177  void *obj;
178 
179  data = ao2_find(aeap->user_data, id, OBJ_SEARCH_KEY);
180  if (!data) {
181  return NULL;
182  }
183 
184  obj = data->obj;
185  ao2_ref(data, -1);
186 
187  /*
188  * Returned object's lifetime is based on how it was registered.
189  * See public function docs for more info
190  */
191  return obj;
192 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
struct ao2_container * user_data
Definition: aeap.c:51
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
void * obj
Definition: aeap.c:37
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.

Note
The "cleanup" is called on un-register, if one is specified
Parameters
aeapAn Asterisk external application object
idThe look up id for the object
objThe user object to register
cleanupOptional user object clean up callback
Returns
0 on success, -1 on error

Definition at line 150 of file aeap.c.

References ao2_link, ao2_ref, and ast_aeap::user_data.

152 {
153  struct aeap_user_data *data;
154 
155  data = aeap_user_data_create(id, obj, cleanup);
156  if (!data) {
157  return -1;
158  }
159 
160  if (!ao2_link(aeap->user_data, data)) {
161  ao2_ref(data, -1);
162  return -1;
163  }
164 
165  ao2_ref(data, -1);
166  return 0;
167 }
struct ao2_container * user_data
Definition: aeap.c:51
static void cleanup(void)
Clean up any old apps that we don't need any more.
Definition: res_stasis.c:327
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
void * obj
Definition: aeap.c:37
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
void ast_aeap_user_data_unregister ( struct ast_aeap aeap,
const char *  id 
)

Un-register a user data object.

Note
If specified on register, the "cleanup" callback is called during unregister.
Parameters
aeapAn Asterisk external application object
idThe look up id for the object

Definition at line 169 of file aeap.c.

References OBJ_NODATA, OBJ_SEARCH_KEY, OBJ_UNLINK, and ast_aeap::user_data.

170 {
171  ao2_find(aeap->user_data, id, OBJ_SEARCH_KEY | OBJ_UNLINK | OBJ_NODATA);
172 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
struct ao2_container * user_data
Definition: aeap.c:51