Wed Jan 8 2020 09:50:11

Asterisk developer's documentation


event.h File Reference

Go to the source code of this file.

Typedefs

typedef void(* ast_event_cb_t )(const struct ast_event *event, void *userdata)
 Subscriber event callback type. More...
 

Functions

int ast_event_append_eid (struct ast_event **event)
 Append the global EID IE. More...
 
int ast_event_append_ie_bitflags (struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t bitflags)
 Append an information element that has a bitflags payload. More...
 
int ast_event_append_ie_raw (struct ast_event **event, enum ast_event_ie_type ie_type, const void *data, size_t data_len)
 Append an information element that has a raw payload. More...
 
int ast_event_append_ie_str (struct ast_event **event, enum ast_event_ie_type ie_type, const char *str)
 Append an information element that has a string payload. More...
 
int ast_event_append_ie_uint (struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t data)
 Append an information element that has an integer payload. More...
 
enum ast_event_subscriber_res ast_event_check_subscriber (enum ast_event_type event_type,...)
 Check if subscribers exist. More...
 
void ast_event_destroy (struct ast_event *event)
 Destroy an event. More...
 
void ast_event_dump_cache (const struct ast_event_sub *event_sub)
 Dump the event cache for the subscriber. More...
 
struct ast_eventast_event_get_cached (enum ast_event_type,...)
 Retrieve an event from the cache. More...
 
uint32_t ast_event_get_ie_bitflags (const struct ast_event *event, enum ast_event_ie_type ie_type)
 Get the value of an information element that has a bitflags payload. More...
 
enum ast_event_ie_pltype ast_event_get_ie_pltype (enum ast_event_ie_type ie_type)
 Get the payload type for a given information element type. More...
 
const void * ast_event_get_ie_raw (const struct ast_event *event, enum ast_event_ie_type ie_type)
 Get the value of an information element that has a raw payload. More...
 
uint16_t ast_event_get_ie_raw_payload_len (const struct ast_event *event, enum ast_event_ie_type ie_type)
 Get the length of the raw payload for a particular IE. More...
 
const char * ast_event_get_ie_str (const struct ast_event *event, enum ast_event_ie_type ie_type)
 Get the value of an information element that has a string payload. More...
 
uint32_t ast_event_get_ie_str_hash (const struct ast_event *event, enum ast_event_ie_type ie_type)
 Get the hash for the string payload of an IE. More...
 
const char * ast_event_get_ie_type_name (enum ast_event_ie_type ie_type)
 Get the string representation of an information element type. More...
 
uint32_t ast_event_get_ie_uint (const struct ast_event *event, enum ast_event_ie_type ie_type)
 Get the value of an information element that has an integer payload. More...
 
size_t ast_event_get_size (const struct ast_event *event)
 Get the size of an event. More...
 
enum ast_event_type ast_event_get_type (const struct ast_event *event)
 Get the type for an event. More...
 
const char * ast_event_get_type_name (const struct ast_event *event)
 Get the string representation of the type of the given event. More...
 
uint32_t ast_event_iterator_get_ie_bitflags (struct ast_event_iterator *iterator)
 Get the value of the current IE in the iterator as a bitflags payload. More...
 
void * ast_event_iterator_get_ie_raw (struct ast_event_iterator *iterator)
 Get the value of the current IE in the iterator instance that has a raw payload. More...
 
uint16_t ast_event_iterator_get_ie_raw_payload_len (struct ast_event_iterator *iterator)
 Get the length of the raw payload for the current IE for an iterator. More...
 
const char * ast_event_iterator_get_ie_str (struct ast_event_iterator *iterator)
 Get the value of the current IE in the iterator as a string payload. More...
 
enum ast_event_ie_type ast_event_iterator_get_ie_type (struct ast_event_iterator *iterator)
 Get the type of the current IE in the iterator instance. More...
 
uint32_t ast_event_iterator_get_ie_uint (struct ast_event_iterator *iterator)
 Get the value of the current IE in the iterator as an integer payload. More...
 
int ast_event_iterator_init (struct ast_event_iterator *iterator, const struct ast_event *event)
 Initialize an event iterator instance. More...
 
int ast_event_iterator_next (struct ast_event_iterator *iterator)
 Move iterator instance to next IE. More...
 
size_t ast_event_minimum_length (void)
 Get the minimum length of an ast_event. More...
 
struct ast_eventast_event_new (enum ast_event_type event_type,...)
 Create a new event. More...
 
int ast_event_queue (struct ast_event *event)
 Queue an event. More...
 
int ast_event_queue_and_cache (struct ast_event *event)
 Queue and cache an event. More...
 
void ast_event_report_subs (const struct ast_event_sub *sub)
 Report current subscriptions to a subscription subscriber. More...
 
int ast_event_str_to_event_type (const char *str, enum ast_event_type *event_type)
 Convert a string into an event type. More...
 
int ast_event_str_to_ie_type (const char *str, enum ast_event_ie_type *ie_type)
 Convert a string to an IE type. More...
 
int ast_event_sub_activate (struct ast_event_sub *sub)
 Activate a dynamically built subscription. More...
 
int ast_event_sub_append_ie_bitflags (struct ast_event_sub *sub, enum ast_event_ie_type ie_type, uint32_t flags)
 Append a bitflags parameter to a subscription. More...
 
int ast_event_sub_append_ie_exists (struct ast_event_sub *sub, enum ast_event_ie_type ie_type)
 Append an 'exists' parameter to a subscription. More...
 
int ast_event_sub_append_ie_raw (struct ast_event_sub *sub, enum ast_event_ie_type ie_type, void *data, size_t raw_datalen)
 Append a raw parameter to a subscription. More...
 
int ast_event_sub_append_ie_str (struct ast_event_sub *sub, enum ast_event_ie_type ie_type, const char *str)
 Append a string parameter to a subscription. More...
 
int ast_event_sub_append_ie_uint (struct ast_event_sub *sub, enum ast_event_ie_type ie_type, uint32_t uint)
 Append a uint parameter to a subscription. More...
 
void ast_event_sub_destroy (struct ast_event_sub *sub)
 Destroy an allocated subscription. More...
 
struct ast_event_subast_event_subscribe (enum ast_event_type event_type, ast_event_cb_t cb, const char *description, void *userdata,...)
 Subscribe to events. More...
 
struct ast_event_subast_event_subscribe_new (enum ast_event_type type, ast_event_cb_t cb, void *userdata)
 Allocate a subscription, but do not activate it. More...
 
const char * ast_event_subscriber_get_description (struct ast_event_sub *sub)
 Get description for a subscription. More...
 
struct ast_event_subast_event_unsubscribe (struct ast_event_sub *event_sub)
 Un-subscribe from events. More...
 

Detailed Description

Typedef Documentation

typedef void(* ast_event_cb_t)(const struct ast_event *event, void *userdata)

Subscriber event callback type.

Parameters
eventthe event being passed to the subscriber
userdatathe data provider in the call to ast_event_subscribe()
Returns
The event callbacks do not return anything.

Definition at line 74 of file event.h.

Function Documentation

int ast_event_append_eid ( struct ast_event **  event)

Append the global EID IE.

Parameters
eventthe event to append IE to
Note
For ast_event_new() that includes IEs, this is done automatically for you.
Return values
0success
-1failure

Definition at line 1308 of file event.c.

References ast_eid_default, ast_event_append_ie_raw(), and AST_EVENT_IE_EID.

Referenced by ast_event_new().

1309 {
1311  &ast_eid_default, sizeof(ast_eid_default));
1312 }
Entity ID Used by All events Payload type: RAW This IE indicates which server the event originated fr...
Definition: event_defs.h:266
int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, const void *data, size_t data_len)
Append an information element that has a raw payload.
Definition: event.c:1174
struct ast_eid ast_eid_default
Global EID.
Definition: asterisk.c:192
int ast_event_append_ie_bitflags ( struct ast_event **  event,
enum ast_event_ie_type  ie_type,
uint32_t  bitflags 
)

Append an information element that has a bitflags payload.

Parameters
eventthe event that the IE will be appended to
ie_typethe type of IE to append
bitflagsthe flags that are the payload of the IE
Return values
0success
-1failure
Since
1.8

The pointer to the event will get updated with the new location for the event that now contains the appended information element. If the re-allocation of the memory for this event fails, it will be set to NULL.

Definition at line 1167 of file event.c.

References ast_event_append_ie_raw().

Referenced by ast_event_get_cached(), ast_event_new(), and gen_sub_event().

1169 {
1170  flags = htonl(flags);
1171  return ast_event_append_ie_raw(event, ie_type, &flags, sizeof(flags));
1172 }
int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, const void *data, size_t data_len)
Append an information element that has a raw payload.
Definition: event.c:1174
enum ast_event_ie_type ie_type
Definition: event.c:110
int ast_event_append_ie_raw ( struct ast_event **  event,
enum ast_event_ie_type  ie_type,
const void *  data,
size_t  data_len 
)

Append an information element that has a raw payload.

Parameters
eventthe event that the IE will be appended to
ie_typethe type of IE to append
dataA pointer to the raw data for the payload of the IE
data_lenThe amount of data to copy into the payload
Return values
0success
-1failure

The pointer to the event will get updated with the new location for the event that now contains the appended information element. If the re-allocation of the memory for this event fails, it will be set to NULL.

Definition at line 1174 of file event.c.

References ast_free, ast_realloc, ast_event::event_len, ast_event_ie::ie_payload, and ast_event_ie::ie_payload_len.

Referenced by ast_event_append_eid(), ast_event_append_ie_bitflags(), ast_event_append_ie_str(), ast_event_append_ie_uint(), ast_event_get_cached(), ast_event_new(), and gen_sub_event().

1176 {
1177  struct ast_event_ie *ie;
1178  struct ast_event *old_event;
1179  unsigned int extra_len;
1180  uint16_t event_len;
1181 
1182  event_len = ntohs((*event)->event_len);
1183  extra_len = sizeof(*ie) + data_len;
1184 
1185  old_event = *event;
1186  *event = ast_realloc(*event, event_len + extra_len);
1187  if (!*event) {
1188  ast_free(old_event);
1189  return -1;
1190  }
1191 
1192  ie = (struct ast_event_ie *) ( ((char *) *event) + event_len );
1193  ie->ie_type = htons(ie_type);
1194  ie->ie_payload_len = htons(data_len);
1195  memcpy(ie->ie_payload, data, data_len);
1196 
1197  (*event)->event_len = htons(event_len + extra_len);
1198 
1199  return 0;
1200 }
An event.
Definition: event.c:85
uint16_t ie_payload_len
Definition: event.c:58
An event information element.
Definition: event.c:57
#define ast_free(a)
Definition: astmm.h:97
uint16_t event_len
Definition: event.c:87
#define ast_realloc(a, b)
Definition: astmm.h:103
unsigned char ie_payload[0]
Definition: event.c:61
int ast_event_append_ie_str ( struct ast_event **  event,
enum ast_event_ie_type  ie_type,
const char *  str 
)

Append an information element that has a string payload.

Parameters
eventthe event that the IE will be appended to
ie_typethe type of IE to append
strThe string for the payload of the IE
Return values
0success
-1failure

The pointer to the event will get updated with the new location for the event that now contains the appended information element. If the re-allocation of the memory for this event fails, it will be set to NULL.

Definition at line 1139 of file event.c.

