Point of Service device claim and enable model

Use the Point of Service device claim and enable APIs to claim devices and enable them for I/O operations.

Claiming for exclusive use

After creating a PointOfService device object, you must claim it using the appropriate claim method for the device type before you can use the device for input or output. Claim grants the application exclusive access to many of the device's functions to ensure that one application does not interfere with the use of the device by another application. Only one application at a time can claim a PointOfService device for exclusive use.

Note

The claim action establishes an exclusive lock to a device, but does not put it into an operational state. See Enable device for I/O operations for more information.

APIs used to claim / release

Device	Claim	Release
BarcodeScanner	BarcodeScanner.ClaimScannerAsync	ClaimedBarcodeScanner.Close
CashDrawer	CashDrawer.ClaimDrawerAsync	ClaimedCashDrawer.Close
LineDisplay	LineDisplay.ClaimAsync	ClaimedineDisplay.Close
MagneticStripeReader	MagneticStripeReader.ClaimReaderAsync	ClaimedMagneticStripeReader.Close
PosPrinter	PosPrinter.ClaimPrinterAsync	ClaimedPosPrinter.Close

Enable device for I/O operations

The claim action establishes exclusive rights to the device, but does not put it into an operational state. In order to receive events or perform any output operations you must enable the device using EnableAsync. Conversely, you can call DisableAsync to stop listening to events from the device or stop performing output. You can also use IsEnabled to determine the state of your device.

APIs used enable / disable

Device	Enable	Disable	IsEnabled?
ClaimedBarcodeScanner	EnableAsync	DisableAsync	IsEnabled
ClaimedCashDrawer	EnableAsync	DisableAsync	IsEnabled
ClaimedLineDisplay	Not Applicable¹	Not Applicable¹	Not Applicable¹
ClaimedMagneticStripeReader	EnableAsync	DisableAsync	IsEnabled
ClaimedPosPrinter	EnableAsync	DisableAsync	IsEnabled

¹ Line Display does not require you to explicitly enable the device for I/O operations. Enabling is performed automatically by the PointOfService LineDisplay APIs which perform I/O.

Code sample: claim and enable

This sample shows how to claim a barcode scanner device after you have successfully created a barcode scanner object.

    BarcodeScanner barcodeScanner = await BarcodeScanner.FromIdAsync(DeviceId);

    if(barcodeScanner != null)
    {
        // after successful creation, claim the scanner for exclusive use 
        claimedBarcodeScanner = await barcodeScanner.ClaimScannerAsync();

        if(claimedBarcodeScanner != null)
        {
            // after successful claim, enable scanner for data events to fire
            await claimedBarcodeScanner.EnableAsync();
        }
        else
        {
            Debug.WriteLine("Failure to claim barcodeScanner");
        }
    }
    else
    {
        Debug.WriteLine("Failure to create barcodeScanner object");
    }
    

Warning

A claim can be lost in the following circumstances:

1. Another app has requested a claim of the same device and your app did not issue a RetainDevice in response to the ReleaseDeviceRequested event. (See Claim negotiation below for more information.)
2. Your app has been suspended, which resulted in the device object being closed and as a result the claim is no longer valid. (See Device object lifecycle for more information.)

Claim negotiation

Since Windows is a multi-tasking environment, it is possible for multiple applications on the same computer to require access to peripherals in a cooperative manner. The PointOfService APIs provide a negotiation model that allows for multiple applications to share peripherals connected to the computer.

When a second application on the same computer requests a Claim for a PointOfService peripheral that is already claimed by another application, a ReleaseDeviceRequested event notification is published. The application with the active claim must respond to the event notification by calling RetainDevice if the application is currently using the device to avoid losing the claim.

If the application with the active claim does not respond with RetainDevice right away it is assumed that the application has been suspended or does not need the device and the claim is revoked and given to the new application.

The first step is to create an event handler that responds to the ReleaseDeviceRequested event with RetainDevice.

    /// <summary>
    /// Event handler for the ReleaseDeviceRequested event which occurs when 
    /// the claimed barcode scanner receives a Claim request from another application
    /// </summary>
    void claimedBarcodeScanner_ReleaseDeviceRequested(object sender, ClaimedBarcodeScanner myScanner)
    {
        // Retain exclusive access to the device
        myScanner.RetainDevice();
    }

Next, register the event handler in association with your claimed device

    BarcodeScanner barcodeScanner = await BarcodeScanner.FromIdAsync(DeviceId);

    if(barcodeScanner != null)
    {
        // after successful creation, claim the scanner for exclusive use 
        claimedBarcodeScanner = await barcodeScanner.ClaimScannerAsync();

        if(claimedBarcodeScanner != null)
        {
            // register a release request handler to prevent loss of scanner during active use
            claimedBarcodeScanner.ReleaseDeviceRequested += claimedBarcodeScanner_ReleaseDeviceRequested;

            // after successful claim, enable scanner for data events to fire
            await claimedBarcodeScanner.EnableAsync();          
        }
        else
        {
            Debug.WriteLine("Failure to claim barcodeScanner");
        }
    }
    else
    {
        Debug.WriteLine("Failure to create barcodeScanner object");
    }

APIs used for claim negotiation

Claimed device	Release Notification	Retain Device
ClaimedBarcodeScanner	ReleaseDeviceRequested	RetainDevice
ClaimedCashDrawer	ReleaseDeviceRequested	RetainDevice
ClaimedLineDisplay	ReleaseDeviceRequested	RetainDevice
ClaimedMagneticStripeReader	ReleaseDeviceRequested	RetainDevice
ClaimedPosPrinter	ReleaseDeviceRequested	RetainDevice