Class: Events

Events()

https://www.onvif.org/ver10/events/wsdl/event.wsdl
https://www.onvif.org/wp-content/uploads/2017/07/ONVIF_Event_Handling_Test_Specification_v17.06.pdf

Functions

createPullPointSubscription, Events#getEventProperties, Events#getServiceCapabilities, pullMessages, seek, Events#setSynchronizationPoint

Overview

An event is an action or occurrence detected by a device that a client can subscribe to.
Events are handled through the event service. This specification defines event handling based on the [WS-BaseNotification] and [WS-Topics] specifications. It extends the event notion to allow clients to track object properties (such as digital input and motion alarm properties) through events. Properties are defined in Section 9.4.
The description of event payload and their filtering within subscriptions is discussed in section 9.5. Section 9.6 describes how a synchronization point can be requested by clients using one of the three notification interfaces. Section 9.7 describes the integration of Topics and section 9.10 discusses the handling of faults.
Section 9.11 demonstrates the usage of the Real-Time Pull-Point Notification Interface including Message Filtering and Topic Set. Examples for the basic notification interface can be found in the corresponding [WS-BaseNotification] specification.
An ONVIF compliant device shall provide an event service as defined in [ONVIF Event WSDL].
Both device and client shall support [WS-Addressing] for event services.

Push Events

  • -> GetEventProperties
  • <- GetEventPropertiesResponse
  • -> Subscribe (specifying URI of your server)
  • <- Notify
  • -> Renew (specifying termination time)
  • <- RenewResponse
  • -> Unsubscribe
  • <- UnsubscribeResponse

Pull Events

  • -> GetEventProperties
  • <- GetEventPropertiesResponse
  • -> CreatePullPointSubscription
  • <- CreatePullPointSubscriptionResponse
  • -> PullMessages
  • -> PullMessagesResponse
  • -> Renew (specifying termination time)
  • <- RenewResponse
  • -> Unsubscribe
  • <- UnsubscribeResponse

Constructor

new Events()

Source:

Methods

createPullPointSubscription(filteropt, initialTerminationTimeopt, subscriptionPolicyopt, callbackopt)

Event Type: Pull Event
This method returns a PullPointSubscription that can be polled using PullMessages. This message contains the same elements as the SubscriptionRequest of the WS-BaseNotification without the ConsumerReference.
If no Filter is specified the pullpoint notifies all occurring events to the client.
This method is mandatory.
Parameters:
Name Type Attributes Description
filter string <optional>
 Optional XPATH expression to select specific topics.
initialTerminationTime integer <optional>
 Optional Initial termination time (in milliseconds)
subscriptionPolicy xml <optional>
 Optional Refer to Web Services Base Notification 1.3 (WS-BaseNotification).
callback callback <optional>
 Optional callback, instead of a Promise.
Source:

createRequest(body, subscriptionIdopt)

Private function for creating a SOAP request.
Parameters:
Name Type Attributes Description
body string The body of the xml.
subscriptionId object <optional>
 Used internally.
Source:

getEventProperties(callbackopt)

Event Type: Agnostic
The WS-BaseNotification specification defines a set of OPTIONAL WS-ResouceProperties. This specification does not require the implementation of the WS-ResourceProperty interface. Instead, the subsequent direct interface shall be implemented by an ONVIF compliant device in order to provide information about the FilterDialects, Schema files and topics supported by the device.
Parameters:
Name Type Attributes Description
callback callback <optional>
 Optional callback, instead of a Promise.
Source:

getServiceCapabilities(callbackopt)

Event Type: Agnostic
Returns the capabilities of the event service. The result is returned in a typed answer.
Parameters:
Name Type Attributes Description
callback callback <optional>
 Optional callback, instead of a Promise.
Source:

init(timeDiff, serviceAddress, usernameopt, passwordopt)

Call this function directly after instantiating an Events object.
Parameters:
Name Type Attributes Description
timeDiff number The onvif device's time difference.
serviceAddress object An url object from url package - require('url').
username string <optional>
 Optional only if the device does NOT have a user.
password string <optional>
 Optional only if the device does NOT have a password.
