Use an emulator to simulate a barcode scanner (Handheld 8)

  • Article

2/18/2014

The Windows Embedded 8 Handheld SDK provides a driver for a simulated scanner object named FakeScanner. This fake scanner allows you to experiment with the Point of Service (POS) APIs by modeling the claim/release lifecycle of a barcode scanner, injecting simulated scan data events, error events, and more.

Before you can use the Windows Embedded 8 Handheld emulator that is included with the Windows Embedded 8 Handheld SDK, you must meet the following requirements:

Required Hardware

  • 64-bit motherboard with Second Level Address Translation (SLAT) support. This is necessary to run the emulator.
  • 8 GB of free disk space.

Required Software

Important

Ensure that the Windows Phone 8.0 SDK, Visual Studio, and the Windows Embedded 8 Handheld SDK are installed according to the instructions that came with the Windows Embedded 8 Handheld SDK.

Overview of tasks

  • Prepare a project to use the fake scanner
  • Code snippets that simulate a barcode scanner
  • Claim the barcode scanner
  • Simulate a scan event
  • Simulate releasing the barcode scanner
  • Run your application

Prepare a project to use the fake scanner

To use the fake scanner you must first prepare a Windows Phone project. Complete the following tasks to prepare a project that you will use with the code snippets that follow to simulate a barcode scanner on an emulator.

  1. In Visual Studio, create a C# Windows Phone App project that targets Windows Phone 8.

  2. Add a reference from your project to POSTestNativeUtils.winmd. If you installed the Windows Embedded 8 Handheld SDK to its default location, you will find POSTestNativeUtils.winmd under C:\Program Files (x86)\Microsoft SDKs\Windows Embedded Handheld\v8.0\Libraries\x86.

  3. Select a Windows Embedded 8 Handheld emulator to deploy the built project to. In the Visual Studio Debug Target drop-down list, select one of the Windows Embedded 8 Handheld emulators, such as WE8H Emulator WVGA.

    Warning

    If you neglect to choose one of the Windows Embedded 8 Handheld emulators, you will get a type load exception when you run the project.

  4. Because the Windows Embedded 8 Handheld emulator is based on the x86 architecture, you must change the platform of your project to x86. To do this, from the Build menu, click Configuration Manager, and then change the platform to x86.

    Warning

    If you neglect to make this platform change, you will get a build error about a mismatch between the project processor architecture and the processor architecture of POSTestNativeUtils.winmd. To remedy this error, change the platform to X86.

Code snippets that simulate a barcode scanner

The following code snippets illustrate how to use the fake scanner to simulate the behavior of a real barcode scanner. This overview is not exhaustive but illustrates how to enable a barcode scanner, simulate reading data from the scanner, and then release the scanner.

Important

For readability, the following code examples do not contain security checking or error handling. Do not use the following code in a production environment.

Add the following using statements to the top of the class in your project that you will use to simulate a barcode scanner.

using Windows.Devices.PointOfService; // The Windows RT point of service APIs
using POSTestNativeUtils; // The namespace where FakeScanner is defined

Add the following private class variables to the class in your project that you will use to simulate a barcode scanner.

private BarcodeScanner scanner;
private ClaimedBarcodeScanner claimedScanner; // the instance of the barcode scanner that is reserved for this application’s use
private POSTestNativeUtils.FakeScanner fakeScanner; // the fake scanner that simulates a barcode scanner

scanner stores the instance of the default scanner object.

claimedScanner stores the instance of the barcode scanner object that is reserved for exclusive use by your application.

fakeScanner stores the instance of the fake scanner driver object that you will use to simulate a barcode scanner.

Claim the barcode scanner

You must claim the barcode scanner before you can use it in your application. This ensures that your application has exclusive access to the barcode scanner. In the following code snippet, a FakeScanner is created and claimed. An event listener is added to capture scan events from fakeScanner.

private async void ClaimBarcodeScanner()
{
    scanner = await BarcodeScanner.GetDefaultAsync(); // get the default instance of the scanner
    fakeScanner = new FakeScanner(scanner.DeviceId);
    claimedScanner = await scanner.ClaimScannerAsync();
    claimedScanner.DataReceived += claimedScanner_DataReceived;
    await claimedScanner.EnableAsync();
    claimedScanner.IsDecodeDataEnabled = true; // provide decoded label data
}

Tip

The ClaimBarcodeScanner() method is annotated with async. This is necessary because methods that contain await calls must be marked async. The claimedScanner_DataRecieved code snippet follows.

Simulate a scan event

In the following code snippet, the fake scanner simulates a barcode scan event. You can specify the symbology of the scanned item, as well as the label and data that is sent in the simulated barcode scan event.

private void SimulateScanEvent ()
{
    fakeScanner.InjectDataEvent((uint)BarcodeSymbologies.Code128, // symbology
    System.Text.Encoding.UTF8.GetBytes("012345677"), // label
    System.Text.Encoding.UTF8.GetBytes("$1.46")); // data
}

In the following code snippet, when the fakeScanner scan event fires, the event listener that we set up when we claimed the barcode scanner is called. A datareader is used to extract the event data from the event argument into strings. The using statement is used to ensure that the datareader is disposed of properly.

void claimedScanner_DataReceived(ClaimedBarcodeScanner sender, BarcodeScannerDataReceivedEventArgs args)
{
    string label, data;
    UInt32 symbology = args.Report.ScanDataType; // the symbology of the scanned data
    using (var datareader = Windows.Storage.Streams.DataReader.FromBuffer( args.Report.ScanDataLabel ))
    {
        label = datareader.ReadString( args.Report.ScanDataLabel.Length);
    }
    using (var datareader = Windows.Storage.Streams.DataReader.FromBuffer( args.Report.ScanData ))
    {
        data = datareader.ReadString( args.Report.ScanData.Length);
    }
}

Simulate releasing the barcode scanner

Dispose the scanner object when you are ready to release exclusive control of the barcode scanner. The following code snippet illustrates how to release the barcode scanner.

In this code snippet the objects are set to null as a preventative measure so that it will be clear that the object is no longer in use.

private void DisableScanner()
{
    if (fakeScanner != null)
    {
        fakeScanner.Dispose();
        fakeScanner = null;
    }

    if (claimedScanner != null)
    {
        claimedScanner.Dispose();
        claimedScanner = null;
    }
}

Run your application

Click one of the Windows Embedded 8 Handheld emulators in the Visual Studio Debug Target drop-down menu to build the project and deploy it to the emulator.

Warning

If you neglect to choose one of the Windows Embedded 8 Handheld emulators, you will get a type load exception when you run the project.

Conclusion

The preceding code snippets illustrate how to obtain access to a barcode scanner, simulate a scan event, and release the scanner so that other applications may access it.The fake scanner driver included in the Windows Embedded 8 Handheld SDK also allows you to simulate scan error events, image preview events, status updates, trigger events, statistics updating, getting/setting properties, and more. See the class definition for FakeScanner in Visual Studio by navigating in Class view to POSTestNativeUtils, FakeScanner to see the full list of behaviors that the FakeScanner can simulate.

See Also

Concepts

Windows Embedded 8 Handheld