res_aeap.h File Reference

Asterisk External Application Protocol API. More...

#include <stdint.h>

Include dependency graph for res_aeap.h:

This graph shows which files directly or indirectly include this file:

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

Functions
const struct ast_format_cap *	ast_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_container *	ast_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_aeap *	ast_aeap_create (const char *type, const struct ast_aeap_params *params)
	Create an Asterisk external application object. More...
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. More...
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. More...
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. More...
struct ast_variable *	ast_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_sorcery *	ast_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.

Macro Definition Documentation

AEAP_CONFIG_CLIENT

#define AEAP_CONFIG_CLIENT   "client"

Definition at line 35 of file res_aeap.h.

Typedef Documentation

ast_aeap_on_message

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

aeap	An Asterisk external application object
message	The received message
obj	Associated user object

Returns

0 on if message handled, otherwise non-zero

Definition at line 101 of file res_aeap.h.

ast_aeap_on_timeout

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

aeap	An Asterisk external application object
message	The message sent that received no response
obj	Associated user object

Definition at line 123 of file res_aeap.h.

ast_aeap_user_obj_cleanup

typedef void(* ast_aeap_user_obj_cleanup) (void *obj)

Callback to cleanup a user object.

Parameters

obj	The user object

Definition at line 130 of file res_aeap.h.

Enumeration Type Documentation

AST_AEAP_DATA_TYPE

enum AST_AEAP_DATA_TYPE

Supported Asterisk external application data types.

Enumerator
AST_AEAP_DATA_TYPE_NONE
AST_AEAP_DATA_TYPE_BINARY
AST_AEAP_DATA_TYPE_STRING

Definition at line 135 of file res_aeap.h.

                        {
    AST_AEAP_DATA_TYPE_NONE,
    AST_AEAP_DATA_TYPE_BINARY,
    AST_AEAP_DATA_TYPE_STRING,
};

Function Documentation

ast_aeap_client_config_codecs()

const struct ast_format_cap * ast_aeap_client_config_codecs

(

const struct ast_aeap_client_config *

cfg

)

Retrieve codec capabilities from the configuration.

Parameters

cfg	A configuration object

Returns

The configuration's codec capabilities

Definition at line 131 of file res_aeap.c.

{
    return cfg->codecs;
}

References ast_aeap_client_config::codecs.

Referenced by load_engine().

ast_aeap_client_config_has_protocol()

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

cfg	A configuration object
protocol	The protocol to check

Returns

True if the configuration's protocol matches, false otherwise

Definition at line 136 of file res_aeap.c.

{
    return !strcmp(protocol, cfg->protocol);
}

References ast_aeap_client_config::protocol.

Referenced by load_engine(), and unload_engine().

ast_aeap_client_configs_get()

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

protocol

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

{
    struct ao2_container *container;
    struct ast_variable *var;
 
    var = protocol ? ast_variable_new("protocol ==", protocol, "") : NULL;
 
    container = ast_sorcery_retrieve_by_fields(aeap_sorcery,
        AEAP_CONFIG_CLIENT, AST_RETRIEVE_FLAG_MULTIPLE | AST_RETRIEVE_FLAG_ALL, var);
 
    ast_variables_destroy(var);
 
    return container;
}

References AEAP_CONFIG_CLIENT, aeap_sorcery, AST_RETRIEVE_FLAG_ALL, AST_RETRIEVE_FLAG_MULTIPLE, ast_sorcery_retrieve_by_fields(), ast_variable_new, ast_variables_destroy(), container, NULL, and var.

Referenced by client_config_show(), client_config_show_all(), load_module(), speech_observer_loaded(), and unload_module().

ast_aeap_connect()

int ast_aeap_connect	(	struct ast_aeap *	aeap,
		const char *	url,
		const char *	protocol,
		int	timeout
	)

Connect to an external application.

Parameters

aeap	An Asterisk external application object
url	The url to connect to
protocol	A protocol to use
timeout	How 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.

{
    SCOPED_AO2LOCK(lock, aeap);
 
    if (aeap_transport_is_connected(aeap->transport)) {
        /* Should already be connected, so nothing to do */
        return 0;
    }
 
    if (aeap_transport_connect(aeap->transport, url, protocol, timeout)) {
        aeap_error(aeap, NULL, "unable to connect transport");
        return -1;
    }
 
    if (ast_pthread_create_background(&aeap->read_thread_id, NULL,
            aeap_receive, aeap)) {
        aeap_error(aeap, NULL, "unable to start read thread: %s",
            strerror(errno));
        ast_aeap_disconnect(aeap);
        return -1;
    }
 
    return 0;
}

References aeap_error, aeap_receive(), aeap_transport_connect(), aeap_transport_is_connected(), ast_aeap_disconnect(), ast_pthread_create_background, errno, lock, NULL, ast_aeap::read_thread_id, SCOPED_AO2LOCK, ast_aeap::transport, and url.

Referenced by ast_aeap_create_and_connect().

ast_aeap_create()

