Socket Scanners Dk

8/14/2019 Socket Scanners Dk

1/76

SocketScan SDK Users Guide

&

ScanAPI: Scanning Application Program Interface

Document # 6410-00147 G

January 10, 2006


2/76

01/2006 Document # 6410-00147 G

Copyright Notice

Copyright 2005 Socket Communications, Inc. All rights reserved.

Socket, the Socket logo and Mobility Friendly are registered trademarks of Socket Communications, Inc.SocketScan, Cordless Hand Scanner with BluetoothWireless Technology, CF Scan Card, SD Scan Card, 2D ScanCard, Gun Scanner, Wand Scanner, CF RFID Reader Card, and CF RFID Reader-Scan Card are trademarks ofSocket Communications, Inc. All other brand and product names are trademarks of their respective holders.

Reproduction of the contents of this manual without the permission of Socket Communications is expresslyprohibited. Please be aware that the products described in this manual may change without notice.

Feel free to contact SOCKET COMMUNICATIONS at:

Socket Communications, Inc.37400 Central CourtNewark, CA 94560

Other than the above, Socket Communications can assume no responsibility for anything resulting from theapplication of information contained in this manual.

You can track new product releases, software updates and technical bulletins by visitingt: www.socketcom.com.

Socket Communications, Inc. January 27, 2006 Page 2Document#: 6410-00147 G Revision 2.24


3/76

Revision History

Revision Date Autho r Comments

1.00 10/26/1999 G. Cuevas, L. Ott Genesis.

1.01 11/01/1999 G. Cuevas, J. Houston Updated registry section; added correct doc number; cleaned up typos,etc.

1.02 11/02/1999 G. Cuevas, L. Ott Additional corrections.

1.03 11/04/1999 G. Cuevas Changed keyboard wedge product name to SocketScan.

1.04 11/04/1999 G. Cuevas Corrected registry entry section.

1.05 11/13/1999 G. Cuevas Updated for disk layout change.

2.00 03/29/2000 G. Cuevas Additions for Win32 Desktop, Preview DLL, Bar Code Wand.

2.01 05/06/2000G. Cuevas, P. Subbaraya,J. Houston

General edits and corrections.

2.02 05/10/2000 G. Cuevas, P. Subbaraya Additional edits.

2.03 05/12/2000 G. Cuevas, P. Subbaraya Additions and corrections.

2.04 05/15/2000G. Cuevas, P. Subbaraya,J. Houston Minor edits.

2.05 05/17/2000 G. Cuevas, P. Subbaraya Minor edits.

2.06 05/23/2000 G. Cuevas, P. Subbaraya Additional minor changes.

2.07 12/11/2000 G. Cuevas Updates for HPC 2000, Windows 2000 and Windows Me.

2.08 12/20/2000 G. Cuevas, M. Man Minor edits.

2.09 12/20/2000 G. Cuevas Minor edits.

2.10 9/27/2001 T. NewmanChanges for SocketScan 3.2

Added ScanGetStatus() API call (WinCE).Polling calls from Embedded Visual Basic (EVB). Minor edits to API calls.

2.11 12/17/2002 D. Acquistapace Added ScanParamSend and ScanParamRequest API calls (WinCE).

2.12 12/23/2002 P. SubbarayaChanges for SocketScan 4.0 to support the 2DSC for bar code. Minoredits

2.13 07/11/2003 P. SubbarayaChanges for SocketScan 4.0 to support the 2DSCScanSendCommand() API call(WinCE.)

2.14 01/22/2004 P. SubbarayaChanges for SocketScan 4.1.xx to support DriverMan registry structure.Minor edits.

2.15 08/11/2004 D. Singh, S. Gutti Updated CHS information, modified desktop information

2.16 08/30/2004 T. Newman RFID Reader functions added

2.17 10/28/2004 S. Gutti Updated CHS information for Windows XP.

2.18 11/16/2004 D. Singh Added SDK QuickStart guide

2.19 12/08/2004 D. Singh Update ScanGetData() details and Section 4 and 12 for specific DLLs

2.20 01/07/2005 S. GuttiAdd new APIs for CHS configuration commands in Section 8.0 & 9.0 andupdated registry entry section

2.21 03/17/2005 S. Gutti Updated ScanEnableCHS() & ScanDisableCHS() APIs2.22 06/09/2005 S. Gutti Added new APIs to handle Symbologies for all Scanners

2.23 09/23/2005A. Hersh, D. Singh,T. Newman, M. Man

Added CF RFID Reader-Scan Card APIs, CHS programming info, andSocketScan Trigger Applications

2.24 01/10/2006 A. HershMinor edits to reflect WM 5.0 support, Mag Stripe Reader and CordlessRing Scanner.



4/76

Table of Contents

1.0 Introduction ..........................................................................................................................71.1 SDK QuickStart Guide.................................................................................................7

2.0 Revision Notes .....................................................................................................................82.1 Windows CE................................................................................................................82.2 Windows Desktop/Notebook .......................................................................................8

3.0 Using ScanAPI ...................................................................................................................103.1 SDK Initialization/De-initialization..............................................................................103.2 Device Control...........................................................................................................103.3 Scanner Data Access................................................................................................103.4 Miscellaneous Utility..................................................................................................113.5 Cordless Scanner Specific Functions........................................................................113.6 RFID Specific Funtions..............................................................................................11

4.0 Setting Up The Target Device............................................................................................124.1 Setting up Windows CE Devices...............................................................................124.2 Setting up Win32 Desktop Systems ..........................................................................13

5.0 Writing Your Application.....................................................................................................145.1 Preview DLL ..............................................................................................................155.2 RFID Demo ...............................................................................................................155.3 ScanApiTester...........................................................................................................155.4 ScanApiTester...........................................................................................................15

6.0 Soft Triggering....................................................................................................................167.0 ScanAPI Type Reference...................................................................................................178.0 ScanAPI Function Reference.............................................................................................20

8.1 ScanInit() ...................................................................................................................208.2 ScanOpenDevice() ....................................................................................................228.3 ScanCloseDevice()....................................................................................................238.4 ScanGetDevInfo()......................................................................................................248.5 ScanGetStatus()........................................................................................................268.6 ScanRequestDataEvents()........................................................................................278.7 ScanTrigger() ............................................................................................................298.8 ScanAbort() ...............................................................................................................318.9 ScanGetData() ..........................................................................................................32



5/76

8.10 ScanSetGoodReadSound().......................................................................................348.11 ScanDeinit()...............................................................................................................358.12 ScanErrToText()........................................................................................................368.13 ScanParamSend().....................................................................................................378.14 ScanParamRequest()................................................................................................398.15 ScanSendCommand()...............................................................................................408.16 ScanParamSendEx().................................................................................................418.17 ScanParamRequestEx()............................................................................................438.18 IsScannerConnected() ..............................................................................................448.19 IsScannerConnectedEx() ..........................................................................................448.20 ScanEnableDisableSymbology()...............................................................................458.21 ScanReadSymbologyConfig() ...................................................................................468.22 ScanWriteSymbologyConfig() ...................................................................................478.23 ScanEnableMultiScanner()........................................................................................478.24 ScanGetScannerRegKey () .......................................................................................488.25 Sample symbology config code:................................................................................49

8.25.1 Sample Code to Enable or Disable CODE39 symbology:.............................498.25.2 Sample code for Read configuration: ............................................................498.25.3 Sample Code to Enable or Disable CODE39 symbology:.............................50

9.0 Cordless Scanner (CS) Specifics.......................................................................................519.1 ScanEnableCHS() .....................................................................................................529.2 ScanDisableCHS() ....................................................................................................539.3 ScanSendCmdtoCHS() .............................................................................................549.4 BluetoothConnection Status.....................................................................................569.5 CHS Commands .......................................................................................................57

9.5.1 Set Security Mode .........................................................................................579.5.2 Set Friendly Name.........................................................................................579.5.3 Set PIN Code.................................................................................................57

9.6 CHS Control commands............................................................................................589.6.1 Set Indicators.................................................................................................589.6.2 Battery Charge State Inquiry .........................................................................589.6.3 Battery Charge State Response ....................................................................589.6.4 Friendly Name Inquiry ...................................................................................589.6.5 Friendly Name Response ..............................................................................59

9.7 Registry Settings for the Cordless Hand Scanner .....................................................60 Socket Communications, Inc. January 27, 2006 Page 5Document#: 6410-00147 G Revision 2.24


6/76

