Use an emulator to simulate a barcode scanner (Handheld 8.1)
7/17/2014
The Windows Embedded 8.1 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 Handheld 8.1 emulator that is included with the Handheld 8.1 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
- Windows 8.1 Professional or higher 64-bit operating system.
- Visual Studio 2013 with Update 2 or later. Visual Studio 2013 Update 2 is available here. Visual Studio 2013 with Update 2 also contains the Windows Phone 8.1 SDK, which you will need.
- Windows Embedded 8.1 Handheld SDK, available here.
Important
Ensure that Visual Studio 2013, Visual Studio 2013 with Update 2, and the Handheld 8.1 SDK are installed according to the instructions that came with the Handheld 8.1 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.
In Visual Studio, create a C# Windows Phone App project that targets Windows Phone 8.1.
Add a reference from your project to POSTestNativeUtils.winmd. If you installed the Windows Phone 8.1 and Handheld 8.1 SDKs to their default locations, you will find POSTestNativeUtils.winmd under C:\Program Files (x86)\Windows Phone Kits\8.1\Samples\POSTestNativeUtils\x86.
Select a Handheld 8.1 emulator to deploy the built project to. In the Visual Studio Debug Target drop-down list, select one of the Handheld 8.1 emulators.
Warning
If you neglect to choose one of the Handheld 8.1 emulators, you will get a type load exception when you run the project.
Because the Handheld 8.1 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 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_DataReceived 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 Handheld 8.1 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 Handheld 8.1 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 Handheld 8.1 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.