I have been consulting Milestone Development and can share the following answer.
--
Authentication:
Please note that although the documentation implies so the ‘Authenticate’ command is not yet supported.
The token provided is only validated when the connection is established, and thus the connection will not be interrupted because the token expires.
The connection will however most likely be interrupted eventually due to other reasons, so the connection will not be kept indefinite. E.g. the API gateway is by default recycled every 27 hours, which will cause a disconnect, and require a new connection with a new token.
It is not possible to provide a new token to an existing connection.
Content of data:
The content of the data depends on the event type, and there are quite some variants..
There are some event types that has a fixed format, where the most common are
Analytics Events and Access Control Events
The structures are not yet documented properly but they are the following structures serialized as json:
public class AnalyticsData: AnalyticsDataWithoutSnapshots
{
/// <summary>
/// Images related to the analytics event.
/// If the <see cref="EventsAndState.State.Source"/> is a camera and recording is enabled, it is not necessary to attach a snapshot from that camera at the time of the analytics event.
/// </summary>
public virtual AnalyticsSnapshot[] Snapshots { get; set; }
}
public class AnalyticsDataWithoutSnapshots
{
/// <summary>
/// The description of the analytics event.
/// </summary>
public virtual string Description { get; set; }
/// <summary>
/// The start time of the analytics event, if it takes place over a period of time.
/// </summary>
public virtual DateTime? StartTime { get; set; }
/// <summary>
/// The end time of the analytics event, if it takes place over a period of time.
/// </summary>
public virtual DateTime? EndTime { get; set; }
/// <summary>
/// The location of the analytics event (this will typically be the same as the camera's location).
/// </summary>
public virtual string Location { get; set; }
/// <summary>
/// The count value, if the analytics event contains a counting value. Default is 0 (no count).
/// </summary>
public virtual uint Count { get; set; }
/// <summary>
/// Information about the rule(s) that triggered the analytics event.
/// </summary>
public virtual AnalyticsRule[] Rules { get; set; }
/// <summary>
/// The detected object(s) in the scene.
/// </summary>
public virtual AnalyticsObject[] Objects { get; set; }
/// <summary>
/// Array of references to other entities in the system, e.g. cameras.
/// Every entry must be set to a valid REST resource string.
/// E.g. if the entity is a camera the format will be `cameras/{id}` or simply `{id}`
/// </summary>
/// <example>[ "cameras/e028f597-c64b-4f27-bb8d-08f5cd768e1c", "cameras/cd865c62-4962-4861-b109-5f4f1172f09e" ]</example>
public virtual string[] References { get; set; }
/// <summary>
/// The analytics vendor including any custom data.
/// </summary>
public virtual AnalyticsVendor Vendor { get; set; }
}
/// <summary>
/// Data of an access control event.
/// </summary>
public class AccessControlData
{
/// <summary>
/// The ID of the access control system.
/// </summary>
public Guid? System { get; set; }
/// <summary>
/// The event ID in the access control system.
/// </summary>
public string Id { get; set; }
/// <summary>
/// The ID of the event type in the access control system.
/// </summary>
public Guid? EventType { get; set; }
/// <summary>
/// The ID of the source in the access control system.
/// </summary>
public Guid? Source { get; set; }
/// <summary>
/// The ID of the source type in the access control system.
/// </summary>
public Guid? SourceType { get; set; }
/// <summary>
/// ID's of the related access control credential holders.
/// </summary>
public string[] CredentialHolders { get; set; }
/// <summary>
/// ID's of the related access control elements.
/// </summary>
public Guid[] Elements { get; set; }
/// <summary>
/// ID's of the event categories.
/// </summary>
public Guid[] Categories { get; set; }
/// <summary>
/// List of the related surveillance items.
/// Every entry must be set to a valid REST resource string.
/// If the source device is camera the format will be `cameras/{id}` or simply `{id}`
/// </summary>
/// <example>cameras/e028f597-c64b-4f27-bb8d-08f5cd768e1c</example>
public string[] SurveillanceItems { get; set; }
/// <summary>
/// Reason of the event.
/// </summary>
public string Reason { get; set; }
/// <summary>
/// Additional access control properties.
/// </summary>
public Dictionary<string, string> Properties { get; set; }
}
For other event types, the format may differ. In that case, the best (only) option is to make the ‘interesting’ event happen and capture the data received.
