Scanner SDK for Windows - About - Zebra Technologies

Overview

This documentation provides a detailed guide on using PowerShell scripts to interact with Zebra scanners via the Interop.CoreScanner.dll. It covers how to retrieve scanner information, handle various events like barcode data events, and translate C# and C++ API calls into PowerShell commands. It also includes the full scripts you provided, along with explanations of their components.

Prerequisites

PowerShell Version: Ensure PowerShell version 5 or higher is installed on your system.
Zebra SDK: The Zebra Scanner SDK must be installed, and the Interop.CoreScanner.dll should be located at C:\Program Files\Zebra Technologies\Barcode Scanners\Common\.
Permissions: Run PowerShell with administrative privileges to ensure all commands execute successfully.

Common Components

Loading the DLL

Each script begins by loading the Interop.CoreScanner.dll, which provides methods and properties necessary for interacting with the scanner hardware.


[System.Reflection.Assembly]::LoadFile("C:\Program Files\Zebra Technologies\Barcode Scanners\Common\Interop.CoreScanner.dll") | Out-Null

Creating the Scanner Object

The scripts create an instance of CCoreScannerClass, the primary class for scanner interactions.


$ScannerObject = New-Object Interop.CoreScanner.CCoreScannerClass

Initializing Variables

Several variables are initialized to manage scanner operations and store results.


$Status = 0
$AppHandle = 0
$OutXML = ""
$ScannerCount = 0

Opening the Scanner Connection

The Open method is used to establish a connection with the scanner, taking parameters such as application handle and scanner types.


$ScannerTypes = New-Object int16[] 11
$ScannerTypes[0] = 1
$NumberOfScannerTypes = [int16] 1
$ScannerObject.Open($AppHandle, $ScannerTypes, $NumberOfScannerTypes, [ref] $Status)

Retrieving Scanner Data

GetScanners retrieves information about the connected scanners and stores it in an XML format.


$ScannerObject.GetScanners([ref] $ScannerCount, $ScannerIDList, [ref] $OutXML, [ref] $Status)

Process-Out-XML Function

The Process-Out-XML function is designed to parse and format the XML data returned from the scanner. This function extracts useful information about the scanners and formats it for display.

Key Points:

XML Parsing:
- The function begins by creating an instance of System.Xml.XmlDocument. This class allows for easy manipulation and querying of XML data.
```
$XmlContent = New-Object -TypeName System.Xml.XmlDocument
$XmlContent.LoadXml($XML)
```

Extracting Scanner Information:

The function uses the scanners and scanner nodes from the XML to extract details about each connected scanner.
It pipes the extracted data to Format-Table, which organizes the data into a readable table format.


$XmlContent.scanners.scanner | Format-Table -AutoSize @{
    Name = 'Scanner ID'; Expression = {$_.scannerID}
}, @{
    Name = 'Host Mode'; Expression = {$_.type}
}, @{
    Name = 'Model Number'; Expression = {$_.modelnumber}
}, @{
    Name = 'Serial Number'; Expression = {$_.serialnumber}
}, @{
    Name = 'Date of Manufacture'; Expression = {$_.DoM}
}, @{
    Name = 'Scanner Firmware Version'; Expression = {$_.firmware}
}

Processing and Formatting Output:
- The main purpose of this function is to transform the raw XML data into a human-readable format, making it easy to review scanner attributes like ID, model number, serial number, and firmware version.
- The scripts use Format-Table to neatly display the processed output data, making it easier to read and interpret.

Logging

Start-Transcript is used to log script execution details, which is helpful for troubleshooting and auditing.


Start-Transcript -Append -Path "$PSScriptRoot\YourLogFile.log.txt"

Translating API Commands to PowerShell

C# and C++ API calls references are available here.

The Zebra scanner API provides several commands that can be used to control and interact with scanners. Here’s how these commands translate into PowerShell:

Scanner ID

In the SDK context, scanner ID uniquely identifies a scanner device connected to the CoreScanner driver, and is required to communicate programmatically with the device. Developers need to call the GetScanners method of the CoreScanner API in order to retrieve the scanner IDs of connected devices. For example, to switch on a scanner's red LED, the scanner ID of that particular scanner must be obtained to provide that value in the <scannerID> element of inXML of the ExecCommand method call.

During each CoreScanner driver instance, scanner IDs are sequentially assigned to each connected device. When the CoreScanner driver is restarted, the array of connected scanners is reinitialized and previous scanner IDs may no longer be valid. In this case, the GetScanners method must be executed to obtain the new scanner IDs.

During a single CoreScanner driver instance, an RSM (Remote Scanner Management) supported scanner that is unplugged, and reconnected retain its unique scanner ID. However, a non-RSM device is assigned a different scanner ID each time it is reconnected.

Open command:

C# Syntax:


void Open(int reserved, System.Array sfTypes, short lengthOfTypes, out int status);