References ast_alloca, ast_event_append_ie_raw(), AST_EVENT_IE_DEVICE, ast_str_hash(), ast_strdupa, ast_tech_to_upper(), ast_event_ie_str_payload::hash, and ast_event_ie_str_payload::str.

Referenced by add_ie(), add_ipv4_ie(), add_timeval_ie(), ast_event_get_cached(), ast_event_new(), and gen_sub_event().

1141 {
1142  struct ast_event_ie_str_payload *str_payload;
1143  size_t payload_len;
1144 
1145  payload_len = sizeof(*str_payload) + strlen(str);
1146  str_payload = ast_alloca(payload_len);
1147 
1148  strcpy(str_payload->str, str);
1149  if (ie_type == AST_EVENT_IE_DEVICE) {
1150  char *uppertech = ast_strdupa(str);
1151  ast_tech_to_upper(uppertech);
1152  str_payload->hash = ast_str_hash(uppertech);
1153  } else {
1154  str_payload->hash = ast_str_hash(str);
1155  }
1156 
1157  return ast_event_append_ie_raw(event, ie_type, str_payload, payload_len);
1158 }
uint32_t hash
A hash calculated with ast_str_hash(), to speed up comparisons.
Definition: event.c:69
#define ast_alloca(size)
call __builtin_alloca to ensure we get gcc builtin semantics
Definition: utils.h:653
const char * str
Definition: app_jack.c:144
char str[1]
The actual string, null terminated.
Definition: event.c:71
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: utils.h:663
char * ast_tech_to_upper(char *dev_str)
Convert the tech portion of a device string to upper case.
Definition: strings.h:939
int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, const void *data, size_t data_len)
Append an information element that has a raw payload.
Definition: event.c:1174
Device Name Used by AST_EVENT_DEVICE_STATE_CHANGE Payload type: STR.
Definition: event_defs.h:107
The payload for a string information element.
Definition: event.c:67
static force_inline int attribute_pure ast_str_hash(const char *str)
Compute a hash value on a string.
Definition: strings.h:949
int ast_event_append_ie_uint ( struct ast_event **  event,
enum ast_event_ie_type  ie_type,
uint32_t  data 
)

Append an information element that has an integer payload.

Parameters
eventthe event that the IE will be appended to
ie_typethe type of IE to append
dataThe integer for the payload of the IE
Return values
0success
-1failure

The pointer to the event will get updated with the new location for the event that now contains the appended information element. If the re-allocation of the memory for this event fails, it will be set to NULL.

Definition at line 1160 of file event.c.

References ast_event_append_ie_raw().

Referenced by add_ie(), ast_event_get_cached(), ast_event_new(), and gen_sub_event().

1162 {
1163  data = htonl(data);
1164  return ast_event_append_ie_raw(event, ie_type, &data, sizeof(data));
1165 }
int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, const void *data, size_t data_len)
Append an information element that has a raw payload.
Definition: event.c:1174
enum ast_event_subscriber_res ast_event_check_subscriber ( enum ast_event_type  event_type,
  ... 
)

Check if subscribers exist.

Parameters
event_typeThis is the type of event that the caller would like to check for subscribers to.

The rest of the arguments to this function specify additional parameters for checking for subscriptions to subsets of an event type. The arguments must in sets of:

* <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
*

and must end with AST_EVENT_IE_END.

If the ie_type specified is not AST_EVENT_IE_END, then it must be followed by a valid IE payload type. If the payload type specified is AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. Otherwise, a payload must also be specified.

Returns
This returns one of the values defined in the ast_event_subscriber_res enum which will indicate if subscribers exist that match the given criteria.

Example usage:

This example will check if there are any subscribers to MWI events for the mailbox defined in the "mailbox" variable.

Definition at line 448 of file event.c.

References ARRAY_LEN, ast_alloca, AST_EVENT_ALL, AST_EVENT_IE_END, AST_EVENT_IE_PLTYPE_BITFLAGS, AST_EVENT_IE_PLTYPE_EXISTS, AST_EVENT_IE_PLTYPE_RAW, AST_EVENT_IE_PLTYPE_STR, AST_EVENT_IE_PLTYPE_UINT, AST_EVENT_IE_PLTYPE_UNKNOWN, AST_EVENT_SUB_EXISTS, AST_EVENT_SUB_NONE, ast_event_subs, AST_LIST_HEAD_NOLOCK_INIT_VALUE, AST_LIST_INSERT_TAIL, AST_LIST_TRAVERSE, ast_log(), AST_RWDLLIST_RDLOCK, AST_RWDLLIST_TRAVERSE, AST_RWDLLIST_UNLOCK, AST_RWLIST_FIRST, ast_event_ie_val::ie_pltype, ast_event_ie_val::ie_type, ast_event_sub::ie_vals, ast_ev_check_list::ie_vals, LOG_ERROR, LOG_WARNING, match_sub_ie_val_to_event(), ast_event_ie_val::payload, ast_event_ie_val::raw, ast_event_ie_val::raw_datalen, ast_event_ie_val::str, ast_event_sub::type, and ast_event_ie_val::uint.

Referenced by ast_event_queue(), ast_event_sub_activate(), and ast_event_unsubscribe().