struct ast_aeap * ast_aeap_create	(	const char *	type,
		const struct ast_aeap_params *	params
	)

Create an Asterisk external application object.

Parameters

type	The type of underlying transport
params	Callbacks 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.

{
    struct ast_aeap *aeap;
 
    aeap = ao2_alloc(sizeof(*aeap), aeap_destructor);
    if (!aeap) {
        ast_log(LOG_ERROR, "AEAP: unable to create");
        return NULL;
    }
 
    aeap->params = params;
    aeap->read_thread_id = AST_PTHREADT_NULL;
 
    aeap->user_data = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0, USER_DATA_BUCKETS,
        aeap_user_data_hash_fn, NULL, aeap_user_data_cmp_fn);
    if (!aeap->user_data) {
        aeap_error(aeap, NULL, "unable to create user data container");
        ao2_ref(aeap, -1);
        return NULL;
    }
 
    aeap->transactions = aeap_transactions_create();
    if (!aeap->transactions) {
        aeap_error(aeap, NULL, "unable to create transactions container");
        ao2_ref(aeap, -1);
        return NULL;
    }
 
    aeap->transport = aeap_transport_create(transport_type);
    if (!aeap->transport) {
        aeap_error(aeap, NULL, "unable to create transport");
        ao2_ref(aeap, -1);
        return NULL;
    }
 
    return aeap;
}

References aeap_destructor(), aeap_error, aeap_transactions_create(), aeap_transport_create(), ao2_alloc, AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ao2_ref, ast_log, AST_PTHREADT_NULL, LOG_ERROR, NULL, ast_aeap::params, ast_aeap::read_thread_id, ast_aeap::transactions, ast_aeap::transport, ast_aeap::user_data, and USER_DATA_BUCKETS.

Referenced by aeap_create(), and ast_aeap_create_and_connect().

ast_aeap_create_and_connect()

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

type	The type of client connection to make
params	Callbacks and other parameters to use
url	The url to connect to
protocol	A protocol to use
timeout	How 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.

{
    struct ast_aeap *aeap;
 
    aeap = ast_aeap_create(type, params);
    if (!aeap) {
        return NULL;
    }
 
    if (ast_aeap_connect(aeap, url, protocol, timeout)) {
        ao2_ref(aeap, -1);
        return NULL;
    }
 
    return aeap;
}

References ao2_ref, ast_aeap_connect(), ast_aeap_create(), NULL, ast_aeap::params, type, and url.

Referenced by aeap_create(), and AST_TEST_DEFINE().

ast_aeap_create_and_connect_by_id()

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

id	The sorcery id to lookup
params	Callbacks and other parameters to use
timeout	How 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.

{
    return aeap_create(id, params, 1, timeout);
}

References aeap_create(), and ast_aeap::params.

Referenced by speech_aeap_engine_create().

ast_aeap_create_by_id()

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

id	The sorcery id to lookup
params	Callbacks 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.

{
    return aeap_create(id, params, 0, 0);
}

References aeap_create(), and ast_aeap::params.

ast_aeap_custom_fields_get()

struct ast_variable * ast_aeap_custom_fields_get

(

const char *

id

)

Retrieve a list of custom configuration fields.

Parameters

id	configuration id/sorcery lookup key

Returns

variables, or NULL on error

Definition at line 328 of file res_aeap.c.

{
    struct ast_aeap_client_config *cfg;
    struct ast_variable *vars;
 
    cfg = client_config_get(id);
    if (!cfg) {
        ast_log(LOG_WARNING, "AEAP: no client configuration '%s' to get fields\n", id);
        return NULL;
    }
 
    vars = ast_sorcery_objectset_create(aeap_sorcery, cfg);
 
    ao2_ref(cfg, -1);
    return vars;
}

References aeap_sorcery, ao2_ref, ast_log, ast_sorcery_objectset_create, client_config_get(), LOG_WARNING, and NULL.

Referenced by speech_aeap_engine_create().

ast_aeap_disconnect()

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

aeap	An Asterisk external application object

Returns

0 on success, -1 on error

Definition at line 381 of file aeap.c.

{
    ao2_lock(aeap);
 
    aeap_transport_disconnect(aeap->transport);
 
    if (aeap->read_thread_id != AST_PTHREADT_NULL) {
        /*
         * The read thread calls disconnect if an error occurs, so
         * unlock the aeap before "joining" to avoid a deadlock.
         */
        ao2_unlock(aeap);
        pthread_join(aeap->read_thread_id, NULL);
        ao2_lock(aeap);
 
        aeap->read_thread_id = AST_PTHREADT_NULL;
    }
 
    ao2_unlock(aeap);
 
    return 0;
}

References aeap_transport_disconnect(), ao2_lock, ao2_unlock, AST_PTHREADT_NULL, NULL, ast_aeap::read_thread_id, and ast_aeap::transport.

Referenced by aeap_destructor(), aeap_receive(), and ast_aeap_connect().

ast_aeap_send_binary()

int ast_aeap_send_binary	(	struct ast_aeap *	aeap,
		const void *	buf,
		uintmax_t	size
	)

