Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Functions | Variables
res_aeap_message.h File Reference

Asterisk External Application Protocol Message API. More...

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

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

Variables

const struct ast_aeap_message_typeast_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

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
typeThe type of message object to create
paramsAny 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.

References ao2_ref, ast_aeap_message_type::construct1, and ast_aeap_message_type::type_name.

Referenced by ast_aeap_message_deserialize().

61 {
62  struct ast_aeap_message *msg;
63 
64  ast_assert(type != NULL);
65  ast_assert(type->construct1 != NULL);
66 
67  msg = message_create(type);
68  if (!msg) {
69  return NULL;
70  }
71 
72  if (type->construct1(msg, params)) {
73  ast_log(LOG_ERROR, "AEAP message %s: unable to construct1\n", type->type_name);
74  ao2_ref(msg, -1);
75  return NULL;
76  }
77 
78  return msg;
79 }
int(* construct1)(struct ast_aeap_message *self, const void *params)
Construct/Initialize a message object.
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Asterisk external application base message.
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
typeThe type of message object to create
msg_typeThe type of message (e.g. request or response)
nameThe name of the message
idThe message id
paramsOther 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.

References ao2_ref, ast_aeap_message_type::construct2, and ast_aeap_message_type::type_name.

Referenced by ast_aeap_message_create_request(), and ast_aeap_message_create_response().

83 {
84  struct ast_aeap_message *msg;
85 
86  ast_assert(type != NULL);
87  ast_assert(type->construct2 != NULL);
88  ast_assert(msg_type != NULL);
89  ast_assert(name != NULL);
90 
91  msg = message_create(type);
92  if (!msg) {
93  return NULL;
94  }
95 
96  if (type->construct2(msg, msg_type, name, id, params)) {
97  ast_log(LOG_ERROR, "AEAP message %s: unable to construct2\n", type->type_name);
98  ao2_ref(msg, -1);
99  return NULL;
100  }
101 
102  return msg;
103 }
int(* construct2)(struct ast_aeap_message *self, const char *msg_type, const char *name, const char *id, const void *params)
Construct/Initialize a message object.
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Asterisk external application base message.
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
typeThe type of message object to create
nameThe name of the message
idOptional id
error_msgError 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.

References ao2_ref, ast_aeap_message_create_response(), and ast_aeap_message_error_msg_set().

131 {
132  struct ast_aeap_message *msg;
133 
134  msg = ast_aeap_message_create_response(type, name, id, NULL);
135  if (!msg) {
136  return NULL;
137  }
138 
139  if (ast_aeap_message_error_msg_set(msg, error_msg)) {
140  ao2_ref(msg, -1);
141  return NULL;
142  }
143 
144  return msg;
145 }
int ast_aeap_message_error_msg_set(struct ast_aeap_message *message, const char *error_msg)
Set an error message.
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
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.
Asterisk external application base message.
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
typeThe type of message object to create
nameThe name of the message
idOptional id (if NULL an id is generated)
paramsOther 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.

References ao2_ref, ast_aeap_message_create2(), and ast_aeap_message_id_generate().

107 {
108  struct ast_aeap_message *msg;
109 
110  msg = ast_aeap_message_create2(type, "request", name, id, params);
111  if (!msg) {
112  return NULL;
113  }
114 
115  if (!id && !ast_aeap_message_id_generate(msg)) {
116  ao2_ref(msg, -1);
117  return NULL;
118  }
119 
120  return msg;
121 }
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Asterisk external application base message.
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.
const char * ast_aeap_message_id_generate(struct ast_aeap_message *message)
Generate an id, and set it for the message.
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
typeThe type of message object to create
nameThe name of the message
idOptional id
paramsOther 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.

References ast_aeap_message_create2().

Referenced by ast_aeap_message_create_error().

125 {
126  return ast_aeap_message_create2(type, "response", name, id, params);
127 }
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.
void* ast_aeap_message_data ( struct ast_aeap_message message)

Retrieve the core message data/body.

Parameters
messageA message object

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

References ast_aeap_message_type::data, and ast_aeap_message::type.