449 {
450  va_list ap;
451  enum ast_event_ie_type ie_type;
453  struct ast_event_ie_val *ie_val;
454  struct ast_event_sub *sub;
455  struct ast_ev_check_list check_ie_vals = {
457  };
458  const enum ast_event_type event_types[] = { type, AST_EVENT_ALL };
459  int i;
460  int want_specific_event;/* TRUE if looking for subscribers wanting specific parameters. */
461 
462  if (type >= AST_EVENT_TOTAL) {
463  ast_log(LOG_ERROR, "%u is an invalid type!\n", type);
464  return res;
465  }
466 
467  want_specific_event = 0;
468  va_start(ap, type);
469  for (ie_type = va_arg(ap, enum ast_event_ie_type);
470  ie_type != AST_EVENT_IE_END;
471  ie_type = va_arg(ap, enum ast_event_ie_type))
472  {
473  struct ast_event_ie_val *ie_value = ast_alloca(sizeof(*ie_value));
474  int insert = 0;
475 
476  memset(ie_value, 0, sizeof(*ie_value));
477  ie_value->ie_type = ie_type;
478  ie_value->ie_pltype = va_arg(ap, enum ast_event_ie_pltype);
479  switch (ie_value->ie_pltype) {
481  ie_value->payload.uint = va_arg(ap, uint32_t);
482  insert = 1;
483  break;
485  ie_value->payload.uint = va_arg(ap, uint32_t);
486  insert = 1;
487  break;
489  ie_value->payload.str = va_arg(ap, const char *);
490  insert = 1;
491  break;
493  {
494  void *data = va_arg(ap, void *);
495  size_t datalen = va_arg(ap, size_t);
496 
497  ie_value->payload.raw = ast_alloca(datalen);
498  memcpy(ie_value->payload.raw, data, datalen);
499  ie_value->raw_datalen = datalen;
500  insert = 1;
501  break;
502  }
505  /* Unsupported payload type. */
506  break;
507  }
508 
509  if (insert) {
510  want_specific_event = 1;
511  AST_LIST_INSERT_TAIL(&check_ie_vals.ie_vals, ie_value, entry);
512  } else {
513  ast_log(LOG_WARNING, "Unsupported PLTYPE(%d)\n", ie_value->ie_pltype);
514  }
515  }
516  va_end(ap);
517 
518  for (i = 0; i < ARRAY_LEN(event_types); i++) {
519  AST_RWDLLIST_RDLOCK(&ast_event_subs[event_types[i]]);
520  if (want_specific_event) {
521  AST_RWDLLIST_TRAVERSE(&ast_event_subs[event_types[i]], sub, entry) {
522  AST_LIST_TRAVERSE(&sub->ie_vals, ie_val, entry) {
523  if (!match_sub_ie_val_to_event(ie_val, &check_ie_vals)) {
524  /* The current subscription ie did not match an event ie. */
525  break;
526  }
527  }
528  if (!ie_val) {
529  /* Everything matched. A subscriber is looking for this event. */
530  break;
531  }
532  }
533  } else {
534  /* Just looking to see if there are ANY subscribers to the event type. */
535  sub = AST_RWLIST_FIRST(&ast_event_subs[event_types[i]]);
536  }
537  AST_RWDLLIST_UNLOCK(&ast_event_subs[event_types[i]]);
538  if (sub) {
539  break;
540  }
541  }
542 
544 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
#define ast_alloca(size)
call __builtin_alloca to ensure we get gcc builtin semantics
Definition: utils.h:653
ast_event_ie_pltype
Payload types for event information elements.
Definition: event_defs.h:299
enum ast_event_ie_pltype ie_pltype
Definition: event.c:111
struct ast_event_ie_val::@256 entry
#define LOG_WARNING
Definition: logger.h:144
union ast_event_ie_val::@257 payload
Subscription event check list.
Definition: event.c:369
ast_event_subscriber_res
Results for checking for subscribers.
Definition: event_defs.h:318
size_t raw_datalen
Definition: event.c:120
struct ast_ev_check_list::@261 ie_vals
const char * str
Definition: event.c:116
static struct ast_event_sub_list ast_event_subs[AST_EVENT_TOTAL]
ast_event_ie_type
Event Information Element types.
Definition: event_defs.h:62
ast_event_type
Event types.
Definition: event_defs.h:30
#define AST_RWDLLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: dlinkedlists.h:134
static int match_sub_ie_val_to_event(const struct ast_event_ie_val *sub_ie_val, const struct ast_ev_check_list *check_ie_vals)
Definition: event.c:383
#define LOG_ERROR
Definition: logger.h:155
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
enum ast_event_ie_type ie_type
Definition: event.c:110
Event subscription.
Definition: event.c:124
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
void * raw
Definition: event.c:118
struct ast_event_sub::@260 ie_vals
static const char type[]
Definition: chan_nbs.c:57
#define AST_LIST_HEAD_NOLOCK_INIT_VALUE
Defines initial values for a declaration of AST_LIST_HEAD_NOLOCK.
Definition: linkedlists.h:251
#define AST_RWDLLIST_TRAVERSE
Definition: dlinkedlists.h:506
#define AST_RWLIST_FIRST
Definition: linkedlists.h:422
#define AST_RWDLLIST_RDLOCK(head)
Read locks a list.
Definition: dlinkedlists.h:71
uint32_t uint
Definition: event.c:113
void ast_event_destroy ( struct ast_event event)

Destroy an event.

Parameters
eventthe event to destroy
Returns
Nothing
Note
Events that have been queued should not be destroyed by the code that created the event. It will be automatically destroyed after being dispatched to the appropriate subscribers.

Definition at line 1314 of file event.c.

References ast_free.

Referenced by ast_cel_report_event(), ast_event_get_cached(), ast_event_queue(), ast_event_queue_and_cache(), ast_event_ref_destroy(), ast_event_report_subs(), ast_event_sub_activate(), ast_event_unsubscribe(), devstate_cached(), event_update_cache(), get_cached_mwi(), handle_security_event(), has_voicemail(), process_collection(), sig_pri_mwi_cache_update(), stun_monitor_request(), unistim_send_mwi_to_peer(), and update_registry().

1315 {
1316  ast_free(event);
1317 }
#define ast_free(a)
Definition: astmm.h:97
void ast_event_dump_cache ( const struct ast_event_sub event_sub)

Dump the event cache for the subscriber.

Since
1.6.1

Dump the event cache for the subscriber.

Definition at line 654 of file event.c.

References ao2_callback, ast_event_cache, dump_cache_cb(), OBJ_NODATA, and ast_event_sub::type.

Referenced by add_publish_event(), aji_init_event_distribution(), ast_ais_evt_membership_changed(), and handle_devstate_change().

655 {
656  ao2_callback(ast_event_cache[event_sub->type].container, OBJ_NODATA,
657  dump_cache_cb, (void *) event_sub);
658 }
#define ao2_callback(c, flags, cb_fn, arg)
Definition: astobj2.h:910
static int dump_cache_cb(void *obj, void *arg, int flags)
Definition: event.c:632
static struct @255 ast_event_cache[AST_EVENT_TOTAL]
Event types that are kept in the cache.
enum ast_event_type type
Definition: event.c:125
struct ast_event* ast_event_get_cached ( enum  ast_event_type,
  ... 
)

Retrieve an event from the cache.

Parameters
ast_event_typeThe type of event to retrieve from the cache

The rest of the arguments to this function specify information elements to match for retrieving events from the cache. They are specified in the form:

and must end with AST_EVENT_IE_END.

If the ie_type specified is not AST_EVENT_IE_END, then it must be followed by a valid IE payload type. If the payload type specified is AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. Otherwise, a payload must also be specified.

Returns
A reference to an event retrieved from the cache. If no event was found that matches the specified criteria, then NULL will be returned.
Note
If more than one event in the cache matches the specified criteria, only one will be returned, and it is undefined which one it will be.
The caller of this function must call ast_event_destroy() on the returned event after it is done using it.

Example Usage:

This example will check for an MWI event in the cache that matches the specified mailbox. This would be the way to find out the last known state of a mailbox without having to poll the mailbox directly.

Definition at line 1342 of file event.c.

References ao2_find, ao2_ref, ast_event_append_ie_bitflags(), ast_event_append_ie_raw(), ast_event_append_ie_str(), ast_event_append_ie_uint(), ast_event_cache, ast_event_destroy(), ast_event_dup(), AST_EVENT_IE_END, AST_EVENT_IE_PLTYPE_BITFLAGS, AST_EVENT_IE_PLTYPE_EXISTS, AST_EVENT_IE_PLTYPE_RAW, AST_EVENT_IE_PLTYPE_STR, AST_EVENT_IE_PLTYPE_UINT, AST_EVENT_IE_PLTYPE_UNKNOWN, ast_event_new(), ast_log(), container, ast_event_ref::event, LOG_ERROR, LOG_WARNING, and OBJ_POINTER.

Referenced by devstate_cached(), get_cached_mwi(), has_voicemail(), process_collection(), sig_pri_mwi_cache_update(), unistim_send_mwi_to_peer(), and update_registry().

1343 {
1344  va_list ap;
1346  struct ast_event *dup_event = NULL;
1347  struct ast_event_ref *cached_event_ref;
1348  struct ast_event *cache_arg_event;
1349  struct ast_event_ref tmp_event_ref = {
1350  .event = NULL,
1351  };
1352  struct ao2_container *container = NULL;
1353 
1354  if (type >= AST_EVENT_TOTAL) {
1355  ast_log(LOG_ERROR, "%u is an invalid type!\n", type);
1356  return NULL;
1357  }
1358 
1359  if (!(container = ast_event_cache[type].container)) {
1360  ast_log(LOG_ERROR, "%u is not a cached event type\n", type);
1361  return NULL;
1362  }
1363 
1364  if (!(cache_arg_event = ast_event_new(type, AST_EVENT_IE_END))) {
1365  return NULL;
1366  }
1367 
1368  va_start(ap, type);
1369  for (ie_type = va_arg(ap, enum ast_event_ie_type);
1370  ie_type != AST_EVENT_IE_END;
1371  ie_type = va_arg(ap, enum ast_event_ie_type))
1372  {
1373  enum ast_event_ie_pltype ie_pltype;
1374 
1375  ie_pltype = va_arg(ap, enum ast_event_ie_pltype);
1376 
1377  switch (ie_pltype) {
1379  ast_event_append_ie_uint(&cache_arg_event, ie_type, va_arg(ap, uint32_t));
1380  break;
1382  ast_event_append_ie_bitflags(&cache_arg_event, ie_type, va_arg(ap, uint32_t));
1383  break;
1385  ast_event_append_ie_str(&cache_arg_event, ie_type, va_arg(ap, const char *));
1386  break;
1388  {
1389  void *data = va_arg(ap, void *);
1390  size_t datalen = va_arg(ap, size_t);
1391  ast_event_append_ie_raw(&cache_arg_event, ie_type, data, datalen);
1392  break;
1393  }
1395  ast_log(LOG_WARNING, "PLTYPE_EXISTS not supported by this function\n");
1396  break;
1398  break;
1399  }
1400  }
1401  va_end(ap);
1402 
1403  tmp_event_ref.event = cache_arg_event;
1404 
1405  cached_event_ref = ao2_find(container, &tmp_event_ref, OBJ_POINTER);
1406 
1407  ast_event_destroy(cache_arg_event);
1408  cache_arg_event = NULL;
1409 
1410  if (cached_event_ref) {
1411  dup_event = ast_event_dup(cached_event_ref->event);
1412  ao2_ref(cached_event_ref, -1);
1413  cached_event_ref = NULL;
1414  }
1415 
1416  return dup_event;
1417 }
A holder for an event.
Definition: event.c:104
An event.
Definition: event.c:85
ast_event_ie_pltype
Payload types for event information elements.
Definition: event_defs.h:299
#define LOG_WARNING
Definition: logger.h:144
struct ast_event * event
Definition: event.c:105
int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t bitflags)
Append an information element that has a bitflags payload.
Definition: event.c:1167
struct ao2_container * container
The asterisk data main content structure.
Definition: data.c:177
ast_event_ie_type
Event Information Element types.
Definition: event_defs.h:62
static struct ast_event * ast_event_dup(const struct ast_event *event)
Definition: event.c:1326
#define ao2_ref(o, delta)
Definition: astobj2.h:472
#define LOG_ERROR
Definition: logger.h:155
int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, const void *data, size_t data_len)
Append an information element that has a raw payload.
Definition: event.c:1174
enum ast_event_ie_type ie_type
Definition: event.c:110
int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, const char *str)
Append an information element that has a string payload.
Definition: event.c:1139
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
static struct @255 ast_event_cache[AST_EVENT_TOTAL]
Event types that are kept in the cache.
#define ao2_find(arg1, arg2, arg3)
Definition: astobj2.h:964
static const char type[]
Definition: chan_nbs.c:57
void ast_event_destroy(struct ast_event *event)
Destroy an event.
Definition: event.c:1314
struct ast_event * ast_event_new(enum ast_event_type event_type,...)
Create a new event.
Definition: event.c:1202
int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t data)
Append an information element that has an integer payload.
Definition: event.c:1160
uint32_t ast_event_get_ie_bitflags ( const struct ast_event event,
enum ast_event_ie_type  ie_type 
)

Get the value of an information element that has a bitflags payload.

Parameters
eventThe event to get the IE from
ie_typethe type of information element to retrieve
Returns
This returns the payload of the information element with the given type. However, an IE with a payload of 0, and the case where no IE is found yield the same return value.

Definition at line 1084 of file event.c.

References ast_event_get_ie_raw(), and get_unaligned_uint32().

Referenced by append_ie(), and match_ie_val().

1085 {
1086  const uint32_t *ie_val;
1087 
1088  ie_val = ast_event_get_ie_raw(event, ie_type);
1089 
1090  return ie_val ? ntohl(get_unaligned_uint32(ie_val)) : 0;
1091 }
static unsigned int get_unaligned_uint32(const void *p)
Definition: unaligned.h:38
const void * ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a raw payload.
Definition: event.c:1111
enum ast_event_ie_pltype ast_event_get_ie_pltype ( enum ast_event_ie_type  ie_type)

Get the payload type for a given information element type.

Parameters
ie_typethe information element type to get the payload type of
Returns
the payload type for the provided IE type
Since
1.6.1

Definition at line 314 of file event.c.

References ARRAY_LEN, AST_EVENT_IE_PLTYPE_UNKNOWN, ast_log(), ie_maps, ie_map::ie_pltype, and LOG_ERROR.

Referenced by append_ie(), ast_event_cmp(), and event_dump_cli().

315 {
316  if (ie_type <= 0 || ie_type >= ARRAY_LEN(ie_maps)) {
317  ast_log(LOG_ERROR, "Invalid IE type - '%d'\n", ie_type);
319  }
320 
321  return ie_maps[ie_type].ie_pltype;
322 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
static struct ie_map ie_maps[AST_EVENT_IE_TOTAL]
#define LOG_ERROR
Definition: logger.h:155
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
enum ast_event_ie_pltype ie_pltype
Definition: event.c:217
const void* ast_event_get_ie_raw ( const struct ast_event event,
enum ast_event_ie_type  ie_type 
)

Get the value of an information element that has a raw payload.

Parameters
eventThe event to get the IE from
ie_typethe type of information element to retrieve
Returns
This returns the payload of the information element with the given type. If the information element isn't found, NULL will be returned.

Definition at line 1111 of file event.c.

References ast_event_iterator_get_ie_raw(), ast_event_iterator_get_ie_type(), ast_event_iterator_init(), and ast_event_iterator_next().

Referenced by aji_devstate_cb(), aji_mwi_cb(), ast_event_cb(), ast_event_get_ie_bitflags(), ast_event_get_ie_str(), ast_event_get_ie_str_hash(), ast_event_get_ie_uint(), ast_event_new(), devstate_cache_cb(), devstate_change_collector_cb(), evt_event_deliver_cb(), ie_is_present(), and match_ie_val().

1112 {
1113  struct ast_event_iterator iterator;
1114  int res;
1115 
1116  for (res = ast_event_iterator_init(&iterator, event); !res; res = ast_event_iterator_next(&iterator)) {
1117  if (ast_event_iterator_get_ie_type(&iterator) == ie_type) {
1118  return ast_event_iterator_get_ie_raw(&iterator);
1119  }
1120  }
1121 
1122  return NULL;
1123 }
supposed to be an opaque type
Definition: event_defs.h:335
int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event)
Initialize an event iterator instance.
Definition: event.c:1014
int ast_event_iterator_next(struct ast_event_iterator *iterator)
Move iterator instance to next IE.
Definition: event.c:1030
void * ast_event_iterator_get_ie_raw(struct ast_event_iterator *iterator)
Get the value of the current IE in the iterator instance that has a raw payload.
Definition: event.c:1060
enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator)
Get the type of the current IE in the iterator instance.
Definition: event.c:1036
uint16_t ast_event_get_ie_raw_payload_len ( const struct ast_event event,
enum ast_event_ie_type  ie_type 
)

Get the length of the raw payload for a particular IE.

Parameters
eventThe event to get the IE payload length from
ie_typethe type of information element to get the length of
Returns
If an IE of type ie_type is found, its payload length is returned. Otherwise, 0 is returned.

Definition at line 1125 of file event.c.

References ast_event_iterator_get_ie_raw_payload_len(), ast_event_iterator_get_ie_type(), ast_event_iterator_init(), and ast_event_iterator_next().