Send a binary data to an external application.

Parameters

aeap	An Asterisk external application object
buf	Binary data to send
size	The size of the binary data

Returns

0 on success, -1 on error

Definition at line 434 of file aeap.c.

{
    return aeap_send(aeap, buf, size, AST_AEAP_DATA_TYPE_BINARY);
}

References aeap_send(), AST_AEAP_DATA_TYPE_BINARY, and buf.

Referenced by speech_aeap_engine_write().

ast_aeap_send_msg()

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

aeap	An Asterisk external application object
msg	The message to send

Returns

0 on success, -1 on error

Definition at line 439 of file aeap.c.

{
    void *buf;
    intmax_t size;
    int res;
 
    if (!msg) {
        aeap_error(aeap, NULL, "no message to send");
        return -1;
    }
 
    if (ast_aeap_message_serialize(msg, &buf, &size)) {
        aeap_error(aeap, NULL, "unable to serialize outgoing message");
        ao2_ref(msg, -1);
        return -1;
    }
 
    res = aeap_send(aeap, buf, size, msg->type->serial_type);
 
    ast_free(buf);
    ao2_ref(msg, -1);
 
    return res;
}

References aeap_error, aeap_send(), ao2_ref, ast_aeap_message_serialize(), ast_free, buf, NULL, ast_aeap_message_type::serial_type, and ast_aeap_message::type.

Referenced by ast_aeap_send_msg_tsx(), handle_request_set(), and raise_msg_handler().

ast_aeap_send_msg_tsx()

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

aeap	An 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.

{
    struct aeap_transaction *tsx = NULL;
    int res = 0;
 
    if (!params) {
        return -1;
    }
 
    if (!params->msg) {
        aeap_transaction_params_cleanup(params);
        aeap_error(aeap, NULL, "no message to send");
        return -1;
    }
 
    /* The transaction will take over params cleanup, which includes the msg reference */
    tsx = aeap_transaction_create_and_add(aeap->transactions,
        ast_aeap_message_id(params->msg), params, aeap);
    if (!tsx) {
        return -1;
    }
 
    if (ast_aeap_send_msg(aeap, ao2_bump(params->msg))) {
        aeap_transaction_end(tsx, -1); /* Removes container, and tsx ref */
        return -1;
    }
 
    if (aeap_transaction_start(tsx)) {
        aeap_transaction_end(tsx, -1); /* Removes container, and tsx ref */
        return -1;
    }
 
    res = aeap_transaction_result(tsx);
 
    ao2_ref(tsx, -1);
 
    return res;
}

References aeap_transaction::aeap, aeap_error, aeap_transaction_create_and_add(), aeap_transaction_end(), aeap_transaction_params_cleanup(), aeap_transaction_result(), aeap_transaction_start(), ao2_bump, ao2_ref, ast_aeap_message_id(), ast_aeap_send_msg(), ast_aeap_tsx_params::msg, NULL, aeap_transaction::params, and ast_aeap::transactions.

Referenced by AST_TEST_DEFINE(), and speech_aeap_send_request().

ast_aeap_sorcery()

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.

                                           {
    return aeap_sorcery;
}

References aeap_sorcery.

Referenced by load_module(), and unload_module().

ast_aeap_user_data_object_by_id()

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

aeap	An Asterisk external application object
id	The look up id for the object

Returns

A user data object

Definition at line 174 of file aeap.c.

{
    struct aeap_user_data *data;
    void *obj;
 
    data = ao2_find(aeap->user_data, id, OBJ_SEARCH_KEY);
    if (!data) {
        return NULL;
    }
 
    obj = data->obj;
    ao2_ref(data, -1);
 
    /*
     * Returned object's lifetime is based on how it was registered.
     * See public function docs for more info
     */
    return obj;
}

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

Referenced by ast_aeap_speech_on_error(), handle_msg(), handle_request_set(), handle_string(), and handle_timeout().

ast_aeap_user_data_register()

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

aeap	An Asterisk external application object
id	The look up id for the object
obj	The user object to register
cleanup	Optional user object clean up callback

Returns

0 on success, -1 on error

Definition at line 150 of file aeap.c.

{
    struct aeap_user_data *data;
 
    data = aeap_user_data_create(id, obj, cleanup);
    if (!data) {
        return -1;
    }
 
    if (!ao2_link(aeap->user_data, data)) {
        ao2_ref(data, -1);
        return -1;
    }
 
    ao2_ref(data, -1);
    return 0;
}

References aeap_user_data_create(), ao2_link, ao2_ref, cleanup(), aeap_user_data::obj, and ast_aeap::user_data.

Referenced by AST_TEST_DEFINE(), and speech_aeap_engine_create().

ast_aeap_user_data_unregister()

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

aeap	An Asterisk external application object
id	The look up id for the object

Definition at line 169 of file aeap.c.

{
    ao2_find(aeap->user_data, id, OBJ_SEARCH_KEY | OBJ_UNLINK | OBJ_NODATA);
}

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

Referenced by AST_TEST_DEFINE().