streamEvents

This command opens a connection for streaming live events to the client.

Note: This function requires an API license.

When an event occurs in the system, it will be send (pushed) to the client. The system keeps pushing events until the connection is closed or another request is send over the current connection. The events are send as part of a multipart HTTP stream. All arguments are optional and can be used to filter the kind of event.The parameters deviceid and serverid can be used to get events from a specific device (from a specific server). The types parameter is a semicolon (;) seperated list of event types that should be included in the results. If this parameter is present, only events of matching types are included in the results. All other event types are excluded.

Event types are not grouped, as used in the command getEvents. Instead, every event type of an event that occured should match partially one (or more) of the event types of the supplied parameter before it is send to the client. Partially means that if i.e. types ‘alarm,motion’ are requested, all events with the text ‘alarm’ or ‘motion’ somewhere in the event type of the event that occured will be send to the client. In this example events with the following event types will be send: ‘AlarmTrigger1’, ‘AlarmTrigger2’, ‘AlarmTrigger3’, ‘USBAlarmInput’, ‘USBAlarmInputLow’, ‘Motion’ and so on. By using the same event types as described in the chapter Event Types the same kind of grouping can be made as is used in the command getEvents. See also ‘Event result values’ in this chapter for a list of event types that can occur.

This command will return immediately with a multipart/x-mixed-replace content type and specific boundary. When an event occures, it will be send as xml message as denoted below, together with the boundary indicating the end of the multipart. If another request is send from the client, the ending boundary will be send.

Request

command=streamEvents&types=[string]&deviceid=[uid]&serverid=[uid]
parameter type remarks
types [string] semicolon (;) separated list of event types that should be included in the results. All other types are excluded.
deviceid [uid] filters events from a specific device.
serverid [uid] filters events from a specific server.

Response

<event>
  <id>[uid]</id>
  <name>[string]</name>
  <value>[string]</value>
  <time>[timestamp]</time>
  <serverid>[uid]</serverid>
  <deviceid>[uid]</deviceid>
 </event>
node value remarks
/event
id [uid] id of event.
name [string] name of event. (API version 2.7.1+)
type [string] type of event. (<= API version 2.6.1)
value [string] value of event.
time [timestamp] Time stamp of event in UTC time.
serverid [uid] Id of server where the event occurred.
deviceid [uid] Id of device which triggered the event, could be ommited or zero if it wasn't a device related event (i.e. SystemEvent).
error code description remarks
0 Ok Ok, no error
-18 General error An undefined error occured

See Also

Changelog

  • 2.7.1 – Replaced <type> tag with <name>
  • 2.3.1 – Added