Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

Loading...
Searching...
No Matches
Event Service

A large number of IDL-defined interfaces define events to notify client applications about changed data (port status, updated settings, etc.). Changes are pushed from the server to the client without need for frequent polling. This allows to write client applications that respond quickly to changes; for instance the web GUI makes heavy use of this feature.

Note
  This section is not about configuring event rules and actions! See Event Rules and Actions instead.

# Push Mechanism

The event service uses a so-called long polling technique to emulate a push mechanism. Clients invoke the pollEvents() method to get new events. The server delays the handling of this request for up to 30 seconds as long as no new events are available. The request is immediately completed as soon as events become available, allowing the client to respond without delay.

Long polling is particularly useful for applications that support handling multiple requests in parallel, either by using asynchronous response handling or multithreading. If this is not possible, clients can use the non-blocking variant pollEventsNb(), which returns immediately even when no events are available. The client must call this method frequently to get new events, which is still better than individually polling a large number of objects.

# Programming Model

Events are distributed by the event.Service instance at `/eventservice`. Clients need to register an event channel, which is their own server-side queue for pending events. Event channels must be actively used to be kept alive. Event channels that are not accessed for 30 seconds are destroyed to reclaim server memory.

After registering an event channel, the client uses the demandEvent and cancelEvent family of methods to configure a filter for events they are interested in. Events can be selected based on type (e.g. KVM device temperature change) and/or originating object (e.g. the KVM device). Subscriptions can be added and removed at any time as long as the event channel is alive.

Finally, the client repeatedly calls the pollEvents method to get new events. The request completes as soon as new events become available that match one of the client's subscriptions, or after a maximum wait time of 30 seconds.

# Event Definitions

Supported events and their contained data fields are defined in IDL as a hierarchy of `valueobject` declaration. The root event type is `idl.Event`, all other events are derived from that type.

All events have a source data field that contains a reference to the object originating the event. E.g., the source of an KvmPort.SettingsChangedEvent is the port whose settings have changed. Most events declare additional data fields, in this case the old and new port settings.

Subscriptions for a base event type include derived types. For instance, each of the AccountAdded, AccountRenamed and AccountRemoved events in the UserManager interface extend the base AccountEvent. A client subscribing for this base event will receive add, rename and remove events.

# Python example: Blocking event poll
import xeruskvm.rpc.event
import xeruskvm.rpc.usermgmt
event_service = xeruskvm.rpc.event.Service("/eventservice", agent)
# Register an event channel
channel = event_service.createChannel()
# Subscribe for any updates to user accounts
channel.demandEventType(xeruskvm.rpc.usermgmt.AccountEvent)
# Poll for events until interrupted
print("Polling for events, Ctrl-C to stop ...")
try:
while True:
result, events = channel.pollEvents()
for event in events:
print(event)
except KeyboardInterrupt:
print("\n")