Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Macros | Functions | Variables
stasis_message.c File Reference

Stasis Message API. More...

#include "asterisk.h"
#include "asterisk/astobj2.h"
#include "asterisk/stasis.h"
#include "asterisk/utils.h"
#include "asterisk/hashtab.h"

Go to the source code of this file.

Data Structures

struct  stasis_message
 
struct  stasis_message_type
 

Macros

#define HAS_VIRTUAL(fn, msg)
 
#define INVOKE_VIRTUAL(fn, ...)
 

Functions

static void message_type_dtor (void *obj)
 
int stasis_message_can_be_ami (struct stasis_message *msg)
 Determine if the given message can be converted to AMI. More...
 
struct stasis_messagestasis_message_create (struct stasis_message_type *type, void *data)
 Create a new message. More...
 
struct stasis_messagestasis_message_create_full (struct stasis_message_type *type, void *data, const struct ast_eid *eid)
 Create a new message for an entity. More...
 
void * stasis_message_data (const struct stasis_message *msg)
 Get the data contained in a message. More...
 
static void stasis_message_dtor (void *obj)
 
const struct ast_eidstasis_message_eid (const struct stasis_message *msg)
 Get the entity id for a stasis_message. More...
 
const struct timeval * stasis_message_timestamp (const struct stasis_message *msg)
 Get the time when a message was created. More...
 
struct ast_manager_event_blobstasis_message_to_ami (struct stasis_message *msg)
 Build the AMI representation of the message. More...
 
struct ast_eventstasis_message_to_event (struct stasis_message *msg)
 Build the Generic event system representation of the message. More...
 
struct ast_jsonstasis_message_to_json (struct stasis_message *msg, struct stasis_message_sanitizer *sanitize)
 Build the JSON representation of the message. More...
 
struct stasis_message_typestasis_message_type (const struct stasis_message *msg)
 Get the message type for a stasis_message. More...
 
enum stasis_subscription_message_formatters stasis_message_type_available_formatters (const struct stasis_message_type *type)
 Get a bitmap of available formatters for a message type. More...
 
enum stasis_message_type_result stasis_message_type_create (const char *name, struct stasis_message_vtable *vtable, struct stasis_message_type **result)
 Create a new message type. More...
 
unsigned int stasis_message_type_hash (const struct stasis_message_type *type)
 Gets the hash of a given message type. More...
 
int stasis_message_type_id (const struct stasis_message_type *type)
 Gets the id of a given message type. More...
 
const char * stasis_message_type_name (const struct stasis_message_type *type)
 Gets the name of a given message type. More...
 

Variables

static int message_type_id
 
static struct stasis_message_vtable null_vtable = {}
 

Detailed Description

Stasis Message API.

Author
David M. Lee, II dlee@.nosp@m.digi.nosp@m.um.co.nosp@m.m

Definition in file stasis_message.c.

Function Documentation

int stasis_message_can_be_ami ( struct stasis_message msg)

Determine if the given message can be converted to AMI.

Parameters
msgMessage to see if can be converted to AMI.
Return values
0Cannot be converted
non-zeroCan be converted

Definition at line 251 of file stasis_message.c.

252 {
253  return HAS_VIRTUAL(to_ami, msg);
254 }
struct stasis_message* stasis_message_create ( struct stasis_message_type type,
void *  data 
)

Create a new message.

This message is an ao2 object, and must be ao2_cleanup()'ed when you are done with it. Messages are also immutable, and must not be modified after they are initialized. Especially the data in the message.

Parameters
typeType of the message
dataImmutable data that is the actual contents of the message
Returns
New message
Return values
NULLon error
Since
12

Definition at line 174 of file stasis_message.c.

References ast_eid_default, and stasis_message_create_full().

