Merge some more changes from team/russell/events
[asterisk/asterisk.git] / include / asterisk / event_defs.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007 - 2008, Digium, Inc.
5  *
6  * Russell Bryant <russell@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20  * \file
21  * \author Russell Bryant <russell@digium.com>
22  * \brief Generic event system
23  */
24
25 #ifndef AST_EVENT_DEFS_H
26 #define AST_EVENT_DEFS_H
27
28 /*! \brief Event types
29  * \note These values can *never* change. */
30 enum ast_event_type {
31         /*! Reserved to provide the ability to subscribe to all events.  A specific
32          *  event should never have a payload of 0. */
33         AST_EVENT_ALL                 = 0x00,
34         /*! This event type is reserved for use by third-party modules to create
35          *  custom events without having to modify this file. 
36          *  \note There are no "custom" IE types, because IEs only have to be
37          *  unique to the event itself, not necessarily across all events. */
38         AST_EVENT_CUSTOM              = 0x01,
39         /*! Voicemail message waiting indication */
40         AST_EVENT_MWI                 = 0x02,
41         /*! Someone has subscribed to events */
42         AST_EVENT_SUB                 = 0x03,
43         /*! Someone has unsubscribed from events */
44         AST_EVENT_UNSUB               = 0x04,
45         /*! The aggregate state of a device across all servers configured to be
46          *  a part of a device state cluster has changed. */
47         AST_EVENT_DEVICE_STATE        = 0x05,
48         /*! The state of a device has changed on _one_ server.  This should not be used
49          *  directly, in general.  Use AST_EVENT_DEVICE_STATE instead. */
50         AST_EVENT_DEVICE_STATE_CHANGE = 0x06,
51         /*! Number of event types.  This should be the last event type + 1 */
52         AST_EVENT_TOTAL               = 0x07,
53 };
54
55 /*! \brief Event Information Element types */
56 enum ast_event_ie_type {
57         /*! Used to terminate the arguments to event functions */
58         AST_EVENT_IE_END       = -1,
59
60         /*! 
61          * \brief Number of new messages
62          * Used by: AST_EVENT_MWI 
63          * Payload type: UINT
64          */
65         AST_EVENT_IE_NEWMSGS   = 0x01,
66         /*! 
67          * \brief Number of
68          * Used by: AST_EVENT_MWI 
69          * Payload type: UINT
70          */
71         AST_EVENT_IE_OLDMSGS   = 0x02,
72         /*! 
73          * \brief Mailbox name \verbatim (mailbox[@context]) \endverbatim
74          * Used by: AST_EVENT_MWI 
75          * Payload type: STR
76          */
77         AST_EVENT_IE_MAILBOX   = 0x03,
78         /*! 
79          * \brief Unique ID
80          * Used by: AST_EVENT_SUB, AST_EVENT_UNSUB
81          * Payload type: UINT
82          */
83         AST_EVENT_IE_UNIQUEID  = 0x04,
84         /*! 
85          * \brief Event type 
86          * Used by: AST_EVENT_SUB, AST_EVENT_UNSUB
87          * Payload type: UINT
88          */
89         AST_EVENT_IE_EVENTTYPE = 0x05,
90         /*!
91          * \brief Hint that someone cares that an IE exists
92          * Used by: AST_EVENT_SUB
93          * Payload type: UINT (ast_event_ie_type)
94          */
95         AST_EVENT_IE_EXISTS    = 0x06,
96         /*!
97          * \brief Device Name
98          * Used by AST_EVENT_DEVICE_STATE_CHANGE
99          * Payload type: STR
100          */
101         AST_EVENT_IE_DEVICE    = 0x07,
102         /*!
103          * \brief Generic State IE
104          * Used by AST_EVENT_DEVICE_STATE_CHANGE
105          * Payload type: UINT
106          * The actual state values depend on the event which
107          * this IE is a part of.
108          */
109          AST_EVENT_IE_STATE    = 0x08,
110          /*!
111           * \brief Context IE
112           * Used by AST_EVENT_MWI
113           * Payload type: str
114           */
115          AST_EVENT_IE_CONTEXT  = 0x09,
116          /*!
117           * \brief Entity ID
118           * Used by All events
119           * Payload type: RAW
120           * This IE indicates which server the event originated from
121           */
122          AST_EVENT_IE_EID      = 0x0A,
123 };
124
125 #define AST_EVENT_IE_MAX AST_EVENT_IE_EID
126
127 /*!
128  * \brief Payload types for event information elements
129  */
130 enum ast_event_ie_pltype {
131         AST_EVENT_IE_PLTYPE_UNKNOWN = -1,
132         /*! Just check if it exists, not the value */
133         AST_EVENT_IE_PLTYPE_EXISTS,
134         /*! Unsigned Integer (Can be used for signed, too ...) */
135         AST_EVENT_IE_PLTYPE_UINT,
136         /*! String */
137         AST_EVENT_IE_PLTYPE_STR,
138         /*! Raw data, compared with memcmp */
139         AST_EVENT_IE_PLTYPE_RAW,
140 };
141
142 /*!
143  * \brief Results for checking for subscribers
144  *
145  * \ref ast_event_check_subscriber()
146  */
147 enum ast_event_subscriber_res {
148         /*! No subscribers exist */
149         AST_EVENT_SUB_NONE,
150         /*! At least one subscriber exists */
151         AST_EVENT_SUB_EXISTS,
152 };
153
154 struct ast_event;
155 struct ast_event_ie;
156 struct ast_event_sub;
157 struct ast_event_iterator;
158
159 /*!
160  * \brief supposed to be an opaque type
161  *
162  * This is only here so that it can be declared on the stack.
163  */
164 struct ast_event_iterator {
165         uint16_t event_len;
166         const struct ast_event *event;
167         struct ast_event_ie *ie;
168 };
169
170 #endif /* AST_EVENT_DEFS_H */