diff options
Diffstat (limited to 'include/asterisk')
| -rw-r--r-- | include/asterisk/devicestate.h | 2 | ||||
| -rw-r--r-- | include/asterisk/event.h | 127 | ||||
| -rw-r--r-- | include/asterisk/event_defs.h | 238 | ||||
| -rw-r--r-- | include/asterisk/stasis.h | 31 |
4 files changed, 287 insertions, 111 deletions
diff --git a/include/asterisk/devicestate.h b/include/asterisk/devicestate.h index ccc46311e..4f9aa739b 100644 --- a/include/asterisk/devicestate.h +++ b/include/asterisk/devicestate.h @@ -59,7 +59,7 @@ enum ast_device_state { AST_DEVICE_RINGING, /*!< Device is ringing */ AST_DEVICE_RINGINUSE, /*!< Device is ringing *and* in use */ AST_DEVICE_ONHOLD, /*!< Device is on hold */ - AST_DEVICE_TOTAL, /*/ Total num of device states, used for testing */ + AST_DEVICE_TOTAL, /*!< Total num of device states, used for testing */ }; /*! \brief Device State Cachability diff --git a/include/asterisk/event.h b/include/asterisk/event.h index 3178de5c2..7eea0581d 100644 --- a/include/asterisk/event.h +++ b/include/asterisk/event.h @@ -25,33 +25,27 @@ /*! * \page AstGenericEvents Generic event system * - * The purpose of this API is to provide a generic way to share events between - * Asterisk modules. Code can generate events, and other code can subscribe to - * them. + * Prior to the creation of \ref stasis, the purpose of this API was to provide + * a generic way to share events between Asterisk modules. Once there was a need + * to disseminate data whose definition was provided by the producers/consumers, + * it was no longer possible to use the binary representation in the generic + * event system. + * + * That aside, the generic event system is still useful and used by several + * modules in Asterisk. + * - CEL uses the \ref ast_event representation to pass information to registered + * backends. + * - The \file res_corosync module publishes \ref ast_event representations of + * information to other Asterisk instances in a cluster. + * - Security event represent their event types and data using this system. + * - Theoretically, any \ref stasis message can use this system to pass + * information around in a binary format. * * Events have an associated event type, as well as information elements. The * information elements are the meta data that go along with each event. For * example, in the case of message waiting indication, the event type is MWI, * and each MWI event contains at least three information elements: the * mailbox, the number of new messages, and the number of old messages. - * - * Subscriptions to events consist of an event type and information elements, - * as well. Subscriptions can be to all events, or a certain subset of events. - * If an event type is provided, only events of that type will be sent to this - * subscriber. Furthermore, if information elements are supplied with the - * subscription, only events that contain the specified information elements - * with specified values will be sent to the subscriber. For example, when a - * SIP phone subscribes to MWI for mailbox 1234, then chan_sip can subscribe - * to internal Asterisk MWI events with the MAILBOX information element with - * a value of "1234". - * - * Another key feature of this event system is the ability to cache events. - * It is useful for some types of events to be able to remember the last known - * value. These are usually events that indicate some kind of state change. - * In the example of MWI, app_voicemail can instruct the event core to cache - * these events based on the mailbox. So, the last known MWI state of each - * mailbox will be cached, and other modules can retrieve this information - * on demand without having to poll the mailbox directly. */ #ifndef AST_EVENT_H @@ -109,9 +103,6 @@ struct ast_event *ast_event_new(enum ast_event_type event_type, ...); * * \return 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. */ void ast_event_destroy(struct ast_event *event); @@ -150,6 +141,55 @@ int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie uint32_t data); /*! + * \brief Append an information element that has a bitflags payload + * + * \param event the event that the IE will be appended to + * \param ie_type the type of IE to append + * \param bitflags the flags that are the payload of the IE + * + * \retval 0 success + * \retval -1 failure + * \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. + */ +int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type, + uint32_t bitflags); + +/*! + * \brief Append an information element that has a raw payload + * + * \param event the event that the IE will be appended to + * \param ie_type the type of IE to append + * \param data A pointer to the raw data for the payload of the IE + * \param data_len The amount of data to copy into the payload + * + * \retval 0 success + * \retval -1 failure + * + * 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. + */ +int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, + const void *data, size_t data_len); + +/*! + * \brief Append the global EID IE + * + * \param event the event to append IE to + * + * \note For ast_event_new() that includes IEs, this is done automatically + * for you. + * + * \retval 0 success + * \retval -1 failure + */ +int ast_event_append_eid(struct ast_event **event); + +/*! * \brief Get the value of an information element that has an integer payload * * \param event The event to get the IE from @@ -173,6 +213,38 @@ uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_ const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type); /*! + * \brief Get the value of an information element that has a raw payload + * + * \param event The event to get the IE from + * \param ie_type the type of information element to retrieve + * + * \return This returns the payload of the information element with the given type. + * If the information element isn't found, NULL will be returned. + */ +const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type); + +/*! + * \brief Get the length of the raw payload for a particular IE + * + * \param event The event to get the IE payload length from + * \param ie_type the type of information element to get the length of + * + * \return If an IE of type ie_type is found, its payload length is returned. + * Otherwise, 0 is returned. + */ +uint16_t ast_event_get_ie_raw_payload_len(const struct ast_event *event, enum ast_event_ie_type ie_type); + +/*! + * \brief Get the string representation of the type of the given event + * + * \arg event the event to get the type of + * + * \return the string representation of the event type of the provided event + * \since 1.6.1 + */ +const char *ast_event_get_type_name(const struct ast_event *event); + +/*! * \brief Get the string representation of an information element type * * \param ie_type the information element type to get the string representation of @@ -273,6 +345,13 @@ uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator); */ const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator); +/*! + * \brief Get the minimum length of an ast_event. + * + * \return minimum amount of memory that will be consumed by any ast_event. + */ +size_t ast_event_minimum_length(void); + #if defined(__cplusplus) || defined(c_plusplus) } #endif diff --git a/include/asterisk/event_defs.h b/include/asterisk/event_defs.h index f8f98ace0..80a8d7dda 100644 --- a/include/asterisk/event_defs.h +++ b/include/asterisk/event_defs.h @@ -25,23 +25,41 @@ #ifndef AST_EVENT_DEFS_H #define AST_EVENT_DEFS_H -/*! \brief Event types - * \note These values no longer go over the wire and can change when items are removed. */ enum ast_event_type { /*! Reserved to provide the ability to subscribe to all events. A specific * event should never have a payload of 0. */ AST_EVENT_ALL = 0x00, /*! This event type is reserved for use by third-party modules to create - * custom events without having to modify this file. + * custom events without having to modify this file. * \note There are no "custom" IE types, because IEs only have to be * unique to the event itself, not necessarily across all events. */ AST_EVENT_CUSTOM = 0x01, + /*! Voicemail message waiting indication */ + AST_EVENT_MWI = 0x02, /*! Someone has subscribed to events */ - AST_EVENT_SUB = 0x02, + AST_EVENT_SUB = 0x03, + /*! Someone has unsubscribed from events */ + AST_EVENT_UNSUB = 0x04, + /*! The aggregate state of a device across all servers configured to be + * a part of a device state cluster has changed. */ + AST_EVENT_DEVICE_STATE = 0x05, + /*! The state of a device has changed on _one_ server. This should not be used + * directly, in general. Use AST_EVENT_DEVICE_STATE instead. */ + AST_EVENT_DEVICE_STATE_CHANGE = 0x06, /*! Channel Event Logging events */ - AST_EVENT_CEL = 0x03, + AST_EVENT_CEL = 0x07, + /*! A report of a security related event (see security_events.h) */ + AST_EVENT_SECURITY = 0x08, + /*! Used by res_stun_monitor to alert listeners to an exernal network address change. */ + AST_EVENT_NETWORK_CHANGE = 0x09, + /*! The presence state for a presence provider */ + AST_EVENT_PRESENCE_STATE = 0x0a, + /*! Used to alert listeners when a named ACL has changed. */ + AST_EVENT_ACL_CHANGE = 0x0b, + /*! Send out a ping for debugging distributed events */ + AST_EVENT_PING = 0x0c, /*! Number of event types. This should be the last event type + 1 */ - AST_EVENT_TOTAL = 0x04, + AST_EVENT_TOTAL = 0x0d, }; /*! \brief Event Information Element types */ @@ -49,199 +67,243 @@ enum ast_event_ie_type { /*! Used to terminate the arguments to event functions */ AST_EVENT_IE_END = -1, - /*! + /*! + * \brief Number of new messages + * Used by: AST_EVENT_MWI + * Payload type: UINT + */ + AST_EVENT_IE_NEWMSGS = 0x0001, + /*! + * \brief Number of + * Used by: AST_EVENT_MWI + * Payload type: UINT + */ + AST_EVENT_IE_OLDMSGS = 0x0002, + /*! + * \brief Mailbox name \verbatim (mailbox[@context]) \endverbatim + * Used by: AST_EVENT_MWI + * Payload type: STR + */ + AST_EVENT_IE_MAILBOX = 0x0003, + /*! * \brief Unique ID * Used by: AST_EVENT_SUB, AST_EVENT_UNSUB * Payload type: UINT */ - AST_EVENT_IE_UNIQUEID = 0x0001, - /*! - * \brief Event type + AST_EVENT_IE_UNIQUEID = 0x0004, + /*! + * \brief Event type * Used by: AST_EVENT_SUB, AST_EVENT_UNSUB * Payload type: UINT */ - AST_EVENT_IE_EVENTTYPE = 0x0002, + AST_EVENT_IE_EVENTTYPE = 0x0005, /*! * \brief Hint that someone cares that an IE exists * Used by: AST_EVENT_SUB * Payload type: UINT (ast_event_ie_type) */ - AST_EVENT_IE_EXISTS = 0x0003, - /*! - * \brief Context IE - * Used by AST_EVENT_MWI - * Payload type: str - */ - AST_EVENT_IE_CONTEXT = 0x0004, - /*! + AST_EVENT_IE_EXISTS = 0x0006, + /*! + * \brief Device Name + * Used by AST_EVENT_DEVICE_STATE_CHANGE + * Payload type: STR + */ + AST_EVENT_IE_DEVICE = 0x0007, + /*! + * \brief Generic State IE + * Used by AST_EVENT_DEVICE_STATE_CHANGE + * Payload type: UINT + * The actual state values depend on the event which + * this IE is a part of. + */ + AST_EVENT_IE_STATE = 0x0008, + /*! + * \brief Context IE + * Used by AST_EVENT_MWI + * Payload type: str + */ + AST_EVENT_IE_CONTEXT = 0x0009, + /*! * \brief Channel Event Type * Used by: AST_EVENT_CEL * Payload type: UINT */ - AST_EVENT_IE_CEL_EVENT_TYPE = 0x0005, - /*! + AST_EVENT_IE_CEL_EVENT_TYPE = 0x000a, + /*! * \brief Channel Event Time (seconds) * Used by: AST_EVENT_CEL * Payload type: UINT */ - AST_EVENT_IE_CEL_EVENT_TIME = 0x0006, - /*! + AST_EVENT_IE_CEL_EVENT_TIME = 0x000b, + /*! * \brief Channel Event Time (micro-seconds) * Used by: AST_EVENT_CEL * Payload type: UINT */ - AST_EVENT_IE_CEL_EVENT_TIME_USEC = 0x0007, - /*! + AST_EVENT_IE_CEL_EVENT_TIME_USEC = 0x000c, + /*! * \brief Channel Event User Event Name * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_USEREVENT_NAME = 0x0008, - /*! + AST_EVENT_IE_CEL_USEREVENT_NAME = 0x000d, + /*! * \brief Channel Event CID name * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_CIDNAME = 0x0009, - /*! + AST_EVENT_IE_CEL_CIDNAME = 0x000e, + /*! * \brief Channel Event CID num * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_CIDNUM = 0x000a, - /*! + AST_EVENT_IE_CEL_CIDNUM = 0x000f, + /*! * \brief Channel Event extension name * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_EXTEN = 0x000b, - /*! + AST_EVENT_IE_CEL_EXTEN = 0x0010, + /*! * \brief Channel Event context name * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_CONTEXT = 0x000c, - /*! + AST_EVENT_IE_CEL_CONTEXT = 0x0011, + /*! * \brief Channel Event channel name * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_CHANNAME = 0x000d, - /*! + AST_EVENT_IE_CEL_CHANNAME = 0x0012, + /*! * \brief Channel Event app name * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_APPNAME = 0x000e, - /*! + AST_EVENT_IE_CEL_APPNAME = 0x0013, + /*! * \brief Channel Event app args/data * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_APPDATA = 0x000f, - /*! + AST_EVENT_IE_CEL_APPDATA = 0x0014, + /*! * \brief Channel Event AMA flags * Used by: AST_EVENT_CEL * Payload type: UINT */ - AST_EVENT_IE_CEL_AMAFLAGS = 0x0010, - /*! + AST_EVENT_IE_CEL_AMAFLAGS = 0x0015, + /*! * \brief Channel Event AccountCode * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_ACCTCODE = 0x0011, - /*! + AST_EVENT_IE_CEL_ACCTCODE = 0x0016, + /*! * \brief Channel Event UniqueID * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_UNIQUEID = 0x0012, - /*! + AST_EVENT_IE_CEL_UNIQUEID = 0x0017, + /*! * \brief Channel Event Userfield * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_USERFIELD = 0x0013, - /*! + AST_EVENT_IE_CEL_USERFIELD = 0x0018, + /*! * \brief Channel Event CID ANI field * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_CIDANI = 0x0014, - /*! + AST_EVENT_IE_CEL_CIDANI = 0x0019, + /*! * \brief Channel Event CID RDNIS field * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_CIDRDNIS = 0x0015, - /*! + AST_EVENT_IE_CEL_CIDRDNIS = 0x001a, + /*! * \brief Channel Event CID dnid * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_CIDDNID = 0x0016, - /*! + AST_EVENT_IE_CEL_CIDDNID = 0x001b, + /*! * \brief Channel Event Peer -- for Things involving multiple channels, like BRIDGE * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_PEER = 0x0017, - /*! + AST_EVENT_IE_CEL_PEER = 0x001c, + /*! * \brief Channel Event LinkedID * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_LINKEDID = 0x0018, - /*! + AST_EVENT_IE_CEL_LINKEDID = 0x001d, + /*! * \brief Channel Event peeraccount * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_PEERACCT = 0x0019, - /*! + AST_EVENT_IE_CEL_PEERACCT = 0x001e, + /*! * \brief Channel Event extra data * Used by: AST_EVENT_CEL * Payload type: STR */ - AST_EVENT_IE_CEL_EXTRA = 0x001a, + AST_EVENT_IE_CEL_EXTRA = 0x001f, /*! * \brief Description * Used by: AST_EVENT_SUB, AST_EVENT_UNSUB * Payload type: STR */ - AST_EVENT_IE_DESCRIPTION = 0x001b, + AST_EVENT_IE_DESCRIPTION = 0x0020, /*! * \brief Entity ID * Used by All events * Payload type: RAW * This IE indicates which server the event originated from */ - AST_EVENT_IE_EVENT_VERSION = 0x001c, - AST_EVENT_IE_SERVICE = 0x001d, - AST_EVENT_IE_MODULE = 0x001e, - AST_EVENT_IE_ACCOUNT_ID = 0x001f, - AST_EVENT_IE_SESSION_ID = 0x0020, - AST_EVENT_IE_SESSION_TV = 0x0021, - AST_EVENT_IE_ACL_NAME = 0x0022, - AST_EVENT_IE_LOCAL_ADDR = 0x0023, - AST_EVENT_IE_REMOTE_ADDR = 0x0024, - AST_EVENT_IE_EVENT_TV = 0x0025, - AST_EVENT_IE_REQUEST_TYPE = 0x0026, - AST_EVENT_IE_REQUEST_PARAMS = 0x0027, - AST_EVENT_IE_AUTH_METHOD = 0x0028, - AST_EVENT_IE_SEVERITY = 0x0029, - AST_EVENT_IE_EXPECTED_ADDR = 0x002a, - AST_EVENT_IE_CHALLENGE = 0x002b, - AST_EVENT_IE_RESPONSE = 0x002c, - AST_EVENT_IE_EXPECTED_RESPONSE = 0x002e, - AST_EVENT_IE_RECEIVED_CHALLENGE = 0x002f, - AST_EVENT_IE_RECEIVED_HASH = 0x0030, - AST_EVENT_IE_USING_PASSWORD = 0x0031, - AST_EVENT_IE_ATTEMPTED_TRANSPORT = 0x0032, + AST_EVENT_IE_EID = 0x0021, + AST_EVENT_IE_SECURITY_EVENT = 0x0022, + AST_EVENT_IE_EVENT_VERSION = 0x0023, + AST_EVENT_IE_SERVICE = 0x0024, + AST_EVENT_IE_MODULE = 0x0025, + AST_EVENT_IE_ACCOUNT_ID = 0x0026, + AST_EVENT_IE_SESSION_ID = 0x0027, + AST_EVENT_IE_SESSION_TV = 0x0028, + AST_EVENT_IE_ACL_NAME = 0x0029, + AST_EVENT_IE_LOCAL_ADDR = 0x002a, + AST_EVENT_IE_REMOTE_ADDR = 0x002b, + AST_EVENT_IE_EVENT_TV = 0x002c, + AST_EVENT_IE_REQUEST_TYPE = 0x002d, + AST_EVENT_IE_REQUEST_PARAMS = 0x002e, + AST_EVENT_IE_AUTH_METHOD = 0x002f, + AST_EVENT_IE_SEVERITY = 0x0030, + AST_EVENT_IE_EXPECTED_ADDR = 0x0031, + AST_EVENT_IE_CHALLENGE = 0x0032, + AST_EVENT_IE_RESPONSE = 0x0033, + AST_EVENT_IE_EXPECTED_RESPONSE = 0x0034, + AST_EVENT_IE_RECEIVED_CHALLENGE = 0x0035, + AST_EVENT_IE_RECEIVED_HASH = 0x0036, + AST_EVENT_IE_USING_PASSWORD = 0x0037, + AST_EVENT_IE_ATTEMPTED_TRANSPORT = 0x0038, + AST_EVENT_IE_PRESENCE_PROVIDER = 0x0039, + AST_EVENT_IE_PRESENCE_STATE = 0x003a, + AST_EVENT_IE_PRESENCE_SUBTYPE = 0x003b, + AST_EVENT_IE_PRESENCE_MESSAGE = 0x003c, + /*! + * \brief Event non-cachability flag + * Used by: All events + * Payload type: UINT + */ + AST_EVENT_IE_CACHABLE = 0x003d, /*! \brief Must be the last IE value +1 */ - AST_EVENT_IE_TOTAL = 0x0033, + AST_EVENT_IE_TOTAL = 0x003e, }; /*! @@ -249,12 +311,16 @@ enum ast_event_ie_type { */ enum ast_event_ie_pltype { AST_EVENT_IE_PLTYPE_UNKNOWN = -1, + /*! Just check if it exists, not the value */ + AST_EVENT_IE_PLTYPE_EXISTS, /*! Unsigned Integer (Can be used for signed, too ...) */ AST_EVENT_IE_PLTYPE_UINT, /*! String */ AST_EVENT_IE_PLTYPE_STR, /*! Raw data, compared with memcmp */ AST_EVENT_IE_PLTYPE_RAW, + /*! Bit flags (unsigned integer, compared using boolean logic) */ + AST_EVENT_IE_PLTYPE_BITFLAGS, }; /*! diff --git a/include/asterisk/stasis.h b/include/asterisk/stasis.h index 20870e6d6..f5b4a60d9 100644 --- a/include/asterisk/stasis.h +++ b/include/asterisk/stasis.h @@ -171,6 +171,7 @@ #include "asterisk/json.h" #include "asterisk/manager.h" #include "asterisk/utils.h" +#include "asterisk/event.h" /*! @{ */ @@ -255,6 +256,21 @@ struct stasis_message_vtable { */ struct ast_manager_event_blob *(*to_ami)( struct stasis_message *message); + + /*! + * \since 12.3.0 + * \brief Build the \ref ast_event representation of the message. + * + * May be \c NULL, or may return \c NULL, to indicate no representation. + * The returned object should be free'd. + * + * \param message Message to convert to an \ref ast_event. + * \return Newly allocated \ref ast_event. + * \return \c NULL on error. + * \return \c NULL if AMI format is not supported. + */ + struct ast_event *(*to_event)( + struct stasis_message *message); }; /*! @@ -389,6 +405,19 @@ struct ast_json *stasis_message_to_json(struct stasis_message *message, struct s struct ast_manager_event_blob *stasis_message_to_ami( struct stasis_message *message); +/*! + * \brief Build the \ref AstGenericEvents representation of the message. + * + * May return \c NULL, to indicate no representation. The returned object should + * be disposed of via \ref ast_event_destroy. + * + * \param message Message to convert to AMI. + * \return \c NULL on error. + * \return \c NULL if AMI format is not supported. + */ +struct ast_event *stasis_message_to_event( + struct stasis_message *message); + /*! @} */ /*! @{ */ @@ -1020,6 +1049,7 @@ void stasis_log_bad_type_access(const char *name); * STASIS_MESSAGE_TYPE_DEFN(ast_foo_type, * .to_ami = foo_to_ami, * .to_json = foo_to_json, + * .to_event = foo_to_event, * ); * \endcode * @@ -1046,6 +1076,7 @@ void stasis_log_bad_type_access(const char *name); * STASIS_MESSAGE_TYPE_DEFN_LOCAL(ast_foo_type, * .to_ami = foo_to_ami, * .to_json = foo_to_json, + * .to_event = foo_to_event, * ); * \endcode * |