Referenced by match_ie_val().

1126 {
1127  struct ast_event_iterator iterator;
1128  int res;
1129 
1130  for (res = ast_event_iterator_init(&iterator, event); !res; res = ast_event_iterator_next(&iterator)) {
1131  if (ast_event_iterator_get_ie_type(&iterator) == ie_type) {
1133  }
1134  }
1135 
1136  return 0;
1137 }
supposed to be an opaque type
Definition: event_defs.h:335
int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event)
Initialize an event iterator instance.
Definition: event.c:1014
int ast_event_iterator_next(struct ast_event_iterator *iterator)
Move iterator instance to next IE.
Definition: event.c:1030
uint16_t ast_event_iterator_get_ie_raw_payload_len(struct ast_event_iterator *iterator)
Get the length of the raw payload for the current IE for an iterator.
Definition: event.c:1065
enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator)
Get the type of the current IE in the iterator instance.
Definition: event.c:1036
const char* ast_event_get_ie_str ( const struct ast_event event,
enum ast_event_ie_type  ie_type 
)

Get the value of an information element that has a string payload.

Parameters
eventThe event to get the IE from
ie_typethe type of information element to retrieve
Returns
This returns the payload of the information element with the given type. If the information element isn't found, NULL will be returned.

Definition at line 1102 of file event.c.

References ast_event_get_ie_raw(), and ast_event_ie_str_payload::str.

Referenced by aji_devstate_cb(), aji_mwi_cb(), append_ie(), ast_cel_fill_record(), ast_event_hash_devstate(), ast_event_hash_devstate_change(), ast_event_hash_mwi(), device_state_cb(), devstate_change_collector_cb(), generic_monitor_devstate_cb(), match_ie_val(), mwi_sub_event_cb(), print_cel_sub(), and sig_pri_mwi_event_cb().

1103 {
1104  const struct ast_event_ie_str_payload *str_payload;
1105 
1106  str_payload = ast_event_get_ie_raw(event, ie_type);
1107 
1108  return str_payload ? str_payload->str : NULL;
1109 }
char str[1]
The actual string, null terminated.
Definition: event.c:71
const void * ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a raw payload.
Definition: event.c:1111
The payload for a string information element.
Definition: event.c:67
uint32_t ast_event_get_ie_str_hash ( const struct ast_event event,
enum ast_event_ie_type  ie_type 
)

Get the hash for the string payload of an IE.

Parameters
eventThe event to get the IE from
ie_typethe type of information element to retrieve the hash for
Returns
This function returns the hash value as calculated by ast_str_hash() for the string payload. This is stored in the event to avoid unnecessary string comparisons.

Definition at line 1093 of file event.c.

References ast_event_get_ie_raw(), and ast_event_ie_str_payload::hash.

Referenced by match_ie_val().

1094 {
1095  const struct ast_event_ie_str_payload *str_payload;
1096 
1097  str_payload = ast_event_get_ie_raw(event, ie_type);
1098 
1099  return str_payload ? str_payload->hash : 0;
1100 }
uint32_t hash
A hash calculated with ast_str_hash(), to speed up comparisons.
Definition: event.c:69
const void * ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a raw payload.
Definition: event.c:1111
The payload for a string information element.
Definition: event.c:67
const char* ast_event_get_ie_type_name ( enum ast_event_ie_type  ie_type)

Get the string representation of an information element type.

Parameters
ie_typethe information element type to get the string representation of
Returns
the string representation of the information element type
Since
1.6.1

Definition at line 304 of file event.c.

References ARRAY_LEN, ast_log(), ie_maps, LOG_ERROR, and ie_map::name.

Referenced by append_ie(), dump_raw_ie(), event_dump_cache(), event_dump_cli(), and security_event_cb().

