res_aeap_message.h File Reference

Asterisk External Application Protocol Message API. More...

#include <stdint.h>
#include "asterisk/res_aeap.h"

Include dependency graph for res_aeap_message.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
	Asterisk external application base message. More...
struct	ast_aeap_message_type
	Message type virtual method table. More...

Functions
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.
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.
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.
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.
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.
void *	ast_aeap_message_data (struct ast_aeap_message *message)
	Retrieve the core message data/body.
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.
const char *	ast_aeap_message_error_msg (const struct ast_aeap_message *message)
	Retrieve the error message if it has one.
int	ast_aeap_message_error_msg_set (struct ast_aeap_message *message, const char *error_msg)
	Set an error message.
const char *	ast_aeap_message_id (const struct ast_aeap_message *message)
	Retrieve a message id.
const char *	ast_aeap_message_id_generate (struct ast_aeap_message *message)
	Generate an id, and set it for the message.
int	ast_aeap_message_id_set (struct ast_aeap_message *message, const char *id)
	Set a message id.
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.
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_is_response (const struct ast_aeap_message *message)
	Retrieve whether or not this is a response message.
const char *	ast_aeap_message_name (const struct ast_aeap_message *message)
	Retrieve a message name.
enum AST_AEAP_DATA_TYPE	ast_aeap_message_serial_type (const struct ast_aeap_message_type *type)
	Retrieve the serial type a message type.
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.

Variables
const struct ast_aeap_message_type *	ast_aeap_message_type_json
	Asterisk external application JSON message type.

Detailed Description

Asterisk External Application Protocol Message API.

Definition in file res_aeap_message.h.

Function Documentation

ast_aeap_message_create1()

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.

Parameters

type	The type of message object to create
params	Any parameter(s) to pass to the type's constructor

Returns

An ao2 reference counted AEAP message object, or NULL on error

Definition at line 59 of file res/res_aeap/message.c.

{
    struct ast_aeap_message *msg;
 
    ast_assert(type != NULL);
    ast_assert(type->construct1 != NULL);
 
    msg = message_create(type);
    if (!msg) {
        return NULL;
    }
 
    if (type->construct1(msg, params)) {
        ast_log(LOG_ERROR, "AEAP message %s: unable to construct1\n", type->type_name);
        ao2_ref(msg, -1);
        return NULL;
    }
 
    return msg;
}

References ao2_ref, ast_assert, ast_log, LOG_ERROR, message_create(), NULL, and type.

Referenced by ast_aeap_message_deserialize().

ast_aeap_message_create2()

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.

Parameters

type	The type of message object to create
msg_type	The type of message (e.g. request or response)
name	The name of the message
id	The message id
params	Other optional parameter(s) to possibly use

Returns

An ao2 reference counted AEAP message object, or NULL on error

Definition at line 81 of file res/res_aeap/message.c.

{
    struct ast_aeap_message *msg;
 
    ast_assert(type != NULL);
    ast_assert(type->construct2 != NULL);
    ast_assert(msg_type != NULL);
    ast_assert(name != NULL);
 
    msg = message_create(type);
    if (!msg) {
        return NULL;
    }
 
    if (type->construct2(msg, msg_type, name, id, params)) {
        ast_log(LOG_ERROR, "AEAP message %s: unable to construct2\n", type->type_name);
        ao2_ref(msg, -1);
        return NULL;
    }
 
    return msg;
}

References ao2_ref, ast_assert, ast_log, LOG_ERROR, message_create(), name, NULL, and type.

Referenced by ast_aeap_message_create_request(), and ast_aeap_message_create_response().

ast_aeap_message_create_error()

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.

Parameters

type	The type of message object to create
name	The name of the message
id	Optional id
error_msg	Error message to set

Returns

An ao2 reference counted AEAP response object, or NULL on error

Definition at line 129 of file res/res_aeap/message.c.

{
    struct ast_aeap_message *msg;
 
    msg = ast_aeap_message_create_response(type, name, id, NULL);
    if (!msg) {
        return NULL;
    }
 
    if (ast_aeap_message_error_msg_set(msg, error_msg)) {
        ao2_ref(msg, -1);
        return NULL;
    }
 
    return msg;
}

References ao2_ref, ast_aeap_message_create_response(), ast_aeap_message_error_msg_set(), name, NULL, and type.

Referenced by handle_request_set(), and raise_msg_handler().

ast_aeap_message_create_request()

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.

Parameters

type	The type of message object to create
name	The name of the message
id	Optional id (if NULL an id is generated)
params	Other optional parameter(s) to possibly use

Returns

