Raritan / Server Technology Xerus™ PDU JSON-RPC API: EventService.idl Source File

Raritan / Server Technology Xerus™ PDU JSON-RPC API

EventService.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3 * Copyright 2011 Raritan Inc. All rights reserved.
4 */
5
6 #ifndef __EVENT_SERVICE_IDL__
7 #define __EVENT_SERVICE_IDL__
8
9 #include<Event.idl>
10
11 /** Event interface */
12 module event {
13
14 /// @cond
15 /**
16 * Consumer interface is for event consumers that want to be
17 * called back in case new events have occured. Subscription
18 * with this interface happens in Channel interface.
19 * Note that this interface cannot be used over transports that
20 * do not support callbacks.
21 *
22 * Not available via JSON-RPC.
23 */
24 interface Consumer {
25
26 /**
27 * This method is called by EventService to notify Consumer
28 * about new events. Consumer is not supposed to block this
29 * function but return immidiately. Policy of how often and
30 * with how many events this method is called is up to the
31 * EventService Implementation.
32 */
33 void pushEvents(in vector<idl.Event> events);
34
35 };
36 /// @endcond
37
38 /** Event Channel */
39 interface Channel {
40
41 /* --- filter interface --- */
42
43 /**
44 * Subscribe for events of a given type.
45 *
46 * @param evttype typecode of valueobject of demanded event
47 */
48 void demandEventType(in typecode type);
49
50 /**
51 * Cancel the subscription for events of a given type.
52 *
53 * @param evttype typecode of valueobject of demanded event
54 */
55 void cancelEventType(in typecode type);
56
57 /**
58 * Subscribe for multiple event types at once.
59 *
60 * @param evttypes List of event typecodes
61 */
62 void demandEventTypes(in vector<typecode> types);
63
64 /**
65 * Cancel subscription for events that are of any of given types.
66 *
67 * @param evttypes List of event typecodes
68 */
69 void cancelEventTypes(in vector<typecode> types);
70
71 /**
72 * Subscribe for events that are of given type and emitted by a
73 * specific object instance.
74 *
75 * @param evttype %Event typecode
76 * @param src %Event source instance
77 */
78 void demandEvent(in typecode type, in Object src);
79
80 /**
81 * Cancel the subscription for events that are of given type and
82 * emitted by a specific object instance.
83 *
84 * @param evttype %Event typecode
85 * @param src %Event source instance
86 */
87 void cancelEvent(in typecode type, in Object src);
88
89 /**
90 * Structure to select an Event *
91 */
92 structure EventSelect {
93 typecode type;
94 Object src;
95 };
96
97 /**
98 * Subscribe for multiple specific events at once.
99 *
100 * @param events List of typecodes to subscribe for
101 */
102 void demandEvents(in vector<EventSelect> events);
103
104 /**
105 * Cancel the subscription for multiple specific events.
106 *
107 * @param events List of typecodes to unsubscribe from
108 */
109 void cancelEvents(in vector<EventSelect> events);
110
111
112 /// @cond
113 /* --- push interface --- */
114
115 /**
116 * Subsribe for push notifications from EventService.
117 *
118 * Not available via JSON-RPC.
119 *
120 * @param consumer interface on which subscriber is called back.
121 */
122 void subscribe(in Consumer consumer);
123
124 /**
125 * Unsubscribe from push notifications from EventService.
126 *
127 * Not available via JSON-RPC.
128 *
129 * @param consumer interface which was used for the subscription.
130 * @return 0 if OK
131 * 1 if consumer is unknown to channel
132 */
133 int unsubscribe(in Consumer consumer);
134 /// @endcond
135
136
137 /* --- poll interface --- */
138
139 /**
140 * Poll for new events blockingly.
141 *
142 * This method will block in case the queue is empty. It will return
143 * as soon as at least one event is available, or after a maximum
144 * wait time of 30 seconds.
145 *
146 * The method will not return more than an implementation-defined
147 * maximum number of events. The boolean return value indicates
148 * whether there are more events in the queue.
149 *
150 * @param events List of new events
151 * @return \c true if there are more events in the queue
152 * \c false if the queue is empty
153 */
154 boolean pollEvents(out vector<idl.Event> events);
155
156 /**
157 * Poll for new events non-blockingly.
158 *
159 * The method will not return more than an implementation-defined
160 * maximum number of events. The boolean return value indicates
161 * whether there are more events in the queue.
162 *
163 * @param events List of new events
164 * @return \c true if there are more events in the queue
165 * \c false if the queue is empty
166 */
167 boolean pollEventsNb(out vector<idl.Event> events);
168
169 };
170
171 /** Event Service */
172 interface Service {
173
174 constant int INVALID_CHANNEL = 1;
175
176 /**
177 * Create a new event channel.
178 *
179 * @return New event channel reference
180 * or nil if all channels have been used
181 */
182 Channel createChannel();
183
184 /**
185 * Destroy an event channel.
186 *
187 * @param channel %Event channel reference
188 * @return 0 if OK
189 * @return INVALID_CHANNEL if channel is not implemented by this Service
190 */
191 int destroyChannel(in Channel channel);
192
193 /**
194 * Push an Event into the service and to all existing
195 * receiver channels
196 */
197 void pushEvent(in idl.Event event);
198
199 /**
200 * Push a vector of Events into the service and to all existing
201 * receiver channels
202 */
203 void pushEvents(in vector<idl.Event> events);
204
205 };
206
207 }
208
209 #endif
event::Channel
Event Channel.
Definition: EventService.idl:39
event::Channel::demandEvent
void demandEvent(in typecode type, in Object src)
Subscribe for events that are of given type and emitted by a specific object instance.
event::Channel::demandEventTypes
void demandEventTypes(in vector< typecode > types)
Subscribe for multiple event types at once.
event::Channel::pollEventsNb
boolean pollEventsNb(out vector< idl::Event > events)
Poll for new events non-blockingly.
event::Channel::cancelEventTypes
void cancelEventTypes(in vector< typecode > types)
Cancel subscription for events that are of any of given types.
event::Channel::cancelEventType
void cancelEventType(in typecode type)
Cancel the subscription for events of a given type.
event::Channel::demandEventType
void demandEventType(in typecode type)
Subscribe for events of a given type.
event::Channel::pollEvents
boolean pollEvents(out vector< idl::Event > events)
Poll for new events blockingly.
event::Channel::demandEvents
void demandEvents(in vector< EventSelect > events)
Subscribe for multiple specific events at once.
event::Channel::cancelEvents
void cancelEvents(in vector< EventSelect > events)
Cancel the subscription for multiple specific events.
event::Channel::cancelEvent
void cancelEvent(in typecode type, in Object src)
Cancel the subscription for events that are of given type and emitted by a specific object instance.
event::Service
Event Service.
Definition: EventService.idl:172
event::Service::createChannel
Channel createChannel()
Create a new event channel.
event::Service::pushEvents
void pushEvents(in vector< idl::Event > events)
Push a vector of Events into the service and to all existing receiver channels.
event::Service::destroyChannel
int destroyChannel(in Channel channel)
Destroy an event channel.
event::Service::pushEvent
void pushEvent(in idl::Event event)
Push an Event into the service and to all existing receiver channels.
event
Event interface.
Definition: AlarmManager.idl:12
idl
Basic IDL definitions.
Definition: Event.idl:10
event::Channel::EventSelect
Structure to select an Event *.
Definition: EventService.idl:92
idl::Event
Common base for all events.
Definition: Event.idl:13