Events and State subscription

Introduction

Events and state subscriptions are based on a WebSocket API where applications can subscribe to specific events and state.

What it is used for

An events and state session allows an application to receive events from an XProtect system on a persistent connection. The application can granularly specify which events are of interest and use stateful events to keep track state.

The same session can also be used to retrieve state on-demand.

If the connection is interrupted, events will be cached on the server and can be retrieved if the client reconnects within a timeout (default: 30 seconds).

Classes

Functionality

Event receiver

Implement the IEventReceiver interface to be able to receive events and state.

This interfaces will deliver events on the OnEventsReceivedAsync method.

The interface also delivers the state of the underlying connection to the XProtect system on the OnConnectionStateChangedAsync method.

Creating a session with an even receiver

The static class EventsAndStateSession has a factory method to create a session for receiving events and state. Calling the create method and passing the login settings (see Component environments for login) and an event receiver, will create a session defined by the interface IEventsAndStateSession.

The IEventsAndStateSession interface is where an application can add/remove subscriptions and get the current state.

Defining subscription rules for a session

Subscription rules specify which events should be received in a session.

When defining a SubscriptionRule, it is possible to specify either specific types/ids that should be matched or indicate that all types/ids should be matched.

Available event types, states and event source(s) can be looked up using the RESTful Configuration API

Subscription rules can be added to an IEventsAndStateSession using the AddSubscriptionAsync method, which returns a subscription id. The subscription id can be used to remove the subscription again.

Subscription properties

NOTE:
An event must match all specifiers to be covered by a rule.

Relation between a session, subscription rules and modifiers

• A session must be established before any subscriptions can be created.
• A subscription may contain multiple subscription rules.
• Include and Exclude controls whether the events specified in the subscription rule are included or excluded.
• Exclude modifiers have higher priority than include modifiers - i.e., if an event is excluded by any subscription rule, it cannot be included by another subscription rule in the same subscription.
• A client can create multiple subscriptions.
• Individual subscriptions do not affect each other - i.e., events matching any subscription will be received, and events included in one subscription cannot be excluded by another subscription.
• An event that is included in multiple subscriptions will only be sent to the client once.

Remove a subscription

Remove a previously created subscription specified by the subscription id.

Getting events

Events are received in the OnEventsReceivedAsync method of the IEventReceiver implementation.

Getting state

An application can get the current state satisfying the subscription by calling GetCurrentStateAsync. Alternatively, the application can request all stateful events by calling SendAllStatefulEventsAsync. Stateful events will then be received in the OnEventsReceivedAsync method of the IEventReceiver implementation.

This can be useful to retrieve the initial state after one or more subscriptions have been made.

Connection state

Changes in the state of the underlying connection are received in the OnConnectionStateChangedAsync method of the IEventReceiver implementation. See VideoOS.Platform.EventsAndState.ConnectionState for the possible connection states and their meanings.

If disconnected, the connection will automatically be reestablished and the session resumed.

If the session is successfully resumed, then all missed events will be retrieved. If the session cannot be resumed (e.g. if the 30 second timeout has expired), a new session will be created with the previously defined subscriptions. If SendStatefulEventsOnReconnect is set on the IEventsAndStateSession (default is true), then the current state will automatically be be received as stateful events in OnEventsReceivedAsync.

Sample code

async Task SampleAsync()
{
    var loginSettings = LoginSettingsCache.GetLoginSettings(EnvironmentManager.Instance.MasterSite);

    // Create event receiver and session
    var eventReceiver = new EventReceiver();
    var session = EventsAndStateSession.Create(loginSettings, eventReceiver);

    // Add subscription
    var subscription = new[]
        {
            new SubscriptionRule(
                Modifier.Include,
                new ResourceTypes(new[]{ "cameras" }),
                SourceIds.Any,
                new EventTypes(new[]{ KnownStatusEvents.CommunicationStarted, KnownStatusEvents.CommunicationStopped }))
        };
    await session.AddSubscriptionAsync(subscription, default);

    // Send initial state as events, if needed
    await _session.SendAllStatefulEventsAsync(default);

    // Run application / Wait for shutdown
    // Call _session.Dispose() to stop receiving events and close the underlying connection
}

class EventReceiver : IEventReceiver
{
    public async Task OnConnectionStateChangedAsync(ConnectionState newState)
    {
        // Handle connection state change
    }

    public async Task OnEventsReceivedAsync(IEnumerable<Event> events)
    {
        // Handle events
    }
}

Sample

• Event and state viewer Sample

See also

• API Gateway - RESTful APIs General documentation about the API Gateway.
• MIP VMS API Getting started How to obtain and use an OAuth bearer token.