An ao2 reference counted AEAP request object, or NULL on error

Definition at line 105 of file res/res_aeap/message.c.

{
    struct ast_aeap_message *msg;
 
    msg = ast_aeap_message_create2(type, "request", name, id, params);
    if (!msg) {
        return NULL;
    }
 
    if (!id && !ast_aeap_message_id_generate(msg)) {
        ao2_ref(msg, -1);
        return NULL;
    }
 
    return msg;
}

References ao2_ref, ast_aeap_message_create2(), ast_aeap_message_id_generate(), name, NULL, and type.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), and speech_aeap_send_request().

ast_aeap_message_create_response()

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.

Parameters

type	The type of message object to create
name	The name of the message
id	Optional id
params	Other optional parameter(s) to possibly use

Returns

An ao2 reference counted AEAP response object, or NULL on error

Definition at line 123 of file res/res_aeap/message.c.

{
    return ast_aeap_message_create2(type, "response", name, id, params);
}

References ast_aeap_message_create2(), name, and type.

Referenced by ast_aeap_message_create_error(), AST_TEST_DEFINE(), and handle_request_set().

ast_aeap_message_data()

void * ast_aeap_message_data

(

struct ast_aeap_message *

message

)

Retrieve the core message data/body.

Parameters

message

A message object

Definition at line 232 of file res/res_aeap/message.c.

{
    ast_assert(message != NULL);
    ast_assert(message->type != NULL);
 
    return message->type->data ? message->type->data(message) : NULL;
}

References ast_assert, and NULL.

Referenced by handle_request_set(), handle_response_get(), and handle_response_setup().

ast_aeap_message_deserialize()

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.

Parameters

type	The message type to create, and deserialize to
buf	The buffer to deserialize
size	The size/length of the buffer

Returns

An ao2 reference counted AEAP message object, or NULL on error

Definition at line 147 of file res/res_aeap/message.c.

{
    struct ast_aeap_message *msg;
 
    ast_assert(type != NULL);
    ast_assert(type->deserialize != NULL);
 
    msg = ast_aeap_message_create1(type, NULL);
    if (!msg) {
        return NULL;
    }
 
    if (type->deserialize(msg, buf, size)) {
        ao2_ref(msg, -1);
        return NULL;
    }
 
    return msg;
}

References ao2_ref, ast_aeap_message_create1(), ast_assert, buf, NULL, and type.

Referenced by raise_msg().

ast_aeap_message_error_msg()

const char * ast_aeap_message_error_msg

(

const struct ast_aeap_message *

message

)

Retrieve the error message if it has one.

Parameters

message

A message object

Returns

The error message if available, or NULL

Definition at line 256 of file res/res_aeap/message.c.

{
    ast_assert(message != NULL);
    ast_assert(message->type != NULL);
 
    return message->type->error_msg ? message->type->error_msg(message) : NULL;
}

References ast_assert, and NULL.

Referenced by raise_msg_handler().

ast_aeap_message_error_msg_set()

int ast_aeap_message_error_msg_set	(	struct ast_aeap_message *	message,
		const char *	error_msg
	)

Set an error message.

Parameters

message	A message object
error_msg	The error string to set

Returns

0 on success, -1 on error

Definition at line 264 of file res/res_aeap/message.c.

{
    ast_assert(message != NULL);
    ast_assert(message->type != NULL);
 
    return message->type->error_msg_set ? message->type->error_msg_set(message, error_msg) : 0;
}

References ast_assert, and NULL.

Referenced by ast_aeap_message_create_error().

ast_aeap_message_id()

const char * ast_aeap_message_id

(

const struct ast_aeap_message *

message

)

Retrieve a message id.

Parameters

message

A message object

Returns

The message id, or an empty string

Definition at line 177 of file res/res_aeap/message.c.

{
    const char *id = NULL;
 
    ast_assert(message != NULL);
    ast_assert(message->type != NULL);
 
    if (message->type->id) {
        id = message->type->id(message);
    }
 
    return id ? id : "";
}

References ast_assert, id, and NULL.

Referenced by ast_aeap_message_id_generate(), ast_aeap_send_msg_tsx(), handle_msg(), handle_request_set(), raise_msg(), and raise_msg_handler().

ast_aeap_message_id_generate()

const char * ast_aeap_message_id_generate

(

struct ast_aeap_message *

message

)

Generate an id, and set it for the message.

Parameters

message

A message object

Returns

the generated id on success, or NULL on error

Definition at line 199 of file res/res_aeap/message.c.

