Socket Scanners DK

SocketScan SDK Users Guide & ScanAPI: Scanning Application Program Interface
Document # 6410-00147 G January 10, 2006
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 Bluetooth Wireless Technology, CF Scan Card, SD Scan Card, 2D Scan Card, Gun Scanner, Wand Scanner, CF RFID Reader Card, and CF RFID Reader-Scan Card are trademarks of Socket 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 expressly prohibited. 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 Court Newark, CA 94560 Other than the above, Socket Communications can assume no responsibility for anything resulting from the application 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. Document#: 6410-00147 G
January 27, 2006
Page 2 Revision 2.24
Revision History
Revision 1.00 1.01 1.02 1.03 1.04 1.05 2.00 2.01 2.02 2.03 2.04 2.05 2.06 2.07 2.08 2.09 2.10 2.11 2.12 2.13 2.14 2.15 2.16 2.17 2.18 2.19 2.20 2.21 2.22 2.23 2.24 Date 10/26/1999 11/01/1999 11/02/1999 11/04/1999 11/04/1999 11/13/1999 03/29/2000 05/06/2000 05/10/2000 05/12/2000 05/15/2000 05/17/2000 05/23/2000 12/11/2000 12/20/2000 12/20/2000 9/27/2001 12/17/2002 12/23/2002 07/11/2003 01/22/2004 08/11/2004 08/30/2004 10/28/2004 11/16/2004 12/08/2004 01/07/2005 03/17/2005 06/09/2005 09/23/2005 01/10/2006 Author G. Cuevas, L. Ott G. Cuevas, J. Houston G. Cuevas, L. Ott G. Cuevas G. Cuevas G. Cuevas G. Cuevas G. Cuevas, P. Subbaraya, J. Houston G. Cuevas, P. Subbaraya G. Cuevas, P. Subbaraya G. Cuevas, P. Subbaraya, J. Houston G. Cuevas, P. Subbaraya G. Cuevas, P. Subbaraya G. Cuevas G. Cuevas, M. Man G. Cuevas T. Newman D. Acquistapace P. Subbaraya P. Subbaraya P. Subbaraya D. Singh, S. Gutti T. Newman S. Gutti D. Singh D. Singh S. Gutti S. Gutti S. Gutti A. Hersh, D. Singh, T. Newman, M. Man A. Hersh Comments Genesis. Updated registry section; added correct doc number; cleaned up typos, etc. Additional corrections. Changed keyboard wedge product name to SocketScan. Corrected registry entry section. Updated for disk layout change. Additions for Win32 Desktop, Preview DLL, Bar Code Wand. General edits and corrections. Additional edits. Additions and corrections. Minor edits. Minor edits. Additional minor changes. Updates for HPC 2000, Windows 2000 and Windows Me. Minor edits. Minor edits. Changes for SocketScan 3.2 Added ScanGetStatus() API call (WinCE). Polling calls from Embedded Visual Basic (EVB). Minor edits to API calls. Added ScanParamSend and ScanParamRequest API calls (WinCE). Changes for SocketScan 4.0 to support the 2DSC for bar code. Minor edits Changes for SocketScan 4.0 to support the 2DSC ScanSendCommand() API call(WinCE.) Changes for SocketScan 4.1.xx to support DriverMan registry structure. Minor edits. Updated CHS information, modified desktop information RFID Reader functions added Updated CHS information for Windows XP. Added SDK QuickStart guide Update ScanGetData() details and Section 4 and 12 for specific DLLs Add new APIs for CHS configuration commands in Section 8.0 & 9.0 and updated registry entry section Updated ScanEnableCHS() & ScanDisableCHS() APIs Added new APIs to handle Symbologies for all Scanners Added CF RFID Reader-Scan Card APIs, CHS programming info, and SocketScan Trigger Applications Minor edits to reflect WM 5.0 support, Mag Stripe Reader and Cordless Ring Scanner.
January 27, 2006
Table of Contents
1.0 2.0 Introduction .......................................................................................................................... 7 1.1 2.1 2.2 3.0 3.1 3.2 3.3 3.4 3.5 3.6 4.0 4.1 4.2 5.0 5.1 5.2 5.3 5.4 6.0 7.0 8.0 SDK QuickStart Guide................................................................................................. 7 Windows CE................................................................................................................ 8 Windows Desktop/Notebook ....................................................................................... 8 SDK Initialization/De-initialization.............................................................................. 10 Device Control........................................................................................................... 10 Scanner Data Access................................................................................................ 10 Miscellaneous Utility.................................................................................................. 11 Cordless Scanner Specific Functions........................................................................ 11 RFID Specific Funtions.............................................................................................. 11 Setting up Windows CE Devices............................................................................... 12 Setting up Win32 Desktop Systems .......................................................................... 13 Preview DLL .............................................................................................................. 15 RFID Demo ............................................................................................................... 15 ScanApiTester........................................................................................................... 15 ScanApiTester........................................................................................................... 15 Revision Notes ..................................................................................................................... 8
Using ScanAPI ................................................................................................................... 10
Setting Up The Target Device............................................................................................ 12
Writing Your Application..................................................................................................... 14
Soft Triggering.................................................................................................................... 16 ScanAPI Type Reference................................................................................................... 17 ScanAPI Function Reference............................................................................................. 20 8.1 8.2 8.3 8.4 8.5 8.6 8.7 8.8 8.9 ScanInit() ................................................................................................................... 20 ScanOpenDevice() .................................................................................................... 22 ScanCloseDevice().................................................................................................... 23 ScanGetDevInfo()...................................................................................................... 24 ScanGetStatus()........................................................................................................ 26 ScanRequestDataEvents()........................................................................................ 27 ScanTrigger() ............................................................................................................ 29 ScanAbort() ............................................................................................................... 31 ScanGetData() .......................................................................................................... 32
January 27, 2006
8.10 ScanSetGoodReadSound()....................................................................................... 34 8.11 ScanDeinit()............................................................................................................... 35 8.12 ScanErrToText()........................................................................................................ 36 8.13 ScanParamSend()..................................................................................................... 37 8.14 ScanParamRequest()................................................................................................ 39 8.15 ScanSendCommand() ............................................................................................... 40 8.16 ScanParamSendEx()................................................................................................. 41 8.17 ScanParamRequestEx()............................................................................................ 43 8.18 IsScannerConnected() .............................................................................................. 44 8.19 IsScannerConnectedEx() .......................................................................................... 44 8.20 ScanEnableDisableSymbology()............................................................................... 45 8.21 ScanReadSymbologyConfig() ................................................................................... 46 8.22 ScanWriteSymbologyConfig() ................................................................................... 47 8.23 ScanEnableMultiScanner()........................................................................................ 47 8.24 ScanGetScannerRegKey () ....................................................................................... 48 8.25 Sample symbology config code:................................................................................ 49 8.25.1 Sample Code to Enable or Disable CODE39 symbology: ............................. 49 8.25.2 Sample code for Read configuration: ............................................................ 49 8.25.3 Sample Code to Enable or Disable CODE39 symbology: ............................. 50 9.0 Cordless Scanner (CS) Specifics....................................................................................... 51 9.1 9.2 9.3 9.4 9.5 ScanEnableCHS() ..................................................................................................... 52 ScanDisableCHS() .................................................................................................... 53 ScanSendCmdtoCHS() ............................................................................................. 54 Bluetooth Connection Status..................................................................................... 56 CHS Commands ....................................................................................................... 57 9.5.1 9.5.2 9.5.3 9.6 9.6.1 9.6.2 9.6.3 9.6.4 9.6.5 9.7 Set Security Mode ......................................................................................... 57 Set Friendly Name ......................................................................................... 57 Set PIN Code................................................................................................. 57 Set Indicators................................................................................................. 58 Battery Charge State Inquiry ......................................................................... 58 Battery Charge State Response .................................................................... 58 Friendly Name Inquiry ................................................................................... 58 Friendly Name Response .............................................................................. 59
CHS Control commands............................................................................................ 58
Registry Settings for the Cordless Hand Scanner ..................................................... 60

January 27, 2006 Page 5 Revision 2.24
10.0 RFID Reader ...................................................................................................................... 62 11.0 MultiScanner Support (WIN CE ONLY) ............................................................................. 63 11.1 Registry Settings for the CF RFID Reader-Scan Card .............................................. 63 12.0 Using SocketScan (Keyboard Wedge)............................................................................... 65 13.0 SocketScan Trigger Applications (WINCE ONLY) ............................................................. 66 13.1 Triggering Details ...................................................................................................... 67 13.2 Changing the Active Scanner.................................................................................... 67 14.0 The DriverMan dll............................................................................................................... 69 15.0 Installation .......................................................................................................................... 70 15.1 Installation Procedure................................................................................................ 70 15.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: ..... 70 15.1.3 Windows Desktop/Notebook Installation: ...................................................... 70 15.2 Registry Entries ......................................................................................................... 72 15.2.1 Windows CE Registry Entries........................................................................ 72 15.2.2 Win32 Desktop/Notebook Registry Entries.................................................... 72 15.2.3 Other Registry-Related Considerations ......................................................... 73 15.3 Implementing a SocketScan Preview DLL ................................................................ 74 16.0 Implementing a SocketScan Application in .NET ............................................................... 76
January 27, 2006
1.0 INTRODUCTION
Socket Communications ScanAPI is a set of Windows CE and Win32 Desktop DLLs that offer access to Sockets line 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-process the data before its final disposition. Applications may add a prefix or a suffix to the data, and perform any other application-specific character translations, insertions or deletions, if desired. Included in this Developers Kit is a version of Sockets keyboard wedge software, called SocketScan, which is based 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 (for Windows CE only) Registry entries allowing VARs to configure the prefix, suffix, sounds, and other properties at install-time using their own custom installer A Preview DLL can be registered with the wedge, allowing developers to preview and modify data scanned by the user
All binary files for the SocketScan program are supplied and may be freely distributed by the Developer, for use with Socket scanner products. The documentation supplied is protected via copyrights held by their respective owners and cannot be distributed without written permission. The term scanned data is used throughout this document and generally describes data scanned from a bar code or data returned from reading a RFID tag.
1.1
SDK QUICKSTART GUIDE

1) 2) 3) 4) 5) Read Chapters 3 and 8 of this Users Guide to understand the Scanner APIs Read Chapter 5 to understand the sequence of events and messages for the API Based on your requirements, examine the Sample code provided in the Source\ScanApiTester Read Chapter 6 to learn how to trigger your scanner 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.
January 27, 2006
2.0 REVISION NOTES