PowerShell Translation:


$ScannerTypes = New-Object int16[] 11
$ScannerTypes[0] = 1
$ScannerObject.Open($AppHandle, $ScannerTypes, $NumberOfScannerTypes, [ref] $Status)

GetScanners command:

C# Syntax:


void GetScanners(out short numberOfScanners, System.Array sfScannerIDList, out string outXML, out int status);

PowerShell Translation:


$ScannerObject.GetScanners([ref] $ScannerCount, $ScannerIDList, [ref] $OutXML, [ref] $Status)

ExecCommand:

C# Syntax:


void ExecCommand(int opcode, ref string inXML, out string outXML, out int status);

PowerShell Translation:


$ScannerObject.ExecCommand($OpCode, [ref] $InXML, [ref] $OutXML, [ref] $Status)

Close command:

C# Syntax:


void Close(int reserved, out int status);

PowerShell Translation:


$ScannerObject.Close($AppHandle, [ref] $Status)

Reference

Refer to the Appendix of Barcode Scanner SDK for Windows for more details. It covers the followings.

Error/Status Codes.
Methods Invoked Through ExecCommand Or ExecCommandAsync.
Action Attributes and Values

NOTE: For a list of a scanner's supported attribute (parameter) numbers and definitions, refer to the Product Reference Guide for that model scanner, available from the Zebra Support website at http://www.zebra.com/support. Attributes include configuration parameters, monitored data, and asset tracking information.

References:

Event Handling in PowerShell

To handle events in PowerShell, you must use the RegisterForEvents method in your C# code block, specifying the event types you wish to subscribe to. Once events are registered, they can be handled using PowerShell's Register-ObjectEvent.

Event Registration for Barcode Data

In the script for handling barcode data scan events, a process is set up to register for barcode events and handle them as they occur.

Event Handling (Barcode Events)

C# Syntax:


void OnBarcodeEvent(short eventType, ref string pscanData);

PowerShell Integration:

The event handling is set up in PowerShell by integrating C# code using Add-Type to define and handle events.

Key Points

Define a Delegate:
A delegate BarcodeEventHandler is defined in C#. This delegate specifies the signature for methods that can handle barcode events.
```
public delegate void BarcodeEventHandler(int dataType, string pscanData);
```
Event Handling Class:
The CoreScannerWrapper class encapsulates the logic for handling barcode events. It includes an event OnBarcode which is triggered whenever a barcode is scanned.
```
public static event BarcodeEventHandler OnBarcode;
```

Registering for Events:

The RegisterForEvents method configures the scanner to listen for specific events (in this case, barcode events). It constructs an XML string to specify which events to register.


string inXml = "<inArgs><cmdArgs><arg-int>1</arg-int><arg-int>1</arg-int></cmdArgs></inArgs>";

coreScannerObject.GetType().InvokeMember("ExecCommand", BindingFlags.InvokeMethod, null, coreScannerObject, new object[] { 1001, inXml, out outXml, status });

Event Callback:
The BarcodeEvent method serves as the callback that processes barcode data when an event is received. It uses the OnBarcode event to notify subscribers of new barcode data.
```
public void BarcodeEvent(int dataType, string pscanData) {
    if (OnBarcode != null) {
        OnBarcode(dataType, pscanData);
    }
}
```
PowerShell Integration:
In PowerShell, Register-ObjectEvent is used to bind the event handler to a PowerShell action, allowing barcode data to be processed in real-time within the script.
```
$Action = { Write-Host $event.SourceArgs }
Register-ObjectEvent -InputObject $ScannerWrapperObject -SourceIdentifier "BarcodeEvents" -EventName "OnBarcode" -Action $Action
```

API Events

The following events are supported and can be registered using the Zebra API:

ImageEvent: Triggered when an imaging scanner captures images in image mode.
VideoEvent: Triggered when an imaging scanner captures video in video mode.
BarcodeEvent: Triggered when a scanner captures barcodes.
PNPEvent: Triggered when a scanner is attached or detached.
ScanRMDEvent: Receives RMD Events when updating firmware of the scanner.
CommandResponseEvent: Received after an asynchronous command execution.
IOEvent: Received when an exclusively claimed device is accessed by another client application.
ScannerNotificationEvent: Received when a SNAPI scanner changes its operational mode.
BinaryDataEvent: Triggered when an IDC-supported imaging scanner captures an image in Intelligent Document Capture (IDC) or Signature Capture mode.

Comprehensive Zebra Scanner PowerShell Interaction Documentation

Overview

Prerequisites

Common Components

Loading the DLL

Creating the Scanner Object

Initializing Variables

Opening the Scanner Connection

Retrieving Scanner Data

Process-Out-XML Function

Logging

Translating API Commands to PowerShell

Reference

Event Handling in PowerShell

Event Registration for Barcode Data

Event Handling (Barcode Events)

Key Points

API Events