305 {
306  if (ie_type <= 0 || ie_type >= ARRAY_LEN(ie_maps)) {
307  ast_log(LOG_ERROR, "Invalid IE type - '%d'\n", ie_type);
308  return "";
309  }
310 
311  return ie_maps[ie_type].name;
312 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
const char * name
Definition: event.c:218
static struct ie_map ie_maps[AST_EVENT_IE_TOTAL]
#define LOG_ERROR
Definition: logger.h:155
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
uint32_t ast_event_get_ie_uint ( const struct ast_event event,
enum ast_event_ie_type  ie_type 
)

Get the value of an information element that has an integer payload.

Parameters
eventThe event to get the IE from
ie_typethe type of information element to retrieve
Returns
This returns the payload of the information element with the given type. However, an IE with a payload of 0, and the case where no IE is found yield the same return value.

Definition at line 1075 of file event.c.

References ast_event_get_ie_raw(), and get_unaligned_uint32().

Referenced by aji_devstate_cb(), aji_mwi_cb(), append_ie(), ast_cel_fill_record(), device_state_cb(), devstate_cache_cb(), devstate_cached(), devstate_change_collector_cb(), generic_agent_devstate_cb(), generic_monitor_devstate_cb(), get_cached_mwi(), has_voicemail(), match_ie_val(), mwi_event_cb(), mwi_sub_event_cb(), mwi_unsub_event_cb(), process_collection(), security_event_cb(), sig_pri_mwi_cache_update(), sig_pri_mwi_event_cb(), unistim_send_mwi_to_peer(), and update_registry().

1076 {
1077  const uint32_t *ie_val;
1078 
1079  ie_val = ast_event_get_ie_raw(event, ie_type);
1080 
1081  return ie_val ? ntohl(get_unaligned_uint32(ie_val)) : 0;
1082 }
static unsigned int get_unaligned_uint32(const void *p)
Definition: unaligned.h:38
const void * ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a raw payload.
Definition: event.c:1111
size_t ast_event_get_size ( const struct ast_event event)

Get the size of an event.

Parameters
eventthe event to get the size of
Returns
the number of bytes contained in the event
Since
1.6.1

Definition at line 340 of file event.c.

References ast_event::event_len.

Referenced by ast_event_cb(), ast_event_dup(), and ast_event_iterator_init().

341 {
342  size_t res;
343 
344  res = ntohs(event->event_len);
345 
346  return res;
347 }
uint16_t event_len
Definition: event.c:87
enum ast_event_type ast_event_get_type ( const struct ast_event event)

Get the type for an event.

Parameters
eventthe event to get the type for
Returns
the event type as represented by one of the values in the ast_event_type enum

Definition at line 1070 of file event.c.

Referenced by ast_event_cb(), ast_event_cmp(), ast_event_get_type_name(), ast_event_hash(), ast_event_queue_and_cache(), mwi_sub_event_cb(), and mwi_unsub_event_cb().

1071 {
1072  return ntohs(event->type);
1073 }
const char* ast_event_get_type_name ( const struct ast_event event)

Get the string representation of the type of the given event.

  • event the event to get the type of
Returns
the string representation of the event type of the provided event
Since
1.6.1

Definition at line 274 of file event.c.

References ARRAY_LEN, ast_event_get_type(), ast_log(), event_names, LOG_ERROR, and ast_event_sub::type.

Referenced by event_dump_cli().

275 {
276  enum ast_event_type type;
277 
278  type = ast_event_get_type(event);
279 
280  if (type < 0 || type >= ARRAY_LEN(event_names)) {
281  ast_log(LOG_ERROR, "Invalid event type - '%u'\n", type);
282  return "";
283  }
284 
285  return event_names[type];
286 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
enum ast_event_type ast_event_get_type(const struct ast_event *event)
Get the type for an event.
Definition: event.c:1070
static const char *const event_names[AST_EVENT_TOTAL]
Event Names.
Definition: event.c:200
ast_event_type
Event types.
Definition: event_defs.h:30
#define LOG_ERROR
Definition: logger.h:155
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
static const char type[]
Definition: chan_nbs.c:57
uint32_t ast_event_iterator_get_ie_bitflags ( struct ast_event_iterator iterator)

Get the value of the current IE in the iterator as a bitflags payload.

Parameters
iteratorThe iterator instance
Returns
This returns the payload of the information element as bitflags.

Definition at line 1046 of file event.c.

References get_unaligned_uint32(), ast_event_iterator::ie, and ast_event_ie::ie_payload.

Referenced by event_dump_cli().

1047 {
1048  return ntohl(get_unaligned_uint32(iterator->ie->ie_payload));
1049 }
struct ast_event_ie * ie
Definition: event_defs.h:338
static unsigned int get_unaligned_uint32(const void *p)
Definition: unaligned.h:38
unsigned char ie_payload[0]
Definition: event.c:61
void* ast_event_iterator_get_ie_raw ( struct ast_event_iterator iterator)

Get the value of the current IE in the iterator instance that has a raw payload.

Parameters
iteratorThe iterator instance
Returns
This returns the payload of the information element as type raw.

Definition at line 1060 of file event.c.

References ast_event_iterator::ie, and ast_event_ie::ie_payload.

Referenced by ast_event_get_ie_raw(), and dump_raw_ie().

1061 {
1062  return iterator->ie->ie_payload;
1063 }
struct ast_event_ie * ie
Definition: event_defs.h:338
unsigned char ie_payload[0]
Definition: event.c:61
uint16_t ast_event_iterator_get_ie_raw_payload_len ( struct ast_event_iterator iterator)

Get the length of the raw payload for the current IE for an iterator.

Parameters
iteratorThe IE iterator
Returns
The payload length of the current IE

Definition at line 1065 of file event.c.

References ast_event_iterator::ie, and ast_event_ie::ie_payload_len.

Referenced by ast_event_get_ie_raw_payload_len().

1066 {
1067  return ntohs(iterator->ie->ie_payload_len);
1068 }
struct ast_event_ie * ie
Definition: event_defs.h:338
uint16_t ie_payload_len
Definition: event.c:58
const char* ast_event_iterator_get_ie_str ( struct ast_event_iterator iterator)

Get the value of the current IE in the iterator as a string payload.

Parameters
iteratorThe iterator instance
Returns
This returns the payload of the information element as a string.

Definition at line 1051 of file event.c.

References ast_event_iterator::ie, ast_event_ie::ie_payload, and ast_event_ie_str_payload::str.

Referenced by event_dump_cli().

1052 {
1053  const struct ast_event_ie_str_payload *str_payload;
1054 
1055  str_payload = (struct ast_event_ie_str_payload *) iterator->ie->ie_payload;
1056 
1057  return str_payload ? str_payload->str : NULL;
1058 }
struct ast_event_ie * ie
Definition: event_defs.h:338
char str[1]
The actual string, null terminated.
Definition: event.c:71
unsigned char ie_payload[0]
Definition: event.c:61
The payload for a string information element.
Definition: event.c:67
enum ast_event_ie_type ast_event_iterator_get_ie_type ( struct ast_event_iterator iterator)

Get the type of the current IE in the iterator instance.

Parameters
iteratorThe iterator instance
Returns
the ie type as represented by one of the value sin the ast_event_ie_type enum

Definition at line 1036 of file event.c.

References ast_event_iterator::ie.

Referenced by ast_event_get_ie_raw(), ast_event_get_ie_raw_payload_len(), dump_raw_ie(), and event_dump_cli().

1037 {
1038  return ntohs(iterator->ie->ie_type);
1039 }
struct ast_event_ie * ie
Definition: event_defs.h:338
uint32_t ast_event_iterator_get_ie_uint ( struct ast_event_iterator iterator)

Get the value of the current IE in the iterator as an integer payload.

Parameters
iteratorThe iterator instance
Returns
This returns the payload of the information element as a uint.

Definition at line 1041 of file event.c.

References get_unaligned_uint32(), ast_event_iterator::ie, and ast_event_ie::ie_payload.

Referenced by event_dump_cli().

1042 {
1043  return ntohl(get_unaligned_uint32(iterator->ie->ie_payload));
1044 }
struct ast_event_ie * ie
Definition: event_defs.h:338
static unsigned int get_unaligned_uint32(const void *p)
Definition: unaligned.h:38
unsigned char ie_payload[0]
Definition: event.c:61
int ast_event_iterator_init ( struct ast_event_iterator iterator,
const struct ast_event event 
)

Initialize an event iterator instance.

Parameters
iteratorThe iterator instance to initialize
eventThe event that will be iterated through
Return values
0Success, there are IEs available to iterate
-1Failure, there are no IEs in the event to iterate

Definition at line 1014 of file event.c.

References ast_event_get_size(), ast_event_iterator::event, ast_event_iterator::event_len, and ast_event_iterator::ie.

Referenced by ast_event_get_ie_raw(), ast_event_get_ie_raw_payload_len(), and event_dump_cli().

1015 {
1016  int res = 0;
1017 
1018  iterator->event_len = ast_event_get_size(event);
1019  iterator->event = event;
1020  if (iterator->event_len >= sizeof(*event) + sizeof(struct ast_event_ie)) {
1021  iterator->ie = (struct ast_event_ie *) ( ((char *) event) + sizeof(*event) );
1022  } else {
1023  iterator->ie = NULL;
1024  res = -1;
1025  }
1026 
1027  return res;
1028 }
struct ast_event_ie * ie
Definition: event_defs.h:338
An event information element.
Definition: event.c:57
uint16_t event_len
Definition: event_defs.h:336
struct ast_event * event
Definition: event_defs.h:337
size_t ast_event_get_size(const struct ast_event *event)
Get the size of an event.
Definition: event.c:340
int ast_event_iterator_next ( struct ast_event_iterator iterator)

Move iterator instance to next IE.

Parameters
iteratorThe iterator instance
Return values
0on success
-1if end is reached

Definition at line 1030 of file event.c.

References ast_event_iterator::event, ast_event_iterator::event_len, ast_event_iterator::ie, and ast_event_ie::ie_payload_len.

Referenced by ast_event_get_ie_raw(), ast_event_get_ie_raw_payload_len(), and event_dump_cli().

1031 {
1032  iterator->ie = (struct ast_event_ie *) ( ((char *) iterator->ie) + sizeof(*iterator->ie) + ntohs(iterator->ie->ie_payload_len));
1033  return ((iterator->event_len <= (((char *) iterator->ie) - ((char *) iterator->event))) ? -1 : 0);
1034 }
struct ast_event_ie * ie
Definition: event_defs.h:338
uint16_t ie_payload_len
Definition: event.c:58
An event information element.
Definition: event.c:57
uint16_t event_len
Definition: event_defs.h:336
struct ast_event * event
Definition: event_defs.h:337
size_t ast_event_minimum_length ( void  )

Get the minimum length of an ast_event.

Returns
minimum amount of memory that will be consumed by any ast_event.

Definition at line 1854 of file event.c.

Referenced by evt_event_deliver_cb().

1855 {
1856  return sizeof(struct ast_event);
1857 }
An event.
Definition: event.c:85
struct ast_event* ast_event_new ( enum ast_event_type  event_type,
  ... 
)

Create a new event.

Parameters
event_typeThe type of event to create

The rest of the arguments to this function specify information elements to add to the event. They are specified in the form:

and must end with AST_EVENT_IE_END.

If the ie_type specified is not AST_EVENT_IE_END, then it must be followed by a valid IE payload type. The payload type, EXISTS, should not be used here because it makes no sense to do so. So, a payload must also be specified after the IE payload type.

Note
The EID IE will be appended automatically when this function is used with at least one IE specified.
Returns
This returns the event that has been created. If there is an error creating the event, NULL will be returned.

Example usage:

This creates a MWI event with 3 information elements, a mailbox which is a string, and the number of new and old messages, specified as integers.

Definition at line 1202 of file event.c.

References ast_alloca, ast_calloc, ast_event_append_eid(), ast_event_append_ie_bitflags(), ast_event_append_ie_raw(), ast_event_append_ie_str(), ast_event_append_ie_uint(), ast_event_get_ie_raw(), AST_EVENT_IE_EID, AST_EVENT_IE_END, AST_EVENT_IE_PLTYPE_BITFLAGS, AST_EVENT_IE_PLTYPE_EXISTS, AST_EVENT_IE_PLTYPE_RAW, AST_EVENT_IE_PLTYPE_STR, AST_EVENT_IE_PLTYPE_UINT, AST_EVENT_IE_PLTYPE_UNKNOWN, AST_LIST_HEAD_NOLOCK_STATIC, AST_LIST_INSERT_TAIL, AST_LIST_TRAVERSE, ast_log(), ast_event_ie_val::ie_pltype, ast_event_ie_val::ie_type, LOG_WARNING, ast_event_ie_val::payload, ast_event_ie_val::raw, ast_event_ie_val::raw_datalen, ast_event_ie_val::str, and ast_event_ie_val::uint.

Referenced by aji_handle_pubsub_event(), alloc_event(), ast_cel_report_event(), ast_event_get_cached(), ast_event_unsubscribe(), devstate_event(), gen_sub_event(), handle_request_notify(), notify_message(), process_collection(), queue_mwi_event(), and stun_monitor_request().

1203 {
1204  va_list ap;
1205  struct ast_event *event;
1206  enum ast_event_ie_type ie_type;
1207  struct ast_event_ie_val *ie_val;
1208  int has_ie = 0;
1210 
1211  /* Invalid type */
1212  if (type >= AST_EVENT_TOTAL) {
1213  ast_log(LOG_WARNING, "Someone tried to create an event of invalid "
1214  "type '%u'!\n", type);
1215  return NULL;
1216  }
1217 
1218  va_start(ap, type);
1219  for (ie_type = va_arg(ap, enum ast_event_ie_type);
1220  ie_type != AST_EVENT_IE_END;
1221  ie_type = va_arg(ap, enum ast_event_ie_type))
1222  {
1223  struct ast_event_ie_val *ie_value = ast_alloca(sizeof(*ie_value));
1224  int insert = 0;
1225 
1226  memset(ie_value, 0, sizeof(*ie_value));
1227  ie_value->ie_type = ie_type;
1228  ie_value->ie_pltype = va_arg(ap, enum ast_event_ie_pltype);
1229  switch (ie_value->ie_pltype) {
1231  ie_value->payload.uint = va_arg(ap, uint32_t);
1232  insert = 1;
1233  break;
1235  ie_value->payload.uint = va_arg(ap, uint32_t);
1236  insert = 1;
1237  break;
1239  ie_value->payload.str = va_arg(ap, const char *);
1240  insert = 1;
1241  break;
1243  {
1244  void *data = va_arg(ap, void *);
1245  size_t datalen = va_arg(ap, size_t);
1246  ie_value->payload.raw = ast_alloca(datalen);
1247  memcpy(ie_value->payload.raw, data, datalen);
1248  ie_value->raw_datalen = datalen;
1249  insert = 1;
1250  break;
1251  }
1254  break;
1255  }
1256 
1257  if (insert) {
1258  AST_LIST_INSERT_TAIL(&ie_vals, ie_value, entry);
1259  has_ie = 1;
1260  } else {
1261  ast_log(LOG_WARNING, "Unsupported PLTYPE(%d)\n", ie_value->ie_pltype);
1262  }
1263  }
1264  va_end(ap);
1265 
1266  if (!(event = ast_calloc(1, sizeof(*event)))) {
1267  return NULL;
1268  }
1269 
1270  event->type = htons(type);
1271  event->event_len = htons(sizeof(*event));
1272 
1273  AST_LIST_TRAVERSE(&ie_vals, ie_val, entry) {
1274  switch (ie_val->ie_pltype) {
1276  ast_event_append_ie_str(&event, ie_val->ie_type, ie_val->payload.str);
1277  break;
1279  ast_event_append_ie_uint(&event, ie_val->ie_type, ie_val->payload.uint);
1280  break;
1282  ast_event_append_ie_bitflags(&event, ie_val->ie_type, ie_val->payload.uint);
1283  break;
1285  ast_event_append_ie_raw(&event, ie_val->ie_type,
1286  ie_val->payload.raw, ie_val->raw_datalen);
1287  break;
1290  break;
1291  }
1292 
1293  /* realloc inside one of the append functions failed */
1294  if (!event) {
1295  return NULL;
1296  }
1297  }
1298 
1299  if (has_ie && !ast_event_get_ie_raw(event, AST_EVENT_IE_EID)) {
1300  /* If the event is originating on this server, add the server's
1301  * entity ID to the event. */
1302  ast_event_append_eid(&event);
1303  }
1304 
1305  return event;
1306 }
An event.
Definition: event.c:85
#define ast_alloca(size)
call __builtin_alloca to ensure we get gcc builtin semantics
Definition: utils.h:653
ast_event_ie_pltype
Payload types for event information elements.
Definition: event_defs.h:299
enum ast_event_ie_pltype ie_pltype
Definition: event.c:111
struct ast_event_ie_val::@256 entry
#define LOG_WARNING
Definition: logger.h:144
union ast_event_ie_val::@257 payload
size_t raw_datalen
Definition: event.c:120
int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t bitflags)
Append an information element that has a bitflags payload.
Definition: event.c:1167
Entity ID Used by All events Payload type: RAW This IE indicates which server the event originated fr...
Definition: event_defs.h:266
const char * str
Definition: event.c:116
ast_event_ie_type
Event Information Element types.
Definition: event_defs.h:62
const void * ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a raw payload.
Definition: event.c:1111
#define AST_LIST_HEAD_NOLOCK_STATIC(name, type)
Defines a structure to be used to hold a list of specified type, statically initialized.
Definition: linkedlists.h:345
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, const void *data, size_t data_len)
Append an information element that has a raw payload.
Definition: event.c:1174
enum ast_event_ie_type ie_type
Definition: event.c:110
int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, const char *str)
Append an information element that has a string payload.
Definition: event.c:1139
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
void * raw
Definition: event.c:118
static const char type[]
Definition: chan_nbs.c:57
#define ast_calloc(a, b)
Definition: astmm.h:82
int ast_event_append_eid(struct ast_event **event)
Append the global EID IE.
Definition: event.c:1308
uint32_t uint
Definition: event.c:113
int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t data)
Append an information element that has an integer payload.
Definition: event.c:1160
int ast_event_queue ( struct ast_event event)

Queue an event.

Parameters
eventthe event to be queued
Return values
zerosuccess
non-zerofailure. Note that the caller of this function is responsible for destroying the event in the case of a failure.

This function queues an event to be dispatched to all of the appropriate subscribers. This function will not block while the event is being dispatched because the event is queued up for a dispatching thread to handle.

Definition at line 1517 of file event.c.

References alloc_event_ref(), ao2_ref, ast_event_check_subscriber(), ast_event_destroy(), AST_EVENT_IE_END, AST_EVENT_SUB_NONE, ast_log(), ast_taskprocessor_push(), ast_event_ref::event, handle_event(), and LOG_WARNING.