{
    char uuid_str[AST_UUID_STR_LEN];
 
    ast_uuid_generate_str(uuid_str, sizeof(uuid_str));
    if (strlen(uuid_str) != (AST_UUID_STR_LEN - 1)) {
        ast_log(LOG_ERROR, "AEAP message %s failed to generate UUID for message '%s'",
            message->type->type_name, ast_aeap_message_name(message));
        return NULL;
    }
 
    return ast_aeap_message_id_set(message, uuid_str) ? NULL : ast_aeap_message_id(message);
}

References ast_aeap_message_id(), ast_aeap_message_id_set(), ast_aeap_message_name(), ast_log, ast_uuid_generate_str(), AST_UUID_STR_LEN, LOG_ERROR, and NULL.

Referenced by ast_aeap_message_create_request().

ast_aeap_message_id_set()

int ast_aeap_message_id_set	(	struct ast_aeap_message *	message,
		const char *	id
	)

Set a message id.

Parameters

message	A message object
id	The id to set

Returns

0 on success, -1 on error

Definition at line 191 of file res/res_aeap/message.c.

{
    ast_assert(message != NULL);
    ast_assert(message->type != NULL);
 
    return message->type->id_set ? message->type->id_set(message, id) : 0;
}

References ast_assert, and NULL.

Referenced by ast_aeap_message_id_generate().

ast_aeap_message_is_named()

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.

Note

Case insensitive

Parameters

message	A message object
name	The name to check against

Returns

True if matched, false otherwise

Definition at line 227 of file res/res_aeap/message.c.

{
    return name ? !strcasecmp(ast_aeap_message_name(message), name) : 0;
}

References ast_aeap_message_name(), and name.

Referenced by handle_msg(), and raise_msg_handler().

ast_aeap_message_is_request()

int ast_aeap_message_is_request

(

const struct ast_aeap_message *

message

)

Retrieve whether or not this is a request message.

Parameters

message

A message object

Returns

True if the message is a request, false otherwise

Definition at line 240 of file res/res_aeap/message.c.

{
    ast_assert(message != NULL);
    ast_assert(message->type != NULL);
 
    return message->type->is_request ? message->type->is_request(message) : 0;
}

References ast_assert, and NULL.

Referenced by raise_msg().

ast_aeap_message_is_response()

int ast_aeap_message_is_response

(

const struct ast_aeap_message *

message

)

Retrieve whether or not this is a response message.

Parameters

message

A message object

Returns

True if the message is a response, false otherwise

Definition at line 248 of file res/res_aeap/message.c.

{
    ast_assert(message != NULL);
    ast_assert(message->type != NULL);
 
    return message->type->is_response ? message->type->is_response(message) : 0;
}

References ast_assert, and NULL.

Referenced by raise_msg().

ast_aeap_message_name()

const char * ast_aeap_message_name

(

const struct ast_aeap_message *

message

)

Retrieve a message name.

Parameters

message

A message object

Returns

The message name, or an empty string

Definition at line 213 of file res/res_aeap/message.c.

{
    const char *name = NULL;
 
    ast_assert(message != NULL);
    ast_assert(message->type != NULL);
 
    if (message->type->name) {
        name = message->type->name(message);
    }
 
    return name ? name : "";
}

References ast_assert, name, and NULL.

Referenced by ast_aeap_message_id_generate(), ast_aeap_message_is_named(), handle_msg(), handle_request_set(), raise_msg_handler(), and transaction_end().

ast_aeap_message_serial_type()

enum AST_AEAP_DATA_TYPE ast_aeap_message_serial_type

(

const struct ast_aeap_message_type *

type

)

Retrieve the serial type a message type.

Parameters

type	A message type

Returns

The type's serial type

Definition at line 27 of file res/res_aeap/message.c.

{
    ast_assert(type != NULL);
 
    return type->serial_type;
}

References ast_assert, NULL, and type.

Referenced by raise_msg().

ast_aeap_message_serialize()

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.

Parameters

message	The message object to serialize
buf	[out] The buffer to hold the "packed" data
size	[out] The size of the data written to the buffer

Returns

0 on success, -1 on error

Definition at line 168 of file res/res_aeap/message.c.

{
    ast_assert(message != NULL);
    ast_assert(message->type != NULL);
 
    return message->type->serialize ? message->type->serialize(message, buf, size) : 0;
}

References ast_assert, buf, and NULL.

Referenced by ast_aeap_send_msg().

Variable Documentation

ast_aeap_message_type_json

const struct ast_aeap_message_type* ast_aeap_message_type_json

extern

Asterisk external application JSON message type.

Definition at line 191 of file message_json.c.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), handle_request_set(), load_module(), and speech_aeap_send_request().