Joseph Doherty
82 lines
4.7 KiB
C#
82 lines
4.7 KiB
C#
namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
|
|
|
/// <summary>
|
|
/// Driver capability for data-change subscriptions — covers both native subscriptions
|
|
/// (Galaxy MXAccess advisory, OPC UA monitored items, TwinCAT ADS notifications) and
|
|
/// driver-internal polled subscriptions (Modbus, AB CIP, S7, FOCAS). The driver owns
|
|
/// its polling loop where applicable; the Core just sees <see cref="OnDataChange"/>
|
|
/// callbacks regardless of mechanism.
|
|
/// </summary>
|
|
public interface ISubscribable
|
|
{
|
|
/// <summary>
|
|
/// Subscribe to data changes for a batch of attributes.
|
|
/// The driver MAY fire <see cref="OnDataChange"/> immediately with the current value
|
|
/// (initial-data callback per OPC UA convention) and again on every change.
|
|
/// </summary>
|
|
/// <param name="fullReferences">The full references of the attributes to subscribe to.</param>
|
|
/// <param name="publishingInterval">The desired interval at which to receive data change notifications.</param>
|
|
/// <param name="cancellationToken">A cancellation token to observe for cancellation.</param>
|
|
/// <returns>An opaque subscription handle the caller passes to <see cref="UnsubscribeAsync"/>.</returns>
|
|
Task<ISubscriptionHandle> SubscribeAsync(
|
|
IReadOnlyList<string> fullReferences,
|
|
TimeSpan publishingInterval,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>Cancel a subscription returned by <see cref="SubscribeAsync"/>.</summary>
|
|
/// <param name="handle">The subscription handle to cancel.</param>
|
|
/// <param name="cancellationToken">A cancellation token to observe for cancellation.</param>
|
|
/// <returns>A task representing the asynchronous unsubscribe operation.</returns>
|
|
Task UnsubscribeAsync(ISubscriptionHandle handle, CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Server-pushed data-change notification. Fires whenever a subscribed attribute changes,
|
|
/// and (per OPC UA convention) on subscription establishment for current values.
|
|
/// </summary>
|
|
event EventHandler<DataChangeEventArgs>? OnDataChange;
|
|
}
|
|
|
|
/// <summary>Opaque subscription identity returned by <see cref="ISubscribable.SubscribeAsync"/>.</summary>
|
|
public interface ISubscriptionHandle
|
|
{
|
|
/// <summary>Driver-internal subscription identifier (for diagnostics + post-mortem).</summary>
|
|
string DiagnosticId { get; }
|
|
}
|
|
|
|
/// <summary>Event payload for <see cref="ISubscribable.OnDataChange"/>.</summary>
|
|
/// <param name="SubscriptionHandle">The handle returned by the original <see cref="ISubscribable.SubscribeAsync"/> call.</param>
|
|
/// <param name="FullReference">Driver-side full reference of the changed attribute.</param>
|
|
/// <param name="Snapshot">New value + quality + timestamps.</param>
|
|
public sealed record DataChangeEventArgs(
|
|
ISubscriptionHandle SubscriptionHandle,
|
|
string FullReference,
|
|
DataValueSnapshot Snapshot);
|
|
|
|
/// <summary>One changed attribute within a <see cref="DataChangeBatchEventArgs"/>.</summary>
|
|
/// <param name="FullReference">Driver-side full reference of the changed attribute.</param>
|
|
/// <param name="Snapshot">New value + quality + timestamps.</param>
|
|
public sealed record DataChangeItem(string FullReference, DataValueSnapshot Snapshot);
|
|
|
|
/// <summary>Event payload for <see cref="IBatchSubscribable.OnDataChangeBatch"/> — every attribute
|
|
/// that changed within ONE production burst (a poll cycle, an inbound message, a stream chunk).</summary>
|
|
/// <param name="SubscriptionHandle">The handle returned by the original <see cref="ISubscribable.SubscribeAsync"/> call.</param>
|
|
/// <param name="Items">The changed attributes, one entry per changed tag. Never empty. Ownership transfers
|
|
/// to the consumer, which may retain the list past the raise (it is marshalled onto another thread) — so the
|
|
/// driver MUST NOT mutate or reuse the list instance after raising; allocate a fresh one per burst.</param>
|
|
public sealed record DataChangeBatchEventArgs(
|
|
ISubscriptionHandle SubscriptionHandle,
|
|
IReadOnlyList<DataChangeItem> Items);
|
|
|
|
/// <summary>
|
|
/// Optional driver capability: data changes delivered one event per production burst instead of
|
|
/// one event per tag. A driver implementing this raises <see cref="OnDataChangeBatch"/> once per
|
|
/// burst AND continues raising the per-tag <see cref="ISubscribable.OnDataChange"/> for each item
|
|
/// (legacy consumers: Galaxy cold reads, driver CLIs). A consumer subscribes to EXACTLY ONE of the
|
|
/// two events — subscribing both double-delivers. DriverInstanceActor prefers the batch event.
|
|
/// </summary>
|
|
public interface IBatchSubscribable : ISubscribable
|
|
{
|
|
/// <summary>Batched data-change notification — one raise per production burst.</summary>
|
|
event EventHandler<DataChangeBatchEventArgs>? OnDataChangeBatch;
|
|
}
|