Referenced by aji_handle_pubsub_event(), ast_cel_report_event(), ast_event_queue_and_cache(), ast_event_sub_activate(), ast_event_unsubscribe(), devstate_event(), handle_security_event(), process_collection(), and stun_monitor_request().

1518 {
1519  struct ast_event_ref *event_ref;
1520  uint16_t host_event_type;
1521  int res;
1522 
1523  host_event_type = ntohs(event->type);
1524 
1525  /* Invalid type */
1526  if (host_event_type >= AST_EVENT_TOTAL) {
1527  ast_log(LOG_WARNING, "Someone tried to queue an event of invalid "
1528  "type '%d'!\n", host_event_type);
1529  return -1;
1530  }
1531 
1532  /* If nobody has subscribed to this event type, throw it away now */
1533  if (ast_event_check_subscriber(host_event_type, AST_EVENT_IE_END)
1534  == AST_EVENT_SUB_NONE) {
1535  ast_event_destroy(event);
1536  return 0;
1537  }
1538 
1539  if (!(event_ref = alloc_event_ref())) {
1540  return -1;
1541  }
1542 
1543  event_ref->event = event;
1544 
1546  if (res) {
1547  event_ref->event = NULL;
1548  ao2_ref(event_ref, -1);
1549  }
1550  return res;
1551 }
A holder for an event.
Definition: event.c:104
enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type,...)
Check if subscribers exist.
Definition: event.c:448
int ast_taskprocessor_push(struct ast_taskprocessor *tps, int(*task_exe)(void *datap), void *datap)
Push a task into the specified taskprocessor queue and signal the taskprocessor thread.
#define LOG_WARNING
Definition: logger.h:144
struct ast_event * event
Definition: event.c:105
#define ao2_ref(o, delta)
Definition: astobj2.h:472
static struct ast_taskprocessor * event_dispatcher
Definition: event.c:47
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
static struct ast_event_ref * alloc_event_ref(void)
Definition: event.c:1419
static int handle_event(void *data)
Definition: event.c:1482
void ast_event_destroy(struct ast_event *event)
Destroy an event.
Definition: event.c:1314
int ast_event_queue_and_cache ( struct ast_event event)

Queue and cache an event.

Parameters
eventthe event to be queued and cached

The purpose of caching events is so that the core can retain the last known information for events that represent some sort of state. That way, when code needs to find out the current state, it can query the cache.

The event API already knows which events can be cached and how to cache them.

Return values
0success
non-zerofailure.

Definition at line 1465 of file event.c.

References ast_event_cache, ast_event_destroy(), ast_event_get_type(), ast_event_queue(), ast_log(), container, event_update_cache(), and LOG_WARNING.

Referenced by aji_handle_pubsub_event(), devstate_event(), handle_request_notify(), notify_message(), process_collection(), queue_event(), and queue_mwi_event().

1466 {
1467  struct ao2_container *container;
1468 
1469  container = ast_event_cache[ast_event_get_type(event)].container;
1470  if (!container) {
1471  ast_log(LOG_WARNING, "cache requested for non-cached event type\n");
1472  } else {
1473  event_update_cache(container, event);
1474  }
1475 
1476  if (ast_event_queue(event)) {
1477  ast_event_destroy(event);
1478  }
1479  return 0;
1480 }
enum ast_event_type ast_event_get_type(const struct ast_event *event)
Get the type for an event.
Definition: event.c:1070
#define LOG_WARNING
Definition: logger.h:144
struct ao2_container * container
The asterisk data main content structure.
Definition: data.c:177
int ast_event_queue(struct ast_event *event)
Queue an event.
Definition: event.c:1517
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
static struct @255 ast_event_cache[AST_EVENT_TOTAL]
Event types that are kept in the cache.
static void event_update_cache(struct ao2_container *cache, struct ast_event *event)
Definition: event.c:1434
void ast_event_destroy(struct ast_event *event)
Destroy an event.
Definition: event.c:1314
void ast_event_report_subs ( const struct ast_event_sub event_sub)

Report current subscriptions to a subscription subscriber.

  • sub the subscription subscriber
Returns
nothing

This reports all of the current subscribers to a subscriber of subscribers to a specific event type. (Try saying that a few times fast).

The idea here is that it is sometimes very useful for a module to know when someone subscribes to events. However, when they first subscribe, this provides that module the ability to request the event core report to them all of the subscriptions to that event type that already exist.

Report current subscriptions to a subscription subscriber.

Definition at line 701 of file event.c.

References ast_event_destroy(), AST_EVENT_IE_EVENTTYPE, AST_EVENT_SUB, ast_event_subs, AST_LIST_TRAVERSE, AST_RWDLLIST_RDLOCK, AST_RWDLLIST_TRAVERSE, AST_RWDLLIST_UNLOCK, ast_event_sub::cb, gen_sub_event(), ast_event_ie_val::ie_type, ast_event_sub::ie_vals, ast_event_ie_val::payload, ast_event_sub::type, ast_event_ie_val::uint, and ast_event_sub::userdata.

Referenced by handle_cli_status(), and start_poll_thread().

702 {
703  struct ast_event *event;
704  struct ast_event_sub *sub;
705  enum ast_event_type event_type = -1;
706  struct ast_event_ie_val *ie_val;
707 
708  if (event_sub->type != AST_EVENT_SUB)
709  return;
710 
711  AST_LIST_TRAVERSE(&event_sub->ie_vals, ie_val, entry) {
712  if (ie_val->ie_type == AST_EVENT_IE_EVENTTYPE) {
713  event_type = ie_val->payload.uint;
714  break;
715  }
716  }
717 
718  if (event_type == -1)
719  return;
720 
721  AST_RWDLLIST_RDLOCK(&ast_event_subs[event_type]);
722  AST_RWDLLIST_TRAVERSE(&ast_event_subs[event_type], sub, entry) {
723  if (event_sub == sub) {
724  continue;
725  }
726 
727  event = gen_sub_event(sub);
728  if (!event) {
729  continue;
730  }
731 
732  event_sub->cb(event, event_sub->userdata);
733 
734  ast_event_destroy(event);
735  }
736  AST_RWDLLIST_UNLOCK(&ast_event_subs[event_type]);
737 }
An event.
Definition: event.c:85
struct ast_event_ie_val::@256 entry
union ast_event_ie_val::@257 payload
static struct ast_event_sub_list ast_event_subs[AST_EVENT_TOTAL]
ast_event_type
Event types.
Definition: event_defs.h:30
#define AST_RWDLLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: dlinkedlists.h:134
void * userdata
Definition: event.c:128
Event type Used by: AST_EVENT_SUB, AST_EVENT_UNSUB Payload type: UINT.
Definition: event_defs.h:95
ast_event_cb_t cb
Definition: event.c:126
enum ast_event_ie_type ie_type
Definition: event.c:110
Event subscription.
Definition: event.c:124
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
struct ast_event_sub::@260 ie_vals
void ast_event_destroy(struct ast_event *event)
Destroy an event.
Definition: event.c:1314
enum ast_event_type type
Definition: event.c:125
#define AST_RWDLLIST_TRAVERSE
Definition: dlinkedlists.h:506
static struct ast_event * gen_sub_event(struct ast_event_sub *sub)
Definition: event.c:660
#define AST_RWDLLIST_RDLOCK(head)
Read locks a list.
Definition: dlinkedlists.h:71
uint32_t uint
Definition: event.c:113
int ast_event_str_to_event_type ( const char *  str,
enum ast_event_type event_type 
)

Convert a string into an event type.

Parameters
strthe string to convert
event_typean output parameter for the event type
Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 288 of file event.c.

References ARRAY_LEN, ast_strlen_zero(), and event_names.

Referenced by event_dump_cache().

289 {
290  int i;
291 
292  for (i = 0; i < ARRAY_LEN(event_names); i++) {
293  if (ast_strlen_zero(event_names[i]) || strcasecmp(event_names[i], str)) {
294  continue;
295  }
296 
297  *event_type = i;
298  return 0;
299  }
300 
301  return -1;
302 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
const char * str
Definition: app_jack.c:144
static const char *const event_names[AST_EVENT_TOTAL]
Event Names.
Definition: event.c:200
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
int ast_event_str_to_ie_type ( const char *  str,
enum ast_event_ie_type ie_type 
)

Convert a string to an IE type.

Parameters
strthe string to convert
ie_typean output parameter for the IE type
Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 324 of file event.c.

References ARRAY_LEN, ie_maps, and name.

325 {
326  int i;
327 
328  for (i = 0; i < ARRAY_LEN(ie_maps); i++) {
329  if (strcasecmp(ie_maps[i].name, str)) {
330  continue;
331  }
332 
333  *ie_type = i;
334  return 0;
335  }
336 
337  return -1;
338 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
const char * str
Definition: app_jack.c:144
static struct ie_map ie_maps[AST_EVENT_IE_TOTAL]
enum ast_event_ie_type ie_type
Definition: event.c:110
static const char name[]
int ast_event_sub_activate ( struct ast_event_sub sub)

Activate a dynamically built subscription.

Parameters
subthe subscription to activate that was allocated using ast_event_subscribe_new()

Once a dynamically built subscription has had all of the parameters added to it, it should be activated using this function.

Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 889 of file event.c.

References ast_event_check_subscriber(), ast_event_destroy(), AST_EVENT_IE_END, AST_EVENT_IE_EVENTTYPE, AST_EVENT_IE_PLTYPE_UINT, ast_event_queue(), AST_EVENT_SUB, AST_EVENT_SUB_NONE, ast_event_subs, AST_RWDLLIST_INSERT_TAIL, AST_RWDLLIST_UNLOCK, AST_RWDLLIST_WRLOCK, gen_sub_event(), and ast_event_sub::type.

Referenced by ast_event_subscribe().

890 {
894  struct ast_event *event;
895 
896  event = gen_sub_event(sub);
897  if (event && ast_event_queue(event)) {
898  ast_event_destroy(event);
899  }
900  }
901 
903  AST_RWDLLIST_INSERT_TAIL(&ast_event_subs[sub->type], sub, entry);
905 
906  return 0;
907 }
An event.
Definition: event.c:85
enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type,...)
Check if subscribers exist.
Definition: event.c:448
static struct ast_event_sub_list ast_event_subs[AST_EVENT_TOTAL]
int ast_event_queue(struct ast_event *event)
Queue an event.
Definition: event.c:1517
#define AST_RWDLLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: dlinkedlists.h:134
Event type Used by: AST_EVENT_SUB, AST_EVENT_UNSUB Payload type: UINT.
Definition: event_defs.h:95
#define AST_RWDLLIST_INSERT_TAIL
Definition: dlinkedlists.h:937
#define AST_RWDLLIST_WRLOCK(head)
Write locks a list.
Definition: dlinkedlists.h:58
void ast_event_destroy(struct ast_event *event)
Destroy an event.
Definition: event.c:1314
enum ast_event_type type
Definition: event.c:125
static struct ast_event * gen_sub_event(struct ast_event_sub *sub)
Definition: event.c:660
int ast_event_sub_append_ie_bitflags ( struct ast_event_sub sub,
enum ast_event_ie_type  ie_type,
uint32_t  flags 
)

Append a bitflags parameter to a subscription.