Referenced by ast_bridge_blob_create(), ast_bridge_blob_create_from_snapshots(), ast_bridge_publish_attended_transfer(), ast_bridge_publish_blind_transfer(), ast_bridge_publish_merge(), ast_bridge_publish_state(), ast_cdr_engine_term(), ast_channel_publish_final_snapshot(), ast_channel_publish_snapshot(), ast_endpoint_blob_create(), ast_manager_publish_event(), ast_multi_object_blob_single_channel_publish(), ast_mwi_blob_create(), ast_rtp_publish_rtcp_message(), ast_system_publish_registry(), local_optimization_finished_cb(), local_optimization_started_cb(), publish_cluster_discovery_to_stasis_full(), publish_corosync_ping_to_stasis(), publish_hint_change(), publish_hint_remove(), publish_load_message_type(), publish_parked_call(), publish_parked_call_failure(), stasis_app_user_event(), stasis_cache_clear_create(), stasis_test_message_create(), and stun_monitor_request().

175 {
177 }
struct stasis_message * stasis_message_create_full(struct stasis_message_type *type, void *data, const struct ast_eid *eid)
Create a new message for an entity.
struct ast_eid ast_eid_default
Global EID.
Definition: options.c:93
struct stasis_message* stasis_message_create_full ( struct stasis_message_type type,
void *  data,
const struct ast_eid eid 
)

Create a new message for an entity.

This message is an ao2 object, and must be ao2_cleanup()'ed when you are done with it. Messages are also immutable, and must not be modified after they are initialized. Especially the data in the message.

Parameters
typeType of the message
dataImmutable data that is the actual contents of the message
eidWhat entity originated this message. (NULL for aggregate)
Note
An aggregate message is a combined representation of the local and remote entities publishing the message data. e.g., An aggregate device state represents the combined device state from the local and any remote entities publishing state for a device. e.g., An aggregate MWI message is the old/new MWI counts accumulated from the local and any remote entities publishing to a mailbox.
Return values
Newmessage
NULLon error
Since
12.2.0

Definition at line 140 of file stasis_message.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_ref, ao2_t_alloc_options, ast_tvnow(), stasis_message::data, stasis_message::eid, stasis_message::eid_ptr, stasis_message::timestamp, and stasis_message::type.

Referenced by ast_publish_device_state_full(), and stasis_message_create().

141 {
142  struct stasis_message *message;
143 
144  if (type == NULL || data == NULL) {
145  return NULL;
146  }
147 
148  message = ao2_t_alloc_options(sizeof(*message), stasis_message_dtor,
149  AO2_ALLOC_OPT_LOCK_NOLOCK, type->name);
150  if (message == NULL) {
151  return NULL;
152  }
153 
154  message->timestamp = ast_tvnow();
155  /*
156  * XXX Normal ao2 ref counting rules says we should increment the message
157  * type ref here and decrement it in stasis_message_dtor(). However, the
158  * stasis message could be cached and legitimately cause the type ref count
159  * to hit the excessive ref count assertion. Since the message type
160  * practically has to be a global object anyway, we can get away with not
161  * holding a ref in the stasis message.
162  */
163  message->type = type;
164  ao2_ref(data, +1);
165  message->data = data;
166  if (eid) {
167  message->eid_ptr = &message->eid;
168  message->eid = *eid;
169  }
170 
171  return message;
172 }
struct ast_eid eid
struct timeval ast_tvnow(void)
Returns current timeval. Meant to replace calls to gettimeofday().
Definition: time.h:159
#define ao2_t_alloc_options(data_size, destructor_fn, options, debug_msg)
Allocate and initialize an object.
Definition: astobj2.h:402
struct stasis_message_type * type
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
struct timeval timestamp
const struct ast_eid * eid_ptr
void* stasis_message_data ( const struct stasis_message msg)
const struct ast_eid* stasis_message_eid ( const struct stasis_message msg)

Get the entity id for a stasis_message.

Since
12.2.0
Parameters
msgMessage to get eid.
Return values
Entityid of msg
NULLif msg is an aggregate or msg is NULL.

Definition at line 179 of file stasis_message.c.