10.0 RFID Reader ......................................................................................................................6211.0 MultiScanner Support (WIN CE ONLY) .............................................................................63

11.1 Registry Settings for the CF RFID Reader-Scan Card ..............................................6312.0 Using SocketScan (Keyboard Wedge)...............................................................................6513.0 SocketScan Trigger Applications (WINCE ONLY) .............................................................66

13.1 Triggering Details ......................................................................................................6713.2 Changing the Active Scanner....................................................................................67

14.0 The DriverMan dll ...............................................................................................................6915.0 Installation ..........................................................................................................................70

15.1 Installation Procedure................................................................................................7015.1.1 WinCE Sample: SocketScan for a Pocket PC with an ARM processor:........70 15.1.2 WinCE Sample: ScanAPI only for a Pocket PC with an ARM processor: .....7015.1.3 Windows Desktop/Notebook Installation: ......................................................70

15.2 Registry Entries .........................................................................................................7215.2.1 Windows CE Registry Entries........................................................................7215.2.2 Win32 Desktop/Notebook Registry Entries....................................................7215.2.3 Other Registry-Related Considerations.........................................................73

15.3 Implementing a SocketScan Preview DLL ................................................................7416.0 Implementing a SocketScan Application in .NET...............................................................76



7/76

1.0 INTRODUCTION

Socket Communications ScanAPI is a set of Windows CE and Win32 Desktop DLLs that offer access to Socketsline of data collection products. By using the ScanAPI, applications can easily perform the following:

Receive notification of the insertion or removal of a scanning device

Determine the type and properties of scanning devices inserted

Trigger (and abort) scanning on supported devices that do not have a hardware trigger

Receive notification of data available from the scanner

Configure end-user good-read acknowledgement using a beep or by playing a .wav file

Since ScanAPI returns the data block read from the scanner, it is a simple matter for applications to pre-processthe data before its final disposition. Applications may add a prefix or a suffix to the data, and perform any otherapplication-specific character translations, insertions or deletions, if desired.

Included in this Developers Kit is a version of Sockets keyboard wedge software, called SocketScan, which isbased on the ScanAPI. Its features include:

Recognition of Sockets entire line of scanning products

Flexible addition of prefix and/or suffix to the scanned data

Configuration of a good-read acknowledgement sound

A silent mode allowing VARs to run the wedge software in the background, making it invisible to the user (forWindows CE only)

Registry entries allowing VARs to configure the prefix, suffix, sounds, and other properties at install-time usingtheir own custom installer

A Preview DLL can be registered with the wedge, allowing developers to preview and modify data scanned bythe user

All binary files for the SocketScan program are supplied and may be freely distributed by the Developer, for usewith Socket scanner products. The documentation supplied is protected via copyrights held by their respectiveowners and cannot be distributed without written permission.

The term scanned data is used throughout this document and generally describes data scanned from a bar codeor data returned from reading a RFID tag.

1.1 SDKQUICKSTART GUIDE

1) Read Chapters 3 and 8 of this Users Guideto understand the Scanner APIs2) Read Chapter 5 to understand the sequence of events and messages for the API3) Based on your requirements, examine the Sample code provided in the Source\ScanApiTester

4) Read Chapter 6 to learn how to trigger your scanner5) Read Chapters 4 and 12.3 to understand DLL and registry requirements.

You should now be ready to add support for any of Sockets scanner products to your Windows application.

If needed, refer to Section 12.2 for a sample of how install your application on the target device.



8/76

2.0 REVISION NOTES

Although ScanAPI is simple and minimal,it is still designed for future expansion while being backward compatiblewith existing applications. For example, the ability to support multiple scanners simultaneously could be added ifdevelopers require this feature. In the event of adding such functionality, the existing API function interfaces wouldremain unchanged.

WARNING:Do NOT attempt to change any communication protocol settings or scan any Set All Defaultsprogramming bar code with any Socket scanner product un less instructed to do so by Socket TechnicalSupport.

IMPORTANT: ScanAPI currently assumes that the communication parameters for the scanning devices have notbeen changed from their factory defaults. If the baud rate, word size, etc. have been changed from the factorydefaults, they will have to be manually restored before the device will work with ScanAPI. If this happens to the CFScan Card, SD Scan Card or 2D Scan Card, it must be returned to the factory to restore default communicationsettings. The SocketScan keyboard wedge program also expects that the attached scanning device has not beenprogrammed to produce prefix or suffix characters.

The SocketScan keyboard wedge application supplied with the SDK offers a powerful feature for developers. APreview DLL can be written and registered with the SocketScan application. This DLL will see the block of

scanned data before the data is submitted to the keyboard buffer. This provides the developer an opportunity tovalidate, pre-process or perform various other modifications on the scanned data. In cases where the keyboardwedge software is very close, but not quite perfect for your custom applications scanning solution, we believe thisnew feature may provide many with the opportunity to make it so quickly, simply and effectively.

If you plan to deploy a large number of scanners along with your application, contact Socket Communications toexplore the possibility of having the scanners programmed to your specifications during manufacturing. We canensure certain symbologies are enabled or disabled and we can pre-program devices in various other ways to suityour needs.

2.1 WINDOWS CE

This release includes support for Windows CE 3.0 devices up to Windows CE 5.0.

The following Bar code scanning products are supported: CF Scan Card (CFSC), SD Scan Card (SDSC),2D Scan Card (2DSC), Gun Scanner, Laser Scanner System with LS2104 (Discontinued), CordlessHand Scanner with BluetoothWireless Technology (CHS), Cordless Ring Scanner with BluetoothWireless Technology (CRS) and Wand Scanner. The Cordless Hand Scanner (CHS) and Cordless RingScanner (CRS) are supported only on PPC 2003 and above.

Support for Sockets CF RFID Reader Card and CF RFID Reader-Scan Card has been added to thisrelease. These products can read most of the ISO 15693 High Frequency (13.56MHz) RFID tagsavailable. Refer to the RFID SDK documentation for more information.

You will be unable to develop scanning applications for a Handheld PC 2.00, Palm-size PC or Pocket PCv2.11 devices with this release of the SDK. Contact Socket Communications Technical Support [email protected] obtain release 1.0 of the Scanner SDK to develop for these older,

discontinued devices.

2.2 WINDOWS DESKTOP/NOTEBOOK

This release supports the CF Scan Card, Gun Scanner, Laser Scanner Systems with LS2104(Discontinued) and Cordless Hand Scanner on Windows XP and XP Tablet computers.

Note:The RFID Reader and RFID-Scan card are not current ly supported in the WindowsDesktop/Notebook version.

mailto:[email protected]:[email protected]


9/76

Starting from this Desktop Release v3.7, SocketScan application support for Win 95, 98, Me and NTplatforms will be discontinued. Scanner products may run on these older devices, but compatibility is nolonger verified or guaranteed.

This release includes support for Windows XP. Full hot-swapping support is present for Windows XP.



10/76

3.0 USING SCANAPI

The ScanAPI SDK offers API calls that are grouped into the following categories:

The ScanAPI.DLL file is written in C++. This file can only be used in development environments that can directlycall Win32 DLLs and process Windows messages. At this time there is no support for Java.

3.1 SDKINITIALIZATION/DE-INITIALIZATION

ScanInit()initializes the ScanAPI DLL and allows the client to register for device insertion andremoval messages

ScanEnableMultiScanner()enables multiple scanners

ScanDeinit()closes any open scanning devices and performs clean-up in the DLL pendingshutdown

3.2 DEVICE CONTROL

ScanOpenDevice()opens a scanning device for use

ScanCloseDevice()closes a scanning device

ScanGetDevInfo()returns a structure giving device identification and capabilities

ScanSetGoodReadSound()allows the selection of a sound to be made when the user scans data

ScanGetStatus()returns current status of the scanner

ScanParamSend()modifies a parameter of the scanner (CFSC/SDSC/CHS only)

ScanParamRequest()retrieves a parameter of the scanner (CFSC/SDSC/CHS only)

ScanParamSendEx() modifies a 2 byte parameter of the scanner (CFSC/SDSC/CHS only)

ScanParamRequestEx()retrieves a 2 byte parameter of the scanner (CFSC/SDSC/CHS only)

ScanSendCommand() sends a command to the 2DSC (2DSC only)

3.3 SCANNER DATAACCESS

ScanRequestDataEvents()allows the client to register for scanned data notifications

ScanTrigger()initiates a scan (soft-trigger) usually for a scanner with no hardware trigger(CFSC/2DSC/SDSC) or a Select Tag for the RFID reader and also works with the CHS