Parameters
subthe dynamic subscription allocated with ast_event_subscribe_new()
ie_typethe information element type for the parameter
flagsthe flags that must be present in the event to match this subscription
Return values
0success
non-zerofailure
Since
1.8

Definition at line 783 of file event.c.

References ast_calloc, AST_EVENT_IE_PLTYPE_BITFLAGS, AST_EVENT_IE_TOTAL, AST_LIST_INSERT_TAIL, ast_event_ie_val::ie_pltype, ast_event_ie_val::ie_type, ast_event_sub::ie_vals, ast_event_ie_val::payload, and ast_event_ie_val::uint.

Referenced by ast_event_subscribe().

785 {
786  struct ast_event_ie_val *ie_val;
787 
788  if (ie_type <= 0 || ie_type >= AST_EVENT_IE_TOTAL) {
789  return -1;
790  }
791 
792  if (!(ie_val = ast_calloc(1, sizeof(*ie_val)))) {
793  return -1;
794  }
795 
796  ie_val->ie_type = ie_type;
797  ie_val->payload.uint = flags;
799 
800  AST_LIST_INSERT_TAIL(&sub->ie_vals, ie_val, entry);
801 
802  return 0;
803 }
enum ast_event_ie_pltype ie_pltype
Definition: event.c:111
struct ast_event_ie_val::@256 entry
union ast_event_ie_val::@257 payload
Must be the last IE value +1.
Definition: event_defs.h:293
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
enum ast_event_ie_type ie_type
Definition: event.c:110
struct ast_event_sub::@260 ie_vals
#define ast_calloc(a, b)
Definition: astmm.h:82
uint32_t uint
Definition: event.c:113
int ast_event_sub_append_ie_exists ( struct ast_event_sub sub,
enum ast_event_ie_type  ie_type 
)

Append an 'exists' parameter to a subscription.

Parameters
subthe dynamic subscription allocated with ast_event_subscribe_new()
ie_typethe information element type that must be present in the event for it to match this subscription.
Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 805 of file event.c.

References ast_calloc, AST_EVENT_IE_PLTYPE_EXISTS, AST_EVENT_IE_TOTAL, AST_LIST_INSERT_TAIL, ast_event_ie_val::ie_pltype, ast_event_ie_val::ie_type, and ast_event_sub::ie_vals.

Referenced by ast_event_subscribe().

807 {
808  struct ast_event_ie_val *ie_val;
809 
810  if (ie_type <= 0 || ie_type >= AST_EVENT_IE_TOTAL) {
811  return -1;
812  }
813 
814  if (!(ie_val = ast_calloc(1, sizeof(*ie_val)))) {
815  return -1;
816  }
817 
818  ie_val->ie_type = ie_type;
820 
821  AST_LIST_INSERT_TAIL(&sub->ie_vals, ie_val, entry);
822 
823  return 0;
824 }
enum ast_event_ie_pltype ie_pltype
Definition: event.c:111
struct ast_event_ie_val::@256 entry
Must be the last IE value +1.
Definition: event_defs.h:293
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
enum ast_event_ie_type ie_type
Definition: event.c:110
struct ast_event_sub::@260 ie_vals
#define ast_calloc(a, b)
Definition: astmm.h:82
int ast_event_sub_append_ie_raw ( struct ast_event_sub sub,
enum ast_event_ie_type  ie_type,
void *  data,
size_t  raw_datalen 
)

Append a raw parameter to a subscription.

Parameters
subthe dynamic subscription allocated with ast_event_subscribe_new()
ie_typethe information element type for the parameter
datathe data that must be present in the event to match this subscription
raw_datalenlength of data
Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 860 of file event.c.

References ast_calloc, AST_EVENT_IE_PLTYPE_RAW, AST_EVENT_IE_TOTAL, ast_free, AST_LIST_INSERT_TAIL, ast_malloc, ast_event_ie_val::ie_pltype, ast_event_ie_val::ie_type, ast_event_sub::ie_vals, ast_event_ie_val::payload, ast_event_ie_val::raw, and ast_event_ie_val::raw_datalen.

Referenced by ast_event_subscribe().

862 {
863  struct ast_event_ie_val *ie_val;
864 
865  if (ie_type <= 0 || ie_type >= AST_EVENT_IE_TOTAL) {
866  return -1;
867  }
868 
869  if (!(ie_val = ast_calloc(1, sizeof(*ie_val)))) {
870  return -1;
871  }
872 
873  ie_val->ie_type = ie_type;
875  ie_val->raw_datalen = raw_datalen;
876 
877  if (!(ie_val->payload.raw = ast_malloc(raw_datalen))) {
878  ast_free(ie_val);
879  return -1;
880  }
881 
882  memcpy(ie_val->payload.raw, data, raw_datalen);
883 
884  AST_LIST_INSERT_TAIL(&sub->ie_vals, ie_val, entry);
885 
886  return 0;
887 }
enum ast_event_ie_pltype ie_pltype
Definition: event.c:111
struct ast_event_ie_val::@256 entry
union ast_event_ie_val::@257 payload
Must be the last IE value +1.
Definition: event_defs.h:293
size_t raw_datalen
Definition: event.c:120
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
enum ast_event_ie_type ie_type
Definition: event.c:110
void * raw
Definition: event.c:118
#define ast_free(a)
Definition: astmm.h:97
struct ast_event_sub::@260 ie_vals
#define ast_calloc(a, b)
Definition: astmm.h:82
#define ast_malloc(a)
Definition: astmm.h:91
int ast_event_sub_append_ie_str ( struct ast_event_sub sub,
enum ast_event_ie_type  ie_type,
const char *  str 
)

Append a string parameter to a subscription.

Parameters
subthe dynamic subscription allocated with ast_event_subscribe_new()
ie_typethe information element type for the parameter
strthe string that must be present in the event to match this subscription
Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 826 of file event.c.

References ast_calloc, AST_EVENT_IE_DEVICE, AST_EVENT_IE_PLTYPE_STR, AST_EVENT_IE_TOTAL, ast_free, AST_LIST_INSERT_TAIL, ast_str_hash(), ast_strdup, ast_strdupa, ast_tech_to_upper(), ast_event_ie_val::hash, ast_event_ie_val::ie_pltype, ast_event_ie_val::ie_type, ast_event_sub::ie_vals, ast_event_ie_val::payload, and ast_event_ie_val::str.

Referenced by ast_event_subscribe(), and handle_devstate_change().

828 {
829  struct ast_event_ie_val *ie_val;
830 
831  if (ie_type <= 0 || ie_type >= AST_EVENT_IE_TOTAL) {
832  return -1;
833  }
834 
835  if (!(ie_val = ast_calloc(1, sizeof(*ie_val)))) {
836  return -1;
837  }
838 
839  ie_val->ie_type = ie_type;
841 
842  if (!(ie_val->payload.str = ast_strdup(str))) {
843  ast_free(ie_val);
844  return -1;
845  }
846 
847  if (ie_type == AST_EVENT_IE_DEVICE) {
848  char *uppertech = ast_strdupa(str);
849  ast_tech_to_upper(uppertech);
850  ie_val->payload.hash = ast_str_hash(uppertech);
851  } else {
852  ie_val->payload.hash = ast_str_hash(str);
853  }
854 
855  AST_LIST_INSERT_TAIL(&sub->ie_vals, ie_val, entry);
856 
857  return 0;
858 }
#define ast_strdup(a)
Definition: astmm.h:109
enum ast_event_ie_pltype ie_pltype
Definition: event.c:111
struct ast_event_ie_val::@256 entry
union ast_event_ie_val::@257 payload
Must be the last IE value +1.
Definition: event_defs.h:293
const char * str
Definition: app_jack.c:144
const char * str
Definition: event.c:116
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: utils.h:663
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
char * ast_tech_to_upper(char *dev_str)
Convert the tech portion of a device string to upper case.
Definition: strings.h:939
enum ast_event_ie_type ie_type
Definition: event.c:110
#define ast_free(a)
Definition: astmm.h:97
struct ast_event_sub::@260 ie_vals
#define ast_calloc(a, b)
Definition: astmm.h:82
uint32_t hash
Definition: event.c:115
Device Name Used by AST_EVENT_DEVICE_STATE_CHANGE Payload type: STR.
Definition: event_defs.h:107
static force_inline int attribute_pure ast_str_hash(const char *str)
Compute a hash value on a string.
Definition: strings.h:949
int ast_event_sub_append_ie_uint ( struct ast_event_sub sub,
enum ast_event_ie_type  ie_type,
uint32_t  uint 
)

Append a uint parameter to a subscription.

Parameters
subthe dynamic subscription allocated with ast_event_subscribe_new()
ie_typethe information element type for the parameter
uintthe value that must be present in the event to match this subscription
Return values
0success
non-zerofailure
Since
1.6.1

Definition at line 761 of file event.c.

References ast_calloc, AST_EVENT_IE_PLTYPE_UINT, AST_EVENT_IE_TOTAL, AST_LIST_INSERT_TAIL, ast_event_ie_val::ie_pltype, ast_event_ie_val::ie_type, ast_event_sub::ie_vals, ast_event_ie_val::payload, and ast_event_ie_val::uint.

Referenced by ast_event_subscribe(), and handle_cli_status().

763 {
764  struct ast_event_ie_val *ie_val;
765 
766  if (ie_type <= 0 || ie_type >= AST_EVENT_IE_TOTAL) {
767  return -1;
768  }
769 
770  if (!(ie_val = ast_calloc(1, sizeof(*ie_val)))) {
771  return -1;
772  }
773 
774  ie_val->ie_type = ie_type;
775  ie_val->payload.uint = unsigned_int;
777 
778  AST_LIST_INSERT_TAIL(&sub->ie_vals, ie_val, entry);
779 
780  return 0;
781 }
enum ast_event_ie_pltype ie_pltype
Definition: event.c:111
struct ast_event_ie_val::@256 entry
union ast_event_ie_val::@257 payload
Must be the last IE value +1.
Definition: event_defs.h:293
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
enum ast_event_ie_type ie_type
Definition: event.c:110
struct ast_event_sub::@260 ie_vals
#define ast_calloc(a, b)
Definition: astmm.h:82
uint32_t uint
Definition: event.c:113
void ast_event_sub_destroy ( struct ast_event_sub sub)

Destroy an allocated subscription.

Parameters
subthe subscription to destroy

This function should be used when a subscription is allocated with ast_event_subscribe_new(), but for some reason, you want to destroy it instead of activating it. This could be because of an error when reading in the configuration for the dynamically built subscription.

Since
1.6.1

Definition at line 971 of file event.c.

References ast_event_ie_val_destroy(), ast_free, AST_LIST_REMOVE_HEAD, and ast_event_sub::ie_vals.

Referenced by ast_event_unsubscribe(), event_shutdown(), handle_cli_status(), and handle_devstate_change().

972 {
973  struct ast_event_ie_val *ie_val;
974 
975  while ((ie_val = AST_LIST_REMOVE_HEAD(&sub->ie_vals, entry))) {
976  ast_event_ie_val_destroy(ie_val);
977  }
978 
979  ast_free(sub);
980 }
struct ast_event_ie_val::@256 entry
#define AST_LIST_REMOVE_HEAD(head, field)
Removes and returns the head entry from a list.
Definition: linkedlists.h:818
#define ast_free(a)
Definition: astmm.h:97
struct ast_event_sub::@260 ie_vals
static void ast_event_ie_val_destroy(struct ast_event_ie_val *ie_val)
Definition: event.c:349
struct ast_event_sub* ast_event_subscribe ( enum ast_event_type  event_type,
ast_event_cb_t  cb,
const char *  description,
void *  userdata,
  ... 
)

