Socket ScanAPI User manual

ScanAPI Reference
History
Date
Description
4/29/2011
First release supporting Windows (big and WinMo), Android and
BlackBerry
6/16/2011
Added iOS details
9/16/2011
ScanApiHelper support for iOS, new Error code
ESKT_OUTDATEDVERSION
10/19/2011
Added more information about xCode integration
11/04/2011
Added Recommendations chapter
12/02/2011
Adding more information regarding Android permissions in
Recommendations for Android.
01/06/2012
Re-ordered the paragraph, reworded the Concept paragraph, and
modified the IDE integration for Xcode.
06/19/2012
Adding the properties, and the description of the SoftScan feature.
09/19/2012
Adding the missing symbology ids (USPS Intel. and DPM).
12/06/2012
Adding the Android permission
android.permission.BLUETOOTH_ADMIN that is required.
01/15/2013
Added new statistical counter names
01/18/2013
Added 2 new error codes for determining why a COM port can’t be
opened
02/25/2013
Minor editorial updates based on feedback
05/29/2013
Update kSktScanPropIdTimersDevice

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 2/152
06/03/2013
Update the framework requirements for iOS ScanAPI RedLaser
06/3/2013
Correct all endian references to ‘big-endian’

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 3/152
6/2012 Document# 6410-00319 A
COPYRIGHT NOTICE
Copyright © 2012 Socket Mobile, Inc. All rights reserved.
Socket, the Socket logo, Battery Friendly, Socket Bluetooth Cordless Hand Scanner, and SocketScan are trademarks or
registered trademarks of Socket Mobile, Inc. Bluetooth and the Bluetooth logos are registered trademarks owned by Bluetooth
SIG, Inc., U.S.A. and licensed to Socket Mobile, Inc. All other brand and product names are trademarks of their respective
holders.
The Socket Bluetooth Cordless Hand Scanner includes technology licensed under United States Patent Numbers 5,902,991,
7,429,000 B1 and D526,320 S.
Reproduction of the contents of this manual without the permission of Socket Mobile is expressly prohibited. Please be aware
that the products described in this manual may change without notice. Feel free to contact Socket Mobile at:
Socket Mobile, Inc.
39700 Eureka Drive, Newark, CA 94560-4808, USA
[phone]
USA/Canada Toll-free: 1-800-552-3300
http://www.socketmobile.com/contact
Other than the above, Socket Mobile can assume no responsibility for anything resulting from the application of information
contained in this manual.
Please refrain from any applications of the Socket Bluetooth Cordless Hand Scanner that are not described in this manual.
Please refrain from disassembling the Bluetooth Cordless Hand Scanner. Disassembly of this device will void the product
warranty.
You can track new product releases, software updates and technical bulletins by visiting the Socket Mobile website at:
http://www.socketmobile.com.

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 4/152
Table of contents
COPYRIGHT NOTICE................................................................................................................ 3
1Scanner connection overview .................................................................................. 7
1.1 Scanner connection information........................................................................... 7
2ScanAPI Introduction .............................................................................................. 10
3SoftScan Feature....................................................................................................... 11
3.1 Licensing requirements ...................................................................................... 11
3.2 iOS requirements................................................................................................ 11
3.3 Android requirements......................................................................................... 12
4Concept..................................................................................................................... 12
4.1 ScanAPI object................................................................................................... 12
4.2 Device object...................................................................................................... 13
4.3 ScanObject ......................................................................................................... 13
4.4 Using ScanAPI ................................................................................................... 14
4.5 ScanAPI configuration....................................................................................... 14
4.6 Get or Set a property ........................................................................................ 15
4.7 Example of sending a command...................................................................... 16
4.8 Handling asynchronous events or completion events .................................. 25
4.9 Termination ...................................................................................................... 25
5ScanAPI Helper (available for Java, C# and Objective C) ..................................... 26
5.1 Handling the ScanAPI Helper notifications .................................................... 26
5.2 Set ScanAPI Helper notification....................................................................... 32
5.3 Open ScanAPI Helper ....................................................................................... 32
5.4 Close ScanAPI Helper ....................................................................................... 32
5.5 Scanner arrival.................................................................................................. 32
5.6 Decoded data notification ................................................................................ 33
5.7 Scanner removal ............................................................................................... 33
5.8 Is there a connected Scanner........................................................................... 34
5.9 Get the list of scanners ..................................................................................... 34
5.10 No Device Connected item ........................................................................... 34
6IDE Integration ........................................................................................................ 34
6.1 C/C++ Version................................................................................................... 34
6.2 Java Version....................................................................................................... 34
6.3 C# Version ......................................................................................................... 36
6.4 Objective C Xcode integration.......................................................................... 36
7Recommendations..................................................................................................... 37
7.1 General............................................................................................................... 37
7.2 Android............................................................................................................... 37
7.3 iOS...................................................................................................................... 38
8Device Connection and Disconnection process .................................................... 38
8.1 Initial Connection ............................................................................................. 38
8.2 Subsequent Connection.................................................................................... 39
8.3 Reconnection..................................................................................................... 39
8.4 Disconnection.................................................................................................... 39

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 5/152
8.5 Roaming............................................................................................................. 40
8.6 Socket EZ Pair feature ...................................................................................... 40
9API Functions........................................................................................................... 41
9.1 Open Function................................................................................................... 41
9.2 Close Function................................................................................................... 46
9.3 Set Function....................................................................................................... 48
9.4 Get Function ...................................................................................................... 53
9.5 Wait Function.................................................................................................... 57
9.6 Release Function............................................................................................... 60
10 ScanObject............................................................................................................. 62
11 Asynchronous messages and events .................................................................. 63
11.1 Device Arrival ................................................................................................ 63
11.2 Device Removal ............................................................................................. 63
11.3 Terminate ...................................................................................................... 63
11.4 Set Complete.................................................................................................. 63
11.5 Get Complete ................................................................................................. 64
11.6 Events............................................................................................................. 64
12 Introduction to Properties................................................................................... 69
13 ScanAPI object properties ................................................................................... 70
13.1 Property kSktScanPropIdAbort ................................................................... 70
13.2 Property kSktScanPropIdVersion................................................................ 71
13.3 Property kSktScanPropIdInterfaceVersion ................................................ 73
13.4 Property kSktScanPropIdConfiguration ..................................................... 74
13.5 Property kSktScanPropIdDataConfirmationMode..................................... 76
13.6 Property kSktScanPropIdDataConfirmationAction ................................... 78
13.7 Property kSktScanPropIdMonitorMode ..................................................... 79
13.8 Property kSktScanPropIdSoftScanStatus ....................................................... 81
14 Device object properties ...................................................................................... 82
14.1 Property kSktScanPropIdVersionDevice .................................................... 82
14.2 Property kSktScanPropIdDeviceType......................................................... 82
14.3 Property kSktScanPropIdDeviceSpecific .................................................... 84
14.4 Property kSktScanPropIdSymbologyDevice............................................... 85
14.5 Property kSktScanPropIdTriggerDevice..................................................... 87
14.6 Property kSktScanPropIdApplyConfigDevice ............................................ 88
14.7 Property kSktScanPropIdPreambleDevice ................................................. 89
14.8 Property kSktScanPropIdPostambleDevice ............................................... 89
14.9 Property kSktScanPropIdCapabilitiesDevice ............................................. 90
14.10 Property kSktScanPropIdChangeIdDevice ................................................. 92
14.11 Property kSktScanPropIdFriendlyNameDevice ......................................... 93
14.12 Property kSktScanPropIdSecurityModeDevice.......................................... 95
14.13 Property kSktScanPropIdPinCodeDevice ................................................... 96
14.14 Property kSktScanPropIdDeletePairingBondingDevice............................ 97
14.15 Property kSktScanPropIdRestoreFactoryDefaultsDevice ......................... 98
14.16 Property kSktScanPropIdSetPowerOffDevice ............................................ 98
14.17 Property kSktScanPropIdButtonStatusDevice ........................................... 98
14.18 Property kSktScanPropIdSoundConfigDevice............................................ 99

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 6/152
14.19 Property kSktScanPropIdTimersDevice ................................................... 102
14.20 Property kSktScanPropIdLocalAcknowledgmentDevice ........................ 104
14.21 Property kSktScanPropIdDataConfirmationDevice................................. 105
14.22 Property kSktScanPropIdBatteryLevelDevice.......................................... 106
14.23 Property kSktScanPropIdLocalDecodeActionDevice............................... 107
14.24 Property kSktScanPropIdBluetoothAddress ............................................ 108
14.25 Property kSktScanPropIdStatisticCountersDevice .................................. 108
14.26 Property kSktScanPropIdRumbleConfigDevice ....................................... 111
14.27 Property kSktScanPropIdProfileConfigDevice ......................................... 113
14.28 Property kSktScanPropIdDisconnectDevice............................................. 114
14.29 Property kSktScanPropIdDataStoreDevice .............................................. 115
14.30 Property kSktScanPropIdNotificationsDevice.......................................... 116
14.31 Property kSktScanPropIdConnectReasonDevice ..................................... 117
14.32 Property kSktScanPropIdPowerStateDevice............................................ 118
14.33 Property kSktScanPropIdStartUpRoleSPPDevice .................................... 119
14.34 Property kSktScanPropIdConnectionBeepConfigDevice......................... 120
14.35 Property kSktScanPropIdFlashDevice ......................................................... 121
14.36 Property kSktScanPropIdOverlayViewDevice............................................. 122
15 ScanAPI Error handling and definitions........................................................... 124
15.1 Error codes .................................................................................................. 127
16 Symbologies Enumeration................................................................................. 129
17 Data confirmation feature ................................................................................. 130
18 Sample handling asynchronous events of ScanAPI ......................................... 131
19 SktScanAPIOwnership (available for Java platforms)..................................... 138
19.1 Constructor.................................................................................................. 139
19.2 register......................................................................................................... 140
19.3 unregister .................................................................................................... 142
19.4 askForOwnership........................................................................................ 143
19.5 claimOwnership .......................................................................................... 144
19.6 releaseOwnership ....................................................................................... 146
19.7 Notification onScanApiOwnershipChange................................................ 147
20 SoftScan feature...................................................................................................... 150
20.1 Usage ............................................................................................................ 150
20.2 iOS integration.............................................................................................. 151
20.3 Android integration....................................................................................... 152

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 7/152
1Scanner connection overview
This SDK is designed for use with the Socket CHS 7 series scanners on several
OS platforms including Apple iOS, Android, RIM, Windows Desktop and
Windows Mobile 6.x. The intended usage is to develop a native application that
includes built in support for the Socket 7 series scanners. This SDK gives the full
programmatic access to a connected 7 series scanner to customize the scanner
Symbology and data support, manages scanner feedback messages and
functions or modifies default scanner behavior.
Before beginning the process of implementing the ScanAPI into an application it
is first recommended reading through this intro regarding the connection process
of the scanner as this might answer many questions in regards to how an
application communicates with the scanner.
1.1 Scanner connection information
The connection information below applies mainly to the Android, RIM and
Windows operating systems.
For the iOS platform the connection is simplified based on the host iOS handling
the connection. It is recommended to refer to the readme.rtf file from the ScanAPI
SDK DMG install that is part of the ScanAPI iOS SDK..
1.1.1 Scanner HID mode
The CHS 7 series scanners are shipped by default in HID profile mode and will
display the following friendly name:
For the 7Xi series:
Socket 7Xi [xxxxxx] (where x’s are the last 6 digits of the BD address of the
scanner)
Or for the 7Ci/M/P series:
Socket CHS [xxxxxx]
In this mode the scanner functions as a standard HID keyboard device and can
be tested in this mode as if it is a keyboard.
It will NOT work with an application using ScanAPI.
NOTE: if the scanner in HID mode is discovered and tested it may cause conflicts

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 8/152
with discovering and using the scanner in SPP mode due to the fact that some
devices will cache the name and service information of the device.
Socket recommends that the pairing information is removed by deleting or
unpairing the device using the host device Bluetooth manager before connecting
the scanner in a different mode.
1.1.2 SPP Mode for the SDK
The SPP Mode is the required mode for the Scanner to be able to communicate
with an application using ScanAPI.
The SPP Mode has 2 configurations. One configuration called Acceptor, and
another called Initiator.
In Acceptor configuration, the scanner is discoverable and connectable and
basically waits for a host to connect. The scanner indicates that it is in this mode
by a slow blue LED flashing.
In Initiator configuration, the scanner knows the Bluetooth address of the host to
connect to.
Each time the scanner is powered on in this configuration, it will try to connect to
the host corresponding to the Bluetooth address it has in memory.
The scanner indicates that it is in this mode by a fast blue LED flashing. The
scanner stays in this mode until it successfully connects to the host or after a
2minutes timeout occurs, which it will signal by doing a long beep.
At this point the scanner can be powered off and on to retry to connect to the
host.
1.1.3 Initial connection to iOS host or to any host for a 7Ci,M and P
series
The process of connecting a scanner to an iOS host device or a 7Ci, M and P
scanner to any host device is the same and can be summarized to these simple
steps.
Step 1: The scanner must be in Acceptor mode.
For an iOS device, the scanner can be in configured in Acceptor mode by
scanning a barcode that has the value of “#FNC IOS ACCEPTOR
000000000000#” for a 7Xi or “#FNB00F40002#” for a 7Ci.
For any other host Device (not iOS) the scanner can be configured in Acceptor
mode by scanning a barcode that has the value of “#FNB00F40000#” for a 7 P,M
or Ci series, or “#FNC SPP ACCEPTOR 0000000000#” for a 7Xi series scanner.

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 9/152
The barcode can be a 2D barcode for a 7Xi scanner only.
Step 2: Discover and pair the scanner from the host.
By using the Bluetooth settings of your host device, discover and pair the
scanner. If a PIN code is request use “0000” (4 zeros) and the pairing should
complete.
For iOS host device this is the final step. The scanner can now be used by the
application using ScanAPI.
Step 3: (For all hosts but iOS devices) Instruct the scanner to connect back to the
host by using Socket EZ Pair application.
Once the scanner is configured correctly, it will always try to reconnect back to
the host each time it is powered on or back in range.
1.1.4 Simplified connection process to any host but iOS devices
There is a simplified process that can be used when the host Bluetooth device
address is known either by printing out barcode or by using 7xi with Socket
EzPair.
This process isn’t possible for iOS device as there is no API to retrieve the iOS
Bluetooth address and the iOS devices won’t authorize a scanner to connect
and pair unless the Bluetooth Settings page is displayed on the screen.
The following steps for 7Xi series is as simple as scanning a 2D barcode that has
the value: “#FNC SPP INITIATOR xxxxxxxxxxxx#” with xxxxxxxxxxxx replaced by
the host Bluetooth address, or by scanning out of the Socket EZ Pair screen the
2D barcode.
The same principle for 7 P, M and Ci series scanner, by scanning a Code 128
barcode that has the value: “#FNIxxxxxxxxxxxx#” with xxxxxxxxxxxx replaced by
the host Bluetooth address. NOTE the 7 P, M and Ci series scanner shoud be
first and only once set to SPP mode by scanning the “#FNB00F40000#” Code
128 barcode.
1.1.5 Connection Process integration
For the 7P, M and Ci series scanners there are two methods that canbe used to
configure the scanner to be an initiator to the host device:
Method 1:

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 10/152
Implement the 1D EZ Pair process in your app to select a pre discovered scanner
and configure it to be an initiator to the host device. This process is explained in
paragraph 8.6 Socket EZ Pair feature.
Method 2:
-Manually create an EZ Pair barcode with each host system Bluetooth address
so that the 1D scanner simply needs to scan the barcode to configure it as an
initiator to the host device
For the 7Xi series scanners you can just present the EZ pair barcode as part of
your application setup process.
Either way once that part is done your app just needs to have ScanAPI initialized
and waiting to receive the incoming connection of the scanner.
2ScanAPI Introduction
ScanAPI delivers an application programming interface (API) to control and
configure Socket Bluetooth Cordless Handled Scanners (CHS) connected to a host
computer.
A ScanApi Helper component is provided for Objective C, C# and Java platforms to
integrate more easily ScanAPI into an application. ScanAPI Helper handles the
asynchronous events through callbacks, and gives an easy way to manipulate the
asynchronous commands an application can send to a CHS by providing a callback
mechanism that is invoked when the command response is received.
A CHS has severall properties that can be retrieved, modified or actioned.
CHS properties can be by example a symbology state, its friendly name, or triggering
a scan.
This API is asynchronous. The property operation is therefore a 2-step process. The
application sends a property get or set command and if this is successful, a property
get or set complete event is received with the CHS result of that property command.
At any time a CHS can send events to the host that are retrieved using the same
mechanism as the completion of the property operation.
ScanAPI has only one entry point to receive these asynchronous events making it
very easy to manage.
The other benefit of this asynchronous API is to be able to drive a scanner from a
graphical user interface (GUI) application without danger of blocking the user
interface while waiting for a lengthy operation to complete.

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 11/152
3 SoftScan Feature
The SoftScan is a feature that makes the host device built-in camera acting as a
barcode scanner. This feature is implemented using third-party technology and
therefore the developer should comply to the third-party license agreement.
Currently the SoftScan feature is available on for iOS and Android based devices.
This feature is not activated by default. In order to activate it, the application should
set the ScanAPI kSktScanPropIdSoftScanStatus to kSktScanEnableSoftScan. As soon
as ScanAPI is initialized and SoftScan is enabled, a SoftScanner device arrival event
is generated.
A device removal event is generated when the SoftScan feature is disabled by using
the same ScanAPI property with its value sets to kSktScanDisableSoftScan.
The SoftScanner doesn’t support all the properties described in this document and
returns a ESKT_NOTSUPPORTED error for them.
3.1 Licensing requirements
The third-party used for implementing the SoftScan feature is RedLaser from eBay
corporation. The RedLaser requires a license to be purchased in order to offer
unlimited scan. Without the license the SoftScanner is limited to 25 scans on a
particular host.
The License should be purchase on RedLaser portal, and the license file should be
part of the application package.
3.2 iOS requirements
The ScanAPI library for iOS is split in to 2 versions; one that supports the SoftScan
feature and one that doesn’t.
In the version that doesn’t support the SoftScan feature the required frameworks
are:
-externalAccessory.framework
-audioToolbox.framework
In the version that does support the SoftScan feature the extra frameworks required
are:
-QuartzCore.framework,
-CoreVideo.framework,
-CoreMedia.framework,
-CoreGraphics.framework,
-AVFoundation.framework,
-OpenGLES.framework,

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 12/152
-Security.framework,
-libiconv.dylib,
-libstdc++.dylib or libstd++6.0.9.dylib if you’re using OS6.x SDK.
3.3 Android requirements
The overlay view is a requirement for the SoftScanner in order to display the video
output in the application. This is implemented through an Activity that must be
added to the application manifest. This activity is defined as
com.SocketMobile.ScanAPI.SoftScanActivity.
The manifest should also have the following permissions:
-android.permission.CAMERA,
-android.permission.ACCESS_NETWORK_STATE
-android.permission.INTERNET
A specific layout should be created that will be displayed as the overlay view of the
SoftScan. This layout can have a white rectangle that is called a “View Finder” that is
used as a scanning guide but also is use by the softscan scanner to improve the
barcode recognition in this region. The “View Finder” ID can be passed in the hash
table of the kSktScanPropIdOverlayViewDevice property. A flash button can be
added as well and its ID should be also specified in the same hash table of the same
property. If the flash feature is not available the SoftScan scanner will disable it
automatically.
The RedLaser libraries must be added to the Android application. The simplest way
for doing this is to copy the redlasersdk.jar and the armeabi/libredlaser.so in the
“libs” directory of the Android application. That “libs” subdirectory is automatically
taking in consideration by Android Development tools (ADT 18 or higher).
4Concept
This API defines 3 main objects: ScanAPI object, Device object and ScanObject.
4.1 ScanAPI object
This object controls the API.
In order to use ScanAPI, this object must be opened first and this first open
initializes ScanAPI. The handle returned from this open must be used for any
subsequent ScanAPI operations.
All asynchronous events are received through this ScanAPI object.

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 13/152
The ScanAPI object has few properties that can be retrieved or modified.
When an application is ready to use ScanAPI, it can open it by using the ScanAPI
Open API with no device name in the parameter.
4.2 Device object
The Device object represents a CHS. In order to use and receive events from a CHS,
its corresponding Device object must be opened.
The handle returned from opening a Device object is used by the application to
retrieve or modify a particular property of the CHS.
ScanAPI notifies the application each time a Device Object is available by sending a
Device Arrival event with a UUID identifying the Device Object. The application can
open this particular Device Object by specifying this UUID in the ScanAPI open API.
If a CHS disconnects from the host, a Device Removal is sent by ScanAPI to the
application to indicate that the matching Device Object is no longer valid and the
application should close it if it has it opened.
4.3 ScanObject
The ScanObject is a data placeholder used for exchanging information between the
application and the CHS or ScanAPI object.
A ScanObject holds 2 kinds of information: a property and a message.
When a ScanObject is sent from the application to ScanAPI, only the property
information in ScanObject is relevant.
When a ScanObject is received from ScanAPI by the application, the message
information is always relevant and depending on the message received the property
information might be relevant.
ScanAPI creates a ScanObject each time it receives an asynchronous event, and in
this case the application must release this ScanObject by calling a ScanAPI release
API.
The application can create a ScanObject to send specific information to either a
Device or ScanAPI. In this case the application is responsible for releasing the
ScanObject correctly.

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 14/152
4.4 Using ScanAPI
An application has two things to do in order to setup ScanAPI correctly. It needs first
to open ScanAPI by specifying no name in the open parameter API, and then starts
either a timer or a thread to consume the asynchronous events coming from
ScanAPI.
When a CHS connects to the host, ScanAPI sends a Device Arrival event to the
application through the application ScanAPI consumer logic.
The Device Arrival event contains an UUID identifying a Device Object that
represents a CHS. The application can open the Device Object by specifying this
UUID in the ScanAPI open function.
Once the Device Object is opened, the application can retrieve or modify the CHS
properties by using the get property or set property API.
The get property and set property APIs are asynchronous. These APIs return
success if the property has been sent correctly to the CHS. The property completion
event is received in the application consumer.
If the CHS doesn't respond to a get or set property within the timeout period (about
5 seconds), for whatever reason, a matching property get or set complete event is
generated with a timeout error.
Only one property can be sent at the time to the CHS. An error occurs if a property is
sent prior the completion of the previous property operation.
ScanAPI sends a Device Removal event when a CHS disconnects from the host. The
application should close the matching Device Object if it has it opened.
4.5 ScanAPI configuration
ScanAPI has one thread listening on a serial communication port. This configuration
can be retrieved or modified by creating a ScanObject and setting its property to
ScanAPI configuration property. The ScanObject can be sent to ScanAPI using the get
property or set property API to respectively retrieve or modify this property.
Modifying the ScanAPI configuration will prompt the listener thread to restart. An
error event is generated if the configuration is incorrect.
Each time the listener starts, a Listener Start event is generated.

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 15/152
ScanAPI drops the connection to a CHS if it was connected during the process of
changing the ScanAPI configuration.
Please refer to the ScanAPI object properties paragraph for more information.
4.6 Get or Set a property
The ScanAPI object and the Device object have both properties that can be retrieved
or altered by using the get property or set property API.
The process of getting or setting a property is simple. A ScanObject holds a Property
field. The application must create a ScanObject instance and fill its Property member
according to the property of the object it would like to modify.
A property has an ID, a data type,data value and a context. They must be specified
accordingly to the characteristics of the property that needs to be retrieved or
modified.
The context is a field an application can use for maintaining a context. This context is
returned when a property set or get operation completes.
Once the property member of the ScanObject has been filled correctly, the
application can call the get or set API with the reference of the object to which it
wishes to retrieve or modify the property.
If the API returns success, the application can wait for the completion to be received
through the wait API.
An application cannot send multiple properties to the same object before the
previous set or get property operation has been fully completed. An error is
generated during the Set or Get API call if the previous property of the same object
hasn’t been completed yet.
The application receives the complete event through its ScanAPI consumer logic that
uses the wait API with the ScanAPI object reference.
A ScanObject that is received from ScanAPI has always its message field filled out.
The property complete event is received in a ScanObject with a Message ID set to a
Get Complete ID or Set Complete ID.
The Message has a result field that indicates if the completion of the get or set
property has been successful or not. The Property member of the ScanObject
contains the Property ID matching to the one that has been set, and in case of
success, the data type and value are filled as expected.

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 16/152
An important point is the fact that a property set or get can fail for many reasons,
and some of them will require the application to retry the operation and some
should just be taken into consideration. For example, if a property returns a
REQUEST TIMEOUT error because the scanner is out of the range for a brief instant
or busy receiving decoded data, having retry logic can fix this issue.
4.7 Example of sending a command
This section describes the steps for sending a command to a device.
Let’s imagine an application using ScanAPI has a button on its UI to trigger a scan.
For clarity purposes we assume the application correctly handles the connection of
the scanner and has kept a handle to ScanAPI and to this scanner accessible.
The application has ScanAPI consumer logic that will receive the messages from
ScanAPI.
This consumer logic uses the wait API with the ScanAPI object reference that has
been previously opened with the open API with NULL as device name.
The button handler creates a ScanObject, and fills the Property part with a property
ID set to kSktScanPropIdTriggerDevice, a property type set to byte, and the property
byte value set to kSktScanTriggerStart as explained in the paragraph 14.5 Property
kSktScanPropIdTriggerDevice.
This button handler uses the set API to send this property to the device identified by
its reference. If the return code of this API is successful, the button handler can then
disable the trigger button indicating the trigger is in progress.
The application’s ScanAPI consumer logic that was waiting for ScanAPI messages by
using the wait API should receive the Set Complete message with the property ID set
to kSktScanPropIdTriggerDevice.
The result indicates if the trigger worked. At that point the device should have the
aim light turned on and should be ready to scan and decode data. The application
trigger button can then be enabled.
C++ Source code sample:
void CMyAppDlg::OnTriggerButton()
{
SKTRESULT Result=ESKT_NOERROR;
TSktScanObject ScanObj;
memset(&ScanObj,0,sizeof(ScanObj));

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 17/152
// initialize a ScanObject to
// trigger the device
ScanObj.Property.ID=kSktScanPropIdTriggerDevice;
ScanObj.Property.Type=kSktScanPropTypeByte;
ScanObj.Property.Byte=kSktScanTriggerStart;
// set the property with the
// device handle
Result=SktScanSet(m_hDevice,&ScanObj);
// check the Set result
if(SKTSUCCESS(Result))
m_TriggerBtn.Enable(FALSE);
else
{
// display an error message
DisplayError(_T("Unable to trigger: %d"),Result);
}
}
SKTRESULT CMyAppDlg::Consume(
IN SKTHANDLE hScanAPI,
IN unsigned long ulTimeoutInMilliseconds,
OUT BOOL* pbContinue)
{
SKTRESULT Result;
TSktScanObject* pSktObject=NULL;
Result=SktScanWait(hScanAPI,&pSktObject,ulTimeoutInMilliseconds);
if(SKTSUCCESS(Result))
{
if(Result!=ESKT_WAITTIMEOUT)
{
if(pSktObject)
{
switch(pSktObject->Msg.MsgID)
{
case kSktScanMsgIdDeviceArrival:
Result=HandleDeviceArrival(pSktObject);
break;
case kSktScanMsgIdDeviceRemoval:
Result=HandleDeviceRemoval(pSktObject);
break;
case kSktScanMsgIdTerminate:
// we are done with ScanAPI, somebody
// called SktSet with Abort MsgId
if(pbContinue)
*pbContinue=FALSE;// quit the for
TraceInfo(_T("Receive a Terminate Msg, \
then shutdown the App receiving \ thread"));
break;
case kSktScanMsgSetComplete:
case kSktScanMsgGetComplete:
Result=
HandleGetOrSetComplete(pSktObject);
break;

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 18/152
case kSktScanMsgEvent:
Result=
HandleAsynchronousEvent(pSktObject);
break;
default:
{
TraceInfo(_T("unknown Message ID \
received:0x%x"),
pSktObject->Msg.MsgID);
}
break;
}
// release the ScanObj we received in the wait
SktScanRelease(hScanAPI,pSktObject);
}
}
}
return Result;
}
// called from the ScanAPI consumer logic
// that is using SktScanWait API
void CMyAppDlg::HandleGetOrSetComplete(
IN TSktScanObject* pScanObj
)
{
switch(pScanObj->Property.ID)
{
case kSktScanPropIdTrigger:
// ungray out the trigger btn
m_TriggerBtn.Enable(TRUE);
if(!SKTSUCCESS(pScanObj->Msg.Result))
{
DisplayError(_T("Failed to trigger: %d"),
pScanObj->Msg.Result);
}
break;
}
}
C# source code:
public partial class Form1 : Form
{
private ISktScanApi _scanApi;
private ISktScanDevice _device;
public Form1()
{
InitializeComponent();
InitializeScanAPI();
}

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 19/152
private void buttonTrigger_Click(object sender, EventArgs e)
{
// create a ScanObject instance
ISktScanObject scanObj =
SktClassFactory.createScanObject();
// Initialize a ScanObject to
// Trigger the device
scanObj.Property.ID =
ISktScanProperty.propId.kSktScanPropIdTriggerDevice;
scanObj.Property.Type =
ISktScanProperty.types.kSktScanPropTypeByte;
scanObj.Property.Byte =
ISktScanProperty.values.trigger.kSktScanTriggerStart;
// set the property with the device
// reference
long result = _device.SetProperty(scanObj);
if (SktScanErrors.SKTSUCCESS(result))
{
buttonTrigger.Enabled = false;
}
else
{
// display an error message
DisplayError("Unable to trigger: " + result);
}
}
// timer to checking and consuming ScanObject from ScanAPI
private void timerScanAPIConsumer_Tick(object sender,
EventArgs e
{
ISktScanObject scanObj=null;
// wait for ScanAPI ScanObject
long result = _scanApi.WaitForScanObject(out scanObj, 10);
if (SktScanErrors.SKTSUCCESS(result))
{
if (result != SktScanErrors.ESKT_WAITTIMEOUT)
{
int propId = scanObj.Msg.ID;
switch (propId)
{
case ISktScanMsg.kSktScanMsgIdDeviceArrival:
result = HandleDeviceArrival(scanObj);
break;
case ISktScanMsg.kSktScanMsgIdDeviceRemoval:
result = HandleDeviceRemoval(scanObj);
break;
case ISktScanMsg.kSktScanMsgIdTerminate:
// we are done with ScanAPI, somebody

Socket ScanAPI Reference
© 2013 Socket Mobile, Inc. 20/152
// called Set with kSktScanPropIdAbort
// as Property ID
result = HandleTerminate(scanObj);
break;
case ISktScanMsg.kSktScanMsgGetComplete:
case ISktScanMsg.kSktScanMsgSetComplete:
result = HandleGetOrSetComplete(scanObj);
break;
case ISktScanMsg.kSktScanMsgEvent:
result = HandleEvent(scanObj);
break;
}
// release the ScanObject we received in the wait
_scanApi.ReleaseScanObject(scanObj);
}
}
}
private long HandleGetOrSetComplete(ISktScanObject scanObj)
{
long result = SktScanErrors.ESKT_NOERROR;
ISktScanProperty property = scanObj.Property;
switch (property.ID)
{
case ISktScanProperty.propId.kSktScanPropIdTriggerDevice:
// ungrey out the trigger button
buttonTrigger.Enabled = true;
result = scanObj.Msg.Result;
if (!SktScanErrors.SKTSUCCESS(result))
{
DisplayError("Failed to trigger: " + result);
}
break;
}
return result;
}
Java source code:
// handler for the Trigger button
class TriggerButtonHandler implements Runnable {
private ISktScanDevice _device=null;
private ButtonField _button;
// constructor
public TriggerButtonHandler(
ISktScanDevice device,
ButtonField button)
{
_device=device;
_button=button;
}