ScanAbort()aborts a scan on a TAG read if one is in progress

ScanGetScannerRegKey()returns the scanners active key or driver key

ScanGetData()retrieves scanned data



11/76

3.4 MISCELLANEOUS UTILITY

ScanErrToText()can be used to translate ScanAPI error codes to human-readable text

IsScannerConntected() Check if the scanner is connected and open for communications

IsScannerConnectedEx() Checks if a specified scanner is connected

3.5 CORDLESS SCANNER SPECIFIC FUNCTIONS

ScanEnable() activates the Cordless Scanner (CS) and loads its driver

ScanDisable() deactivates the Cordless Scanner and unloads its driver

ScanSendCmdtoCHS() sends the Cordless Scanner configuration commands

3.6 RFIDSPECIFIC FUNTIONS

ScanRFIDSelectTag()select one or more tags

ScanRFIDReadTag()read one or more data blocks from a tag

ScanRFIDGetData()get the response and data from a Select, Read, or Write tag command

ScanRFIDWriteTag()write one or more data blocks to a tag



12/76

4.0 SETTING UP THE TARGET DEVICE

Whether you are developing for Window CE or for Win32 Desktop systems, setting up the target device is similar.

4.1 SETTING UP WINDOWS CEDEVICES

On the target CE device, the file ScanAPI.DLL must be present in the \Windows directory. Additionally,you must copy one or more device driver files to the \Windows directory to support the scanningdevice(s). The files and devices to choose from are:

COMMON REQUIRED FOR ALL:

DRIVERMAN.DLL required for sequencing of driver startup

SCANAPI.DLL, SDK API

RFIDSETUP.DLL

HHPIMGRSDK.DLL

CF RFID READER CARD:

RFIDSCAN.DLL, which supports the RFID Reader

DIO_SCAN.DLL, serial protocol driver for RFID reader

CF RFID READER-SCAN CARD: RFIDSCAN.DLL, supports the RFID Reader

DIO_SCAN.DLL, serial protocol driver for RFID reader

RFIDSETUP.DLL controls parameters for ScanTrigger (tag reading)

ISC.DLL, provides support for the CF Scan Card

CF SCAN CARD:

ISC.DLL, provides support for the CF Scan Card

SIO_SCAN.DLL, serial protocol driver

SD SCAN CARD:

SD_SIO.DLL, SDIO serial protocol driver

ISC.DLL, provides support for the SD Scan Card

SD_STUB.DLL

Cordless Hand/Ring Scanner:

CHSDRIVER.DLL provides support for CHS/CRS communication (PPC 2003 and above)

CHSCPAPP.CPL, control panel applet to configure Bluetoothconnection with the CHS/CRS.

SBDDRIVER.DLL

ScktVirtualSerialPort.dll

GUN SCANNER:

GUNSCANNER.DLL, which provides support for the Gun Scanner

WAND SCANNER

GENSCAN.DLL, which supports the Wand Scanner

2D SCAN CARD

HHPIMGRSDK.DLL, provides support for the 2D Scan Card(for bar codes only )

COMDRV.DLL, serial interface for the 2D Scan Card (for bar codes only ) SIO_SCAN.DLL

CF Mag Stripe Reader Card:

MagStripe.DLL, provides support for the CF Mag Stripe Reader Card

SIO_SCAN.DLL, serial protocol driver



13/76

Several registry entries are necessary to associate the driver DLLs with the Socket scanning products.These registry entries are documented in the file CeReg.txt (in the Driver+SDK Binaries subdirectory ofthe distribution CD.)

If you install the SocketScan program to your target CE device, all necessary API and driver files will beinstalled and configured. SocketScan will run on the Microsoft Pocket PC and Windows CE platformsversion 3.0 or higher. Before installing SocketScan, uninstall any previously installed scanner software,including the In-Hand Scanner program (supplied with the initial shipments of the CF Scan Card) on thetarget CE device. Also uninstall any legacy versions of Sockets Wand Scanner programs from the targetdevice, if present.

Installing SocketScan will install all the DLLs and set up the proper registry entries but it should not beused for installing the final users application program because it can confuse the user with additionalprograms and Icons. The developer should follow the guidelines listed in this SDK guide to can create aninstaller which will setup only the applications, drivers, and registry entries needed to support theapplication.

*** It is recommended that SDK users determine exactly which DLLs and registry settings are required fortheir application rather than blindly using all Socketscan DLLs and settings ***

4.2 SETTING UP WIN32DESKTOP SYSTEMS

On the target system, the files ScanAPI.DLL and ScanHook.DLL must be present in the systemdirectory, typically C:\Windows\System32 or C:\WinNT\System32. Additionally, you must copy one ormore device driver files to the system directory to support the scanning device(s). The files to choosefrom are:

COMMON REQUIRED FOR ALL:

SCANHOOK.DLL required for handling global keyboard hook

HOTSWP2K.DLL, For Hot swap functionality.

SCANAPI.DLL, SDK APICF SCAN CARD:

ISC.DLL, which provides support for the CFSC

CHS:

CHSDRIVER.DLL required for CHS communication (PPC2003 and above)

SCKTSCAN.CPL, control panel applet to configure Bluetoothconnection with the CHS scanner.

GUN SCANNER:

GUNSCANNER.DLL, which provides support for the Gun Scanner

WAND SCANNER:

GENSCAN.DLL, which supports the Wand Scanner

2D SCAN CARD

HHPIMGRSDK.DLL, provides support for the 2D Scan Card

COMMDRV, serial interface for the 2D Scan Card

Several registry entries are necessary to associate the driver DLLs with the Socket scanning products.These registry entries are described in detail, please see section 12.3.2

If you install the SocketScan program to your target system, all necessary API and driver files will becompletely installed and configured.

http://socketscance/SDK/Driver+SDK%20Binaries/CEReg.txthttp://socketscance/SDK/Driver+SDK%20Binaries/CEReg.txthttp://socketscance/SDK/Driver+SDK%20Binaries/CEReg.txthttp://socketscance/SDK/Driver+SDK%20Binaries/CEReg.txt


14/76

5.0 WRITING YOURAPPLICATION

Applications that use ScanAPI must include the ScanAPI.h file in their project, and must either link to theappropriate ScanAPI.lib file supplied with the SDK or use GetProcAddress() to access the functions. The .h and .libfiles are located in the ScanSDK subdirectory of the distribution CD. The Win32-based sample applicationssupplied on the CD assume that you have copied the \ScanSDK (and all subdirectories) directly from the root of theCD to the root of your development drive. If you choose to copy this directory somewhere other than the root of

your development drive, you will have to change the Win32 sample application settings accordingly before you cansuccessfully recompile them.

Two windows messages must be defined, within the WM_USER range defined by Windows that will be sent to theapplication when scanning devices are inserted or removed. This document generically refers to these messagesas wmInsertion (or WM_INSERTION) and wmRemoval (or WM_REMOVAL). You must also choose a window thatwill service these messages, typically the main window of your application. Use the window handle and the twomessages as arguments to ScanInit(). You must call ScanInit() before using any other ScanAPI function calls.Upon a successful call to ScanInit(), your window will begin receiving WM_INSERTION and WM_REMOVALmessages, as appropriate, when a scanner is inserted or removed from the host device. You will likely get aWM_INSERTION immediately if a scanning device is present when the ScanInit() function call is made.

Note: If your application gets a SR_TOO_MANY_USERS error from ScanInit(), you may have ScktScan.exe

(keyboard wedge) running. You need to close the program before running your ScanAPI application program.

Message handlers must be written for your WM_INSERTION and WM_REMOVAL messages. TheWM_INSERTION handler should save the ScanAPI-assigned scanner handle (provided in lParam), then callScanOpenDevice() using the scanner handle. Upon success, you would use ScanGetDevInfo() if you are interestedin the type of scanner that was inserted, and optionally use ScanSetGoodReadSound() if you do not like the defaultsound, which is to produce a MessageBeep(0) when a successful scan is completed. For multiple devicesScanOpen()/ScanClose() should be called with the appropriate scanner handle.

The message handler for WM_REMOVAL should first check that the scanner handle returned in lParam is, in fact,the handle of the scanner the application is currently aware of, then call ScanCloseDevice(). This release ofScanAPI supports multiple scanners in this case, multiple WM_INSERTION and WM_REMOVAL message areseen, each with a different scanner handle supplied in lParam. If you do not require multiple scanners there is no