Although ScanAPI is simple and minimal,it is still designed for future expansion while being backward compatible with existing applications. For example, the ability to support multiple scanners simultaneously could be added if developers require this feature. In the event of adding such functionality, the existing API function interfaces would remain unchanged. WARNING: Do NOT attempt to change any communication protocol settings or scan any Set All Defaults programming bar code with any Socket scanner product unless instructed to do so by Socket Technical Support. IMPORTANT: ScanAPI currently assumes that the communication parameters for the scanning devices have not been changed from their factory defaults. If the baud rate, word size, etc. have been changed from the factory defaults, they will have to be manually restored before the device will work with ScanAPI. If this happens to the CF Scan Card, SD Scan Card or 2D Scan Card, it must be returned to the factory to restore default communication settings. The SocketScan keyboard wedge program also expects that the attached scanning device has not been programmed to produce prefix or suffix characters. The SocketScan keyboard wedge application supplied with the SDK offers a powerful feature for developers. A Preview 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 to validate, pre-process or perform various other modifications on the scanned data. In cases where the keyboard wedge software is very close, but not quite perfect for your custom applications scanning solution, we believe this new 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 to explore the possibility of having the scanners programmed to your specifications during manufacturing. We can ensure certain symbologies are enabled or disabled and we can pre-program devices in various other ways to suit your 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), Cordless Hand Scanner with Bluetooth Wireless Technology (CHS), Cordless Ring Scanner with Bluetooth Wireless Technology (CRS) and Wand Scanner. The Cordless Hand Scanner (CHS) and Cordless Ring Scanner (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 this release. These products can read most of the ISO 15693 High Frequency (13.56MHz) RFID tags available. 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 PC v2.11 devices with this release of the SDK. Contact Socket Communications Technical Support at support@socketcom.com to 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 currently supported in the Windows Desktop/Notebook version.
January 27, 2006
Starting from this Desktop Release v3.7, SocketScan application support for Win 95, 98, Me and NT platforms will be discontinued. Scanner products may run on these older devices, but compatibility is no longer verified or guaranteed. This release includes support for Windows XP. Full hot-swapping support is present for Windows XP.
January 27, 2006
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 directly call Win32 DLLs and process Windows messages. At this time there is no support for Java.
3.1
SDK INITIALIZATION/DE-INITIALIZATION
ScanInit() initializes the ScanAPI DLL and allows the client to register for device insertion and removal messages ScanEnableMultiScanner() enables multiple scanners ScanDeinit() closes any open scanning devices and performs clean-up in the DLL pending shutdown
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 DATA ACCESS

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
January 27, 2006
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
RFID SPECIFIC 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
January 27, 2006
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 CE DEVICES

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 scanning device(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 Bluetooth connection 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
January 27, 2006
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 of the distribution CD.) If you install the SocketScan program to your target CE device, all necessary API and driver files will be installed and configured. SocketScan will run on the Microsoft Pocket PC and Windows CE platforms version 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 the target CE device. Also uninstall any legacy versions of Sockets Wand Scanner programs from the target device, if present. Installing SocketScan will install all the DLLs and set up the proper registry entries but it should not be used for installing the final users application program because it can confuse the user with additional programs and Icons. The developer should follow the guidelines listed in this SDK guide to can create an installer which will setup only the applications, drivers, and registry entries needed to support the application. *** It is recommended that SDK users determine exactly which DLLs and registry settings are required for their application rather than blindly using all Socketscan DLLs and settings ***
4.2
SETTING UP WIN32 DESKTOP SYSTEMS

On the target system, the files ScanAPI.DLL and ScanHook.DLL must be present in the system directory, typically C:\Windows\System32 or C:\WinNT\System32. Additionally, you must copy one or more device driver files to the system directory to support the scanning device(s). The files to choose from are: COMMON REQUIRED FOR ALL: SCANHOOK.DLL required for handling global keyboard hook HOTSWP2K.DLL, For Hot swap functionality. SCANAPI.DLL, SDK API CF 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 Bluetooth connection 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 be completely installed and configured.
January 27, 2006
5.0 WRITING YOUR APPLICATION

Applications that use ScanAPI must include the ScanAPI.h file in their project, and must either link to the appropriate ScanAPI.lib file supplied with the SDK or use GetProcAddress() to access the functions. The .h and .lib files are located in the ScanSDK subdirectory of the distribution CD. The Win32-based sample applications supplied on the CD assume that you have copied the \ScanSDK (and all subdirectories) directly from the root of the CD 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 can successfully recompile them. Two windows messages must be defined, within the WM_USER range defined by Windows that will be sent to the application when scanning devices are inserted or removed. This document generically refers to these messages as wmInsertion (or WM_INSERTION) and wmRemoval (or WM_REMOVAL). You must also choose a window that will service these messages, typically the main window of your application. Use the window handle and the two messages 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_REMOVAL messages, as appropriate, when a scanner is inserted or removed from the host device. You will likely get a WM_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. The WM_INSERTION handler should save the ScanAPI-assigned scanner handle (provided in lParam), then call ScanOpenDevice() using the scanner handle. Upon success, you would use ScanGetDevInfo() if you are interested in the type of scanner that was inserted, and optionally use ScanSetGoodReadSound() if you do not like the default sound, which is to produce a MessageBeep(0) when a successful scan is completed. For multiple devices ScanOpen()/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 of ScanAPI supports multiple scanners in this case, multiple WM_INSERTION and WM_REMOVAL message are seen, 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 the handle 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 scanning application will define a third windows message, which this document generically refers to as wmScannerData (or WM_SCANNERDATA). This message is supplied along with the handle of the window you want to process this message. 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 application desires. A simple application would probably call ScanRequestDataEvents() as part of the WM_INSERTION message handler. Since this registration is nullified whenever the scanning device is closed, it is necessary to call ScanRequestDataEvents() again at some point when the device is re-opened. A more complex application may want to dynamically change the window that will process the WM_SCANNERDATA message, and may even want to change the actual message to be received. This can be done simply by calling ScanRequestDataEvents() again when you want the change to take effect. You can temporarily ignore all scanned data, if desired, by supplying NULL as the hWnd argument to ScanRequestDataEvents(). 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.
Socket Communications, Inc. Document#: 6410-00147 G January 27, 2006 Page 14 Revision 2.24
All ScanAPI function calls return SR_SUCCESS if the function succeeds. If a failure occurs, the error returned by the ScanAPI library can be translated to text using the ScanErrToText() function. This function translates the error code into fairly technical jargon and, while this may be useful during software development, the text may not be suitable for display in an end-user application. Since the error messages are located within a string resource that is bound to the ScanAPI DLL file, you may change the wording of these error messages, or translate the messages to different 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 following subdirectories:
5.1
PREVIEW DLL
This project demonstrates how to create a SocketScan Preview DLL.
5.2 5.3 5.4
RFID DEMO
This project demonstrates the usage of the RFID specific API calls.
SCANAPITESTER
This project demonstrates the usage of the ScanAPI.
SCANAPITESTER
This application demonstrates how to send a trigger message directly to the ScanAPI library.
January 27, 2006
6.0 SOFT TRIGGERING

Soft triggering is different from local and remote triggering options. This is a means to trigger a scan on a scanner through 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 the host CE device as the trigger, or a function key on Win32 Desktop systems as the trigger, but find it necessary to have this mechanism separate from the application that is directly using the ScanAPI. Since only one executable is allowed to use the ScanAPI at any given time, one way to accomplish this is to write a custom message handler in your application that will handle a WM_SCAN message that you define. The message handler for this WM_SCAN message will call ScanTrigger(). You can then write a very small application that you can assign to one of the hardware buttons on the CE device, or a similar application for the Win32 Desktop environment that hooks the keyboard to detect function key presses. This application should do a FindWindow() to find your applications main window 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 as a parameter to the executable and can be used to trigger any scanner. It will also work with a .NET application since it sends the message directly to ScanAPI. The SocketTriggerScan and SocketTriggerRFID applications effectively function as the sample Trigger application with the appropriate preferred handle passed in. Refer to Chapters 10 and 11 for more details. NOTE: SocketTriggerSelect is only used with Socketscan.exe
January 27, 2006
7.0 SCANAPI TYPE REFERENCE

The following excerpts are taken from ScanAPI.h. The brief explanations that follow the excerpts further document the 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, SCANNER_CFCARD, SCANNER_WAND, SCANNER_GUN, SCANNER_ISCI, SCANNER_CHS, SCANNER_SDIO, SCANNER_RFID, SCANNER_MAG_STRIPE, SCANNER_CRS }; // no scanner // Socket In-Hand Scan Card // a wand // a gun // an ISCI // a CHS (cordless hand scanner) // an SDIO scanner // an RFID scanner // a Magnetic Stripe Reader // a CRS (cordless ring scanner)
SCANNER_TYPE is a value that is filled 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 CF Scan Card, etc. // Types of good-read sounds enum GRS_TYPE {GRS_NONE = 0, GRS_MESSAGEBEEP, GRS_WAVFILE}; // no good read sound // play MessageBeep(0) on good read // 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; SCANNER_TYPE ScannerType; unsigned int fHardwareTrigger :1; unsigned int fSoftwareTrigger :1; unsigned int fSoftwareAbortTrigger :1; unsigned int fGoodReadLight :1; unsigned int fGoodReadSound :1; THCAR SymbolType; } SCANDEVINFO, *LPSCANDEVINFO;
// size of the structure // gun, wand, integrated card or an imager // most likely a gun // most likely an integrated card // most likely an integrated card // most likely a gun // most likely a gun // the symbol type (UPC, Code 128, etc.) for last scan
The SCANDEVINFO structure is filled in when it is used in a call to ScanGetDevInfo(). You must fill in the size of the structure, using sizeof(SCANDEVINFO) before calling ScanGetDevInfo(), or an error will result. The rest of the fields have the following meanings: ScannerType is as defined above. 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
January 27, 2006
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 to the 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 will be one of the other defined error codes. Note that SR_HOTSWAP_ERROR is defined in the Win32 Desktop header file only and SR_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_FAILURE SR_OPEN_FAILURE SR_MEMORY_FAILURE SR_DEVICE_FAILURE SR_INTERNAL_FAILURE If you receive one of these return codes, it means something has gone wrong internally in the ScanAPI DLL, the scanning device has experienced a failure (or unexpected removal), or there are too few resources available on the host device to carry out the request. Any of the first 4 failures listed above may be correctable if the user is asked to close other programs that may be running on the device, thereby freeing up additional resources. A condition
that causes SR_DEVICE_FAILURE may be correctable if the user removes the scanner from the device and restarts your application. SR_INTERNAL_FAILURE is a catch-all for unknown failures that may occur in the ScanAPI DLL. 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 not correct the error condition, the user may be forced to remove the scanner from the CE device and perform a soft reset, or restart the system if the failure has occurred on a Win32 Desktop platform. Please report to Socket Communications Technical Support at http://www.socketcom.com/support/ if you consistently receive one of these errors 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 the Readme.txt file for details on how to properly set the communication parameters for your particular device.
January 27, 2006
8.0 SCANAPI FUNCTION REFERENCE