Subscribe to events.

Parameters
event_typeThe type of events to subscribe to
cbThe function to be called with events
descriptionDescription of the subscription.
userdatadata to be passed to the event callback

The rest of the arguments to this function specify additional parameters for the subscription to filter which events are passed to this subscriber. The arguments must be in sets of:

and must end with AST_EVENT_IE_END.

If the ie_type specified is not AST_EVENT_IE_END, then it must be followed by a valid IE payload type. If the payload type specified is AST_EVENT_IE_PLTYPE_EXISTS, then the 3rd argument should not be provided. Otherwise, a payload must also be specified.

Returns
This returns a reference to the subscription for use with un-subscribing later. If there is a failure in creating the subscription, NULL will be returned.

Example usage:

This creates a subscription to AST_EVENT_MWI events that contain an information element, AST_EVENT_IE_MAILBOX, with the same string value contained in peer->mailbox. Also, the event callback will be passed a pointer to the peer.

Note
A NULL description will cause this function to crash, so watch out!

Definition at line 909 of file event.c.

References ast_copy_string(), AST_EVENT_IE_END, AST_EVENT_IE_PLTYPE_BITFLAGS, AST_EVENT_IE_PLTYPE_EXISTS, AST_EVENT_IE_PLTYPE_RAW, AST_EVENT_IE_PLTYPE_STR, AST_EVENT_IE_PLTYPE_UINT, AST_EVENT_IE_PLTYPE_UNKNOWN, ast_event_sub_activate(), ast_event_sub_append_ie_bitflags(), ast_event_sub_append_ie_exists(), ast_event_sub_append_ie_raw(), ast_event_sub_append_ie_str(), ast_event_sub_append_ie_uint(), ast_event_subscribe_new(), ast_event_sub::description, and str.

Referenced by add_peer_mwi_subs(), add_publish_event(), aji_init_event_distribution(), ast_enable_distributed_devstate(), build_gateway(), build_peer(), cc_generic_agent_start_monitoring(), config_line(), create_new_generic_list(), load_module(), load_pbx(), mkintf(), network_change_event_subscribe(), sig_pri_start_pri(), and start_poll_thread().

911 {
912  va_list ap;
914  struct ast_event_sub *sub;
915 
916  if (!(sub = ast_event_subscribe_new(type, cb, userdata))) {
917  return NULL;
918  }
919 
920  ast_copy_string(sub->description, description, sizeof(sub->description));
921 
922  va_start(ap, userdata);
923  for (ie_type = va_arg(ap, enum ast_event_ie_type);
924  ie_type != AST_EVENT_IE_END;
925  ie_type = va_arg(ap, enum ast_event_ie_type))
926  {
927  enum ast_event_ie_pltype ie_pltype;
928 
929  ie_pltype = va_arg(ap, enum ast_event_ie_pltype);
930 
931  switch (ie_pltype) {
933  break;
935  {
936  uint32_t unsigned_int = va_arg(ap, uint32_t);
937  ast_event_sub_append_ie_uint(sub, ie_type, unsigned_int);
938  break;
939  }
941  {
942  uint32_t unsigned_int = va_arg(ap, uint32_t);
943  ast_event_sub_append_ie_bitflags(sub, ie_type, unsigned_int);
944  break;
945  }
947  {
948  const char *str = va_arg(ap, const char *);
949  ast_event_sub_append_ie_str(sub, ie_type, str);
950  break;
951  }
953  {
954  void *data = va_arg(ap, void *);
955  size_t data_len = va_arg(ap, size_t);
956  ast_event_sub_append_ie_raw(sub, ie_type, data, data_len);
957  break;
958  }
960  ast_event_sub_append_ie_exists(sub, ie_type);
961  break;
962  }
963  }
964  va_end(ap);
965 
967 
968  return sub;
969 }
int ast_event_sub_append_ie_str(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, const char *str)
Append a string parameter to a subscription.
Definition: event.c:826
int ast_event_sub_append_ie_bitflags(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, uint32_t flags)
Append a bitflags parameter to a subscription.
Definition: event.c:783
ast_event_ie_pltype
Payload types for event information elements.
Definition: event_defs.h:299
const char * str
Definition: app_jack.c:144
ast_event_ie_type
Event Information Element types.
Definition: event_defs.h:62
void * userdata
Definition: event.c:128
int ast_event_sub_append_ie_raw(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, void *data, size_t raw_datalen)
Append a raw parameter to a subscription.
Definition: event.c:860
ast_event_cb_t cb
Definition: event.c:126
enum ast_event_ie_type ie_type
Definition: event.c:110
Event subscription.
Definition: event.c:124
int ast_event_sub_activate(struct ast_event_sub *sub)
Activate a dynamically built subscription.
Definition: event.c:889
int ast_event_sub_append_ie_uint(struct ast_event_sub *sub, enum ast_event_ie_type ie_type, uint32_t uint)
Append a uint parameter to a subscription.
Definition: event.c:761
char description[64]
Definition: event.c:127
static const char type[]
Definition: chan_nbs.c:57
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:223
struct ast_event_sub * ast_event_subscribe_new(enum ast_event_type type, ast_event_cb_t cb, void *userdata)
Allocate a subscription, but do not activate it.
Definition: event.c:739
int ast_event_sub_append_ie_exists(struct ast_event_sub *sub, enum ast_event_ie_type ie_type)
Append an &#39;exists&#39; parameter to a subscription.
Definition: event.c:805
struct ast_event_sub* ast_event_subscribe_new ( enum ast_event_type  type,
ast_event_cb_t  cb,
void *  userdata 
)

Allocate a subscription, but do not activate it.

Parameters
typethe event type to subscribe to
cbthe function to call when an event matches this subscription
userdatadata to pass to the provided callback

This function should be used when you want to dynamically build a subscription.

Returns
the allocated subscription, or NULL on failure
Since
1.6.1

Definition at line 739 of file event.c.

References ast_atomic_fetchadd_int(), ast_calloc, ast_log(), ast_event_sub::cb, LOG_ERROR, ast_event_sub::type, ast_event_sub::uniqueid, and ast_event_sub::userdata.

Referenced by ast_event_subscribe(), handle_cli_status(), and handle_devstate_change().

741 {
742  struct ast_event_sub *sub;
743 
744  if (type < 0 || type >= AST_EVENT_TOTAL) {
745  ast_log(LOG_ERROR, "%u is an invalid type!\n", type);
746  return NULL;
747  }
748 
749  if (!(sub = ast_calloc(1, sizeof(*sub)))) {
750  return NULL;
751  }
752 
753  sub->type = type;
754  sub->cb = cb;
755  sub->userdata = userdata;
756  sub->uniqueid = ast_atomic_fetchadd_int((int *) &sub_uniqueid, 1);
757 
758  return sub;
759 }
int ast_atomic_fetchadd_int(volatile int *p, int v)
Atomically add v to *p and return * the previous value of *p. This can be used to handle reference co...
Definition: lock.h:603
uint32_t uniqueid
Definition: event.c:129
void * userdata
Definition: event.c:128
#define LOG_ERROR
Definition: logger.h:155
ast_event_cb_t cb
Definition: event.c:126
static uint32_t sub_uniqueid
Definition: event.c:134
Event subscription.
Definition: event.c:124
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
static const char type[]
Definition: chan_nbs.c:57
enum ast_event_type type
Definition: event.c:125
#define ast_calloc(a, b)
Definition: astmm.h:82
const char* ast_event_subscriber_get_description ( struct ast_event_sub sub)

Get description for a subscription.

Parameters
subsubscription
Returns
string description of the subscription

Definition at line 982 of file event.c.

References ast_event_sub::description.

983 {
984  return sub ? sub->description : NULL;
985 }
char description[64]
Definition: event.c:127
struct ast_event_sub* ast_event_unsubscribe ( struct ast_event_sub event_sub)

Un-subscribe from events.

Parameters
event_subThis is the reference to the subscription returned by ast_event_subscribe.

This function will remove a subscription and free the associated data structures.

Returns
NULL for convenience.
Version
1.6.1 return changed to NULL

Definition at line 987 of file event.c.

References AST_DLLIST_REMOVE, ast_event_check_subscriber(), ast_event_destroy(), AST_EVENT_IE_DESCRIPTION, AST_EVENT_IE_END, AST_EVENT_IE_EVENTTYPE, AST_EVENT_IE_PLTYPE_STR, AST_EVENT_IE_PLTYPE_UINT, AST_EVENT_IE_UNIQUEID, ast_event_new(), ast_event_queue(), ast_event_sub_destroy(), AST_EVENT_SUB_NONE, ast_event_subs, AST_EVENT_UNSUB, AST_RWDLLIST_UNLOCK, AST_RWDLLIST_WRLOCK, ast_event_sub::description, ast_event_sub::type, and ast_event_sub::uniqueid.

Referenced by add_peer_mwi_subs(), cc_generic_agent_destructor(), destroy_dahdi_pvt(), destroy_endpoint(), destroy_mailbox(), generic_agent_devstate_unsubscribe(), generic_monitor_instance_list_destructor(), network_change_event_unsubscribe(), peer_destructor(), publish_event_destroy(), sig_pri_start_pri(), sig_pri_stop_pri(), stop_poll_thread(), unload_module(), and unload_pbx().

988 {
989  struct ast_event *event;
990 
991  AST_RWDLLIST_WRLOCK(&ast_event_subs[sub->type]);
992  AST_DLLIST_REMOVE(&ast_event_subs[sub->type], sub, entry);
993  AST_RWDLLIST_UNLOCK(&ast_event_subs[sub->type]);
994 
998 
1004  if (event && ast_event_queue(event)) {
1005  ast_event_destroy(event);
1006  }
1007  }
1008 
1009  ast_event_sub_destroy(sub);
1010 
1011  return NULL;
1012 }
An event.
Definition: event.c:85
enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type,...)
Check if subscribers exist.
Definition: event.c:448
Description Used by: AST_EVENT_SUB, AST_EVENT_UNSUB Payload type: STR.
Definition: event_defs.h:259
void ast_event_sub_destroy(struct ast_event_sub *sub)
Destroy an allocated subscription.
Definition: event.c:971
static struct ast_event_sub_list ast_event_subs[AST_EVENT_TOTAL]
int ast_event_queue(struct ast_event *event)
Queue an event.
Definition: event.c:1517
#define AST_RWDLLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: dlinkedlists.h:134
Event type Used by: AST_EVENT_SUB, AST_EVENT_UNSUB Payload type: UINT.
Definition: event_defs.h:95
#define AST_RWDLLIST_WRLOCK(head)
Write locks a list.
Definition: dlinkedlists.h:58
void ast_event_destroy(struct ast_event *event)
Destroy an event.
Definition: event.c:1314
struct ast_event * ast_event_new(enum ast_event_type event_type,...)
Create a new event.
Definition: event.c:1202
#define AST_DLLIST_REMOVE(head, elm, field)
Removes a specific entry from a list.
Definition: dlinkedlists.h:999
Unique ID Used by: AST_EVENT_SUB, AST_EVENT_UNSUB Payload type: UINT.
Definition: event_defs.h:89