Class StreamingBarCodeScanner

Namespace

Acuit.Pinpoint.BarCodeScanning

Assembly

Acuit.Pinpoint.BarCodeScanning.dll

A bar code scanner that extracts bar codes from an incoming raw data stream.

public abstract class StreamingBarCodeScanner : BarCodeScanner, IConnectedDevice, IHealthCheck, IDisposable, IAsyncDisposable, IBarCodeScanner, IBarCodeScannerRaw

Inheritance

object

ConnectedDevice

BarCodeScanner

StreamingBarCodeScanner

Implements

IConnectedDevice

IHealthCheck

IDisposable

IAsyncDisposable

IBarCodeScanner

IBarCodeScannerRaw

Derived

KeyboardBarCodeScanner

SerialBarCodeScanner

TcpBarCodeScanner

Inherited Members

BarCodeScanner.BarCodeScanned

BarCodeScanner.OnBarCodeScanned(BarCodeScanEventArgs)

ConnectedDevice.Dispose()

ConnectedDevice.DisposeAsync()

ConnectedDevice.Connected

ConnectedDevice.Disconnected

ConnectedDevice.ConnectAsync(CancellationToken)

ConnectedDevice.OnConnectedAsync()

ConnectedDevice.ConnectedDeviceLockAsync(CancellationToken)

ConnectedDevice.DisconnectAsync(CancellationToken)

ConnectedDevice.OnDisconnectingAsync(CancellationToken)

ConnectedDevice.OnDisconnectedAsync()

ConnectedDevice.OnExternalDeviceClosedConnection(Exception)

ConnectedDevice.CheckHealthAsync(HealthCheckRegistration, CancellationToken)

ConnectedDevice.ConnectedHealthIsHealthy()

ConnectedDevice.ConnectedCheckHealthAsync(CancellationToken)

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Remarks

Derived classes must do the following:

• Implement DoConnectAndGetStreamAsync(CancellationToken).
• The Stream returned from DoConnectAndGetStreamAsync(CancellationToken) will be closed when DisconnectAsync(CancellationToken) is called; if additional disconnect logic is required, override DoDisconnectAsync(CancellationToken), being sure to first call the base method in the override (which closes the Stream).
• Optionally call OnRawDataReceived(BarCodeRawDataReceivedEventArgs) to reflect additional control data.
• Override Dispose(bool) and DisposeAsyncCore() as needed (when overriding one, always override the other as well).

StreamingBarCodeScanner will always have a pending read waiting for new data. If the read fails for any reason (in particular, with ObjectDisposedException due to the stream being closed from the other side), or if it completes indicating there is no more data available, then StreamingBarCodeScanner will mark the connection as having closed by calling OnExternalDeviceClosedConnection(Exception).

Constructors

StreamingBarCodeScanner(IErrorHandler, ILogger, ITimeService)

Initializes a new instance of the StreamingBarCodeScanner class.

protected StreamingBarCodeScanner(IErrorHandler errorHandler, ILogger logger, ITimeService timeService)

Parameters

errorHandler IErrorHandler

The error handler to use for unexpected background errors.

logger ILogger

The logger.

timeService ITimeService

The time service.

Exceptions

ArgumentNullException

errorHandler is null.

ArgumentNullException

logger is null.

ArgumentNullException

timeService is null.

Properties

CommandOnConnect

Gets or sets an optional command to send to the bar code scanner once a connection is established. If termination characters such as a carriage return are required, they must be included in this value (i.e., Prefix and Suffix are only used when reading).

public string CommandOnConnect { get; set; }

Property Value

string

Remarks

Only streaming bar code scanners with writable streams support this property. If this is specified with an unsupported bar code scanner (such as KeyboardBarCodeScanner), connection to the bar code scanner will fail with NotSupportedException.

Encoding

Gets or sets the character encoding. Defaults to ASCII.

[Required]
public Encoding Encoding { get; set; }

Property Value

Encoding

IsWaitingForPrefix

Gets whether the bar code scanner is waiting for a bar code prefix.

protected bool IsWaitingForPrefix { get; }

Property Value

bool

MaxMessageLength

Gets or sets the maximum message length allowed. Messages from the scanner longer than this will be discarded.

