Interface IConnectedDevice

Namespace

Acuit.Pinpoint.IO

Assembly

Acuit.Pinpoint.IO.Abstractions.dll

A device that requires a connection to an external device.

public interface IConnectedDevice

Remarks

The IDeviceRegistry service implementation must do the following:

1. Automatically connect to the device when the device object is created (i.e., when the device type is registered or the configured devices changes).
2. Automatically reconnect to the device when the device connection is lost (e.g., due to the device disconnecting from the other side). The convention is to pause for a short time after losing the connection before attempting to reconnect. By default, this should default to three seconds but be configurable via the ReconnectDelay setting.
3. Reflect connection errors in the device health check (i.e., the device implementation does not need to track connection errors itself and return them from its own health check).

Device implementations can also implement this interface to know when to initiate operation, as ConnectAsync(CancellationToken) will not be called until the device class has been completely initialized.

ConnectedDevice provides a default implementation for this interface from which device classes can derive.

Methods

ConnectAsync(CancellationToken)

Connects to the device.

Task<IDeviceConnection> ConnectAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A CancellationToken that can request canceling the connection attempt.

Returns

Task<IDeviceConnection>

A task that represents the asynchronous operation. The value of its Result property contains a IDeviceConnection representing the established connection.

Remarks

This is safe to call even if there is already an active connection, in which case it will do nothing and return the same IDeviceConnection as from the active connection.

Implementations must ensure that the returned IDeviceConnection is fully implemented, including handling callback registrations and indicating when the connection is closed for any reason.

Upon a successful connection, Connected should be raised.

This must be thread-safe: asynchronous implementations must ensure multiple simultaneous calls to this are handled correctly.

Exceptions

Exception

The connection could not be established. Specific exception types will depend on the implementation. This will only occur asynchronously, wrapped in an AggregateException as the faulted task's Exception.

DisconnectAsync(CancellationToken)

Disconnects from the device.

Task DisconnectAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A CancellationToken that can request that the disconnection process no longer be graceful.

Returns

Task

A task that represents the asynchronous operation.

Remarks

This is safe to call even if there is not an active connection.

When cancellationToken is signaled, it indicates that the disconnection should still occur, but not gracefully. The implementation should complete its disconnection process as directly as possible, but the returned Task should still reflect a RanToCompletion status (not Canceled).

Upon a successful connection, Disconnected should be raised.

This must be thread-safe: asynchronous implementations must ensure multiple simultaneous calls to this are handled correctly.

Events

Connected

Raised when the device is connected.

event EventHandler Connected

Event Type

EventHandler

Disconnected

Raised when the device is disconnected.

event EventHandler Disconnected

Event Type

EventHandler