233 {
234  ast_assert(message != NULL);
235  ast_assert(message->type != NULL);
236 
237  return message->type->data ? message->type->data(message) : NULL;
238 }
void *(* data)(struct ast_aeap_message *self)
Retrieve the core message data/body.
const struct ast_aeap_message_type * type
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
typeThe message type to create, and deserialize to
bufThe buffer to deserialize
sizeThe 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.

References ao2_ref, ast_aeap_message_create1(), and ast_aeap_message_type::deserialize.

149 {
150  struct ast_aeap_message *msg;
151 
152  ast_assert(type != NULL);
153  ast_assert(type->deserialize != NULL);
154 
155  msg = ast_aeap_message_create1(type, NULL);
156  if (!msg) {
157  return NULL;
158  }
159 
160  if (type->deserialize(msg, buf, size)) {
161  ao2_ref(msg, -1);
162  return NULL;
163  }
164 
165  return msg;
166 }
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.
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
int(* deserialize)(struct ast_aeap_message *self, const void *buf, intmax_t size)
Deserialize the given buffer into a message object.
Asterisk external application base message.
const char* ast_aeap_message_error_msg ( const struct ast_aeap_message message)

Retrieve the error message if it has one.

Parameters
messageA message object
Returns
The error message if available, or NULL

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

References ast_aeap_message_type::error_msg, and ast_aeap_message::type.

257 {
258  ast_assert(message != NULL);
259  ast_assert(message->type != NULL);
260 
261  return message->type->error_msg ? message->type->error_msg(message) : NULL;
262 }
const char *(* error_msg)(const struct ast_aeap_message *self)
Retrieve the error message if it has one.
const struct ast_aeap_message_type * type
int ast_aeap_message_error_msg_set ( struct ast_aeap_message message,
const char *  error_msg 
)

Set an error message.

Parameters
messageA message object
error_msgThe error string to set
Returns
0 on success, -1 on error

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

References ast_aeap_message_type::error_msg_set, and ast_aeap_message::type.

Referenced by ast_aeap_message_create_error().

265 {
266  ast_assert(message != NULL);
267  ast_assert(message->type != NULL);
268 
269  return message->type->error_msg_set ? message->type->error_msg_set(message, error_msg) : 0;
270 }
int(* error_msg_set)(struct ast_aeap_message *self, const char *error_msg)
Set an error message.
const struct ast_aeap_message_type * type
const char* ast_aeap_message_id ( const struct ast_aeap_message message)

Retrieve a message id.

Parameters
messageA message object
Returns
The message id, or an empty string

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

References ast_aeap_message_type::id, and ast_aeap_message::type.

Referenced by ast_aeap_message_id_generate(), and ast_aeap_send_msg_tsx().

178 {
179  const char *id = NULL;
180 
181  ast_assert(message != NULL);
182  ast_assert(message->type != NULL);
183 
184  if (message->type->id) {
185  id = message->type->id(message);
186  }
187 
188  return id ? id : "";
189 }
const char *(* id)(const struct ast_aeap_message *self)
Retrieve a message id.
const struct ast_aeap_message_type * type
const char* ast_aeap_message_id_generate ( struct ast_aeap_message message)

Generate an id, and set it for the message.

Parameters
messageA message object
Returns
the generated id on success, or NULL on error

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

References ast_aeap_message_id(), ast_aeap_message_id_set(), ast_aeap_message_name(), ast_uuid_generate_str(), ast_aeap_message::type, and ast_aeap_message_type::type_name.

Referenced by ast_aeap_message_create_request().

