Socket SocketScan SDK, User Manual

Page 1: ...SocketScan SDK User s Guide ScanAPI Scanning Application Program Interface Document 6410 00147 K April 8 2010...

Page 2: ...product names are trademarks of their respective holders Reproduction of the contents of this manual without the permission of Socket Mobile is expressly prohibited Please be aware that the products...

Page 3: ...SocketScan 4 0 to support the 2DSC for bar code Minor edits 2 13 07 11 2003 P Subbaraya Changes for SocketScan 4 0 to support the 2DSC ScanSendCommand API call WinCE 2 14 01 22 2004 P Subbaraya Chang...

Page 4: ...ns 12 4 0 Setting Up The Target Device 13 4 1 Setting up Windows CE Devices 13 5 0 Writing Your Application 14 5 1 Preview DLL 15 5 2 RFID Demo 15 5 3 ScanApiTester 15 5 4 TriggerSample 15 5 5 CSharp...

Page 5: ...WriteSymbologyConfig 51 8 25 ScanEnableMultiScanner 51 8 26 ScanGetScannerRegKey 52 8 27 ScanOpenScannerProperty 53 8 28 ScanCloseScannerProperty 53 8 29 ScanGetScannerProperty 53 8 30 ScanSetScannerP...

Page 6: ...iendly Name Response 68 9 7 Registry Settings for the Cordless Hand Scanner 69 10 0 RFID Reader 71 11 0 MultiScanner Support WIN CE ONLY 72 11 1 Registry Settings for the CF RFID Reader Scan Card 72 1...

Page 7: ...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 tran...

Page 8: ...essages for the API 3 Based on your requirements examine the Sample code provided 4 Read Chapter 6 to learn how to trigger your scanner 5 Read Chapter 4 and the Targeted Scanner Deployment document to...

Page 9: ...ix 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...

Page 10: ...F to PC Card adapter available separately at http ww1 socketmobile com products handheld computers accessories hc aspx cat Plug Ins Starting from Desktop Release v3 7 SocketScan application support fo...

Page 11: ...mSend 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 SD...

Page 12: ...CmdtoCHS sends the Cordless Scanner configuration commands 3 6 RFID SPECIFIC FUNCTIONS ScanRFIDSelectTag selects one or more tags ScanRFIDReadTag reads one or more data blocks from a tag ScanRFIDGetDa...

Page 13: ...atforms version 4 2 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...

Page 14: ...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...

Page 15: ...slate the messages to different languages if desired using a resource editing tool The Samples directory of the SDK contains several sample programs that can be found in the following subdirectories 5...

Page 16: ...vice is powered on The Permanent Pair feature can be turned on by using the new Scanner property APIs ScanOpenScannerProperty ScanCloseScannerProperty ScanGetScannerProperty and ScanSetScannerProperty...

Page 17: ...t 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 hardwar...

Page 18: ...cannerType integrated card unsigned int fSoftwareTrigger 1 most likely an integrated card unsigned int fSoftwareAbortTrigger 1 most likely an integrated card THCAR SymbolType the symbol type UPC Code...

Page 19: ...USY SR_HOTSWAP_ERROR Windows XP ONLY SR_SCANNER_REMOVED SR_INVALID_WMCHSSTATUS SR_NOT_CHS_DEVICE SR_WAIT_TIMEOUT_ERROR SR_SYMBOLOGY_NOT_SUPPORTED SR_SCANNER_BUSY SR_INVALID_WMDIRECTSTATUS SR_INCOMPATI...

Page 20: ...tarts 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 on...

Page 21: ...out pdwVersionAPI is the actual ScanAPI version installed on the host computer in lpszApplicationName is the name of the application using ScanAPI Notes If the dwVersionAPP is superior to the actual S...

Page 22: ...this function is called the application will receive the wmInsertion message later when the user inserts a data collection device When a client application receives WM_INSERTION or WM_REMOVAL messages...

Page 23: ...OTSWAP_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...

Page 24: ...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_TH...

Page 25: ...scanner disabled Notes A scanner must be closed if the user removes it during your program s execution Typically a client program will call ScanCloseDevice as part of the message handler of the WM_REM...

Page 26: ...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 retu...

Page 27: ...CE_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 poss...

Page 28: ...doesn t support callbacks hard coding 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...

Page 29: ...verted 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 syste...

Page 30: ...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 va...

Page 31: ...pires 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...

Page 32: ...he 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 removi...

Page 33: ...ted 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 c...

Page 34: ...re processing to the data stream you desire To discover the size of the data available without actually retrieving it from the scanner you may use NULL as the lpBuff argument in this case BufSize will...

Page 35: ...cessfully 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 t...

Page 36: ...ion 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_I...

Page 37: ...et 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 REM...

Page 38: ...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...

Page 39: ...rn 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...

Page 40: ...rt the ScanParamSend function 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 Apr...

Page 41: ...he 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 occ...

Page 42: ...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...

Page 43: ...member of the CommandFeature_t structure CMDID_WRITE_RFID_AFI Write RFID AFI into a RFID tag CMDID_LOCK_RFID_AFI Lock RFID AFI into a RFID tag in out CommandFeature_t pCommandFeature is a pointer to a...