[GreaterThan(0)]
public int MaxMessageLength { get; set; }

Property Value

int

MultipleSeparator

Gets or sets the character(s) that separate multiple bar codes sent in one message from the scanner.

public string MultipleSeparator { get; set; }

Property Value

string

Prefix

Gets or sets the prefix character(s) that start each message from the scanner.

public string Prefix { get; set; }

Property Value

string

Suffix

Gets or sets the suffix character(s) that terminate each message from the scanner. This is required.

public string Suffix { get; set; }

Property Value

string

Timeout

Gets or sets the maximum time allowed between characters while receiving a message from the scanner.

[GreaterThan(typeof(TimeSpan), "0:00:00")]
public TimeSpan Timeout { get; set; }

Property Value

TimeSpan

Methods

Dispose(bool)

Closes and releases all resources used by the object.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true when this is in response to a call to Dispose().

Remarks

Derived classes should override this when they have any resources that should be disposed.

When Dispose() is called on the object, Dispose(bool) will be called with true for the parameter value.

When DisposeAsync() is called on the object, DisposeAsyncCore() will be called, and then Dispose(bool) will be called with false for the parameter value.

DisposeAsyncCore()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

protected override ValueTask DisposeAsyncCore()

Returns

ValueTask

A task that represents the asynchronous operation.

Remarks

Derived classes should override this when they have any resources that should be disposed.

When Dispose() is called on the object, Dispose(bool) will be called with true for the parameter value.

When DisposeAsync() is called on the object, DisposeAsyncCore() will be called, and then Dispose(bool) will be called with false for the parameter value.

DoConnectAndGetStreamAsync(CancellationToken)

Connects to the device and gets the Stream to use to communication with the bar code scanner.

protected abstract Task<Stream> DoConnectAndGetStreamAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation token, which indicates that the connection attempt should be aborted.

Returns

Task<Stream>

A task that represents the asynchronous operation. The value of its Result property contains the stream.

Remarks

This might be called from any thread, but it and DoDisconnectAsync(CancellationToken) will never be called concurrently.

Exceptions

Exception

The connection could not be established.

DoConnectAsync(CancellationToken)

Connects to the device.

protected override Task DoConnectAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A CancellationToken that can request canceling the connection attempt.

Returns

Task

A task that represents the asynchronous operation.

Remarks

This might be called from any thread, but it and DoDisconnectAsync(CancellationToken) will never be called concurrently.

Exceptions

Exception

The connection could not be established. Specific exception types will depend on the implementation.

DoDisconnectAsync(CancellationToken)

Disconnects from the device.

protected override Task DoDisconnectAsync(CancellationToken cancellationToken)

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

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).

This might be called from any thread, but it and DoConnectAsync(CancellationToken) will never be called concurrently.

OnRawDataReceived(BarCodeRawDataReceivedEventArgs)

Raises the RawDataReceived event.

protected virtual void OnRawDataReceived(BarCodeRawDataReceivedEventArgs e)

Parameters

e BarCodeRawDataReceivedEventArgs

The event data.

Remarks

A derived type may override OnRawDataReceived(BarCodeRawDataReceivedEventArgs). The overridden method must call OnRawDataReceived(BarCodeRawDataReceivedEventArgs) on the base class if RawDataReceived needs to be raised.

ProcessReceivedCharacter(char)

Process a received character.

protected bool ProcessReceivedCharacter(char c)

Parameters

c char

The character to process.

Returns

bool

true if the character is processed (i.e., it is part of the prefix, bar code, or suffix characters; otherwise, false.

Remarks

Derived classes can optionally call this directly (effectively bypassing the background stread read loop) to process incoming characters. This might be necessary if the derived class needs to know which characters are processed as bar code characters (e.g., KeyboardBarCodeScanner, which must know which characters are processed as bar code characters, so it can determine whether or not to mark them handled as they are received).

Events

RawDataReceived

Occurs when raw data is received from the bar code scanner.

public event EventHandler<BarCodeRawDataReceivedEventArgs> RawDataReceived

Event Type

EventHandler<BarCodeRawDataReceivedEventArgs>

Remarks

This can be used to help diagnose bar code scanner configuration issues.

This event might be raised on a background worker thread.