Implement event support

Events are passed from the device driver to the WinRT POS API layer by using ReadFile. When an app successfully claims a device through the WinRT POS API, the WinRT POS runtime will maintain a continuous read operation against the device driver to receive events.

Pass ReadFile a buffer sufficiently large enough to read in the current event. The driver retains the message until a read request with a sufficient output buffer to read the entire message is made.

All events consist of a common PosEventDataHeader header composed of a 32-bit unsigned integer indicating the event type and a 32-bit unsigned integer indicating the full size of the event data, including the size of the header, as shown in the following example:

typedef struct _PosEventDataHeader
    // Event enumeration value
    PosEventType EventType;

    // Size of buffer required to read entire event (including header)
    UINT32 DataLength;
} PosEventDataHeader;

The POSUTIL library will raise and respond to events in the correct order. For example, ReleaseRequest events are guaranteed to be delivered before other events.

Driver writers should register POSUTILDeviceIoRead as the read file handler and call appropriate POSUTIL raise event functions to raise events. For example, if the driver would like to raise an error event it should call POSUTILRaisePosBarcodeScannerErrorOccurredEvent. Or, if the driver wants to raise a trigger event, it should call POSUTILRaiseTriggerState. For a list of supported scanner events, see Barcode scanner events.

If you choose not to register POSUTILDeviceIoRead as the read file handler, note that if ReadFile does not have an output buffer large enough to hold the current event data raised from the device, it will return FALSE. GetLastError will return ERROR_INSUFFICIENT_BUFFER and the ReturnedBytes parameter will contain the size of the buffer required to successfully read the message.

POSUTIL queues incoming data from the device and associates it with the app that currently has claimed and enabled the device. The app will receive all of the data generated by the hardware, even in the case where the hardware is generating data faster than the app can process it.

POSUTIL processes the data from the driver synchronously and queues the data in a first in, first out (FIFO) queue, where it remains until it is passed to the app that had a claim on the enabled device when the data was generated. If the app that has a claim on the device releases it before processing all of the data in the queue, the remaining data associated with that app is flushed from the queue.The client should process events in a timely manner because POSUTIL does not limit the size of the incoming queue. POSUTIL will add incoming data to the queue as long as the device is generating it. If it isn’t removed from the queue in a timely manner, the system may eventually run out of memory.

The driver can also raise events that WinRT POS apps can handle by calling the POSUTILRaise* functions. The sample scanner driver illustrates how to raise events. For examples of how to raise an event using the POSUTIL library, see DeviceIoDeviceControl() in Device.c and see the individual Handle* functions, such as HandleInjectImagePreview().

Related topics

POS events
POSUTIL functions