Page 44: ...use does not support the ScanCommandFeature function SR_INTERNAL_FAILURE An internal error occurred requesting the parameter from the scanner SR_NOT_INITIALIZED The ScanAPI is not initialized correct...

Page 45: ...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...

Page 46: ...d 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 April 8 2010 Page 46 Do...

Page 47: ...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 w...

Page 48: ...CONNECTEDEX Prototype SCANAPI_API BOOL IsScannerConnectedEx SCANNER_TYPE scannerType Purpose To determine if either a scanner is connected or a particular type of scanner is connected in a multi scann...

Page 49: ...aram 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 SCA...

Page 50: ...ead 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 w...

Page 51: ...at 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...

Page 52: ...he 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 regis...

Page 53: ...contains the handle to the properties Notes This API accepts only SCANNER_CHS or SCANNER_CRS as ScannerType Returns SR_SUCCESS in case of success SR_INVALID_PARAMETERS if phProperty is NULL SR_MEMORY...

Page 54: ...ty HANDLE hProperty DWORD dwPropertyID LPVOID lpValue DWORD dwValueSize BOOL bUpdateScannerIfPresent Purpose This API can be used to modified a value of a property identified by its identifier Not all...

Page 55: ..._TIMER Purpose Trigger lockout timer Value type DWORD Operation available Read Write and updateable SCAN_PROP_ID_ADVANCED_BEEP_FREQ Purpose defines the advanced beep frequency Value type DWORD Operati...

Page 56: ...DATE Purpose contains the module version date month and day Value type DWORD Operation available Read Only SCAN_PROP_ID_MODULE_VERSION_YEAR Purpose contains the module version year Value type DWORD Op...

Page 57: ...d beep Value type DWORD Operation available Read Write and Updateable SCAN_PROP_ID_SUPPORTED_CONFIG Purpose Bits field indicating what advanced features the scanner supports Value type DWORD Operation...

Page 58: ...K_ALL pvSymVoid PVOID flagsRange else flagsOnly dwStructSize sizeof ScannerSymFlagsOnly_t flagsOnly dwMask SYM_MASK_ALL pvSymVoid PVOID flagsOnly result ScanReadSymbologyConfig hScanner SETUP_TYPE_CUR...

Page 59: ...TLCODE 39 FALSE Australian Postal TRUE AZTEC FALSE AZTEC MESA FALSE British Postal FALSE Canadian Postal TRUE Data Matrix Code FALSE Dutch Postal FALSE Japanese Postal TRUE MaxiCode TRUE Micro PDF TR...

Page 60: ...ordless 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 re...

Page 61: ...ynamic 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...

Page 62: ...nload 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 Retu...

Page 63: ...uration command opcode The following byte s contain the parameter value The SCANAPI opcodes for CHS commands are define SET_SECURITY_MODE_CMD 0 define SET_FRIENDLY_NAME_CMD 1 define SET_PIN_CODE_CMD 4...

Page 64: ...ot 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 April 8 2010 Page 64 Docum...

Page 65: ...ND 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 m...

Page 66: ...thentication Encryption 9 5 2 Set Friendly Name Set Friendly Name Field Name Format Size Description Opcode 0x01 1 Byte Opcode for setting friendly name Payload None Update registry entry Friendly Nam...

Page 67: ...ge State Inquiry Field Name Format Size Description Opcode 0x08 1 Byte Request battery status Payload None 9 6 3 Battery Charge State Response Battery Charge State Response Field Name Format Size Desc...

Page 68: ...Name Response Friendly Name Response Field Name Format Size Description Response Variable 1 to 248 character string is updated in registry entry FriendlyName April 8 2010 Page 68 Document 6410 00147 K...

Page 69: ...x00010001 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 Sof...

Page 70: ...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...

Page 71: ...spond to standard ScanAPI functions for triggering and retrieving scanned data The data that is returned can be a combination of the tag ID and data stored on the card and is configurable through regi...

Page 72: ...m 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 a...

Page 73: ...CHINE Drivers PCMCIA YOUR PNP ID Scanner 2 DisablePlugSnd dword 00000001 DesiredHandle To implement the handle numbers just add the DesiredHandle DWORD value to the registry for each scanner for insta...

Page 74: ...trol to receive the scanned data Additional features of SocketScan can now be utilized by the creation of a special DLL By creating a SocketScan Preview DLL you can process the scanned data before the...

Page 75: ...nAPI will a Scanner Handle that s 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...

Page 76: ...rt a trigger sends a Select Tag command to the RFID reader If a valid tag is within the reader s field SocketScan returns the Tag Type and Tag ID with a in between to the current application that has...

Page 77: ...er 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 Selec...

Page 78: ...ng 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 c...

Page 79: ...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 b...

Page 80: ...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 e...

Page 81: ...es provides a simple to use interface to Socket data collection products for applications written in Net compliant languages such as Visual Basic Net or C Net Refer to the ScanAPI Net User s Guide in...

Page 82: ...ar codes 2D N A N A Aztec Codablock Data Matrix GS1 EAN UCC Matrix 2 of 5 Maxicode PDF 417 Macro PDF 417 Micro PDF 417 Plessey QR Code RM4SCC Standard 2 of 5 Postal Codes N A N A Australia Post BP0 4...