Basics

Getting the decoded data

Using Capture Helper to retrieve the decoded data from a scanner is as simple as registering a decoded data handler to the Capture Helper event: DecodedData.

Here is an example of registering a decoded data handler before opening Capture Helper:

public Form1()
{
    InitializeComponent();

    // initialize CaptureHelper
    capture = new CaptureHelper();

    // make the events running in UI Thread context
    capture.ContextForEvents = WindowsFormsSynchronizationContext.Current;

    // register for the Capture Helper events
    capture.DecodedData += CaptureDecodedData;

    ...
}

And the decoded data handler might look like this:

void CaptureDecodedData(object sender, CaptureHelper.DecodedDataArgs e)
{
    textBoxDecodedData.Text = e.DecodedData.DataToUTF8String;
}

Note

Here the UI can be directly updated because in the Capture Helper initialization the UI Context is passed in the ContextForEvents property of Capture Helper: capture.ContextForEvents = WindowsFormsSynchronizationContext.Current;

Device arrival

The Device arrival is fired when a scanner is connected to the host.

This event can be useful for several things such as:

• confirming to the user the scanner is present and ready

• switching to a view that is ready to receive the decoded data

• adding the Capture Helper Device into a list for future reference

Here is an example of a Device Arrival handler:

void CaptureDeviceArrival(object sender, CaptureHelper.DeviceArgs e)
{
    AddDeviceIntoListBox(listBoxDevices, e.CaptureDevice);
    labelStatus.Text = e.CaptureDevice.GetDeviceInfo().Name;
}

Note

Here the UI can be directly updated because in the Capture Helper initialization the UI Context is passed in the ContextForEvents property of Capture Helper: capture.ContextForEvents = WindowsFormsSynchronizationContext.Current;

This assumes the Device Arrival handler has been registered before opening Capture Helper:

...
// initialize CaptureHelper
capture = new CaptureHelper();

// make the events running in UI Thread context
capture.ContextForEvents = WindowsFormsSynchronizationContext.Current;

// register for the Capture Helper events
capture.DeviceArrival += CaptureDeviceArrival;
...

Device Ownership

Since the introduction of Socket Mobile Companion software, a scanner can now be shared between multiple applications. Although only one application has the scanner ownership at a time. What this means is that the decoded data coming from the scanner will go only to the application that has the scanner ownership. The default behavior is that the last application opening the scanner is the one getting its ownership. If a previous application had the scanner opened before, that application receives a Device Ownership Change with a GUID as argument set to a NULL GUID: {00000000-0000-0000-0000-000000000000} indicating the application has lost the ownership of the scanner. The last application that opens the scanner also receives an Ownership change notification this time with a non-NULL GUID meaning it has the ownership. As soon as this last application closes the scanner, the Ownership goes back to the previous application.

Why this notification could be important?

In the event there are multiple applications using the scanner, and the user switches back to the application that first opened the scanner, the UI can display a status indicating the scanner is not available in this application and offer a button to gain the ownership back. It is not recommended to re-gain the device ownership as soon as it is lost. Another alternative is to automatically claim the device ownership when the application gains the focus. Of course, if the application that is owning a scanner closes, then the previous application may gain the focus and the ownership of the scanner. Even though in this case closing and re-opening the scanner won’t do any harm, it still is an unnecessary operation.

How to claim the ownership back?

The device ownership can be reclaimed by closing the device and re-opening it. Here is an example of a button handler to reclaim the device ownership:

private async void buttonOwnDevice_Click(object sender, EventArgs e)
{
    CaptureDeviceItem item = (CaptureDeviceItem)listBoxDevices.SelectedItem;
    if (item != null)
    {
        await item.Device.CloseAsync();
        await item.Device.OpenAsync();
    }
}

in this sample CaptureDeviceItem is defined as follows:

class CaptureDeviceItem
{
    public string Name;
    public string Extra;
    public CaptureHelperDevice Device;
    public override string ToString()
    {
        return Name + " " + Extra;
    }
}

Get the error

It is a good idea to be notified when an unexpected error occurs. One likely scenario where this could happen is when the Socket Mobile Companion software has trouble opening the Bluetooth inbound port or if the Bluetooth radio has been turned off. Here is an example of the error event handler to display an error message in a status label in the application UI:

void CaptureErrors(object sender, CaptureHelper.ErrorEventArgs e)
{
    string error = string.Format("Error:{0} {1}", e.Result, e.Message);
    labelErrorStatus.Text = error;
}

Note

Here the UI can be directly updated because in the Capture Helper initialization the UI Context is passed in the ContextForEvents property of Capture Helper: capture.ContextForEvents = WindowsFormsSynchronizationContext.Current;

Getting a device property such as Battery Level

Capture Helper helps to retrieve information about a particular scanner or to configure a scanner through a Capture Helper Device object that is received in the Device Arrival event as well as in the DeviceOwnershipChange event and in the DecodedData event. This Capture Helper Device object is also received in argument of the Device Removal event but since the device is disconnected from the host, only limited operations can be done with this Capture Helper Device at this time.

Here is an example of such a command:

// ask for the Battery Level
CaptureHelperDevice.BatteryLevelResult resultBattery = await Device.GetBatteryLevelAsync();
labelBatteryLevel.Text = resultBattery.Percentage;

With device being defined as a CaptureHelperDevice object.

Please refer to the other topics for more information about configuring the device or retrieving.