need to call ScanEnableMultiScanner(). If an application wants to ignore multiple scanners, it can simply save thehandle of the first scanner it sees in a WM_INSERTION message and ignore all other WM_INSERTIONs.

Scanning applications will not be able to receive data until ScanRequestDataEvents() is called. A simple scanningapplication will define a third windows message, which this document generically refers to as wmScannerData (orWM_SCANNERDATA). This message is supplied along with the handle of the window you want to process thismessage. The handler for the WM_SCANNERDATA message will take the scanner handle (supplied in lParam)and the size of the data (supplied in wParam), then call ScanGetData(). The data retrieved can then be validated,pre-processed if desired, then sent to an edit control, a list box, or dispatched in any manner the applicationdesires.

A simple application would probably call ScanRequestDataEvents() as part of the WM_INSERTION messagehandler. Since this registration is nullified whenever the scanning device is closed, it is necessary to callScanRequestDataEvents() again at some point when the device is re-opened.

A more complex application may want to dynamically change the window that will process theWM_SCANNERDATA message, and may even want to change the actual message to be received. This can bedone simply by calling ScanRequestDataEvents() again when you want the change to take effect. You cantemporarily ignore all scanned data, if desired, by supplying NULL as the hWnd argument toScanRequestDataEvents().

When your application closes down, it should call ScanDeinit(). This function will close all open scanning devices,making it unnecessary for you to call ScanCloseDevice() when you shut down.



15/76

All ScanAPI function calls return SR_SUCCESS if the function succeeds. If a failure occurs, the error returned bythe ScanAPI library can be translated to text using the ScanErrToText() function. This function translates the errorcode into fairly technical jargon and, while this may be useful during software development, the text may not besuitable for display in an end-user application. Since the error messages are located within a string resource that isbound to the ScanAPI DLL file, you may change the wording of these error messages, or translate the messages todifferent languages if desired, using a resource editing tool.

The \Source directory of the distribution CD contains several sample programs that can be found in the followingsubdirectories:

5.1 PREVIEW DLL

This project demonstrates how to create a SocketScan Preview DLL.

5.2 RFIDDEMO

This project demonstrates the usage of the RFID specific API calls.

5.3 SCANAPITESTER

This project demonstrates the usage of the ScanAPI.

5.4 SCANAPITESTER

This application demonstrates how to send a trigger message directly to the ScanAPI library.



16/76

6.0 SOFT TRIGGERING

Soft triggering is different from local and remote triggering options. This is a means to trigger a scan on a scannerthrough software; however, this feature is not applicable to all scanners. It is supported in the CFSC, SDSC,2DSC, CHS and RFID Reader. Soft-triggering is enabled within your application via a function key or a button that,when clicked, calls the ScanTrigger() function.

Depending on how your application is designed, some developers may want to assign a hardware button on thehost CE device as the trigger, or a function key on Win32 Desktop systems as the trigger, but find it necessary tohave this mechanism separate from the application that is directly using the ScanAPI. Since only one executable isallowed to use the ScanAPI at any given time, one way to accomplish this is to write a custom message handler inyour application that will handle a WM_SCAN message that you define. The message handler for this WM_SCANmessage will call ScanTrigger(). You can then write a very small application that you can assign to one of thehardware buttons on the CE device, or a similar application for the Win32 Desktop environment that hooks thekeyboard to detect function key presses. This application should do a FindWindow() to find your applications mainwindow and send that window your WM_SCAN message.

Note that the gun scanners have hardware triggers, and the ScanTrigger() function will be ignored. ScanTrigger()is also ignored by the Bar Code Wand.

There is a sample triggering application available on the SDK CD. This sample takes the handle of the scanner asa parameter to the executable and can be used to trigger any scanner. It will also work with a .NET applicationsince it sends the message directly to ScanAPI.

The SocketTriggerScan and SocketTriggerRFID applications effectively function as the sample Trigger applicationwith the appropriate preferred handle passed in. Refer to Chapters 10 and 11 for more details.

NOTE: SocketTriggerSelect is only used with Socketscan.exe



17/76

7.0 SCANAPITYPE REFERENCE

The following excerpts are taken from ScanAPI.h. The brief explanations that follow the excerpts further documentthe purpose of the identifiers. Refer to the RFID SDK documentation for RFID-specific information.

// Types of Socket Scanner products

enum SCANNER_TYPE {SCANNER_NONE = 0, // no scannerSCANNER_CFCARD, // Socket In-Hand Scan CardSCANNER_WAND, // a wandSCANNER_GUN, // a gunSCANNER_ISCI, // an ISCISCANNER_CHS, // a CHS (cordless hand scanner)SCANNER_SDIO, // an SDIO scannerSCANNER_RFID, // an RFID scannerSCANNER_MAG_STRIPE, // a Magnetic Stripe ReaderSCANNER_CRS // a CRS (cordless ring scanner)

};

SCANNER_TYPE is a value that is fil led into the ScannerType field of the SCANDEVINFO structure (defined

below.) By checking this value, you can determine if the user has inserted a Gun Scanner, Wand Scanner, a CFScan Card, etc.

// Types of good-read sounds