References stasis_message::eid_ptr.

180 {
181  if (msg == NULL) {
182  return NULL;
183  }
184  return msg->eid_ptr;
185 }
const struct ast_eid * eid_ptr
const struct timeval* stasis_message_timestamp ( const struct stasis_message msg)

Get the time when a message was created.

Parameters
msgMessage.
Returns
Pointer to the timeval when the message was created.
Return values
NULLif msg is NULL.
Since
12

Definition at line 203 of file stasis_message.c.

References stasis_message::timestamp.

Referenced by handle_bridge_leave_message(), handle_channel_snapshot_update_message(), handle_dial_message(), and handle_parked_call_message().

204 {
205  if (msg == NULL) {
206  return NULL;
207  }
208  return &msg->timestamp;
209 }
struct timeval timestamp
struct ast_manager_event_blob* stasis_message_to_ami ( struct stasis_message msg)

Build the AMI representation of the message.

May return NULL, to indicate no representation. The returned object should be ao2_cleanup()'ed.

Parameters
msgMessage to convert to AMI.
Return values
NULLif AMI format is not supported.

Definition at line 224 of file stasis_message.c.

225 {
226  return INVOKE_VIRTUAL(to_ami, msg);
227 }
struct ast_event* stasis_message_to_event ( struct stasis_message msg)

Build the Generic event system representation of the message.

May return NULL, to indicate no representation. The returned object should be disposed of via ast_event_destroy.

Parameters
msgMessage to convert to AMI.
Return values
NULLif AMI format is not supported.

Definition at line 236 of file stasis_message.c.

237 {
238  return INVOKE_VIRTUAL(to_event, msg);
239 }
struct ast_json* stasis_message_to_json ( struct stasis_message msg,
struct stasis_message_sanitizer sanitize 
)

Build the JSON representation of the message.

May return NULL, to indicate no representation. The returned object should be ast_json_unref()'ed.

Parameters
msgMessage to convert to JSON string.
sanitizeSnapshot sanitization callback.
Returns
Newly allocated string with JSON message.
Return values
NULLif JSON format is not supported.

Definition at line 229 of file stasis_message.c.

232 {
233  return INVOKE_VIRTUAL(to_json, msg, sanitize);
234 }
struct stasis_message_type* stasis_message_type ( const struct stasis_message msg)

Get the message type for a stasis_message.

Parameters
msgMessage to type
Returns
Type of msg
Return values
NULLif msg is NULL.
Since
12

Definition at line 187 of file stasis_message.c.

References stasis_message::type.

Referenced by cache_update(), conf_send_event_to_participants(), device_state_cb(), endpoint_snapshot_get_id(), message_sink_cb(), rtp_reload(), stasis_subscription_final_message(), subscription_invoke(), xmpp_pubsub_devstate_cb(), and xmpp_pubsub_mwi_cb().

188 {
189  if (msg == NULL) {
190  return NULL;
191  }
192  return msg->type;
193 }
struct stasis_message_type * type
enum stasis_subscription_message_formatters stasis_message_type_available_formatters ( const struct stasis_message_type message_type)

Get a bitmap of available formatters for a message type.

Parameters
message_typeMessage type
Returns
A bitmap of stasis_subscription_message_formatters
Since
13.25.0
16.2.0

Definition at line 114 of file stasis_message.c.

116 {
117  return type->available_formatters;
118 }
enum stasis_message_type_result stasis_message_type_create ( const char *  name,
struct stasis_message_vtable vtable,
struct stasis_message_type **  result 
)

Create a new message type.

stasis_message_type is an AO2 object, so ao2_cleanup() when you're done with it.

Parameters
nameName of the new type.
vtableVirtual table of message methods. May be NULL.
[out]resultThe location where the new message type will be placed
Note
Stasis message type creation may be declined if the message type is disabled
Returns
A stasis_message_type_result enum
Since
12