This section provides complete documentation of the 17 functions present in the ScanAPI DLL. Refer to the RFID SDK 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 insertion and removal notifications. Arguments: [in] hWnd is the handle of the window you want to receive wmInsertion and wmRemoval messages. It is typically the main window of the client program, but it can be any window that is guaranteed to exist for the 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 Socket scanning 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 Socket scanning device is removed from the host device. Notes: Upon success, the ScanAPI DLL is initialized. If a Socket scanning device is present when this function is called, the client application will immediately receive the message specified by the wmInsertion argument. If there is no scanning device present when this function is called, the application will receive the wmInsertion message later, when the user inserts a scanning device. When a client application receives WM_INSERTION or WM_REMOVAL messages, the lParam will contain a scanner handle that must be used to open and close the scanning device, and to perform various 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 its subsequent removal. If more than one scanning device is present when the SDK is initialized, the SDK will randomly choose one of the devices as being the supported device. Returns: SR_SUCCESS The operation completed successfully. SR_TOO_MANY_USERS In this release of the SDK, only one client may use the ScanAPI DLL. Your application program will generally get this error if ScktScan.exe is running. You need to close the program before starting your application. SR_INVALID_WMINSERTION The specified wmInsertion message is not within the valid WM_USER range. SR_INVALID_WMREMOVAL
January 27, 2006
The specified wmRemoval message is not within the valid WM_USER range. SR_PLUG_THREAD_FAILURE An 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 other processes on the device and re-tries the operation. SR_HOTSWAP_ERROR HotSwp32.dll failed to load or initialize. This error is only applicable to Windows 95, 98 or Me host machines. HotSwp32.dll is either missing or corrupt, has not been registered properly, or there are insufficient system resources available to load the DLL. The ScanAPI will not be able to detect card insertion or removal events under these circumstances, so your custom scanning application will be rendered inoperative. SR_DEVICE_FAILURE May occur as a result of calling ScanInit() on Windows NT systems only. An internal error occurred while communicating with the scanning device (perhaps the device was removed during the function call.) The client application will probably need to be re-started, and possibly the Win32 Desktop system reset (after first removing the scanning device from the host.)
January 27, 2006
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 message specified 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() as part of the message handler for the WM_INSERTION message (from ScanInit() ). Returns: SR_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED A successful call to ScanInit() must be made first. SR_INVALID_SCANNER_HANDLE The hScanner argument is not a valid scanner handle. SR_OPEN_FAILURE The ScanAPI DLL was unable to open the device. SR_DEVICE_THREAD_FAILURE An 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 other processes on the device and re-tries the operation. SR_DEVICE_FAILURE An internal error occurred communicating with the scanning device (perhaps the device was removed during the function call.) The client application will probably need to be re-started, and possibly the host CE device or Win32 Desktop system reset (after first removing the scanning device from the host.)
January 27, 2006
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 message specified when ScanInit() was called. If the application program doesnt support callbacks, use 1 for the HANDLE (if multi-scanner disabled) . Notes: A scanner must be closed if the user removes it during your programs execution. Typically a client program 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: SR_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED A successful call to ScanInit() must be made first. SR_INVALID_SCANNER_HANDLE The hScanner argument is not a valid scanner handle.
January 27, 2006
8.4
SCANGETDEVINFO()
Prototype: SCAN_RESULT ScanGetDevInfo(HANDLE hScanner, LPSCANDEVINFO lpScanDevInfo); Purpose: Get the general capabilities and identification of the requested device. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. If the application program doesnt support callbacks, use 1 for the HANDLE (if multi-scanner disabled) . [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 prevent the ScanAPI DLL from generating additional sounds. Before calling ScanGetDevInfo(), you must set the StructSize member of your SCANDEVINFO structure to the size of the structure, or the function will fail. Upon successful return, the members of the SCANDEVINFO structure will be filled in with the following information: ScannerType will be SCANNER_ISCI (for a 2D Scan Card), SCANNER_CFCARD (for a CF Scan Card), SCANNER_WAND, SCANNER_GUN (for all laser guns connected via Socket interface cards.), 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_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED A successful call to ScanInit() must be made first. SR_INVALID_SCANNER_HANDLE The hScanner argument is not a valid scanner handle. SR_SCANNER_NOT_OPEN This function fails if the scanner is not open.
January 27, 2006
SR_INVALID_STRUCTURE The lpScanDevInfo argument was NULL or the StructSize field was not set with the sizeof(SCANDEVINFO) value when the function call was made. SR_DEVICE_FAILURE An internal error occurred communicating with the scanning device (perhaps the device was removed during the function call.) The client application will probably need to be re-started, and possibly the host CE device or Win32 Desktop system reset (after first removing the scanning device from the host.)
January 27, 2006
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 application program could query the scanner to determine if scanner data was available or the general state of the scanner (scanner inserted/removed). For the RFID reader, this function works with both legacy (ScanTrigger) and RFID-specific functions.
Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. If the application program doesnt support callbacks, hardcoding the value of 1 will return the proper status. Returns: SR_SUCCESS Indicates the scanner is in place and scanned data is available in the buffer. Call ScanGetData() to retrieve the data. SR_NOT_INITIALIZED The scanner has not been initialized. A successful call to ScanInit() must be made first. SR_INVALID_SCANNER_HANDLE The hScanner argument is not a valid scanner handle. This indicates there is no scanner present or the handled supplied is not correct. SR_SCANNER_NOT_OPEN The scanner is present but ScanOpenDevice() has not been called. SR_NO_DATA There is no data available from the scanning device. SR_SCANNER_REMOVED The scanner has been removed from the socket. A call to ScanCloseDevice() should be made.
January 27, 2006
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_INSERTION message specified when ScanInit() was called. If the application program doesnt support callbacks, use 1 for the HANDLE (if multi-scanner disabled) . [in] hWnd is the handle of the window in the client application that will process the WM_SCANNERDATA message. This value must be non-0 (null) in order for SocketScan to store scanned data in the buffer. This is true even if the application doesnt accept callback events. [in] wmScannerData is a message defined by the client application that will be sent whenever the user successfully scans data. This message must be within the WM_USER range in order for SocketScan to store scanned data in the buffer. 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_SCANNERDATA message. When WM_SCANNERDATA is received by the client application, lParam will contain the scanner handle and wParam will contain the size of the data available in bytes. This can be converted into a character count (if desired) by dividing the size of the data by the sizeof(TCHAR). Typically the size 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 to ScanRequestDataEvents() simply change the desired window and/or user message to be sent. To disable 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 let the main window receive all WM_SCANNERDATA notifications and have it deal with the data (by calling ScanGetData() and routing the data to the desired control). Another more complex but valid approach is to add handlers for WM_SCANNERDATA to numerous windows. Then the application can call ScanRequestDataEvents() with different hWnd arguments (and possibly different wmScannerData arguments) when necessary in the WM_ACTIVATE handlers of these windows. Then each window could 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 received and no scanner data is stored in the buffer. An application program can use this feature to enable/disable scanning depending upon where the keyboard focus is within the application.
January 27, 2006
Returns: SR_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED A successful call to ScanInit() must be made first. SR_INVALID_SCANNER_HANDLE The hScanner argument is not a valid scanner handle. SR_INVALID_WMSCANNERDATA The wmScannerData argument is not within the valid WM_USER range.
January 27, 2006
8.7
SCANTRIGGER()
Prototype: SCAN_RESULT ScanTrigger(HANDLE hScanner); Purpose: Trigger a scan on a scanning device. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. If the application program doesnt support callbacks, use 1 for the HANDLE (if multi-scanner disabled) . Notes: For the CFSC/SDSC/CHS, this function returns immediately and, upon a successful read, the client application will receive the user-defined WM_SCANNERDATA message specified in a prior call to ScanRequestDataEvents(). For scanners that use hardware triggers on the scanner device, this function returns 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 the wand across a bar code. Normally, this call is used start the scanner. The scanning stops after scanning a supported bar code or when the time-out period expires (typically 3 seconds). There is no indication to the calling program if no bar code is found. For RFID, this call will issue a Select Tag command to the reader depending on registry settings this can be modified. This call is made with tag type set to Auto-detect so it returns the first tag ID it can read in its field. The application program will receive a WM_SCANNERDATA message indicating data is available and calling ScanGetData() returns the tag type and tag ID. No message will be received if there is no tag in the field at the time ScanTrigger() is called or if there was an error reading the tag. Note that this 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 that ScanRFIDSelectTag() be used instead. Returns: SR_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED A successful call to ScanInit() must be made first. SR_INVALID_SCANNER_HANDLE The hScanner argument is not a valid scanner handle. SR_SCANNER_NOT_OPEN This function fails if the scanner is not open.
January 27, 2006
SR_DEVICE_FAILURE An internal error occurred communicating with the scanning device (perhaps the device was removed during the function call.) The client application will probably need to be re-started, and possibly the host CE device reset or the Win32 Desktop system restarted (after first removing the scanning device from the host.)
January 27, 2006
8.8
SCANABORT()
Prototype: SCAN_RESULT ScanAbort(HANDLE hScanner); Purpose: Terminate a scan-in-progress on a scanning device. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. If the application program doesnt support callbacks, use 1 for the HANDLE (if multi-scanner disabled) . Notes: For scanning devices that support this operation, the laser beam is switched off and the scan is terminated. Calling this function when a scan is not in progress or on devices that do not support this feature, has no effect and the function returns successfully. This function not implemented for the 2DSC. 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_SCANNERDATA message if ScanRFIDGetData() function is not called. (The application must call ScanRFIDGetData() for every WM_SCANNERDATA message received unless ScanAbort() is called.) Returns: SR_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED A successful call to ScanInit() must be made first. SR_INVALID_SCANNER_HANDLE The hScanner argument is not a valid scanner handle. SR_SCANNER_NOT_OPEN This function fails if the scanner is not open. SR_DEVICE_FAILURE An internal error occurred communicating with the scanning device (perhaps the device was removed during the function call.) The client application will probably need to be re-started, and possibly the host CE device reset, or Win32 Desktop system restarted (after first removing the scanning device from the host.)
January 27, 2006
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. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. If the application program doesnt support callbacks, use 1 for the HANDLE (if multi-scanner disabled) . [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 set to the number of bytes written into lpBuff. This can be converted to a character count by dividing BufSize by 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 data returned will be in UNICODE on CE devices. It is possible for NULL characters to appear in the scanned data, depending on the symbology scanned by the user. Also note that the ScanAPI DLL will not NULL-terminate the scanned data. Therefore, do all necessary 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 preprocessing 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 the function will return 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 return SR_BUFFER_TOO_SMALL. At this point you MUST call ScanGetData() again with a larger buffer to remove the data and allow for continued scanning. Applications should respond to the WM_SCANNERDATA message as soon as possible. The ScanAPI DLL has a small buffer for storing multiple scans (currently 16 scans), in case the user is scanning data more quickly than your application can process it. But when this buffer fills, additional scanned data will be 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 the scanner 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 is one of TagID, Tag Data, or TagID and Tag Data. For example it could return just the TagID as an ASCII string 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
January 27, 2006
Note: This is a legacy function for compatibility with SocketScan and its recommended that the specific RFID functions be used instead of ScanTrigger() and ScanGetData(). Do not call this function when issuing any specific RFID function (i.e. ScanRFIDSelectTag(), ScanRFIDReadTag(), etc.). Returns: SR_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED A successful call to ScanInit() must be made first. SR_INVALID_SCANNER_HANDLE The hScanner argument is not a valid scanner handle. SR_SCANNER_NOT_OPEN This function fails if the scanner is not open. SR_NO_DATA There is no data available from the scanning device. SR_BUFFER_TOO_SMALL A 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 for continued scanning.
January 27, 2006
8.10 SCANSETGOODREADSOUND()
Prototype: SCAN_RESULT ScanSetGoodReadSound(HANDLE hScanner, GRS_TYPE Sound, LPCTSTR lpWavFile); Purpose: Tells the ScanAPI DLL to be silent, call MessageBeep(0), or play a .wav file when the user successfully scans data with the specified device. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. If the application program doesnt support callbacks, use 1 for the HANDLE (if multi-scanner disabled) . [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 device is 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 successfully opening the scanner with ScanOpenDevice() in the WM_INSERTION message handler, if the default sound configuration is not desired. Returns: SR_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED A successful call to ScanInit() must be made first. SR_INVALID_SCANNER_HANDLE The hScanner argument is not a valid scanner handle. SR_INVALID_SOUND_TYPE The Sound argument must be GRS_NONE, GRS_MESSAGEBEEP, or GRS_WAVFILE. SR_WAVFILE_NOT_FOUND Unable to find the file referenced by the lpWavFile argument. SR_MEMORY_FAILURE An 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 other processes on the device and re-tries the operation.
January 27, 2006
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. Any scanning devices that are open will be closed by the ScanDeinit() function. Returns: SR_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED A successful call to ScanInit() must be made first. SR_DEVICE_FAILURE May occur as a result of calling ScanInit() on Windows NT systems only. An internal error occurred while communicating with the scanning device (perhaps the device was removed during the function call.) The client application will probably need to be re-started, and possibly the Win32 Desktop system reset (after first removing the scanning device from the host.) On Windows NT systems, a scanning device MUST be present in the system BEFORE calling ScanInit(). Additionally, the scanning device MUST NOT BE REMOVED from the system while the ScanAPI 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 in progress, the COM port associated with the PC Card will not be configured properly, and ScanAPI errors will result. Under Windows NT, all PC Card devices must be present at boot-time, and can never be safely removed without re-booting. The exception is if you have added third-party Card and Socket Services to your NT system. In this case, the scanning device must be present before the ScanInit() call, but can be safely removed AFTER ScanDeinit() is called.
January 27, 2006
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 in UNICODE 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). Typically the 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 lpBuff argument in this case BufSize will be filled in with the size of the error message and the function will return 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 return SR_BUFFER_TOO_SMALL. Returns: SR_SUCCESS The operation completed successfully. SR_INVALID_ERR The error you are trying to translate is not known. SR_BUFFER_TOO_SMALL A larger buffer is required to accommodate the text. SR_INTERNAL_FAILURE An unexpected error occurred in the ScanAPI DLL.
January 27, 2006
8.13 SCANPARAMSEND()
Prototype: SCANAPI_API SCAN_RESULT ScanParamSend(HANDLE hScanner, PBYTE paramIn, UINT paramInLen, PBYTE paramVal, UINT paramValLen); Purpose: Modifies one or more parameters of the scanner hardware for WinCE only. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. If the application program doesnt support callbacks, use 1 for the HANDLE (if multi-scanner disabled) . [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 specified by the paramIn buffer. All parameter values are bytes but the paramVal buffer may be arranged as 8-bit or 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 this function 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 are permanent 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 this mode, 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. Note that only the upper bit of the first parameter element of the buffer must be set to enable permanent mode. Set the paramValLen parameter to be the length of the paramVal buffer which in permanent mode 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_SUCCESS The operation completed successfully. ERROR_NOT_SUPPORTED The scanner in use does not support the ScanParamSend function.
January 27, 2006
ERROR_NOT_READY A problem occurred sending the command(s) to the scanner. ERROR_OUTOFMEMORY The function was not able to allocated memory needed to complete the request.
January 27, 2006
8.14 SCANPARAMREQUEST()
Prototype: SCAN_RESULT ScanParamRequest(HANDLE hScanner, PBYTE paramIn, UINT paramInLen, PBYTE paramOut, PUINT paramOutLen); Purpose: Retrieves the current setting of one parameter of the scanner hardware for WinCE only Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. 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 calling ScanParamRequest. 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 on other 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: SR_SUCCESS The operation completed successfully. ERROR_NOT_SUPPORTED The scanner in use does not support the ScanParamSend function. ERROR_NOT_READY An internal error occurred requesting the parameter from the scanner. ERROR_INSUFFICIENT_BUFFER The length of the paramOut buffer was not 1.
January 27, 2006
8.15 SCANSENDCOMMAND()
Prototype: SCANAPI_API SCAN_RESULT ScanSendCommand(HANDLE hScanner, IN OUT LPTSTR pCmd_CmdResponse, IN OUT int* piLength); Purpose: Sends a command to the 2DSC hardware and receives the 2DSCs response for WinCE only. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. 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 receives the response to the command by the imager. [in out] piLength is an integer that specifies the maximum number of characters pCmd_CmdResponse buffer 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 return ERROR_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_SUCCESS The operation completed successfully. SR_UNSUPPORTED_FEATURE The scanner in use does not support the ScanSendCommand function. SR_INTERNAL_FAILURE An internal error occurred requesting the parameter from the scanner. SR_BUFFER_TOO_SMALL The length of the pCmd_CmdResponse was insufficient to hold the entire response.
January 27, 2006
8.16 SCANPARAMSENDEX()
Prototype: SCANAPI_API SCAN_RESULT ScanParamSendEx(HANDLE hScanner, PUINT16 paramIn, UINT paramInLen, PBYTE paramVal, UINT paramValLen); Purpose: Modifies one or more parameters of the scanner hardware. This API is slightly different from ScanParamSend() in that the paramIn is now of type PUINT16. This is for opcodes that are of two byte lengths (ie RSS-14) and is for WinCE only. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. 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 specified by the paramIn buffer. All parameter values are bytes but the paramVal buffer may be arranged as 8-bit or 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 on other 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 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 are permanent 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 this mode, 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. Note that only the upper bit of the first parameter element of the buffer must be set to enable permanent mode. Set the paramValLen parameter to be the length of the paramVal buffer which in permanent mode 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_SUCCESS The operation completed successfully. SR_UNSUPPORTED_FEATURE
The scanner in use does not support the ScanParamSendEx function. SR_DEVICE_FAILURE A problem occurred sending the command(s) to the scanner.
January 27, 2006
8.17 SCANPARAMREQUESTEX()
Prototype: SCANAPI_API SCAN_RESULT ScanParamRequestEx(HANDLE hScanner, PUINT16 paramIn, UINT paramInLen, PBYTE paramOut, PUINT paramOutLen); Purpose: Retrieves the current setting of one parameter of the scanner hardware. This API is slightly different from ScanParamRequest() in that the paramIn is now of type PUINT16. This is for opcodes that are of two byte lengths (ie RSS-14). Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. [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 calling ScanParamRequest. 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 than CFSC/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_SUCCESS The operation completed successfully. SR_UNSUPPORTED_FEATURE The scanner in use does not support the ScanParamSendEx function. SR_DEVICE_FAILURE An internal error occurred requesting the parameter from the scanner. SR_BUFFER_TOO_SMALL The length of the paramOut buffer was not 1.
January 27, 2006
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: TRUE The scanner is connected and is open for communications FALSE If 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 multiscanner scenario. IsScannerConnected() calls this API with SCANNER_NONE as a parameter. Arguments: [in] scannerType: Type of scanner to check Returns: TRUE The scanner is connected and is open for communications FALSE If scanner has an invalid handle or is not OPEN.
January 27, 2006
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. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. [in] nSymID is the symbology ID to be Enabled or Disabled. For symbology IDs refer to the enumerated data type SCANNER_SYMBOLOGY in SCANAPI.h file. [in] flag to enable or disable symbology Returns: SR_SUCCESS The operation completed successfully SR_INVALID_SCANNER_HANDLE Invalid scanner handle SR_SYMBOLOGY_NOT_SUPPORTED Invalid symbology ID SR_DEVICE_FAILURE An internal error occurred requesting a call to the scanner
NOTE: This API will supersede ScanParamSend(), ScanParamSendEx() API calls.
January 27, 2006
8.21 SCANREADSYMBOLOGYCONFIG()
Prototype: SCANAPI_API SCAN_RESULT ScanReadSymbologyConfig (HANDLE hScanner, int cfgType, int nSymbol, PVOID pvSym); Purpose: Reads symbology configuration for all types of Socket scanner devices Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. [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 enumerated data 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 contain symbology info on return Returns: SR_SUCCESS The operation completed successfully SR_INVALID_SCANNER_HANDLE Invalid scanner handle SR_INVALID_ERR Invalid structure passed to read the symbology configuration SR_SYMBOLOGY_NOT_SUPPORTED Invalid symbology ID SR_DEVICE_FAILURE An internal error occurred requesting a call to the scanner to Enable/Disable symbology
NOTE: This API will supersede ScanParamRequest(), ScanParamRequestEx() API calls.
Socket Communications, Inc.
November 16, 2004
Revision 2.18
8.22 SCANWRITESYMBOLOGYCONFIG()
Prototype: SCANAPI_API SCAN_RESULT ScanWriteSymbologyConfig (HANDLE hScanner, int nSymbol, PVOID pvSym); Purpose: Writes symbology configuration for all types of Socket scanner devices Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. [in] nSymbol is the symbology ID to write the configuration to. For Symbology IDs refer to the enumerated data type SCANNER_SYMBOLOGY in SCANAPI.h file. [in] pvSym is the void pointer to the structure that has symbology configuration settings Returns: SR_SUCCESS The operation completed successfully SR_INVALID_SCANNER_HANDLE Invalid scanner handle SR_UNSUPPORTED_FEATURE Is returned if any scanner other than the 2D Scan Card tries to set configuration parameters SR_SYMBOLOGY_NOT_SUPPORTED Invalid symbology ID SR_DEVICE_FAILURE An internal error occurred requesting a call to the scanner to Enable/Disable symbology NOTE: This API will supersede ScanParamSend(), ScanParamSendEx() API calls.
8.23 SCANENABLEMULTISCANNER()
Prototype: SCANAPI_API SCAN_RESULT ScanEnableMultiScanner(void); Purpose: This function must be called before ScanInit() by the application in order to enable multiple scanners. Arguments: None Returns: SR_SUCCESS
Socket Communications, Inc. November 16, 2004 Revision 2.18
The operation completed successfully SR_INVALID_ERR The scanner was already initialized SR_NOT_INITIALIZED The Scanning library is not initialized SR_INVALID_SCANNER_HANDLE Scanner handle is not valid SR_SCANNER_NOT_OPEN Scanner is not open
8.24 SCANGETSCANNERREGKEY ()
Prototype: SCANAPI_API SCAN_RESULT ScanGetScannerRegKey(HANDLE hScanner, BOOL activeKey, LPTSTR lpBuff, LPINT BufSize); Purpose: This returns a path to the key of the active device in order to extract parameters for that device from the registry Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. [in] activeKey [in/out] lpBuff contains the registry key [in/out] BufSize contains the size of the string (including terminating zero) in bytes Returns: If activeKey is TRUE, the scanner's active key (\Drivers\Active\NN) key string will be returned, otherwise it returns the driver key (\Drivers\PCMCIA\PnP ID\etc).
SR_INVALID_ERR The scanner was already initialized SR_NOT_INITIALIZED The Scanning library is not initialized SR_INVALID_SCANNER_HANDLE Scanner handle is not valid SR_SCANNER_NOT_OPEN Scanner is not open
January 27, 2006
8.25 SAMPLE SYMBOLOGY CONFIG CODE:
8.25.1 Sample Code to Enable or Disable CODE39 symbology: result = ScanEnableDisableSymbology (hScanner, SYMB_CODE39, TRUE); // Enable OR result = ScanEnableDisableSymbology (hScanner, SYMB_CODE39, FALSE); // Disable if (result != SR_SUCCESS) return FALSE; return TRUE 8.25.2 Sample code for Read configuration: if (SYMBOL_RANGE_FLAG[SYMB_CODE39]) { flagsRange.dwStructSize = sizeof( ScannerSymFlagsRange_t ); flagsRange.dwMask = SYM_MASK_ALL; pvSymVoid = (PVOID) &flagsRange; } else { flagsOnly.dwStructSize = sizeof( ScannerSymFlagsOnly_t ); flagsOnly.dwMask = SYM_MASK_ALL; pvSymVoid = (PVOID) &flagsOnly; } result = ScanReadSymbologyConfig (hScanner, SETUP_TYPE_CURRENT, SYMB_CODE39, pvSymVoid); if (result == SR_SUCCESS) { if (SYMBOL_RANGE_FLAG[SYMB_CODE39]) Flags = flagsRange.dwFlags; else Flags = flagsOnly.dwFlags; mask = SYMBOLOGY_ENABLE; if (Flags & mask) { BARCODES_ENABLED[EnabledBarcodes] = (BYTE) SYMB_CODE39; ++ EnabledBarcodes; } } Look ahead table for checking if the symbology has a range configuration or not:
BYTE SYMBOL_RANGE_FLAG[SYMB_ALL_SYMBOLOGIES] =
January 27, 2006
{ TRUE, TRUE, TRUE, TRUE, TRUE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, FALSE, TRUE, TRUE, TRUE, FALSE, FALSE, TRUE, FALSE, FALSE, FALSE, TRUE, FALSE, FALSE, TRUE, TRUE, TRUE, TRUE, TRUE, FALSE, FALSE, }; // Code 11 // Code 128 // Code 39 // Code 49 // CODE 93 // Code 39 FULL ASCII // Tropotic Code39 // UPC - A // UPC - E // UPC - E0 // UPC - E1 // EAN - 8 // EAN - 13 // BOOKLAND EAN // Composite CODE or UCC/EAN // CODABAR // CODABLOCK // DISCRETE 2/5 // IATA 2/5 // Interleaved 2/5 // ISBT // Matrix 2/5 // MSI PLESSEY // RSS 14 // TLCODE 39 // Australian Postal // AZTEC // AZTEC MESA // British Postal // Canadian Postal // Data Matrix Code // Dutch Postal // Japanese Postal // MaxiCode // Micro PDF // OCR // PDF // QR CODE // US Planet Postal // US Postnet Postal
Structures ScannerSymFlagsRange_t & ScannerSymFlagsOnly_t are declared in ScanAPI.h file for your reference.
8.25.3 Sample Code to Enable or Disable CODE39 symbology: result = ScanEnableDisableSymbology (hScanner, SYMB_CODE39, TRUE); // Enable OR result = ScanEnableDisableSymbology (hScanner, SYMB_CODE39, FALSE); // Disable if (result != SR_SUCCESS) return FALSE; return TRUE
January 27, 2006
9.0 CORDLESS SCANNER (CS) SPECIFICS

The Cordless Scanners integrate Sockets barcode scanning capabilities into a cordless solution. The user can now program the same functionality provided in our SDK through a Bluetooth connection. Along with these changes new APIs are required to configure and manage the Bluetooth connection as well as the scanner. To provide CS functionality is straight-forward. A simple call to ScanEnableCHS() to load the driver and the creation of a user defined message type to handle the connection status is all that is needed! The following information on the relevant APIs and registry settings should provide the required details. An example of its usage is also available in the sample code. At present the CHS and CRS can connect via most commercial Bluetooth stacks. The stack used on your particular device needs to be selected and configured via registry settings. The Builtin stack works with stacks provided by Microsoft, Widcomm and the Other stack can be configured for more recent stacks. Another feature of the Cordless Scanners is remote vs local scanning options. When remote scanning is selected all communication with the PDA is confirmed, hence you cannot trigger a scan until the PDA acknowledges the scan request. Local scanning is a faster and more efficient scanning method; it does not require all communication to be confirmed. Remote works best when the connection proves to be unreliable or when distances are greater; whereas, local scanning is intended for short range scanning. The CS MUST always receive a response from the application for the trigger button to be responsive. If no response is sent back, the trigger button will resume operation after a 10 second lockout. In the case where a user wishes to send a negative ack back to the CS he can call ScanSendCmdtoCHS () with payload of 0x06 (SET_INDICATORS_CMD) and command of 0x00 (None), which will result in no beep or sound being generated. For this mode of operation the following key must be added to the registry: HKLM,"Software\Socket Communications\CHS\1.0", " AutoSendGoodScanInd",0x00010001, 0x00 For more information, refer to registry setting details later in this chapter.
Socket Communications, Inc.
November 16, 2004
Revision 2.18
9.1
SCANENABLECHS()
Prototype: SCANAPI_API SCAN_RESULT ScanEnableCHS(HWND hWnd, UINT wmCHSStatus); Purpose: This function activates the Cordless Scanner and loads its driver. Arguments: [in] hWnd is the handle of the CS status window receives CS notification messages [in] wmCHSStatus is the user status of the CS it notifies the state of dynamic reconnection, if the connection is lost, or reconnected. Generally this is a user defined message handle. Notes: This function is only relevant to CS. This function will send a wmInsertion message to the main window. Returns: SR_SUCCESS The operation completed successfully. SR_INVALID_WMCHSSTATUS The wmCHSStatus message is not within the allowed User message range. SR_NOT_INITIALIZED The scanner has not been initialized SR_INTERNAL_FAILURE The CHS driver failed to load.
January 27, 2006
9.2
SCANDISABLECHS()
Prototype: Windows CE: SCANAPI_API SCAN_RESULT ScanDisableCHS(HANDLE hScanner); Windows XP: SCANAPI_API SCAN_RESULT ScanDisableCHS(HWND hWnd, HANDLE hScanner);
Purpose: This function will disable CHS and unload the CHS driver Arguments: [in] hScanner is the scanner id used to disable the CHS Notes: This function is only relevant to the CHS. This function will send a wmRemoval message to the main window. Returns: SR_SUCCESS The operation completed successfully. SR_DEVICE_FAILURE Unable to communicate with the scanner SR_INTERNAL_FAILURE The CHS driver failed to load.
January 27, 2006
9.3
SCANSENDCMDTOCHS()
Prototype: SCANAPI_API SCAN_RESULT ScanSendCmdtoCHS(HANDLE hScanner, PBYTE paramIn, UINT paramInLen, DWORD Timeout) Purpose: Send Configuration commands to CHS Battery status inquiry, Self test inquiry (CHS version information), Friendly Name inquiry, Set Friendly Name, Set Security (PIN, Authentication), Delete Pairing & Bonding and Set Device configuration. Refer to later sections for more details on command options. Arguments: [in] hScanner is the value received by the client application in lParam of the WM_INSERTION message specified when ScanInit() was called. [in] paramIn is a 8 bit buffer containing the parameter number that will be retrieved. In this buffer the first byte contains the CHS configuration command opcode. The following byte(s) contain the parameter value. The SCANAPI opcodes for CHS commands are:
#define #define #define #define #define #define #define #define
SET_SECURITY_MODE_CMD SET_FRIENDLY_NAME_CMD SET_PIN_CODE_CMD SET_DEVICE_CONFIG_CMD SET_INDICATORS_CMD BATT_CHRG_STATE_INQ_CMD FRIENDLY_NAME_INQ_CMD DEL_PAIRING_BONDING_CMD
0 1 4 5 6 8 10 11
For Example to issue a Set Security mode command check the following sample code: paramIn[0] = SET_SECURITY_MODE_CMD; paramIn[1] = 0 or 1 or 2; paramInLen = 2; Timeout = 3; ScanSendCmdtoCHS (hScanner, paramIn, paramInLen, Timeout); [in] paramInLen is the length of the paramIn buffer in bytes [in] Timeout is the timeout for CHS configuration command response, specified in seconds
Returns: Upon exit, this will be set to 0 if an error occurs, non-zero value otherwise. SR_SUCCESS The operation completed successfully. SR_NOT_INITIALIZED
January 27, 2006
Library is not initialized SR_INVALID_SCANNER_HANDLE Invalid Scanner handle SR_DEVICE_FAILURE IO Control call FAILS SR_WAIT_TIMEOUT_ERROR CHS configuration response timeout has occurred
January 27, 2006
9.4
BLUETOOTH CONNECTION STATUS

When the CHS is configured, the Bluetooth stack needs to be enabled. Along with the appropriate registry settings refer to the section on registry configuration, the wParam and lParam values are used to communicate the state of the stack. To enable the CHS the ScanEnableCHS(HWND hWnd, UINT wmCHSStatus) function is called. The second parameter is a user defined message that can be customized to handle the three possible CHS Bluetooth states. The wParam range for a wmCHSStatus message is: CHS_BTLINK_DROPPED CHS_BTLINK_ABORTED CHS_BTLINK_RE_ESTABLISHED Refer to the SDK sample code for an example. Depending on the desired action the user should customize the error status for their particular application.
January 27, 2006
9.5
CHS COMMANDS
These tables show the various codes that can be sent to configure the CHS via the SendCmdToCHS() API. 9.5.1 Set Security Mode
Set Security Mode Field Name Opcode Payload Format 0x00 Size 1 Byte 1 Byte Select Description Set Security mode Bluetooth security mode 0x00 = None 0x01 = Authentication 0x02 = Authentication +Encryption
9.5.2
Set Friendly Name Set Friendly Name Field Name Opcode Payload Format 0x01 Size 1 Byte None Description Opcode for setting friendly name Update registry entry Friendly Name with 1 to 248 character string before issuing this command
9.5.3
Set PIN Code Set PIN Code Field Name Opcode Payload Format 0x04 Size 1 Byte None Description Set Pin Code Update registry entry PinCode with 1 to 16 byte string before issuing this command
January 27, 2006
9.6
9.6.1
CHS CONTROL COMMANDS

Set Indicators Set Indicators Field Name Opcode Payload Format 0x06 Size 1 Byte 1 Byte Select Description Light LED and or Beep indicator to activate: 0x00 = None 0x01 = Beep 0x02 = Flash Green LED 0x03 = Beep and Flash Green LED
9.6.2
Battery Charge State Inquiry Battery Charge State Inquiry Field Name Opcode Payload Format 0x08 Size 1 Byte None Description Request battery status
9.6.3
Battery Charge State Response Battery Charge State Response Field Name Response Format 0x00 to 0x64 Size 1 Byte Description Battery charge state 0-100 % is updated in registry entry BattCharge
9.6.4
Friendly Name Inquiry Friendly Name Inquiry Field Name Opcode Payload Format 0x0A Size 1 Byte None Description Request Friendly Name
January 27, 2006
9.6.5
Friendly Name Response Friendly Name Response Field Name Response Format Size Variable Description 1 to 248 character string is updated in registry entry FriendlyName
January 27, 2006
9.7
REGISTRY SETTINGS FOR THE CORDLESS HAND SCANNER

To enable the Bluetooth stack and SocketScan SDK, there are registry settings that must be configured appropriately.
HKLM,"Software\Socket Communications\CHS\1.0", "StackType",0x00010001, 1 This key defines the Bluetooth stack to be used. For Win CE: ST_SOCKET ST_BUILTIN ST_OTHER 0 1 2
For Win XP: ST_SOCKET ST_BUILTIN ST_MSFT_SP2 ST_OTHER 0 1 2 3
HKLM,"Software\Socket Communications\CHS\1.0", " BTConnReConnTO", 0x00010001, 0x05 This key is used to set the Bluetooth reconnection time between retries HKLM,"Software\Socket Communications\CHS\1.0", " BTConnRetries", 0x00010001, 0x01 This key is used to set the Bluetooth connection retries HKLM,"Software\Socket Communications\CHS\1.0", " BattCharge",0x00010001, 0x64 This key is used to check the Battery charge level in the CHS HKLM,"Software\Socket Communications\CHS\1.0", " BeeperFreq, 0x00010001, 0x01 This key is used to set the CHS beeper frequency HKLM,"Software\Socket Communications\CHS\1.0", "BtPort", 0x00010001, 0x07 This key defines the COM port to be used. HKLM,"Software\Socket Communications\CHS\1.0", "Beep",0x00010001, 0x01 Should the CHS beep on a good read? No 0 Yes 1 HKLM,"Software\Socket Communications\CHS\1.0", " CHSPICVer", 0x00010001, 0x01 This key defines the PIC version, in the CHS HKLM,"Software\Socket Communications\CHS\1.0", " CHSVerMonthDay", 0x00010001, 0x1015 This key defines the build version, month & day in the CHS
HKLM,"Software\Socket Communications\CHS\1.0", " CHSVerTime", 0x00010001, 0x0923 This key defines the build version, time in the CHS HKLM,"Software\Socket Communications\CHS\1.0", " CHSVerYear", 0x00010001, 0x2004 This key defines the build version, year in the CHS HKLM,"Software\Socket Communications\CHS\1.0", "Flash", 0x00010001, 1 Should the CHS flash green LED on a good read? No 0 Yes 1 HKLM,"Software\Socket Communications\CHS\1.0", " FriendlyName ", 0x00000000, CHS Scanner This key defines the friendly name of the CHS HKLM,"Software\Socket Communications\CHS\1.0", " PinCode ", 0x00000000, 31 32 33 34 This key defines the Pin code to be set in the CHS HKLM,"Software\Socket Communications\CHS\1.0", PowerSave ", 0x00010001, 0x00 This key defines the Auto-power off feature in the CHS HKLM,"Software\Socket Communications\CHS\1.0", "TriggerMode",0x00010001, 0x00 This key sets the trigger mode. Local scanning is for short distances to the PDA; whereas, remote scanning when the PDA connection is further or more unreliable. Local (Scan always) 0 Remote triggering (Only when connected to host) 1 HKLM,"Software\Socket Communications\CHS\1.0", UseCHS",0x00010001, 0x00 This key defines if the CHS is the scanner selected by the user HKLM,"Software\Socket Communications\CHS\1.0", AutoSendGoodScanInd",0x00010001, 0x01 This key defines if the CHS driver will automatically send a good scan indication (beep and/or flash) to the CHS after receiving a scanned bar code. If the registry entry is set to 0, then a good scan acknowledgement must be sent by the application (by sending a Set Indicators command.) Every time the CHS reads a barcode, it expects a good scan acknowledgement (Set Indicators command). If it does not receive it, it waits for 10 seconds to receive it during which it disables scanning capability. Scanning is enabled automatically after the 10 second timeout. Please refer to Chapter 9.5/9.6 for more details about issuing Set Indicator commands. If the AutoSendGoodScanInd registry entry is set to 1, then the driver automatically sends a Set Indicators command after every scan. The parameters for the Set Indicators command are determined by the value set for Beep and Flash registry entries. NOTE: If the registry entry is changed after a CHS connection has been established, the connection should be disconnected and reconnected for the change to take effect.
January 27, 2006
10.0
RFID READER
The Socket CF RFID Reader Card allows the reading and writing of numerous HF RFID tags. The SDK gives the programmer full control over the RFID Reader and tag functions. Refer to the Socket RFID SDK User Guide for more information about the RFID functions and operation.
January 27, 2006
11.0
MULTISCANNER SUPPORT (WIN CE ONLY)
The following describes the changes to SocketScan to handle the CF RFID Reader-Scan Card. The CF RFID Reader-Scan Card is really two scanners in one: RFID + CFSC. This version treats the CF RFID Reader-Scan Card as two individual scanning devices and therefore extends beyond just the CF RFID Reader-Scan Card to allow other scanners to coexist. One example is the CF Scan Card (CFSC) and the Cordless Hand Scanner (CHS). NOTE: Currently, the SDK doesnt support two hardware configurations: CFSC or CF RFID Reader-Scan Card and the SD Scan Card. This version of the SDK allows for multiple scanners if enabled. The goal was to maintain backward compatibility so ScanAPI works exactly like it has with legacy applications (non-multiple-scanner aware). A new scanner API call was added that tells ScanAPI that the application supports multiple scanners. The change to an application to support multiple scanners is the ability to handle multiple wmInsertion and wmRemoval callback messages. When the CF RFID Reader-Scan Card is inserted and an application is registered with ScanApi.dll, it will receive two wmInsertion callbacks (one for RFID and one for CFSC). Each wmInsertion callback will include a unique scanner handle that is used to communicate with that particular scanning device. The scanner handle is used to trigger the device, get scanner status, and determine when data is available from the scanner. In the past this scanner handle has always been assumed to be 1 and still is when the multiple scanning capability is not enabled. It can now range from 1 to 10.. This version of Scan API also supports scanner triggering using a new SendMessage command. The application or a stand-alone program can send a message to ScanAPI to trigger a particular scanner independent of which application is running. (The previous version only allowed an external trigger through the SocketScan.exe application.) To help this process some of the scanner handles have been reserved based on the scanner type. This provides a consistent way to trigger a particular scanning device independent of the "insertion order." The predefined scanner handles are:
RFID 1
CFSC 2
SDSC 3
CHS 4
2DSC 5
Other 6 to 10
Note: The predefined values are defined in the Plug-n-Play string for the scanner type (see DesiredHandle for more information). In the case of multiple scanners with predefined handles, the first scanner gets the reserved handle number and all other scanners of that type get the first available scanner handle starting with 10 and working downwards. A few sample programs have been precompiled to trigger the RFID and CFSC scanners, namely TriggerRFID.exe and TriggerISC.exe. Assigning these programs to a button on the PDA will trigger the RFID or CFSC scanner (if the scanner is present). The developer can use these applications or compile his own to take advantage of this feature.
11.1 REGISTRY SETTINGS FOR THE CF RFID READER-SCAN CARD

DisablePlugSnd Set to 1 to disable the insertion sound. If the entry is missing or set to 0, SocketScan will beep when an insertion message is received for this device. (Used to keep SocketScan from beeping twice when the RFIDScan card is inserted). [HKEY_LOCAL_MACHINE\Drivers\PCMCIA\<YOUR PNP ID>\Scanner 2] "DisablePlugSnd"=dword:00000001
January 27, 2006
DesiredHandled To implement the handle numbers, just add the "DesiredHandle" DWORD value to the registry for each scanner for instance (range 1 to 10): [HKEY_LOCAL_MACHINE\Drivers\PCMCIA\<YOUR PNP ID>\Scanner] "DesiredHandle"=dword:00000001 [HKEY_LOCAL_MACHINE\Drivers\PCMCIA\<YOUR PNP ID>\Scanner 2] "DesiredHandle"=dword:00000002
January 27, 2006
12.0
USING SOCKETSCAN (KEYBOARD WEDGE)
If your scanning application is very simple, or your development language is not able to call a DLL, you may find that using the SocketScan keyboard wedge software (ScktScan.exe) will fill your needs. SocketScan simply runs in the background monitoring scanning devices and, when data is scanned, it is sent to the application that currently has the keyboard focus. You may define a prefix and suffix that will be added to the scanned data, if desired. There are several drawbacks to this approach. Probably the biggest drawback is that you have no control over where the data is going you must take it on faith that the user has selected the appropriate control to receive the scanned data. Other drawbacks that existed in the initial release of SocketScan can now be addressed if you have the ability to create a DLL. By creating a SocketScan Preview DLL, you can process the scanned data before the data is submitted to the keyboard. This gives you the flexibility, for example, to change the data prefix or suffix on-the-fly, shave or filter unwanted characters from the scanned data, etc. The obvious benefit of using SocketScan is that it works with ANY application that is designed to accept keyboard input (which is basically all applications). Data can be scanned into Word Mobile or Excel Mobile as easily as it can be scanned into your application. No changes are required to your existing application code whatsoever.
January 27, 2006
13.0
SOCKETSCAN TRIGGER APPLICATIONS (WINCE ONLY)
SocketScan now supports multiple scanners as well as a number of scan trigger options. This is a short description of those scan trigger options. The following programs can be used to trigger a scanning device: SocketScan Trigger Select Trigger Scan Trigger RFID Trigger xyz SocketScan is a keyboard wedge application as well as a trigger program. If the program is assigned to a PDA button and pressed, it will either load SocketScan, and install itself as a keyboard wedge, or act as a scan trigger application. It does this by first detecting if its already running or if RFID Demo or ScanDemo are running. If it finds one of these three programs running, it sends a message to the running application to tell it that a scan trigger is needed. In the case of SocketScan or ScanDemo, this triggers the selected scan device (the one shown with the checkmark in the applications menu). For RFID Demo, it always triggers the RFID scanner. Trigger Select works specifically with SocketScan and is not really a trigger program but used to advance SocketScan to the next selected device. It only switches to scan devices that only have software triggers (this includes RFID, CFSC, and SDSC it does not include the CHS, Wand Scanner or Gun Scanner). This program is used in conjunction with SocketScan to do the actual triggering. Trigger Scan and Trigger RFID make calls directly to ScanAPI to do a ScanTrigger. These calls are independent of the running application so they will work with the existing SocketScan applications as well as user-written applications. These trigger programs call ScanAPI will a Scanner Handle thats associated with the scanner type. Note: The predefined scanner handles are only valid when ScanApi.dll has been enabled for Multiple Scanners. ScanApi defaults to single scanner mode and the scanner handle is always 1. Since Trigger RFID uses scanner handle 1, it would then trigger whatever scanner was active in the device (provided it accepted a software trigger). Trigger xyz is listed here because it is a user-defined trigger program. Source code for this program is provided in the SDK and all the programmer needs to do is modify the code with the desired scanner handle and compile the program to create a new trigger application. Trigger Scan and Trigger RFID were created in this way. See the SDK documentation for a list of predefined scanner handle numbers. Using the above applications to trigger the RFID scanner may not be the best solution. The ScanTrigger function in ScanApi.dll supports RFID scanning in legacy mode. Originally it would only scan the tag IDs (calling Select Tag in the RFID driver). This was done to mimic the reading of a bar code. This version of SocketScan allows that to be expanded depending upon registry settings controlled by the RFID Setup control panel applet. After installation it defaults to reading only the tag IDs but can be changed to read the tag data blocks or both the tag IDs and data blocks. This may be useful if the user wants a simple way to import tag data into a spreadsheet but if more control is needed, a user application needs to be written using the RFID SDK. The following is a table shows the trigger applications and compatibility with both the supplied SocketScan applications and the user-generated application. Trigger Applications Assigned to Buttons SocketScan.exe RFIDDemo.exe ScanDemo.exe User application (using SDK)
SocketScan Yes Yes* Yes No
Trigger Select Yes No No No
Trigger Scan Yes No Yes Yes
Trigger RFID Yes Yes* Yes Yes
January 27, 2006
* Note: Socket does not recommend using SocketScan or Trigger RFID to do a tag read while using RFID Demo. The data may not appear as expected due to the different options that can be enabled in RFID Setup. RFID Demo only works with the RFID portion of the CF RFID Reader-Scan Card. Whenever these programs are assigned to buttons to trigger a RFID scan, they call ScanTrigger API routine which generates a Select Tag and/or Tag Read Data command. The parameters for this command are set by the registry entries and controlled by RFID Setup.
13.1 TRIGGERING DETAILS

If you are using SocketScan with the CF Scan Card, SD Scan Card or 2D Scan Card for your application, there are two ways to start a scan: 1. Assign a hardware button to execute the Socket Trigger Scan.exe, Socket Trigger RFID.exe or ScktScan.exe program. If ScktScan.exe is already loaded, executing it again will call ScanTrigger() to start a scan. 2. Your application program can execute ScktScan.exe to start a scan. For the RFID Reader, assigning a trigger button or executing ScktScan.exe to start a trigger sends a Select Tag command to the RFID reader. If a valid tag is within the readers field, SocketScan returns the Tag Type and Tag ID (with a : in-between) to the current application that has keyboard focus. Use the SocketScan RFID control panel applet to configure SocketScan to read or write the tag data or for better control over the RFID Reader functions. SocketScan (keyboard wedge) now has the addition of the "selected" scanner. This is the scanner who's ICON shows up in the task tray and has a checkbox (selected) when the SocketScan menu is displayed. The selected scanner is the one that receives the ScanTrigger command when SocketScan is assigned to a PDA button and executed. A number of changes were made to the SocketScan wedge program to support the RFID-Scan card and multiple scanners in general. 1. The program is now multi-scanner aware by calling ScanEnableMultiScanner() before calling ScanInit(). It does not support multiple CHS devices (at this time). 2. The CF RFID Reader-Scan Card is treated as two scanning devices: RFID and CFSC. The program also supports other scanner combinations (i.e. CHS and CFSC, CHS and RFID, etc.) 3. Symbology Selector: When multiple bar code scanners are present (i.e. CFSC and CHS) the symbology selector will show a sub-menu for all scanners that support displaying/changing the symbologies. There is no sub-menu if there is only one supported scanner present
13.2 CHANGING THE ACTIVE SCANNER

Additionally, the support for a windows message to change the active scanner (WM_SELECT_SCANNER) has been implemented. This message allows the caller to set the active Socketscan scanner in one of three ways. The format is:
January 27, 2006
Select the next scanner (wraps around after the last scanner). This only selects scanners with software-only triggers: SendMessage(socketScanWnd, WM_SELECT_SCANNER, 0, 0); Select the specified scanner handle: SendMessage(socketScanWnd, WM_SELECT_SCANNER, 2, 0); Select the first scanner of the specified scanner type: SendMessage(socketScanWnd, WM_SELECT_SCANNER, 0, SCANNER_CHS); 1) If scanner and scannerType are both zero, select the next scanner 2) If scanner is non-zero, select the scanner with that handle 3) If scannerType is not SCANNER_NONE (0), select the first scanner of that type
SelectNext.exe has been precompiled and included in the SocketScan build. You can assign SocketScan.exe to one PDA button and SelectNext.exe to a second PDA button. This allows you to trigger the "selected" scanner and advance to the next scanner. In case of the RFID-Scan card the SelectNext button will toggle between RFID and CFSC scanners. If the CHS is also enabled it will not be included in the toggle since it has a hardware trigger. (The CHS can be made the "selected" device using the SocketScan menu and then the PDA button would remotely trigger the CHS.)
January 27, 2006
14.0
THE DRIVERMAN DLL
DriverMan is a Windows CE device driver created by Socket to provide services and functionality for managing one or more drivers associated with an expansion card. DriverMan exists as a dynamically loaded library (DLL) named DriverMan.dll. DriverMan expands upon and improves the device driver model provided by the Windows CE OS. It supports more loading and unloading options as well as providing more debugging and error-handling capabilities than the built-in device.exe process. One of the key benefits of DriverMan is that it loads and unloads drivers in a specified, synchronous order, and it also enables confirmation of initialization for sequencing the loading of drivers that need additional time to initialize using multiple threads. Overall it allows the SocketScan initialization/de-initialization to be far more robust in providing controlled startup and shutdown
January 27, 2006
15.0
INSTALLATION
If you want to include SocketScan as part of your application setup, all of the files necessary are provided on the distribution CD. Simply select the appropriate binary files for the platform and/or CE OS revision you plan to support. Refer to Section 4 for more details.
15.1 INSTALLATION PROCEDURE

15.1.1 WinCE Sample: SocketScan for a Pocket PC with an ARM processor: Install ScktScan.exe (located in the \Driver+SDK Binaries\PocketPC\Arm\ directory of the distribution disk) to the application directory of your choice on the CE device. Install the drivers listed in Section 4.1 (located in the \Driver+SDK Binaries\PocketPC\Arm\ directory of the distribution disk) to the \Windows directory of the CE device. Create a shortcut that will launch ScktScan.exe in the \Windows\Start Menu directory of the CE device (this step is optional if, for example, you want to make your application start and terminate the program). Add the entries to the CE device registry that are documented as REQUIRED in the following section. Add one or more OPTIONAL registry entries if desired. Assign a trigger button for SocketScan. Unfortunately, we know of no automated way to accomplish this given the variety of different platforms, configuration utilities, etc. present in the CE arena. For an HP Jornada 548 (which would fit the description used in this example), you would use the Start->Settings->Button control panel applet and assign SocketScan to Record, which is the red voice recorder button.
15.1.2 WinCE Sample: ScanAPI only for a Pocket PC with an ARM processor: Install the drivers listed in Section 4.1 (located in the \Driver+SDK Binaries\PocketPC\Arm\ directory of the distribution disk) to the \Windows directory of the CE device. Add the entries to the CE device registry that are documented as REQUIRED in the following section. Add one or more OPTIONAL registry entries if desired.
15.1.3 Windows Desktop/Notebook Installation: With the SDK release there are two installation options possible The first option is to install only the SDK and the second option is to install the ScktScan.exe application along with the SDK. SDK Installation: There is no setup.exe file to install the SDK. The SDK directory structure from the distribution disk has to be copied into the users development environment maintaining the same structure. To compile and try the sample demo applications provided with the SDK, change directory to the \Source\PreviewDLL or the \Source\ScanApiTester to build executables using their respective project files. Install the drivers listed in Section 4.2 (located in the \Driver+SDK Binaries\ directory of the distribution disk) to the System directory of the target Win32 device (typically c:\Windows\System or c:\WinNT\System32).
January 27, 2006
Install the ScktScan.cpl control panel applet file (located in the \Driver+SDK Binaries\ directory of the distribution disk) to the system directory. Add the entries to the target devices registry that are documented as REQUIRED in the section 11.3.2. Add one or more OPTIONAL registry entries if desired.
SocketScan Installation with SDK: There is no setup.exe file to install the SDK. The SDK directory structure from the distribution disk has to be copied into the users development environment maintaining the same structure. To compile and try the sample demo applications provided with the SDK, change directory to the \Source\PreviewDLL or the \Source\ScanApiTester to build executables using their respective project files. To install ScktScan.exe to the application directory of your choice on the target Win32 device, select setup.exe file in the root directory. Follow the Installation instructions in the web page. Installation of ScktScan.exe application will automatically copy the DLL files in \Driver+SDK Binaries\ directory to the System directory of the target Win32 device. For registry update information please see section 12.3.2. Shortcut to launch SocketScan.exe will be created automatically in the Desktop after installation.
January 27, 2006
15.2 REGISTRY ENTRIES

SocketScan and the ScanAPI require several sets of registry entries that ensure the correct drivers load when a scanning device is inserted. 15.2.1 Windows CE Registry Entries CeReg.txt (in the Driver+SDK Binaries subdirectory of the distribution CD) contains all of the latest registry entries. These registry entries are REQUIRED or SocketScan and the ScanAPI will not function as expected. If you elect not to support every Socket scanning product, you may omit the registry entries in the corresponding sections shown below. For your convenience, portions of this text (taken from the file) can be cut and pasted into your installer script.
15.2.2 Win32 Desktop/Notebook Registry Entries Unlike the Windows CE OS, most registry entries required by scanning devices are created automatically in the Win32 Desktop systems. This happens the first time that the user plugs the device into the PC Card slot. The New Hardware Found dialog (or New Hardware Wizard) asks the user to insert a disk containing the required drivers. This disk includes a .INF file that is used by the OS, and it instructs the OS to create the necessary registry entries needed for the device. The file ScktScan.INF, supplied in the root directory of the distribution CD, is the file required by the Win32 Desktop operating systems when one of these New Hardware dialogs becomes activated. If you are distributing SocketScan as part of your custom application, you should include this file in the root directory of your programs distribution disk. As with Windows CE, though, there are several registry entries that are required for the proper operation of SocketScan and the ScanAPI. Due to the small number of required registry entries, no text or .REG file is supplied. NOTE: There are no required registry entries for Windows 2000/XP. The following list applies to Windows NT only. The REQUIRED registry entries are: [HKEY_LOCAL_MACHINE\Software\Socket Communications\ScanAPI\1.0] COM Port: REG_SZ: "COM3:" ; The COM port assigned to the scanner by the OS Scanner Type: REG_DWORD: 0x1 ; The type of scanner: 1=CFSC, 2=Wand, 3=Gun, 5=CHS The above registry entries can be created by your custom installer, or will be created automatically when the Scanner API control panel applet is run. The following registry entries are OPTIONAL. Each controls a configurable behavior of the SocketScan program. You may use any or all of these registry entries as desired. ; Optional entries for SocketScan. Default values are shown, meaning if the ; registry entry is missing, you will get what is shown below. [HKEY_LOCAL_MACHINE\Software\Socket Communications\ScktScan\1.0] Prefix: REG_SZ: ""
January 27, 2006
Suffix: REG_SZ: "" Wave File: REG_SZ: "" Good Read Sound: REG_DWORD:, 0x1 ;0=GRS_NONE, 1=GRS_MESSAGEBEEP, 2=GRS_WAVFILE PreviewDll: REG_SZ: ""
15.2.3 Other Registry-Related Considerations Please see the Flexible addition of prefix and/or suffix to the scanned data discussion in the Features section to see how to create a valid prefix or suffix string. If you use an invalid string, SocketScan will ignore it or generate a runtime error, so please test before shipping. For the Good Read Sound entry, you must use 0, 1, or 2. Any other value will give undefined results, or may generate a runtime error in the SocketScan program. See the function reference for ScanSetGoodReadSound() for more details.
January 27, 2006
15.3 IMPLEMENTING A SOCKETSCAN PREVIEW DLL

A SocketScan Preview DLL can be as simple or as complex as you want to make it. There are very few requirements to follow: The DLL must export a function called DataPreview. The basic prototype for the function is: int DataPreview(TCHAR * lpData, int nSize). See the sample DLL files on the CD for the exact declarations for Win CE and Win XP, located in the \Source\Preview DLL directory. You may modify the characters in lpData and change the number of characters, but the maximum buffer size is 1500 characters (plus room for a NULL). The DataPreview function must return the number of valid characters in the buffer. You must add a registry entry to tell SocketScan that this DLL exists. Under the registry key HKEY_LOCAL_MACHINE\Software\Socket Communications\ScktScan\1.0, create a string value called PreviewDll, and set its value to the path and filename of the DLL youve created.
Very simple examples of a Preview DLL are on the distribution CD in the \Source\Preview Dll directory, one for Windows CE, one for Windows XP. These examples simply delete the first character from the scanned data. Here are a few things to keep in mind when designing your Preview DLL: When creating the Preview DLL with C++, dont let the exported DataPreview() function name get mangled. When expanding the size of the scanned data, be careful not to exceed the 1500 character limit. Doing so will most likely cause Access Violation errors in the SocketScan program. Likewise, do not attempt to free the memory pointer given in the lpData argument. To throw out the scanned data, there is no need to zero out the data buffer instead simply use zero as your function return value. SocketScan will not add a prefix or suffix to the data when a Preview DLL is being used, even if prefix and suffix strings have been configured in the program. Add your own prefix or suffix in the DataPreview() function if desired. Your DataPreview() function should simply do its operation on the data, then move on as quickly as possible. Do not pop up message boxes or other UI elements in this function, since the user may continue to scan data instead of respond to your UI this could lead to re-entrancy or other unexpected problems in your DLL. SocketScan does not null-terminate data and typically your DataPreview() function will not need to do so either. You probably dont want a NULL keystroke to occur in your data entry fields. Remember you are dealing with UNICODE on CE devices, and probably are not on Win32 Desktop OS. Keep in mind that the nSize argument is always the character count regardless of the OS.
Here are a few ideas and reasons for using a Preview DLL: Some barcodes (such as Vehicle Identification Numbers) begin with a character that may not be wanted in the custom application. A Preview DLL can easily knock this character off the data stream. You may want to translate characters that the user has scanned to other characters for example change dollar signs to British pound signs, etc. Route a copy of the scanned data to the serial port of the host device or to some other auxiliary data collection receiver, if desired.
January 27, 2006
You may want certain barcodes to spawn some other process on the host computer, or play a .WAV file, .AVI or .MPG file, etc. If you are printing your own barcode labels, you can include characters that have special meaning to your application trigger special processing based on their presence, and filter them out of the final data stream. By adding your own private functions into the Preview DLL, your custom application can tell the DLL which input field has the focus at any given time. With this information you can validate the scanned data, or even change the suffix from a TAB to a CARRIAGE RETURN when it is appropriate to do so in your application.
We believe the addition of the Preview DLL has made SocketScan a much more powerful tool. We hope that developers will find that SocketScan with this extension can be used as the scanning solution for their application, and reduce the chances that you will need to write code all the way down at the ScanAPI level.
January 27, 2006
16.0
IMPLEMENTING A SOCKETSCAN APPLICATION IN .NET
The ScanAPI .Net Compact Framework and .Net Framework Class libraries provides a simple to use interface to Socket Communications scanning products for applications written in .Net compliant languages such as Visual Basic.Net or C#.Net. Refer to the ScanAPI .Net User Guide in the documents section of this CD for further detail
January 27, 2006

Socket Scanners DK

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Socket Scanners DK

Uploaded by

Copyright:

Available Formats

SocketScan SDK Users Guide & ScanAPI: Scanning Application Program Interface

Document # 6410-00147 G January 10, 2006

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 2 Revision 2.24

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 3 Revision 2.24

Using ScanAPI ................................................................................................................... 10

Setting Up The Target Device............................................................................................ 12

Writing Your Application..................................................................................................... 14

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 4 Revision 2.24

CHS Control commands............................................................................................ 58

Registry Settings for the Cordless Hand Scanner ..................................................... 60

Socket Communications, Inc. Document#: 6410-00147 G

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 6 Revision 2.24

SDK QUICKSTART GUIDE

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 7 Revision 2.24

2.0 REVISION NOTES

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 8 Revision 2.24

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 9 Revision 2.24

3.0 USING SCANAPI

SCANNER DATA ACCESS

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 10 Revision 2.24

CORDLESS SCANNER SPECIFIC FUNCTIONS

RFID SPECIFIC FUNTIONS

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 11 Revision 2.24

4.0 SETTING UP THE TARGET DEVICE

SETTING UP WINDOWS CE DEVICES

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 12 Revision 2.24

SETTING UP WIN32 DESKTOP SYSTEMS

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 13 Revision 2.24

5.0 WRITING YOUR APPLICATION

5.2 5.3 5.4

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 15 Revision 2.24

6.0 SOFT TRIGGERING

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006

Page 16 Revision 2.24

7.0 SCANAPI TYPE REFERENCE

Socket Communications, Inc. Document#: 6410-00147 G

January 27, 2006