enum GRS_TYPE {GRS_NONE = 0, // no good read soundGRS_MESSAGEBEEP, // play MessageBeep(0) on good readGRS_WAVFILE}; // play user-supplied .WAV file on good read

A GRS_TYPE variable is used as an argument when making a call to ScanSetGoodReadSound().

// Scanner device information structure

typedef struct tagSCANDEVINFO{DWORD StructSize; // size of the structureSCANNER_TYPE ScannerType; // gun, wand, integrated card or an imagerunsigned int fHardwareTrigger :1; // most likely a gununsigned int fSoftwareTrigger :1; // most likely an integrated cardunsigned int fSoftwareAbortTrigger :1; // most likely an integrated cardunsigned int fGoodReadLight :1; // most likely a gununsigned int fGoodReadSound :1; // most likely a gunTHCAR SymbolType; // the symbol type (UPC, Code 128, etc.) for last scan} SCANDEVINFO, *LPSCANDEVINFO;

The SCANDEVINFO structure is filled in when it is used in a call to ScanGetDevInfo(). You must fill in the size ofthe structure, using sizeof(SCANDEVINFO) before calling ScanGetDevInfo(), or an error will result. The rest of thefields have the following meanings:

ScannerType is as defined above.fHardwareTrigger will be TRUE if the device has its own hardware triggerfSoftwareTrigger will be TRUE if calling ScanTrigger() can trigger a scan on the devicefSoftwareAbortTrigger will be TRUE if calling ScanAbort() can abort a scan in progressfGoodReadLight will be TRUE if the device has a visual good-read indicator on-boardfGoodReadSound will be TRUE if the device makes a sound when data is successfully scanned



18/76

SymbolType is the code for the last bar code symbol scanned. The value is only valid for the CFSC, SDSC, CHS,and will be 0x00 if the symbol type is not available. This field is updated when ScanGetData() is called. Refer tothe Advanced Programming Guide for the list of bar code values.

// API return codes

enum SCAN_RESULT {SR_SUCCESS = 0,SR_INVALID_WMINSERTION,SR_INVALID_WMREMOVAL,SR_PLUG_THREAD_FAILURE,SR_DEVICE_THREAD_FAILURE,SR_INVALID_SCANNER_HANDLE,SR_OPEN_FAILURE,SR_INVALID_WMSCANNERDATA,SR_NO_DATA,SR_BUFFER_TOO_SMALL,SR_SCANNER_NOT_OPEN,SR_INVALID_SOUND_TYPE,SR_WAVFILE_NOT_FOUND,SR_MEMORY_FAILURE,

SR_INVALID_ERR,SR_TOO_MANY_USERS,SR_NOT_INITIALIZED,SR_DEVICE_FAILURE,SR_INTERNAL_FAILURE,SR_INVALID_STRUCTURE,SR_SCANNER_REMOVED,SR_UNSUPPORTED_FEATURE,SR_INVALID_WMCHSSTATUS,SR_NOT_CHS_DEVICE,SR_WAIT_TIMEOUT_ERROR,SR_SYMBOLOGY_NOT_SUPPORTED,SR_SCANNER_BUSY,

SR_HOTSWAP_ERROR, (Windows XP ONLY)SR_SCANNER_REMOVED,SR_INVALID_WMCHSSTATUS};

All ScanAPI function calls return SR_SUCCESS if the call was successful. If an error occurs, the return value willbe one of the other defined error codes.

Note that SR_HOTSWAP_ERROR is defined in the Win32 Desktop header file only andSR_SCANNER_REMOVED is defined in the WinCE header file only.

Also note that several of the return codes are classified as failures:

SR_PLUG_THREAD_FAILURE

SR_DEVICE_THREAD_FAILURESR_OPEN_FAILURESR_MEMORY_FAILURESR_DEVICE_FAILURESR_INTERNAL_FAILURE

If you receive one of these return codes, it means something has gone wrong internally in the ScanAPI DLL, thescanning device has experienced a failure (or unexpected removal), or there are too few resources available on thehost device to carry out the request. Any of the first 4 failures listed above may be correctable if the user is askedto close other programs that may be running on the device, thereby freeing up additional resources. A condition



19/76

that causes SR_DEVICE_FAILURE may be correctable if the user removes the scanner from the device and re-starts your application. SR_INTERNAL_FAILURE is a catch-all for unknown failures that may occur in the ScanAPIDLL. Again, it may be correctable by taking one of the actions already mentioned.

Receiving one of these return codes should be extremely rare. If one of the suggested courses of action does notcorrect the error condition, the user may be forced to remove the scanner from the CE device and perform a softreset, or restart the system if the failure has occurred on a Win32 Desktop platform. Please report to SocketCommunications Technical Support at http://www.socketcom.com/support/if you consistently receive one of theseerrors for no good reason you may be trying to use the API in ways we did not envision when we created it.

If you encounter a situation where the ScanAPI is returning no errors, but the scanned data is garbled or missing,the most likely cause is that the communication settings in the scanning device are not properly set. See theReadme.txt file for details on how to properly set the communication parameters for your particular device.

http://www.socketcom.com/support/http://www.socketcom.com/support/


20/76

8.0 SCANAPIFUNCTION REFERENCE

This section provides complete documentation of the 17 functions present in the ScanAPI DLL. Refer to the RFIDSDK documentation for information about the RFID-specific functions.

8.1 SCANINIT()

Prototype:SCAN_RESULT ScanInit(HWND hWnd, UINT wmInseriton, UINT wmRemoval);

Purpose:Performs initialization of the ScanAPI DLL and registers the client program to receive device insertionand removal notifications.

Arguments:[in] hWnd is the handle of the window you want to receive wmInsertion and wmRemoval messages. It istypically the main window of the client program, but it can be any window that is guaranteed to exist forthe duration of the client program execution.

If hWnd is 0, no Insertion or Removal Callback events will occur.

[in] wmInsertion is a message within the WM_USER range that the client wants to receive when a Socketscanning device is inserted into the host device.

[in] wmRemoval is a message within the WM_USER range that the client wants to receive when a Socketscanning device is removed from the host device.

Notes:Upon success, the ScanAPI DLL is initialized. If a Socket scanning device is present when this functionis called, the client application will immediately receive the message specified by the wmInsertionargument. If there is no scanning device present when this function is called, the application will receivethe wmInsertion message later, when the user inserts a scanning device.

When a client application receives WM_INSERTION or WM_REMOVAL messages, the lParam willcontain a scanner handle that must be used to open and close the scanning device, and to performvarious other operations on the device with the ScanAPI functions.

This scheme will allow a client application to use multiple scanning devices in future releases of this SDK,though at the present time notifications will be sent only upon the first scanning device insertion and itssubsequent removal. If more than one scanning device is present when the SDK is initialized, the SDKwill randomly choose one of the devices as being the supported device.

Returns:

SR_SUCCESSThe operation completed successfully.

SR_TOO_MANY_USERSIn this release of the SDK, only one client may use the ScanAPI DLL. Your application program willgenerally get this error if ScktScan.exe is running. You need to close the program before starting yourapplication.

SR_INVALID_WMINSERTIONThe specified wmInsertion message is not within the valid WM_USER range.

SR_INVALID_WMREMOVAL



21/76

The specified wmRemoval message is not within the valid WM_USER range.

SR_PLUG_THREAD_FAILUREAn internal error occurred, most likely due to unavailable resources on the host device. The device willprobably need to be reset, though the problem may be correctable if the user terminates other processeson the device and re-tries the operation.

SR_HOTSWAP_ERRORHotSwp32.dll failed to load or initialize. This error is only applicable to Windows 95, 98 or Me hostmachines. HotSwp32.dll is either missing or corrupt, has not been registered properly, or there areinsufficient system resources available to load the DLL. The ScanAPI will not be able to detect cardinsertion or removal events under these circumstances, so your custom scanning application will berendered inoperative.

SR_DEVICE_FAILUREMay occur as a result of calling ScanInit() on Windows NT systems only. An internal error occurred whilecommunicating with the scanning device (perhaps the device was removed during the function call.) Theclient application will probably need to be re-started, and possibly the Win32 Desktop system reset (afterfirst removing the scanning device from the host.)



22/76

8.2 SCANOPENDEVICE()

Prototype:SCAN_RESULT ScanOpenDevice(HANDLE hScanner);

Purpose:

Opens the scanner port and initializes the scanner for use.

Arguments:[in] hScanner is the value received by the client application in lParam of the WM_INSERTION messagespecified when ScanInit() was called.

If the application program doesnt support callbacks, use 1 for the HANDLE (if multi-scanner disabled) .

Notes:Scanners must be opened before being used. Typically a client program will call ScanOpenDevice() aspart of the message handler for the WM_INSERTION message (from ScanInit() ).

Returns:


SR_NOT_INITIALIZEDA successful call to ScanInit() must be made first.

SR_INVALID_SCANNER_HANDLEThe hScanner argument is not a valid scanner handle.

SR_OPEN_FAILUREThe ScanAPI DLL was unable to open the device.

SR_DEVICE_THREAD_FAILUREAn internal error occurred, most likely due to unavailable resources on the host device. The device willprobably need to be reset, though the problem may be correctable if the user terminates other processeson the device and re-tries the operation.

SR_DEVICE_FAILUREAn internal error occurred communicating with the scanning device (perhaps the device was removedduring the function call.) The client application will probably need to be re-started, and possibly the hostCE device or Win32 Desktop system reset (after first removing the scanning device from the host.)



23/76

8.3 SCANCLOSEDEVICE()

Prototype:SCAN_RESULT ScanCloseDevice (HANDLE hScanner);

Purpose:

Closes the scanner port and releases resources.

Arguments:[in] hScanner is the value received by the client application in lParam of the WM_REMOVAL messagespecified when ScanInit() was called.


Notes:A scanner must be closed if the user removes it during your programs execution. Typically a clientprogram will call ScanCloseDevice() as part of the message handler of the WM_REMOVAL message.

All open scanners are closed automatically when the ScanDeinit() function is called.

Returns:






24/76

8.4 SCANGETDEVINFO()

Prototype:SCAN_RESULT ScanGetDevInfo(HANDLE hScanner, LPSCANDEVINFO lpScanDevInfo);

Purpose:

Get the general capabilities and identification of the requested device.



[in/out] lpScanDevInfo is the address of the SCANDEVINFO structure that will receive the information.

Notes:Client applications may want to know a little about the particular scanning device the user has inserted.For example, if a gun with a trigger is inserted, the application may want to hide or disable the

mechanism it uses to generate a soft-trigger. Additionally, since the gun has its own good-read feedback(an on-board beeper and LED), the application may want to use ScanSetGoodReadSound() to preventthe ScanAPI DLL from generating additional sounds.

Before calling ScanGetDevInfo(), you must set the StructSize member of your SCANDEVINFO structureto the size of the structure, or the function will fail. Upon successful return, the members of theSCANDEVINFO structure will be filled in with the following information:

ScannerType will be SCANNER_ISCI (for a 2D Scan Card), SCANNER_CFCARD (for a CF ScanCard), SCANNER_WAND, SCANNER_GUN (for all laser guns connected via Socket interfacecards.), SCANNER_SDIO (for the SDSC), or SCANNER_CHS (for the CHS).

fHardwareTrigger will be TRUE if the device has its own hardware trigger

fSoftwareTrigger will be TRUE if calling ScanTrigger() can trigger a scan on the device fSoftwareAbortTrigger will be TRUE if calling ScanAbort() can abort a scan in progress

fGoodReadLight will be TRUE if the device has a visual good-read indicator on-board

fGoodReadSound will be TRUE if the device makes a sound when data is successfully scanned

Returns:


SR_NOT_INITIALIZED

A successful call to ScanInit() must be made first.


SR_SCANNER_NOT_OPENThis function fails if the scanner is not open.



25/76

SR_INVALID_STRUCTUREThe lpScanDevInfo argument was NULL or the StructSize field was not set with thesizeof(SCANDEVINFO) value when the function call was made.

SR_DEVICE_FAILUREAn internal error occurred communicating with the scanning device (perhaps the device was removedduring the function call.) The client application will probably need to be re-started, and possibly the hostCE device or Win32 Desktop system reset (after first removing the scanning device from the host.)



26/76

8.5 SCANGETSTATUS()

Prototype:SCANAPI_API SCAN_RESULT ScanGetStatus(HANDLE hScanner);

Purpose:

Get the current status of the scanner and device driver. This API call was added so an applicationprogram could query the scanner to determine if scanner data was available or the general state of thescanner (scanner inserted/removed).

For the RFID reader, this function works with both legacy (ScanTrigger) and RFID-specific functions.


If the application program doesnt support callbacks, hardcoding the value of 1 will return the properstatus.

Returns:

SR_SUCCESSIndicates the scanner is in place and scanned data is available in the buffer. Call ScanGetData() toretrieve the data.

SR_NOT_INITIALIZEDThe scanner has not been initialized. A successful call to ScanInit() must be made first.

SR_INVALID_SCANNER_HANDLEThe hScanner argument is not a valid scanner handle. This indicates there is no scanner present or thehandled supplied is not correct.

SR_SCANNER_NOT_OPENThe scanner is present but ScanOpenDevice() has not been called.

SR_NO_DATAThere is no data available from the scanning device.

SR_SCANNER_REMOVEDThe scanner has been removed from the socket. A call to ScanCloseDevice() should be made.



27/76

8.6 SCANREQUESTDATAEVENTS()

Prototype:SCAN_RESULT ScanRequestDataEvents(HANDLE hScanner, HWND hWnd, UINT wmScannerData);

Purpose:

Instruct ScanAPI to send a message to the client application when the user has scanned data.

Arguments:[in] hScanner is the value received by the client application in the lParam of the WM_INSERTIONmessage specified when ScanInit() was called.


[in] hWnd is the handle of the window in the client application that will process the WM_SCANNERDATAmessage.

This value must be non-0 (null) in order for SocketScan to store scanned data in the buffer. This is trueeven if the application doesnt accept callback events.

[in] wmScannerData is a message defined by the client application that will be sent whenever the usersuccessfully scans data.

This message must be within the WM_USER range in order for SocketScan to store scanned data in thebuffer. This is true even if the application doesnt accept callback events

Notes:The client application must call the ScanGetData() API in response to receiving a WM_SCANNERDATAmessage. When WM_SCANNERDATA is received by the client application, lParam will contain thescanner handle and wParam will contain the size of the data available in bytes. This can be convertedinto a character count (if desired) by dividing the size of the data by the sizeof(TCHAR). Typically thesize of the data in bytes will equal the character count when running on Win32 Desktop systems.

Only one window at a time can be notified of the arrival of scanned data. Subsequent calls toScanRequestDataEvents() simply change the desired window and/or user message to be sent. Todisable data notifications altogether, call ScanRequestDataEvents() using NULL as the hWnd argument.

See ScanGetStatus() for information on using ScanAPI without messages.

It is up to the developer to decide where scanned data should be routed. The simplest approach is to letthe main window receive all WM_SCANNERDATA notifications and have it deal with the data (by callingScanGetData() and routing the data to the desired control). Another more complex but valid approach isto add handlers for WM_SCANNERDATA to numerous windows. Then the application can callScanRequestDataEvents() with different hWnd arguments (and possibly different wmScannerDataarguments) when necessary in the WM_ACTIVATE handlers of these windows. Then each windowcould process the scanned data in different ways, if necessary.

If hWnd or wmScannerData parameters are 0, no client message is sent when scanned data is receivedand no scanner data is stored in the buffer. An application program can use this feature toenable/disable scanning depending upon where the keyboard focus is within the application.



28/76

Returns:




SR_INVALID_WMSCANNERDATAThe wmScannerData argument is not within the valid WM_USER range.



29/76

8.7 SCANTRIGGER()

Prototype:SCAN_RESULT ScanTrigger(HANDLE hScanner);

Purpose:

Trigger a scan on a scanning device.



Notes:For the CFSC/SDSC/CHS, this function returns immediately and, upon a successful read, the clientapplication will receive the user-defined WM_SCANNERDATA message specified in a prior call toScanRequestDataEvents(). For scanners that use hardware triggers on the scanner device, this functionreturns successfully but has no effect. For these other devices, the client application will asynchronously

receive the WM_SCANNERDATA message when the user pulls the trigger on the scanner, or swipes thewand across a bar code.

Normally, this call is used start the scanner. The scanning stops after scanning a supported bar code orwhen the time-out period expires (typically 3 seconds). There is no indication to the calling program if nobar code is found.

For RFID, this call will issue a Select Tag command to the reader depending on registry settings thiscan be modified. This call is made with tag type set to Auto-detect so it returns the first tag ID it can readin its field. The application program will receive a WM_SCANNERDATA message indicating data isavailable and calling ScanGetData() returns the tag type and tag ID. No message will be received if thereis no tag in the field at the time ScanTrigger() is called or if there was an error reading the tag. Note thatthis behavior is dependent on the settings found in the registry or modified via the RFID Setup Control

Panel.

Note: This is a legacy function for compatibility with SocketScan and its recommended thatScanRFIDSelectTag() be used instead.

Returns:



SR_INVALID_SCANNER_HANDLE

The hScanner argument is not a valid scanner handle.




30/76

SR_DEVICE_FAILUREAn internal error occurred communicating with the scanning device (perhaps the device was removedduring the function call.) The client application will probably need to be re-started, and possibly the hostCE device reset or the Win32 Desktop system restarted (after first removing the scanning device from thehost.)



31/76

8.8 SCANABORT()

Prototype:SCAN_RESULT ScanAbort(HANDLE hScanner);

Purpose:

Terminate a scan-in-progress on a scanning device.



Notes:For scanning devices that support this operation, the laser beam is switched off and the scan isterminated. Calling this function when a scan is not in progress or on devices that do not support thisfeature, has no effect and the function returns successfully. This function not implemented for the2DSC.

For RFID this function aborts any loop mode operation started by the ScanRFIDSelectTag() function.It may also be used to abort any pending RFID response/data indicated by a WM_SCANNERDATAmessage if ScanRFIDGetData() function is not called. (The application must call ScanRFIDGetData() forevery WM_SCANNERDATA message received unless ScanAbort() is called.)

Returns:





SR_DEVICE_FAILUREAn internal error occurred communicating with the scanning device (perhaps the device was removedduring the function call.) The client application will probably need to be re-started, and possibly the hostCE device reset, or Win32 Desktop system restarted (after first removing the scanning device from thehost.)



32/76

8.9 SCANGETDATA()

Prototype:SCAN_RESULT ScanGetData(HANDLE hScanner, TCHAR * lpBuff, LPINT BufSize);

Purpose:

Returns scanned data after a successful read operation on the scanner device.



[out] lpBuff points to the buffer to receive the scanned data.

[in/out] BufSize points to the size of the buffer in bytes (not characters). Upon return, BufSize will be setto the number of bytes written into lpBuff. This can be converted to a character count by dividing BufSizeby sizeof(TCHAR). Typically the buffer size will be equal to the character count on Win32 Desktop

systems.

Notes:ScanGetData() should be called in response to receiving the WM_SCANNERDATA message. The datareturned will be in UNICODE on CE devices.

It is possible for NULL characters to appear in the scanned data, depending on the symbology scannedby the user. Also note that the ScanAPI DLL will not NULL-terminate the scanned data. Therefore, do allnecessary validity checks on the buffer before you do anything with the data. Once the data is validated,you can add your own prefix or suffix, add your own terminating NULL, or perform any other pre-processing to the data stream you desire.

To discover the size of the data available without actually retrieving it from the scanner, you may use

NULL as the lpBuff argument in this case BufSize will be filled in with the size of the data and thefunction will return successfully. If lpBuff is not NULL and the buffer is too small, no data transfer will takeplace, the size of the buffer necessary will be written to BufSize, and the function will returnSR_BUFFER_TOO_SMALL. At this point you MUST call ScanGetData() again with a larger buffer toremove the data and allow for continued scanning.

Applications should respond to the WM_SCANNERDATA message as soon as possible. The ScanAPIDLL has a small buffer for storing multiple scans (currently 16 scans), in case the user is scanning datamore quickly than your application can process it. But when this buffer fills, additional scanned data willbe discarded, and no notifications of the overflowed data will be sent.

If the application program doesnt accept callback events, calling ScanGetStatus() will return status of thescanner along with data available status.

For RFID this function is called to get the tag ID as a result of a ScanTrigger() call. The data is returned isone of TagID, Tag Data, or TagID and Tag Data. For example it could return just the TagID as an ASCIIstring containing the tag type followed by a : and the tag ID.

As an example, an ISO 15693 tag with an ID of E007000001476301, would be returned in 19 bytes as:01:E007000001476301



33/76

Note: This is a legacy function for compatibility with SocketScan and its recommended that the specificRFID functions be used instead of ScanTrigger() and ScanGetData(). Do not call this function whenissuing any specific RFID function (i.e. ScanRFIDSelectTag(), ScanRFIDReadTag(), etc.).

Returns:





SR_NO_DATAThere is no data available from the scanning device.

SR_BUFFER_TOO_SMALLA larger buffer is required to accommodate the data from the scanner.The user MUST call ScanGetData() again with a larger buffer to remove the data and allow forcontinued scanning.



34/76

8.10 SCANSETGOODREADSOUND()

Prototype:SCAN_RESULT ScanSetGoodReadSound(HANDLE hScanner, GRS_TYPE Sound, LPCTSTRlpWavFile);

Purpose:Tells the ScanAPI DLL to be silent, call MessageBeep(0), or play a .wav file when the user successfullyscans data with the specified device.



[in] Sound is GRS_NONE, GRS_MESSAGEBEEP, or GRS_WAVFILE.

[in] lpWavFile points to the full path and filename of a .wav file to play.

Notes:There is no corresponding function to return the current settings for a device. When a scanning deviceis opened, the default configuration is for a MessageBeep(0) to be executed on a good read.

Applications will probably want to call ScanSetGoodReadSound() immediately after successfullyopening the scanner with ScanOpenDevice() in the WM_INSERTION message handler, if the defaultsound configuration is not desired.

Returns:




SR_INVALID_SOUND_TYPEThe Sound argument must be GRS_NONE, GRS_MESSAGEBEEP, or GRS_WAVFILE.

SR_WAVFILE_NOT_FOUNDUnable to find the file referenced by the lpWavFile argument.

SR_MEMORY_FAILUREAn internal error occurred, most likely due to unavailable resources on the host device. The device will

probably need to be reset, though the problem may be correctable if the user terminates otherprocesses on the device and re-tries the operation.



35/76

8.11 SCANDEINIT()

Prototype:SCAN_RESULT ScanDeinit();

Purpose:

Performs final clean-up in the DLL pending shutdown.

Arguments:None.

Notes:ScanDeinit() is typically called during the shutdown/cleanup phase of the client application. Anyscanning devices that are open will be closed by the ScanDeinit() function.

Returns:



SR_DEVICE_FAILUREMay occur as a result of calling ScanInit() on Windows NT systems only. An internal error occurredwhile communicating with the scanning device (perhaps the device was removed during the functioncall.) The client application will probably need to be re-started, and possibly the Win32 Desktop systemreset (after first removing the scanning device from the host.)

On Windows NT systems, a scanning device MUST be present in the system BEFORE callingScanInit(). Additionally, the scanning device MUST NOT BE REMOVED from the system while theScanAPI is in use. Since the API does not support hot-swapping for this platform, no device removal or

insertions messages are generated. If a card is removed and re-inserted while a scanning session is inprogress, the COM port associated with the PC Card will not be configured properly, and ScanAPIerrors will result.

Under Windows NT, all PC Card devices must be present at boot-time, and can never be safelyremoved without re-booting. The exception is if you have added third-party Card and Socket Services toyour NT system. In this case, the scanning device must be present before the ScanInit() call, but can besafely removed AFTER ScanDeinit() is called.



36/76

8.12 SCANERRTOTEXT()

Prototype:SCAN_RESULT ScanErrToText(SCAN_RESULT Err, LPTSTR lpBuff, LPINT BufSize);

Purpose:

Converts error code to text.

Arguments:[in] Err is the error generated by a ScanAPI function call that you wish to have translated to text.

[out] lpBuff is a buffer allocated by the client program to receive the text. Note the result is returned inUNICODE on CE devices.

[in/out] BufSize points to an integer that must be set to the size of lpBuff before the ScanErrToText()function is called it will be filled in by the SDK with the size of the error text (in bytes) upon return.This value can be converted to a character count by dividing BufSize by the sizeof(TCHAR). Typicallythe byte count will equal the character count on Win32 Desktop systems.

Notes:To discover the size of the error text without actually retrieving it, you may use NULL as the lpBuffargument in this case BufSize will be filled in with the size of the error message and the function willreturn successfully. If lpBuff is not NULL and the buffer is too small, no data transfer will take place,the size of the buffer necessary will be written to BufSize, and the function will returnSR_BUFFER_TOO_SMALL.

Returns:


SR_INVALID_ERR

The error you are trying to translate is not known.

SR_BUFFER_TOO_SMALLA larger buffer is required to accommodate the text.

SR_INTERNAL_FAILUREAn unexpected error occurred in the ScanAPI DLL.



37/76

8.13 SCANPARAMSEND()

Prototype:SCANAPI_API SCAN_RESULT ScanParamSend(HANDLE hScanner, PBYTE paramIn, UINTparamInLen, PBYTE paramVal, UINT paramValLen);

Purpose:Modifies one or more parameters of the scanner hardware for WinCE only.



[in] paramIn is a byte buffer containing one or more parameter numbers that will be modified.

[in] paramInLen is the length of the paramIn buffer in bytes.

[in] paramVal is a buffer containing the values that will be used when changing the parameters specifiedby the paramIn buffer. All parameter values are bytes but the paramVal buffer may be arranged as 8-bitor 16-bit values -- see notes below for important information on the composition of the paramVal buffer.

[in] paramValLen is the size in bytes of the paramVal buffer.

Notes:This function is only supported by the CFSC, SDSC and CHS scanners (not the 2DSC.) Executing thisfunction on other scanners will return ERROR_NOT_SUPPORTED.

The CFSC/SDSC/CHS scanners support two modes for setting scanner parameters. In the first mode,temporary mode, the parameter changes will be in effect only as long as the scanner is powered(inserted in the CF slot with the device powered on). Once power is removed, the parameter(s) will

revert to its previous value. In the second mode, permanent mode, the parameter changes arepermanent and will remain in effect until changed via another ScanParamSend call.

The default behavior of the ScanParamSend call is to make changes in temporary mode. To use thismode, simply create a buffer of 8-bit values for the paramVal parameter.

To make changes in permanent mode, create the paramVal buffer as an array of 16-bit (USHORT)values. Place the desired parameter value in the lower 8-bits and set the upper bit (bit 15) to 1. Notethat only the upper bit of the first parameter element of the buffer must be set to enable permanentmode. Set the paramValLen parameter to be the length of the paramVal buffer which in permanentmode is twice number of parameters (sizeof(USHORT) * sizeof(paramIn)).

Refer to theAdvanced Programming Guide for a list of parameter settings.See the sample source code for an example.

Returns:


ERROR_NOT_SUPPORTEDThe scanner in use does not support the ScanParamSend function.



38/76

ERROR_NOT_READYA problem occurred sending the command(s) to the scanner.

ERROR_OUTOFMEMORYThe function was not able to allocated memory needed to complete the request.



39/76

8.14 SCANPARAMREQUEST()

Prototype:SCAN_RESULT ScanParamRequest(HANDLE hScanner, PBYTE paramIn, UINT paramInLen, PBYTEparamOut, PUINT paramOutLen);

Purpose:Retrieves the current setting of one parameter of the scanner hardware for WinCE only


If the application program doesnt support callbacks , use 1 for the HANDLE (if multi-scanner disabled) .

[in] paramIn is a byte buffer containing the parameter number that will be retrieved.

[in] paramInLen is the length of the paramIn buffer in bytes (should always be 1).

[out] paramOut is a byte buffer that will contain the value of the requested parameter.

[in/out] paramOutLen is the size in bytes of the paramOut buffer. This should be set to 1 when callingScanParamRequest. Upon exit, this will be set to 0 if an error occurs, 1 otherwise.

Notes:This function is only supported by the CFSC/SDSC/CHS (not the 2DSC). Executing this function onother scanners will return ERROR_NOT_SUPPORTED.

Currently, only one parameter at a time can be retrieved via the ScanParamRequest function.

Refer to the Advanced Programming Guide for a list of parameter settings.

Returns:


ERROR_NOT_SUPPORTEDThe scanner in use does not support the ScanParamSend function.

ERROR_NOT_READYAn internal error occurred requesting the parameter from the scanner.

ERROR_INSUFFICIENT_BUFFERThe length of the paramOut buffer was not 1.



40/76

8.15 SCANSENDCOMMAND()

Prototype:SCANAPI_API SCAN_RESULT ScanSendCommand(HANDLE hScanner, IN OUT LPTSTRpCmd_CmdResponse, IN OUT int* piLength);

Purpose:Sends a command to the 2DSC hardware and receives the 2DSCs response for WinCE only.


If the application program doesnt support callbacks , use 1 for the HANDLE (if multi-scanner disabled).

[in out] pCmd_CmdResponse is a TCHAR buffer containing the command to be sent. It also receivesthe response to the command by the imager.

[in out] piLength is an integer that specifies the maximum number of characters pCmd_CmdResponsebuffer can hold. It also receives the number of bytes returned in the pCmd_CmdResponse.

Notes:This function is only supported by the 2DSC. Executing this function on other scanners will returnERROR_NOT_SUPPORTED.

Currently, only one command at a time can be sent via the ScanSendCommand function.

Refer to the Advanced Programming Guide for a list of commands.

Returns:


SR_UNSUPPORTED_FEATUREThe scanner in use does not support the ScanSendCommand function.

SR_INTERNAL_FAILUREAn internal error occurred requesting the parameter from the scanner.

SR_BUFFER_TOO_SMALLThe length of the pCmd_CmdResponse was insufficient to hold the entire response.



41/76

8.16 SCANPARAMSENDEX()

Prototype:SCANAPI_API SCAN_RESULT ScanParamSendEx(HANDLE hScanner, PUINT16 paramIn, UINTparamInLen, PBYTE paramVal, UINT paramValLen);

Purpose:Modifies one or more parameters of the scanner hardware. This API is slightly different fromScanParamSend() in that the paramInis now of type PUINT16. This is for opcodes that are of two bytelengths (ie RSS-14) and is for WinCE only.


If the application program doesnt support callbacks , use 1 for the HANDLE (if multi-scanner disabled) .

[in] paramIn is a 16 bit buffer containing one or more parameter numbers that will be modified.

[in] paramInLen is the length of the paramIn buffer in bytes.

[in] paramVal is a buffer containing the values that will be used when changing the parameters specifiedby the paramIn buffer. All parameter values are bytes but the paramVal buffer may be arranged as 8-bitor 16-bit values -- see notes below for important information on the composition of the paramVal buffer.

[in] paramValLen is the size in bytes of the paramVal buffer.

Notes:This function is only supported by the CFSC, SDSC or CHS (not the 2DSC). Executing this function onother scanners will return ERROR_NOT_SUPPORTED.

The CFSC/SDSC/CHS support two modes for setting scanner parameters. In the first mode, temporary

mode, the parameter changes will be in effect only as long as the scanner is powered (inserted in theCF slot with the device powered on). Once power is removed, the parameter(s) will revert to itsprevious value. In the second mode, permanent mode, the parameter changes are permanent and willremain in effect until changed via another ScanParamSend call.

The default behavior of the ScanParamSend call is to make changes in temporary mode. To use thismode, simply create a buffer of 16-bit values for the paramVal parameter.

To make changes in permanent mode, create the paramVal buffer as an array of 16-bit (USHORT)values. Place the desired parameter value in the lower 8-bits and set the upper bit (bit 15) to 1. Notethat only the upper bit of the first parameter element of the buffer must be set to enable permanentmode. Set the paramValLen parameter to be the length of the paramVal buffer which in permanentmode is twice number of parameters (sizeof(USHORT) * sizeof(paramIn)).

Refer to the Advanced Programming Guide for a list of parameter settings.See the sample source code for an example.

Returns:


SR_UNSUPPORTED_FEATURE



42/76

The scanner in use does not support the ScanParamSendEx function.

SR_DEVICE_FAILUREA problem occurred sending the command(s) to the scanner.



43/76

8.17 SCANPARAMREQUESTEX()

Prototype:SCANAPI_API SCAN_RESULT ScanParamRequestEx(HANDLE hScanner, PUINT16 paramIn, UINTparamInLen, PBYTE paramOut, PUINT paramOutLen);

Purpose:Retrieves the current setting of one parameter of the scanner hardware. This API is slightly differentfrom ScanParamRequest() in that the paramInis now of type PUINT16. This is for opcodes that are oftwo byte lengths (ie RSS-14).


[in] paramIn is a 16 bit buffer containing the parameter number that will be retrieved.

[in] paramInLen is the length of the paramIn buffer in bytes (should always be 1).

[out] paramOut is a byte buffer that will contain the value of the requested parameter.

[in/out] paramOutLen is the size in bytes of the paramOut buffer. This should be set to 1 when callingScanParamRequest. Upon exit, this will be set to 0 if an error occurs, 1 otherwise.

Notes:This function is not supported by the 2DSC. Executing this function on scanners other thanCFSC/SDSC/CHS will return ERROR_NOT_SUPPORTED.

Currently, only one parameter at a time can be retrieved via the ScanParamRequestEx function.

Refer to the Advanced Programming Guide for a list of parameter settings.

Returns:


SR_UNSUPPORTED_FEATUREThe scanner in use does not support the ScanParamSendEx function.

SR_DEVICE_FAILUREAn internal error occurred requesting the parameter from the scanner.

SR_BUFFER_TOO_SMALLThe length of the paramOut buffer was not 1.



44/76

8.18 ISSCANNERCONNECTED()

Prototype:SCANAPI_API BOOL IsScannerConnected (void)

Purpose:

Checks if the scanner is connected and is open for communication.

Arguments:No arguments

Returns:

TRUEThe scanner is connected and is open for communications

FALSEIf scanner has an invalid handle or is not OPEN.

8.19 ISSCANNERCONNECTEDEX()

Prototype:SCANAPI_API BOOL IsScannerConnectedEx (SCANNER_TYPE scannerType)

Purpose:To determine if either a scanner is connected or a particular type of scanner is connected in a multi-scanner scenario. IsScannerConnected() calls this API with SCANNER_NONE as a parameter.

Arguments:[in] scannerType: Type of scanner to check

Returns:

TRUEThe scanner is connected and is open for communications

FALSEIf scanner has an invalid handle or is not OPEN.



45/76

8.20 SCANENABLEDISABLESYMBOLOGY()

Prototype:SCANAPI_API SCAN_RESULT ScanEnableDisableSymbology (HANDLE hScanner, INT nSymID,BOOL flag);

Purpose:Enables or Disables symbologies for all types of Socket scanner devices.


[in] nSymID is the symbology ID to be Enabled or Disabled. For symbology IDs refer to the enumerateddata type SCANNER_SYMBOLOGY in SCANAPI.h file.

[in] flag to enable or disable symbology

Returns:

SR_SUCCESSThe operation completed successfully

SR_INVALID_SCANNER_HANDLEInvalid scanner handle

SR_SYMBOLOGY_NOT_SUPPORTEDInvalid symbology ID

SR_DEVICE_FAILUREAn internal error occurred requesting a call to the scanner

NOTE: This API will supersede ScanParamSend(), ScanParamSendEx() API calls.



46/76

8.21 SCANREADSYMBOLOGYCONFIG()

Prototype:SCANAPI_API SCAN_RESULT ScanReadSymbologyConfig (HANDLE hScanner, int cfgType, intnSymbol, PVOID pvSym);

Purpose:Reads symbology configuration for all types of Socket scanner devices


[in] cfgType is the configuration type to read the CURRENT or DEFAULT configuration of the symbology

[in] nSymbol is the symbology ID to read the configuration. For symbology IDs refer to the enumerateddata type SCANNER_SYMBOLOGY in SCANAPI.h file

[in] pvSym is the void pointer to the structure with that has structure size, mask and that will containsymbology info on return

Returns:

SR_SUCCESSThe operation completed successfully

SR_INVALID_SCANNER_HANDLEInvalid scanner handle

SR_INVALID_ERRInvalid structure passed to read the symbology configuration

SR_SYMBOLOGY_NOT_SUPPORTEDInvalid symbology ID

SR_DEVICE_FAILUREAn internal error occurred requesting a call to the scanner to

Documents

Socket Scanners Dk