Definition at line 56 of file stasis_message.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_t_alloc_options, ast_atomic_fetchadd_int(), ast_hashtab_hash_string(), ast_strdup, STASIS_MESSAGE_TYPE_DECLINED, stasis_message_type_declined(), STASIS_MESSAGE_TYPE_ERROR, STASIS_MESSAGE_TYPE_SUCCESS, STASIS_SUBSCRIPTION_FORMATTER_AMI, STASIS_SUBSCRIPTION_FORMATTER_EVENT, STASIS_SUBSCRIPTION_FORMATTER_JSON, stasis_message_vtable::to_ami, stasis_message_vtable::to_event, and stasis_message_vtable::to_json.

59 {
60  struct stasis_message_type *type;
61 
62  /* Check for declination */
63  if (name && stasis_message_type_declined(name)) {
65  }
66 
67  type = ao2_t_alloc_options(sizeof(*type), message_type_dtor,
68  AO2_ALLOC_OPT_LOCK_NOLOCK, name ?: "");
69  if (!type) {
71  }
72  if (!vtable) {
73  /* Null object pattern, FTW! */
74  vtable = &null_vtable;
75  }
76 
77  type->name = ast_strdup(name);
78  if (!type->name) {
79  ao2_cleanup(type);
81  }
82  type->hash = ast_hashtab_hash_string(name);
83  type->vtable = vtable;
84  if (vtable->to_json) {
85  type->available_formatters |= STASIS_SUBSCRIPTION_FORMATTER_JSON;
86  }
87  if (vtable->to_ami) {
88  type->available_formatters |= STASIS_SUBSCRIPTION_FORMATTER_AMI;
89  }
90  if (vtable->to_event) {
91  type->available_formatters |= STASIS_SUBSCRIPTION_FORMATTER_EVENT;
92  }
93  type->id = ast_atomic_fetchadd_int(&message_type_id, +1);
94  *result = type;
95 
97 }
int stasis_message_type_declined(const char *name)
Check whether a message type is declined.
Definition: stasis.c:2283
#define ao2_t_alloc_options(data_size, destructor_fn, options, debug_msg)
Allocate and initialize an object.
Definition: astobj2.h:402
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
struct ast_event *(* to_event)(struct stasis_message *message)
Build the ast_event representation of the message.
Definition: stasis.h:278
int ast_atomic_fetchadd_int(volatile int *p, int v)
Atomically add v to *p and return the previous value of *p.
Definition: lock.h:757
struct ast_json *(* to_json)(struct stasis_message *message, const struct stasis_message_sanitizer *sanitize)
Build the JSON representation of the message.
Definition: stasis.h:252
struct ast_manager_event_blob *(* to_ami)(struct stasis_message *message)
Build the AMI representation of the message.
Definition: stasis.h:264
unsigned int ast_hashtab_hash_string(const void *obj)
Hashes a string to a number.
Definition: main/hashtab.c:153
unsigned int stasis_message_type_hash ( const struct stasis_message_type type)

Gets the hash of a given message type.

Parameters
typeThe type to get the hash of.
Returns
The hash
Since
13.24.0

Definition at line 104 of file stasis_message.c.

105 {
106  return type->hash;
107 }
int stasis_message_type_id ( const struct stasis_message_type type)

Gets the id of a given message type.

Parameters
typeThe type to get the id of.
Returns
The id
Since
17.0.0

Definition at line 109 of file stasis_message.c.

Referenced by stasis_subscription_accept_message_type(), stasis_subscription_decline_message_type(), and subscription_invoke().

110 {
111  return type->id;
112 }
const char* stasis_message_type_name ( const struct stasis_message_type type)

Gets the name of a given message type.

Parameters
typeThe type to get.
Returns
Name of the type.
Return values
NULLif type is NULL.
Since
12

Definition at line 99 of file stasis_message.c.

Referenced by stasis_subscription_accept_message_type(), and stasis_subscription_decline_message_type().

100 {
101  return type->name;
102 }