200 {
201  char uuid_str[AST_UUID_STR_LEN];
202 
203  ast_uuid_generate_str(uuid_str, sizeof(uuid_str));
204  if (strlen(uuid_str) != (AST_UUID_STR_LEN - 1)) {
205  ast_log(LOG_ERROR, "AEAP message %s failed to generate UUID for message '%s'",
206  message->type->type_name, ast_aeap_message_name(message));
207  return NULL;
208  }
209 
210  return ast_aeap_message_id_set(message, uuid_str) ? NULL : ast_aeap_message_id(message);
211 }
const char * ast_aeap_message_id(const struct ast_aeap_message *message)
Retrieve a message id.
const char * ast_aeap_message_name(const struct ast_aeap_message *message)
Retrieve a message name.
int ast_aeap_message_id_set(struct ast_aeap_message *message, const char *id)
Set a message id.
char * ast_uuid_generate_str(char *buf, size_t size)
Generate a UUID string.
Definition: uuid.c:141
const struct ast_aeap_message_type * type
int ast_aeap_message_id_set ( struct ast_aeap_message message,
const char *  id 
)

Set a message id.

Parameters
messageA message object
idThe id to set
Returns
0 on success, -1 on error

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

References ast_aeap_message_type::id_set, and ast_aeap_message::type.

Referenced by ast_aeap_message_id_generate().

192 {
193  ast_assert(message != NULL);
194  ast_assert(message->type != NULL);
195 
196  return message->type->id_set ? message->type->id_set(message, id) : 0;
197 }
int(* id_set)(struct ast_aeap_message *self, const char *id)
Set a message id.
const struct ast_aeap_message_type * type
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
messageA message object
nameThe name to check against
Returns
True if matched, false otherwise

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

References ast_aeap_message_name().

228 {
229  return name ? !strcasecmp(ast_aeap_message_name(message), name) : 0;
230 }
const char * ast_aeap_message_name(const struct ast_aeap_message *message)
Retrieve a message name.
int ast_aeap_message_is_request ( const struct ast_aeap_message message)

Retrieve whether or not this is a request message.

Parameters
messageA message object
Returns
True if the message is a request, false otherwise

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

References ast_aeap_message_type::is_request, and ast_aeap_message::type.

241 {
242  ast_assert(message != NULL);
243  ast_assert(message->type != NULL);
244 
245  return message->type->is_request ? message->type->is_request(message) : 0;
246 }
int(* is_request)(const struct ast_aeap_message *self)
Retrieve whether or not this is a request message.
const struct ast_aeap_message_type * type
int ast_aeap_message_is_response ( const struct ast_aeap_message message)

Retrieve whether or not this is a response message.

Parameters
messageA message object
Returns
True if the message is a response, false otherwise

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

References ast_aeap_message_type::is_response, and ast_aeap_message::type.

249 {
250  ast_assert(message != NULL);
251  ast_assert(message->type != NULL);
252 
253  return message->type->is_response ? message->type->is_response(message) : 0;
254 }
int(* is_response)(const struct ast_aeap_message *self)
Retrieve whether or not this is a response message.
const struct ast_aeap_message_type * type
const char* ast_aeap_message_name ( const struct ast_aeap_message message)

Retrieve a message name.

Parameters
messageA message object
Returns
The message name, or an empty string

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

References ast_aeap_message_type::name, and ast_aeap_message::type.

Referenced by ast_aeap_message_id_generate(), and ast_aeap_message_is_named().

214 {
215  const char *name = NULL;
216 
217  ast_assert(message != NULL);
218  ast_assert(message->type != NULL);
219 
220  if (message->type->name) {
221  name = message->type->name(message);
222  }
223 
224  return name ? name : "";
225 }
const struct ast_aeap_message_type * type
const char *(* name)(const struct ast_aeap_message *self)
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.

Parameters
typeA message type
Returns
The type's serial type

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

References ast_aeap_message_type::serial_type.

28 {
29  ast_assert(type != NULL);
30 
31  return type->serial_type;
32 }
enum AST_AEAP_DATA_TYPE serial_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.

Parameters
messageThe 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.

References ast_aeap_message_type::serialize, and ast_aeap_message::type.

Referenced by ast_aeap_send_msg().

170 {
171  ast_assert(message != NULL);
172  ast_assert(message->type != NULL);
173 
174  return message->type->serialize ? message->type->serialize(message, buf, size) : 0;
175 }
const struct ast_aeap_message_type * type
int(* serialize)(const struct ast_aeap_message *self, void **buf, intmax_t *size)
Serialize the message object into byte/char buffer.