Source:

pullMessages(subscriptionId, timeout, messageLimit, callbackopt)

Event Type: Pull Event
This method pulls one or more messages from a PullPoint. The device shall provide the following PullMessages command for all SubscriptionManager endpoints returned by the CreatePullPointSubscription command. This method shall not wait until the requested number of messages is available but return as soon as at least one message is available.
The command shall at least support a Timeout of one minute. In case a device supports retrieval of less messages than requested it shall return these without generating a fault.
Parameters:
Name Type Attributes Description
subscriptionId object An object after createPullPointSubscription is called.
Properties
Name Type Description
Address object Address from createPullPointSubscription is called.
Properties
Name Type Description
_ object Raw subscriptionId from createPullPointSubscription.
$ object Raw subscriptionId from createPullPointSubscription.
timeout integer [msec] Maximum time to block until this method returns.
messageLimit integer Upper limit for the number of messages to return at once. A server implementation may decide to return less messages.
callback callback <optional>
 Optional callback, instead of a Promise.
Source:

renew(callbackopt)

Event Type: Agnostic
Parameters:
Name Type Attributes Description
callback callback <optional>
 Optional callback, instead of a Promise.
Source:

seek(utcTime, reverseopt, callbackopt)

Not implemented Event Type: Pull Event
This method readjusts the pull pointer into the past. A device supporting persistent notification storage shall provide the following Seek command for all SubscriptionManager endpoints returned by the CreatePullPointSubscription command. The optional Reverse argument can be used to reverse the pull direction of the PullMessages command.
The UtcTime argument will be matched against the UtcTime attribute on a NotificationMessage.
Parameters:
Name Type Attributes Description
utcTime string The date and time to match against stored messages.
reverse boolean <optional>
 Reverse the pull direction of PullMessages.
callback callback <optional>
 Optional callback, instead of a Promise.
Source:

setSynchronizationPoint(callbackopt)

Event Type: Agnostic
Properties inform a client about property creation, changes and deletion in a uniform way. When a client wants to synchronize its properties with the properties of the device, it can request a synchronization point which repeats the current status of all properties to which a client has subscribed. The PropertyOperation of all produced notifications is set to “Initialized”. The Synchronization Point is requested directly from the SubscriptionManager which was returned in either the SubscriptionResponse or in the CreatePullPointSubscriptionResponse. The property update is transmitted via the notification transportation of the notification interface. This method is mandatory.
Parameters:
Name Type Attributes Description
callback callback <optional>
 Optional callback, instead of a Promise.
Source:

startPull(loopTimeMSopt, timeoutopt, messageLimitopt)

Start a PullMessages event loop
This method does a createPullPointSubscription followed by a pullMessages. The resulting xml from the camera is then sent via an emit('messages', data). On error, emit('messages:error', error)
Parameters:
Name Type Attributes Description
loopTimeMS integer <optional>
 The amount of time between polls (in milliseconds; default 10000).
timeout string <optional>
 The timeout to send to the server (using PT interval format - ex: PT1S is one second; default 'PT1M').
messageLimit integer <optional>
 The message limit to retrive (default 1)
Source:
Example
camera.events.on('messages', messages => {
  console.log('Messages Received:', messages)
})

 camera.events.on('messages:error', error => {
   console.error('Messages Error:', error)
 })

 camera.events.startPull()

stopPull()

Stops a PullMessages event loop that has been started with start().
Source:

subscribe(callbackopt)

Event Type: Push Event
The device shall provide the following Unsubscribe command for all SubscriptionManager endpoints returned by the CreatePullPointSubscription command.
This command shall terminate the lifetime of a pull point.
Parameters:
Name Type Attributes Description
callback callback <optional>
 Optional callback, instead of a Promise.
Source:

unsubscribe(callbackopt)

Event Type: Agnostic
The device shall provide the following Unsubscribe command for all SubscriptionManager endpoints returned by the CreatePullPointSubscription command.
This command shall terminate the lifetime of a pull point.
Parameters:
Name Type Attributes Description
callback callback <optional>
 Optional callback, instead of a Promise.
Source: