680
Page 1 of 680 Data Design Center Network & Enterprise Sector (NE) HC700 Family of Handheld Computers SOFTWARE DEVELOPMENT KIT SPECIFICATION VER 01.16

HC700 SDK Specification

Embed Size (px)

Citation preview

Page 1: HC700 SDK Specification

Page 1 of 680

Data Design Center Network & Enterprise Sector (NE)

HC700

Family of Handheld Computers

SOFTWARE DEVELOPMENT KIT SPECIFICATION

VER 01.16

Page 2: HC700 SDK Specification

Page 2 of 680

Page 3: HC700 SDK Specification

Page 3 of 680

Version History Version Date Owner Change History

00.10 04.05.05 Motorola Initial/Preliminary Draft 00.20 03.11.05 Motorola Add ImagerFunctionalityOption variable for imager info. 00.30 06.11.05 Motorola Update WLAN API, Application Loadr API and Usage Scenario 00.40 13.03.2006 Motorola Update WLAN API – New security APIs were added 00.41 22.03.2006 Motorola Fix Bluetooth pssskey functions description 01.00 29.03.2006 Motorola Update according to latest software version 01.01 5.04.2006 Motorola Update according hc700_sdk_spec_doc_enhancement.pdf 01.02 6.04.2006 Motorola Update OCR data types in Wireless Imager section 01.03 6.04.2006 Motorola Update according hc700_sdk_spec_doc_enhancement.pdf 01.04 9.04.2006 Motorola Update Format according to enhancement docuemnt 01.05 24.04.2006 Motorola Merge the power management and keyboard documents 01.06 17.05.2006 Motorola Fix default Wireless Imager suspend timeout value

01.07 23.05.2006 Motorola Wireless Imager section: add SCAN_AUTOEXPOSURE data type and provide more descriptions for SCAN_IMAGE_ACQUISITION data type.

01.08 06.07.2006 Motorola Wireless Imager section example: fix SCAN_SYM_MASC_FLAGS with SCAN_SYM_MASK_FLAGS.

01.09 11.07.2006 Motorola Add Registry API – for persistent registry 01.10 17.7.2006 Motorola Remove KBD_GetTriggerStatus API from document. 01.11 17.7.2006 Motorola BCR API section: add comments for SCAN_Open function. 01.12 24.7.2006 Motorola Registry API: Add Usage Scenario 01.13 25.7.2006 Motorola Remove Diagnostic set/get screen contrast API

01.14 03.8.2006 Motorola Specify ocr direction as unsupported parameter in Wireless Imager Scanning API

01.15 07.8.2006 Motorola According to HC700 FCC grant WLAN & GPRS are not allowed to operate simultaneously.

01.16 13.8.2006 Motorola Add description that this document is general for all HC700 family. COMPUTER SOFTWARE COPYRIGHTS The Motorola products described in this instruction manual may include copyrighted Motorola computer programs stored in semiconductor memories or other media. Laws in the United States and other countries preserve for Motorola certain exclusive rights for copyrighted computer programs, including the exclusive right to copy or reproduce in any form the copyrighted computer program. Accordingly, any copyrighted Motorola computer programs contained In the Motorola products described in this instruction manual may not be copied or reproduced in any manner without the express written permission of Motorola. Furthermore, the purchase of Motorola products shall not be deemed to grant either directly or by implication, estoppel. or otherwise. any license under the copyrights, patents or patent applications of Motorola, except for the normal non-exclusive, royalty free license to use that arises by operation of law in the sale of a product. EPS – 34440- B This warranty applies within the fifty (50) United States, the District of Columbia and Canada. Document Copyrights No duplication or distribution of this document or any portion thereof shall take place without the express written permission of Motorola. No part of this manual may be reproduced, distributed, or transmitted in any form or by any means, electronic or mechanical, for any purpose without the express written permission of Motorola. Disclaimer The information in this document is carefully examined, and is believed to be entirely reliable. However, no responsibility is assumed for inaccuracies. Furthermore, Motorola reserves the right to make changes to any products herein to improve readability, function, or design. Motorola does not assume any liability arising out of the applications or use of any product or circuit described herein; nor does it cover any license under its patent rights nor the rights of others.

Page 4: HC700 SDK Specification

Page 4 of 680

1. Overview

This document provides the HC700 software application Interface (API) specification as developed in MCIL for the purpose of application development for all HC700 family of Handheld Computers.

This document also includes a general description on power management mechanism and resuming from critical off.

The HC700 API provides to the application a C language interface and therefore is defined as a C API interface. The C API provides an interface to the Microsoft embedded Visual Tools 4.0 (or greater) development environment. The developer uses the API to call any of the exported functions of HC700 platform. The developer uses the API by calls to HC700 SDK functions.

This specification will describe the Motorola Value Added APIs available to provide functionality and control of the following hardware components making up the HC700 family Mobile Device.

The HC700 SDK provides API services for the following software/drivers entities:

• Barcode Reader API

• Wireless Imager Scanning API

• Wireless Imager Usage Scenario

• Wireless imager specifications

• RCM API - Scan Trigger Key Notification

• Display API

• KeyBoard_API

• Notification

• Product Parameters Service API

• Docking API

• BlueTooth API

• GPRS/GSM Radio

• WLAN_API

• Diagnostic API Library

• OEM PM API

Page 5: HC700 SDK Specification

Page 5 of 680

• System-Update Service API

• System-Update Service Usage Scenario

• Application_Loader API

• Application Loader Usage Scenario

• Cradle Interface

• Cradle interface usage scenario

• Registry API for HC700G-EPP

• Registry API Usage Scenario

• NTP Service

• System_Events

• Appendix

Page 6: HC700 SDK Specification

Page 6 of 680

2. Barcode Reader API Overview The BCR Driver is a built-in device driver that provides applications with the ability to read bar code labels. The BCR Driver C API provides applications with a Win32 "C" callable interface. This API fully supports 1D and 2D bar code scanning,

The BCR Driver supports only one appliaction to work with the scanner at same time , The driver provides abilty to set up the scanner in different modes for different windows on the same application .

In the example part there is application that demonstrates how get notification massage to winproc from SCAN key (Up /Down) events.

Functions List

Function Description SCAN_AllocateBuffer Allocates a new SCAN_BUFFER structure for use in the

application.

SCAN_CancelRead Cancels a previously submitted, but not completed, read on an open scanner handle.

SCAN_Close Closes an open scanner. SCAN_DeallocateBuffer Deallocates a scan buffer. SCAN_DeregisterScanMessage Removes non-decode message notification from an open

scanner. SCAN_Disable Disables scanning operations on an open scanner. SCAN_Enable Enables scanning operations on an open scanner. SCAN_FindClose Closes the find handle used by SCAN_FindFirst and

SCAN_FindNext. SCAN_FindFirst Finds the first available scanner and creates a find handle for

use by SCAN_FindNext. SCAN_FindNext Finds the next available scanner in the search specified by

FindHandle. SCAN_Flush Cancels all of the reads submitted on an open scanner handle. SCAN_GetDecoderParams Gets decoder parameters for a specific decoder for an open

scanner handle. SCAN_GetDeviceInfo The SCAN_GetDeviceInfo function gets the device capabilities

information for an open scanner handle. SCAN_GetEnabledDecoders Gets the enabled decoders for an open scanner handle. SCAN_GetScanParameters Gets the enabled decoders for an open scanner handle. SCAN_GetReaderParams Gets the reader parameters for an open handle. SCAN_SetReaderParams Sets the reader parameters for an open handle. SCAN_GetScanStatus Gets the scan status for an open scanner handle. SCAN_GetSupportedDecoders Gets the supported decoders list by an open scanner handle. SCAN_GetVersionInfo Gets the version information for the scanner driver. SCAN_Open Opens the specified scanner device and creates a handle to be

used for all subsequent accesses to this scanner. SCAN_ReadLabelEvent Submits a read request on an open scanner handle. When the

read request is complete, the application will be notified via event notification.

SCAN_ReadLabelMsg Submits a read request on an open scanner handle. When the reads request is complete, the application will be notified via a message.

SCAN_ReadLabelWait Submits a read request on an open scanner handle. The function does not return until the read completes.

SCAN_RegisterScanMessage Registers for scanner, non-decode message notifications.

Page 7: HC700 SDK Specification

Page 7 of 680

SCAN_SetDecoderParams Sets the decoder parameters for a specific decoder for an open scanner handle.

SCAN_SetEnabledDecoders Sets the enabled decoders for an open scanner handle. SCAN_SetScanParameters Sets the scan parameters for an open scanner handle. SCAN_GetImage Gets an image from imager device. SCAN_GetLastImage Gets a last image keeped by imager device after barcode scan

and signature picture operations only. SCAN_GetIntelligentImage Gets signature capture image from the imager. SCAN_CaptureRegionOfInterest Gets signature capture image or another region of interest (ROI)

related to barcode from the imager. SCAN_FormatImageData Gets signature capture image or another region of interest (ROI)

related to barcode from the imager. SCAN_SetDefaultParams Applies the default parameters on the imager. SCAN_GetInternalImagerParams Gets current parameters set of specified configuration item for

internal imager. SCAN_SetInternalImagerParams Sets parameters set of specified configuration item to internal

imager. SCAN_SetImageStream Reads streaming image data (movie mode).

During imager operation in stream mode no barcode and signature reads allowed.

SCAN_IsImagePresent Defines if any image is presented within provided picture data (if it is not empty image).

• Example • Data Types • Return Values

Page 8: HC700 SDK Specification

Page 8 of 680

SCAN_Open

Description The SCAN_Open function opens the specified scanner device and creates a handle to be used for all subsequent accesses to this scanner. After this function is called all scanner parameters are set automatically to their default values.

Function Prototype

DWORD SCAN_Open(LPCTSTR lpszDeviceName,

LPHANDLE lphScanner

);

Parameters lpszDeviceName

[in] Pointer to a string containing the name of the scanner to open. The name can be obtained via a call to SCAN_FindFirst or SCAN_FindNext.

lphScanner [out] Pointer to a handle created for all subsequent accesses to this scanner.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is E_SCN_NULLPTR or E_SCN_INVALIDDEVICE. If Scanner driver is already opened, the E_SCN_INVALIDDEVICE error is returned. If E_SCN_INVALIDDEVICE is returned, the caller can get a more specific error code by calling GetLastError. GetLastError could return a Win32 error code or any one of the following error codes: E_SCN_INVALIDARG, E_SCN_NOTINITIALIZED, E_SCN_NOTENOUGHMEMORY, E_SCN_CANTGETDEFAULTS, E_SCN_CANTSTARTDEVICE.

Comments When calling this function in multi application manner each call will cause scanner parameters to be set automatically to their default values. So one application will imapact the parameters of any other scanner application by calling this function.

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

// If a scanner has not been opened

if ( hScanner == NULL )

{

// Open scanner

dwResult = SCAN_Open(TEXT("SCN1:"),&hScanner);

// If open failed

if ( dwResult != E_SCN_SUCCESS )

Page 9: HC700 SDK Specification

Page 9 of 680

{

// Indicate scanner not open

hScanner = NULL;

// Report an error

ReportError(TEXT("ScanInit Open"),dwResult);

// Return the error

return(dwResult);

}

}

Click here for complete example

Page 10: HC700 SDK Specification

Page 10 of 680

SCAN_Close

Description The SCAN_Close function closes an open scanner.

Function Prototype

DWORD SCAN_Close(HANDLE hScanner);

Parameters hScanner

Handle of an open scanner to close.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is E_SCN_INVALIDHANDLE

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example Click here for complete example

Page 11: HC700 SDK Specification

Page 11 of 680

SCAN_FindFirst

Description The SCAN_FindFirst function finds the first available scanner and creates a find handle for use by SCAN_FindNext.

Function Prototype

DWORD SCAN_FindFirst(LPSCAN_FINDINFO lpScanFindInfo,

LPHANDLE lphFindHandle

);

Parameters lpScanFindInfo Pointer to SCAN_FINDINFO structure to be filled in with information about the first available scanner. Used to open a scanner with SCAN_Open. lphFindHandle Pointer to a new find handle to be used by SCAN_FindNext to continue the search. The handle must be closed by SCAN_FindClose when done.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS. If the function fails, the return value is one of the following error codes: E_SCN_NULLPTR, E_SCN_CANTOPENREGKEY, E_SCN_NOTENOUGHMEMORY, E_SCN_CANTREADREGVAL, E_SCN_NOMOREITEMS

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example Click here for complete example

Page 12: HC700 SDK Specification

Page 12 of 680

SCAN_FindNext

Description The SCAN_FindNext function finds the next available scanner in the search specified by hFindHandle.

Function Prototype

DWORD SCAN_FindNext(LPSCAN_FINDINFO lpScanFindInfo,

HANDLE hFindHandle

);

Parameters lpScanFindInfo Pointer to SCAN_FINDINFO structure to be filled in with information about next available scanner. Used to open a scanner with SCAN_Open. hFindHandle Find handle created by SCAN_FindFirst.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS. If the function fails, the return value is one of the following error codes: E_SCN_NULLPTR, E_SCN_INVALIDHANDLE, E_SCN_NOMOREITEMS.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example Click here for complete example

Page 13: HC700 SDK Specification

Page 13 of 680

SCAN_FindClose

Description The SCAN_FindClose function closes the find handle used by SCAN_FindFirst and SCAN_FindNext.

Function Prototype DWORD SCAN_FindClose(HANDLE hFindHandle);

Parameters hFindHandle Find handle used by SCAN_FindFirst and SCAN_FindNext.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS. If the function fails, the return value is E_SCN_INVALIDHANDLE.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example Click here for complete example

Page 14: HC700 SDK Specification

Page 14 of 680

SCAN_RegisterScanMessage

Description The SCAN_RegisterScanMessage function registers for scanner, non-decode message notifications.

Function Prototype DWORD SCAN_RegisterScanMessage( HANDLE hScanner, HWND hWnd, UINT uiMessage);

Parameters hScanner Handle of an open scanner returned by SCAN_Open. hWnd

Handle to a window to recieve event notification. uiMessage

User Message code (WM_USER+n) to fire when event notification occurs.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is E_SCN_INVALIDHANDLE.

Comments When a scan event occurs in the driver, the Scanner Driver will send a Window message (uiMessage) to the application window (hWnd). The lParam parameter will hold an event specific value, and the wParam parameter will hold the SCAN_EVENT code. Scan events that are applicable to one specific read are only sent to the open scanner handle for which that read was submitted.

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

Click here for complete example

SCAN_DeregisterScanMessage

Description The SCAN_DeregisterScanMessage function removes non-decode message notification from an open scanner.

Function Prototype DWORD SCAN_DeregisterScanMessage(HANDLE hScanner);

Parameters hScanner Handle of an open scanner returned by SCAN_Open.

Page 15: HC700 SDK Specification

Page 15 of 680

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is E_SCN_INVALIDHANDLE.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

Click here for complete example

Page 16: HC700 SDK Specification

Page 16 of 680

SCAN_AllocateBuffer

Description

The SCAN_AllocateBuffer function allocates a new SCAN_BUFFER structure for use in the application.

Function Prototype

LPSCAN_BUFFER SCAN_AllocateBuffer( BOOL bText, DWORD dwSize );

Parameters bText Input flag telling whether the SCAN_BUFFER structure will hold UNICODE (bText=TRUE) or ASCII

(bText=FALSE) text. dwSize The size of the scan data buffer in bytes.

Return Values If the function succeeds, the return value is a pointer to a newly allocated SCAN_BUFFER structure. If the function fails, the return value is NULL and the last error is set to one of the following error codes: E_SCN_NOTENOUGHMEMORY. E_SCN_INVALIDARG, E_SCN_NOTSUPPORTED. Comments The maximum amount of memory that may be allocated by this function is 600 Kbytes.

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example // Allocate a new scan buffer

lpScanBuffer = SCAN_AllocateBuffer(TRUE,dwSize);

Click here for complete example

Page 17: HC700 SDK Specification

Page 17 of 680

SCAN_DeallocateBuffer

Description The SCAN_DeallocateBuffer function deallocates a scan buffer.

Function Prototype DWORD SCAN_DeallocateBuffer(LPSCAN_BUFFER lpScanBuffer);

Parameters lpScanBuffer Pointer to a SCAN_BUFFER created by SCAN_AllocateBuffer.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS. If the function fails, the return value is E_SCN_NULLPTR or E_SCN_INVALIDARG. If E_SCN_INVALIDARG is returned, the caller can get the specific Win32 error code by calling GetLastError.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

// Deallocate the scan buffer

SCAN_DeallocateBuffer(lpScanBuffer);

Click here for complete example

Page 18: HC700 SDK Specification

Page 18 of 680

SCAN_Disable

Description The SCAN_Disable function disables scanning operations on an open scanner.

Function Prototype

DWORD SCAN_Disable(HANDLE hScanner);

Parameters hScanner Handle of an open scanner returned by SCAN_Open.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is E_SCN_INVALIDHANDLE or E_SCN_NOTENABLED.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example // Disable the scanner

dwResult = SCAN_Disable(hScanner);

Click here for complete example

Page 19: HC700 SDK Specification

Page 19 of 680

SCAN_Enable

Description The SCAN_Enable function enables scanning operations on an open scanner.

Function Prototype

DWORD SCAN_Enable(HANDLE hScanner);

Parameters hScanner Handle of an open scanner returned by SCAN_Open.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_ALREADYENABLED, E_SCN_CANTSTARTDEVICE, E_SCN_CANTGETDEFAULTS, E_SCN_CREATEEVENT, E_SCN_CREATETHREAD.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example // Enable the scanner

dwResult = SCAN_Enable(hScanner);

// If the enable failed

if ( dwResult != E_SCN_SUCCESS )

{

// Terminate scanning

ScanTerm();

// Report an error

ReportError(TEXT("ScanInit Enable"),dwResult);

}

Click here for complete example

Page 20: HC700 SDK Specification

Page 20 of 680

SCAN_CancelRead

Description

The SCAN_CancelRead function cancels a previously submitted, but not completed, read on an open scanner handle.

Function Prototype

DWORD SCAN_CancelRead(HANDLE hScanner,

DWORD dwRequestID

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open dwRequestID The ID of the read scanner request to be cancel, Since the scanner driver support only one read barcode operation, this parameter has no meaning. This

function doesn’t check this parameter. Default value is 0.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEIN, E_SCN_INVALIDPARAM, E_SCN_READNOTPENDING.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example // Cancel the read

SCAN_CancelRead(hScanner,1));

Click here for complete example

Page 21: HC700 SDK Specification

Page 21 of 680

SCAN_GetDecoderParams

Description The SCAN_GetDecoderParams function gets decoder parameters for a specific decoder for an open scanner handle.

Function Prototype

DWORD SCAN_GetDecoderParams(HANDLE hScanner,

LPDECODER lpDecoder, LPDECODER_PARAMS lpDecoderParams

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open lpDecoder Pointer to a DECODER specifying which decoder’s parameters to get. lpDecoderParams Pointer to a DECODER_PARAMS structure to be filled in with the decoder parameters.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE, E_SCN_INVALIDPARAM.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

// Get current decoder parameters

dwResult = SCAN_GetDecoderParams(hScanner,lpDecoder,&decoder_params);

Click here for complete example

Page 22: HC700 SDK Specification

Page 22 of 680

SCAN_SetDecoderParams

Description The SCAN_SetDecoderParams function sets the decoder parameters for a specific decoder for an open scanner handle.

Function Prototype

DWORD SCAN_SetDecoderParams(HANDLE hScanner,

LPDECODER lpDecoder,

LPDECODER_PARAMS lpDecoderParams

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open. lpDecoder Pointer to a DECODER specifying which decoder’s parameters to set. lpDecoderParams Pointer to a DECODER_PARAMS structure holding the new decoder parameters.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEIN, E_SCN_STRUCTSIZE, E_SCN_INVALIDPARAM.

Comments This API is implemented for the restricted number of decoders (see Data Types section).

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also SCAN_Open, SCAN_GetDecoderParams, DECODER_PARAMS, DECODER

Example

Click here for complete example

Page 23: HC700 SDK Specification

Page 23 of 680

SCAN_GetDeviceInfo

Description The SCAN_GetDeviceInfo function gets the device capabilities information for an open scanner handle.

Function Prototype

DWORD SCAN_GetDeviceInfo(HANDLE hScanner,

LPDEVICE_INFO lpDeviceInfo

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open lpDeviceInfo Pointer to a DEVICE_INFO structure to be filled in with the device information.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also SCAN_Open, DEVICE_INFO

Example

Click here for complete example

Page 24: HC700 SDK Specification

Page 24 of 680

SCAN_GetEnabledDecoders

Description The SCAN_GetEnabledDecoders function gets the enabled decoders for an open scanner handle.

Function Prototype

DWORD SCAN_GetEnabledDecoders(HANDLE hScanner,

LPDECODER_LIST lpDecoderList

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open lpDecoderList Pointer to a DECODER_LIST structure to be filled in with the enabled decoders.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE, E_SCN_MISSINGFIELD

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also SCAN_Open, SCAN_SetEnabledDecoders, DECODER_LIST Example // Get enabled decoder list

dwResult = SCAN_GetEnabledDecoders(hScanner,&DecoderList);

Click here for complete example

Page 25: HC700 SDK Specification

Page 25 of 680

SCAN_SetEnabledDecoders

Description The SCAN_SetEnabledDecoders function sets the enabled decoders for an open scanner handle.

Function Prototype

DWORD SCAN_SetEnabledDecoders(HANDLE hScanner,

LPDECODER_LIST lpDecoderList

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open. lpDecoderList Pointer to a DECODER_LIST structure holding the new enabled decoders.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEIN, E_SCN_STRUCTSIZE, E_SCN_MISSINGFIELD, E_SCN_INVALIDPARAM.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also SCAN_Open, SCAN_GetEnabledDecoders, DECODER_LIST Example dwResult = SCAN_SetEnabledDecoders(hScanner,&DecoderList); Click here for complete example Click here for complete example

Page 26: HC700 SDK Specification

Page 26 of 680

SCAN_GetScanParameters

Description The SCAN_GetScanParameters function gets the scan parameters for an open handle. Function Prototype DWORD SCAN_GetScanParameters(HANDLE hScanner,

LPSCAN_PARAMS lpScanParams

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open. lpScanParams Pointer to a SCAN_PARAMS structure to be filled in with the scan parameters. Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also SCAN_Open, SCAN_SetScanParameters, SCAN_PARAMS Example // Get current scan parameters

dwResult = SCAN_GetScanParameters(hScanner,&scan_params);

Click here for complete example

Page 27: HC700 SDK Specification

Page 27 of 680

SCAN_SetScanParameters

Description The SCAN_SetScanParameters function sets the scan parameters for an open scanner handle.

Function Prototype

DWORD SCAN_SetScanParameters(HANDLE hScanner,

LPSCAN_PARAMS lpScanParams

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open. lpScanParams Pointer to a SCAN_PARAMS structure holding the new scan parameters.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEIN, E_SCN_STRUCTSIZE, E_SCN_INVALIDPARAM.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also SCAN_Open, SCAN_GetScanParameters, SCAN_PARAMS

Example SCAN_SetScanParameters(hScanner,&scan_params); Click here for complete example

Page 28: HC700 SDK Specification

Page 28 of 680

SCAN_GetReaderParams

Description The SCAN_GetReaderParams function gets the reader parameters for an open handle. Function Prototype DWORD SCAN_GetReaderParams(HANDLE hScanner,

LPREADER_PARAMS lpReaderParams

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open. lpReaderParams Pointer to a READER_PARAMS structure to be filled in with the reader parameters. Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also SCAN_Open, SCAN_SetReaderParameters, READER_PARAMS Example // Get current scan parameters

dwResult = SCAN_GetReaderParams(hScanner,&reader_params);

Click here for complete example

Page 29: HC700 SDK Specification

Page 29 of 680

SCAN_SetReaderParams

Description The SCAN_SetReaderParams function sets the reader parameters for an open handle. Function Prototype DWORD SCAN_GetReaderParams(HANDLE hScanner,

LPREADER_PARAMS lpReaderParams

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open. lpReaderParams Pointer to a READER_PARAMS structure to be set. Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also SCAN_Open, SCAN_GetReaderParameters, READER_PARAMS Example // Get current scan parameters

dwResult = SCAN_SetReaderParams(hScanner,&reader_params);

Click here for complete example

Page 30: HC700 SDK Specification

Page 30 of 680

SCAN_Flush

Description The SCAN_Flush function cancels all of the reads submitted on an open scanner handle. Since the scanner driver supports only the one read barcode operation at the same time, this function has the same functionality as the SCAN_CancelRead function.

Function Prototype DWORD SCAN_Flush(HANDLE hScanner );

Parameters hScanner Handle of an open scanner returned by SCAN_Open.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is E_SCN_INVALIDHANDLE or E_SCN_NOTENABLED

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

// Flush pending read

dwResult = SCAN_Flush(hScanner);

Click here for complete example

Page 31: HC700 SDK Specification

Page 31 of 680

SCAN_GetScanStatus

Description The SCAN_GetScanStatus function gets the scan status for an open scanner handle.

Function Prototype

DWORD SCAN_GetScanStatus(HANDLE hScanner,

LPSCAN_STATUS lpScanStatus

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open lpScanStatus Pointer to a SCAN_STATUS structure to be filled in with the scan status.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

Click here for complete example

Page 32: HC700 SDK Specification

Page 32 of 680

SCAN_GetSupportedDecoders

Description The SCAN_GetSupportedDecoders function gets the supported decoders list by an open scanner handle.

Function Prototype

DWORD SCAN_GetSupportedDecoders(HANDLE hScanner,

LPDECODER_LIST lpDecoderList

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open lpDecoderList Pointer to a DECODER_LIST structure to be filled in with the supported decoders.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE, E_SCN_MISSINGFIELD

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also SCAN_Open, DECODER_LIST Example // Get enabled decoder list

dwResult = SCAN_GetSupportedDecoders(hScanner,&DecoderList);

Click here for complete example

Page 33: HC700 SDK Specification

Page 33 of 680

SCAN_ReadLabelEvent

Description The SCAN_ReadLabelEvent function submits a read request on an open scanner handle. When the read request is complete, the application will be notified via event notification.

Function Prototype

DWORD SCAN_ReadLabelEvent(HANDLE hScanner,

LPSCAN_BUFFER lpScanBuffer,HANDLE hEvent,

DWORD dwTimeOut, LPDWORD lpdwRequestID

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open. lpScanBuffer Pointer to a SCAN_BUFFER structure to be filled in with the scan data and status. If the function succeeds, do not access the buffer until the event is set. hEvent Handle of the event to be set when the read is complete. dwTimeOut Read timeout in milliseconds. A value of 0 ( infinite) is not supported . lpdwRequestID Pointer to DWORD to be filled with request ID to be used in SCAN_CancelRead. Since the scanner driver supports only one opening , this parameter has no meaning. Default value is 0.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS. Further status information can be found in the status field of lpScanBuffer. If the function fails, the return value is one of the following error codes: E_SCN_NOTENOUGHMEMORY, E_SCN_NOTSUPPORTED, E_SCN_NULLPTR, E_SCN_INVALIDARG, E_SCN_CREATETHREAD

Comments Since the scanner driver supports only the one read barcode operation at the same time, the E_SCN_NOTSUPPORTED error code is returned if there is already read submitted on an open scanner handle.

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example Click here for complete example

Page 34: HC700 SDK Specification

Page 34 of 680

SCAN_ReadLabelMsg

Description The SCAN_ReadLabelMsg function submits a read request on an open scanner handle. When the read request is complete, the application will be notified via a message.

Function Prototype

DWORD SCAN_ReadLabelMsg(HANDLE hScanner,

LPSCAN_BUFFER lpScanBuffer,HWND hWnd,

UINT uiMsgNo, DWORD dwTimeOut,

LPDWORD lpdwRequestID

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open lpScanBuffer Pointer to a SCAN_BUFFER structure to be filled in with the scan data and status. If the function succeeds, do not access the buffer until the event is set. hWnd Handle of the window to receive a message when the read is complete. uiMsgNo The message number to send when the read is complete. dwTimeOut Read timeout in milliseconds. A value of 0 ( infinite) is not supported . lpdwRequestID Pointer to DWORD to be filled with request ID to be used in SCAN_CancelRead. Since the scanner driver supports only one opening ,this parameter has no meaning.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS. Further status information can be found in the status field of lpScanBuffer If the function fails, the return value is one of the following codes: E_SCN_NOTENOUGHMEMORY, E_SCN_NOTSUPPORTED, E_SCN_NULLPTR, E_SCN_INVALIDARG, E_SCN_CREATETHREAD.

Comments Since the scanner driver supports only the one read barcode operation at the same time, the E_SCN_NOTSUPPORTED error code is returned if there is already read submitted on an open scanner handle. When the read request is complete or cancelled, the Scanner Driver will send a Window message (uiMsgNo) to the application window (hWnd). The lParam parameter will hold a pointer to the SCAN_BUFFER (lpScanBuffer), and the wParam parameter will hold the read status.

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example

Page 35: HC700 SDK Specification

Page 35 of 680

// Submit the read

dwResult = SCAN_ReadLabelMsg(hScanner,lpScanBuffer,hwnd,uMsg,dwTimeout,NULL);

Click here for complete example

Page 36: HC700 SDK Specification

Page 36 of 680

SCAN_ReadLabelWait

Description The SCAN_ReadLabelWait function submits a read request on an open scanner handle. The function does not return until the read completes.

Function Prototype

DWORD SCAN_ReadLabelWait(HANDLE hScanner,

LPSCAN_BUFFER lpScanBuffer,

DWORD dwTimeOut

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open. lpScanBuffer Pointer to a SCAN_BUFFER structure to be filled in with the scan data and status. dwTimeOut Read time out in milliseconds. A value of 0 ( infinite) is not supported .

Return Values If the function succeeds, the return value is E_SCN_SUCCESS. Further status information can be found in the status field of lpScanBuffer. If the function fails, the return value is one of the following codes: E_SCN_NOTSUPPORTED, E_SCN_INVALIDHANDLE, E_SCN_NULLPTR, E_SCN_INVALIDARG, E_SCN_NOTENABLED, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE, E_SCN_MISSINGFIELD, E_SCN_INVALIDPARAM, E_SCN_NOTENOUGHMEMORY, E_SCN_CREATEEVENT, E_SCN_READINCOMPATIBLE, E_SCN_READCANCELLED, E_SCN_READTIMEOUT, E_SCN_BUFFERTOOSMALL.

Comments Since the scanner driver supports only the one read barcode operation at the same time, the E_SCN_NOTSUPPORTED error code is returned if there is already read submitted on an open scanner handle.

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example Click here for complete example

Page 37: HC700 SDK Specification

Page 37 of 680

SCAN_GetVersionInfo

Description The SCAN_GetVersionInfo function gets the version information for the scanner driver. If the handle is a valid open scanner handle, the function returns versions for the entire driver stack. If the handle is NULL, only the C API version is returned.

Function Prototype

DWORD SCAN_GetVersionInfo(HANDLE hScanner,

LPSCAN_VERSION_INFO lpScanVersionInfo

);

Parameters hScanner Handle of an open scanner returned by SCAN_Open or NULL. lpScanVersionInfo Pointer to a SCAN_VERSION_INFO structure to be filled in with the version info.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is one of the following error codes: E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT, E_SCN_STRUCTSIZE.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

Click here for complete example

Page 38: HC700 SDK Specification

Page 38 of 680

SCAN_GetImage

Description The SCAN_GetImage function is used to get an image from imager device.

Function Prototype

DWORD SCAN_GetImage(HANDLE hScanner,BOOL bWait, LPSCAN_IMAGE_DATA lpImgBuffer, LPDWORD lpdwBufferSize, LPSCAN_IMAGE_PARAMS lpImgParams, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. bWait [In] This value will define the notification mechanism for getting resulting image. When this value is equal to TRUE, this function is blocked and lpImgBuffer will be filled with image data upon return. When this value is equal to FALSE, this function is not-blocked. It will start image processing and will exit. The image itself will be received asynchronously (after SCAN_RegisterNotifications was called) by SCAN_GetNotificationResult with SCAN_NOTIFY_REMOTE_IMAGE notification type. In this case lpImgBuffer and lpdwBufferSize are ignored. lpImgBuffer [Out] In case that this function was called as blocked (bWait=TRUE) this parameter contains the pointer to the buffer that receives the image data. Maybe NULL if bWait is equal to FALSE. lpdwBufferSize [In/Out] This parameter contains the pointer to DWORD with the size in bytes of buffer specified by lpImgBuffer. Upon return with E_SCN_BUFFERTOOSMALL error code, this variable will contains the necessary size to be allocated for the buffer. lpImgParams [In] This parameter contains the pointer to the SCAN_IMAGE_PARAMS structure defines the properties for image to be taken. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example #define MAX_IMAGE_WIDTH 640 #define MAX_IMAGE_HEIGHT 480 #define MAX_IMAGE_BUFFER_SIZE (MAX_IMAGE_WIDTH * MAX_IMAGE_HEIGHT + sizeof(SCAN_IMAGE_DATA)) BYTE bImageBuffer[MAX_IMAGE_BUFFER_SIZE]; DWORD dwResult, dwBufferSize = MAX_IMAGE_BUFFER_SIZE; SCAN_IMAGE_PARAMS g_GetImageParams = {0,0,640,480,1,8,SCAN_FORMAT_RAW_GRAY,255,30,2,FALSE,0,0}; // Call as blocking function dwResult = SCAN_GetImage(hScanner, TRUE, (LPSCAN_IMAGE_DATA)bImageBuffer, &dwBufferSize, &g_GetImageParams, NULL);

Page 39: HC700 SDK Specification

Page 39 of 680

if( dwResult != E_SCN_SUCCESS ) { wsprintf(szString, TEXT("Unable to take the picture. Error 0x%x"), dwResult); MessageBox(hWnd, szString, TEXT("Programm Error"), MB_OK | MB_ICONERROR); return; } LPSCAN_IMAGE_DATA lpImageBuffer = (LPSCAN_IMAGE_DATA)bImageBuffer; LPBYTE lpImageData = (LPBYTE)lpImageBuffer + lpImageBuffer->dwImageDataOffset; DWORD dwImageDataSize = lpImageBuffer->dwImageDataSize;

Page 40: HC700 SDK Specification

Page 40 of 680

SCAN_GetLastImage

Description The SCAN_GetLastImage function is used to get a last image keeped by imager device after barcode scan and signature picture operations only.

Function Prototype

DWORD SCAN_GetLastImage(HANDLE hScanner,BOOL bWait, LPSCAN_IMAGE_DATA lpImgBuffer, LPDWORD lpdwBufferSize,LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. bWait [In] This value will define the notification mechanism for getting resulting image. When this value is equal to TRUE, this function is blocked and lpImgBuffer will be filled with image data upon return. When this value is equal to FALSE, this function is not-blocked. It will start image processing and will exit. The image itself will be received asynchronously (after SCAN_RegisterNotifications was called) by SCAN_GetNotificationResult with SCAN_NOTIFY_REMOTE_IMAGE notification type. In this case lpImgBuffer and lpdwBufferSize are ignored. lpImgBuffer [Out] In case that this function was called as blocked (bWait=TRUE) this parameter contains the pointer to the buffer that receives the image data. Maybe NULL if bWait is equal to FALSE. lpdwBufferSize [In/Out] This parameter contains the pointer to DWORD with the size in bytes of buffer specified by lpImgBuffer. Upon return with E_SCN_BUFFERTOOSMALL error code, this variable will contains the necessary size to be allocated for the buffer. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example #define MAX_IMAGE_WIDTH 640 #define MAX_IMAGE_HEIGHT 480 #define MAX_IMAGE_BUFFER_SIZE (MAX_IMAGE_WIDTH * MAX_IMAGE_HEIGHT + sizeof(SCAN_IMAGE_DATA)) BYTE bImageBuffer[MAX_IMAGE_BUFFER_SIZE]; DWORD dwResult, dwBufferSize = MAX_IMAGE_BUFFER_SIZE; // Call as blocking function dwResult = SCAN_GetLastImage(hScanner, TRUE, (LPSCAN_IMAGE_DATA)bImageBuffer, &dwBufferSize, &g_GetImageParams, NULL); if( dwResult != E_SCN_SUCCESS ) { wsprintf(szString, TEXT("Unable to take the picture. Error 0x%x"), dwResult); MessageBox(hWnd, szString, TEXT("Programm Error"), MB_OK | MB_ICONERROR);

Page 41: HC700 SDK Specification

Page 41 of 680

return; } LPSCAN_IMAGE_DATA lpImageBuffer = (LPSCAN_IMAGE_DATA)bImageBuffer; LPBYTE lpImageData = (LPBYTE)lpImageBuffer + lpImageBuffer->dwImageDataOffset; DWORD dwImageDataSize = lpImageBuffer->dwImageDataSize;

Page 42: HC700 SDK Specification

Page 42 of 680

SCAN_GetIntelligentImage

Description The SCAN_GetIntelligentImage function is used to get signature capture image from the imager.

Function Prototype

DWORD SCAN_GetIntelligentImage(HANDLE hScanner,BOOL bWait, LPSCAN_IQ_IMG_PARAMS lpimgParams, LPSCAN_IMAGE_DATA lpImgBuffer, LPDWORD lpdwBufferSize, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. bWait [In] This value will define the notification mechanism for getting resulting intelligent image. When this value is equal to TRUE, this function is blocked and lpImgBuffer will be filled with image data upon return. When this value is equal to FALSE, this function is not-blocked. It will start intelligent image processing and will exit. The image itself will be received asynchronously (after SCAN_RegisterNotifications was called) by SCAN_GetNotificationResult with SCAN_NOTIFY_REMOTE_IMAGE notification type. In this case lpImgBuffer and lpdwBufferSize are ignored. lpimgParams [In] This parameter contains the pointer to the structure defines the desired intelligent image relatively to barcode. lpImgBuffer [Out] In case that this function was called as blocked (bWait=TRUE) this parameter contains the pointer to the buffer that receives intelligent image data. lpdwBufferSize [In/Out] This parameter contains the pointer to DWORD with the size in bytes of buffer specified by lpImgBuffer. Upon return with E_SCN_BUFFERTOOSMALL error code, this variable will contains the necessary size to be allocated for the buffer. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example #define MAX_IMAGE_WIDTH 640 #define MAX_IMAGE_HEIGHT 480 #define MAX_IMAGE_BUFFER_SIZE (MAX_IMAGE_WIDTH * MAX_IMAGE_HEIGHT + sizeof(SCAN_IMAGE_DATA)) BYTE bImageBuffer[MAX_IMAGE_BUFFER_SIZE]; DWORD dwResult, dwBufferSize = MAX_IMAGE_BUFFER_SIZE; SCAN_IQ_IMG_PARAMS ImgSigParams; ImgSigParams.dwAspectRatio = 18; ImgSigParams.nCenterXoffset = 2; ImgSigParams.nCenterYoffset = -43; ImgSigParams.dwImageWidth = 190;

Page 43: HC700 SDK Specification

Page 43 of 680

ImgSigParams.dwImageHeight = 50; ImgSigParams.dwResolution = 3; ImgSigParams.SignatureFormat= SCAN_FORMAT_RAW_BINARY; ImgSigParams.dwReserved1 = 0; ImgSigParams.dwReserved2 = 0; // Call as blocking function dwResult = SCAN_GetIntelligentImage(hScanner, TRUE, ImgSigParams, (LPSCAN_IMAGE_DATA)bImageBuffer, &dwBufferSize, NULL);

Page 44: HC700 SDK Specification

Page 44 of 680

SCAN_CaptureRegionOfInterest

Description The SCAN_CaptuterRegionOfInterest function is used to get signature capture image or another region of interest (ROI) related to barcode from the imager.

Function Prototype

DWORD SCAN_CaptureRegionOfInterest (HANDLE hScanner,BOOL bWait, LPSCAN_IMG_ROI_PARAMS lpimgParams, LPSCAN_IMAGE_DATA lpImgBuffer, LPDWORD lpdwBufferSize, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. bWait [In] This value will define the notification mechanism for getting resulting intelligent image. When this value is equal to TRUE, this function is blocked and lpImgBuffer will be filled with image data upon return. When this value is equal to FALSE, this function is not-blocked. It will start intelligent image processing and will exit. The image itself will be received asynchronously (after SCAN_RegisterNotifications was called) by SCAN_GetNotificationResult with SCAN_NOTIFY_REMOTE_IMAGE notification type. In this case lpImgBuffer and lpdwBufferSize are ignored. lpimgParams [In] This parameter contains the pointer to the structure defines the desired intelligent image relatively to barcode. lpImgBuffer [Out] In case that this function was called as blocked (bWait=TRUE) this parameter contains the pointer to the buffer that receives intelligent image data. lpdwBufferSize [In/Out] This parameter contains the pointer to DWORD with the size in bytes of buffer specified by lpImgBuffer. Upon return with E_SCN_BUFFERTOOSMALL error code, this variable will contains the necessary size to be allocated for the buffer. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example #define MAX_IMAGE_WIDTH 640 #define MAX_IMAGE_HEIGHT 480 #define MAX_IMAGE_BUFFER_SIZE (MAX_IMAGE_WIDTH * MAX_IMAGE_HEIGHT + sizeof(SCAN_IMAGE_DATA)) BYTE bImageBuffer[MAX_IMAGE_BUFFER_SIZE]; DWORD dwResult, dwBufferSize = MAX_IMAGE_BUFFER_SIZE; SCAN_IMG_ROI_PARAMS ImgRoiParams; ImgRoiParams. dwXdimension = 15000;

Page 45: HC700 SDK Specification

Page 45 of 680

ImgRoiParams. dwBarcodeHeight = 345; ImgRoiParams. XDistanceFromCenterBarcodeToCenterROI= -60; ImgRoiParams. YDistanceFromCenterBarcodeToCenterROI = -1020; ImgRoiParams. dwRoiWidth = 2850; ImgRoiParams. dwRoiHeight = 945; ImgRoiParams. dwRoiDpi = 0; ImgRoiParams. dwRoiWidthInPixels = 928; ImgRoiParams. dwRoiHeightInPixels= 304; ImgRoiParams. ZoomLimit= 0; ImgRoiParams. SignatureFormat= SCAN_FORMAT_RAW_BINARY; // Call as blocking function dwResult = SCAN_GetIntelligentImage(hScanner, TRUE, ImgRoiParams, (LPSCAN_IMAGE_DATA)bImageBuffer, &dwBufferSize, NULL);

Page 46: HC700 SDK Specification

Page 46 of 680

SCAN_IsImagePresent

Description The SCAN_IsImagePresent function is used to define if any image is presented within provided picture data (if it is not empty image).

Function Prototype

DWORD SCAN_IsImagePresent (HANDLE hScanner,LPSCAN_IS_IMAGE_PRESENT lpIsImgPresent, LPSCAN_IS_IMAGE_PRESENT_PARAMS lpIsImgPresentParams, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. lpIsImgPresent [Out] If the provided image will be not empty this parameter will be equal to SCAN_IMAGE_PRESENTED value. lpIsImgPresentParams [In] This parameter provides the necessary parameters for this function. See SCAN_IS_IMAGE_PRESENT_PARAMS for more details. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example SCAN_IS_IMAGE_PRESENT IsImgPresent; SCAN_IS_IMAGE_PRESENT_PARAMS IsImgPresentParams; IsImgPresentParams.dwImgWidth = lpImageBuffer->dwImageWidth; IsImgPresentParams.dwImgHeight = lpImageBuffer->dwImageHeight; IsImgPresentParams.dwImgDepth = 1; IsImgPresentParams.dwMinBlack = 75; // 300 - 30% blackness, 75 - 7.5% blackness IsImgPresentParams.lpImgData = lpImageData; DWORD dwResult = SCAN_IsImagePresent(hScanner, &IsImgPresent, &IsImgPresentParams, NULL); if( dwResult==E_SCN_SUCCESS ) { if( IsImgPresent == SCAN_IMAGE_PRESENTED ) MessageBox(hDlg, TEXT("Valid signature"), TEXT("Success"), MB_OK); else

MessageBox(hDlg, TEXT("Not valid signature"), TEXT("Programm Error"), MB_OK | MB_ICONERROR);

}

Page 47: HC700 SDK Specification

Page 47 of 680

SCAN_FormatImageData

Description The SCAN_FormatImageData function is used to convert the row image data into one of the supported image file formats.

Function Prototype

DWORD SCAN_FormatImageData(HANDLE hScanner, SCAN_IMAGE_FORMAT sourceFormat, SCAN_IMAGE_FORMAT targetFormat, LPVOID lpImageBuffer, LPDWORD lpdwImageBufferSize, DWORD dwImageWidth, DWORD dwImageHeight, DWORD dwJpegQFactor, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. sourceFormat [In] This value will define a current format of the image in buffer pointered by lpImageBuffe. Actually this function support only SCAN_FORMAT_RAW_GRAY for sourceFormat parameter. targetFormat [In] This value will define a format the image data will be converted to. This function will return successful error code and will do nothing if sourceFormat is eaual to targetFormat. lpImageBuffer [In/Out] This parameter contains the pointer to the buffer containing a source (In) and converted image data (Out). lpdwImageBufferSize [In/Out] This parameter contains a pointer to DWORD variable with a size of the buffer filled with source image size and specified by lpImageBuffer. Upon return this variable will contain the new size of converted image in buffer pointed by lpImageBuffer. dwImageWidth This parameter specifies the width of source image in pixels. dwImageHeight This parameter specifies the height of source image in pixels. dwJpegQFactor This parameter specifies the quality factor for JPEG formatted image (quality percent) and may be from 1 to 100. It is relevant only when targetFormat is equal to SCAN_FORMAT_JPEG_GRAY value. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example dwResult = SCAN_FormatImageDatae(hScanner, SCAN_IMAGE_FORMAT_RAW_GRAY, SCAN_IMAGE_FORMAT_TIFF_COMPRESSED, ImageFile, &dwImageSize , ImageBuffer.dwImageWidth,

Page 48: HC700 SDK Specification

Page 48 of 680

ImageBuffer.dwImageHeight, 0, NULL ); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 49: HC700 SDK Specification

Page 49 of 680

SCAN_SetDefaultParams

Description The SCAN_SetDefaultParams function is used to apply the default parameters on the imager.

Function Prototype

DWORD SCAN_SetDefaultParams(HANDLE hScanner, LPVOID lpParamData, LPDWORD lpdwParamSize);

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. lpParamData Reserved. Set to NULL lpParamSize Reserved. Set to NULL Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example dwResult = SCAN_SetDefaultParams(hScanner, NULL, NULL); if( dwResult != E_SCN_SUCCESS ) { wsprintf(szString, TEXT("Unable to set the default params to imager. Error 0x%x"), dwResult); MessageBox(hWnd, szString, TEXT("Programm Error"), MB_OK | MB_ICONERROR); return; }

Page 50: HC700 SDK Specification

Page 50 of 680

SCAN_GetInternalImagerParams

Description The SCAN_GetInternalImagerParams function is used to get current parameters set of specified configuration item for internal imager.

Function Prototype

DWORD SCAN_GetInternalImagerParams(HANDLE hScanner, SCAN_IMAGER ImagerType, SCAN_INTERNAL_PARAM_TYPE ParamType, LPVOID lpParamData, LPDWORD lpdwParamSize);

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. ParamType [In] Specifies the type of internal imager. ParamType [In] Specifies the type of parameter to be retrieved by this function. lpParamData [Out] The pointer appropriate to the required parameter data structure that will be filled with retrieved parameter data. ldwpParamSize [In/Out] The pointer to the DWORD variable contains the size of the data pointed by lpParamData parameter. If this size is insufficient for reading desired parameter, upon return this variable will contain the required size. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes. QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example DWORD dwResult, dwParamSize; SCAN_INTERNAL_DECODE_MODE DecodeMode; dwParamSize = sizeof(SCAN_INTERNAL_DECODE_MODE); dwResult = SCAN_GetInternalImagerParams(hScanner, SCAN_IMAGER_INTERNAL_HHP, SCAN_INTERNAL_PARAM_TYPE_DECODE_MODE, &DecodeMode, &dwParamSize); if( dwResult != E_SCN_SUCCESS ) {

wsprintf(szString, TEXT("Unable to get decode mode param. Error 0x%x"), dwResult); MessageBox(hDlg, szString, TEXT("Programm Error"), MB_OK | MB_ICONERROR); EndDialog(hDlg, 1); return TRUE; }

Page 51: HC700 SDK Specification

Page 51 of 680

SCAN_SetInternalImagerParams

Description The SCAN_SetInternalImagerParams function is used to set parameters set of specified configuration item to internal imager.

Function Prototype

DWORD SCAN_SetInternalImagerParams(HANDLE hScanner, SCAN_IMAGER ImagerType, SCAN_INTERNAL_PARAM_TYPE ParamType, LPVOID lpParamData, LPDWORD lpdwParamSize);

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. ParamType [In] Specifies the type of internal imager. ParamType [In] Specifies the type of parameter to be set by this function. lpParamData [Out] The pointer appropriate to the required parameter data structure with desired parameter’s data. ldwpParamSize [In/Out] The pointer to the DWORD variable contains the size of the data pointed by lpParamData parameter. If this size is insufficient for reading desired parameter, upon return this variable will contain the required size. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes. QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT. Example DWORD dwResult, dwParamSize; SCAN_INTERNAL_DECODE_MODE DecodeMode; dwParamSize = sizeof(SCAN_INTERNAL_DECODE_MODE); DecodeMode.DecodingMode = SCAN_INTERNAL_DECODE_MODE_TYPE_ADVANCED_LINEAR; DecodeMode. WLinearRange = 1; dwResult = SCAN_SetInternalImagerParams(hScanner, SCAN_IMAGER_INTERNAL_HHP, SCAN_INTERNAL_PARAM_TYPE_DECODE_MODE, &DecodeMode, &dwParamSize); if( dwResult != E_SCN_SUCCESS ) {

wsprintf(szString, TEXT("Unable to set decode mode param. Error 0x%x"), dwResult); MessageBox(hDlg, szString, TEXT("Programm Error"), MB_OK | MB_ICONERROR); EndDialog(hDlg, 1); return TRUE; }

Page 52: HC700 SDK Specification

Page 52 of 680

SCAN_SetImageStream

Description The SCAN_SetImageStream function is used to read streaming image data (movie mode). During imager operation in stream mode no barcode and signature reads allowed (the functions SCAN_ReadLabelEvent/Message/Wait, SCAN_GetImage, SCAN_GetLastImage and SCAN_GetIntelligentImage will return E_SCN_INVALIDRESULT).

Function Prototype

DWORD SCAN_SetImageStream(HANDLE hScanner, SCAN_IMAGE_STREAM_CMD StreamCmd, LPSCAN_IMAGE_DATA lpImgBuffer, LPDWORD lpdwBufferSize, SCAN_IMAGE_STREAM_PARAMS lpImgStreamParams, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. StreamCmd [In] Specifies the command code of operation to be performed by SCAN_SetImageStream function. This may be equal to one of the following three values: • SCAN_IMAGE_STREAM_CMD_START - Command for the initializing of the imager stream mode. • SCAN_IMAGE_STREAM_CMD_READ - Command for reading pictures data in stream mode. • SCAN_IMAGE_STREAM_CMD_STOP - Command for the deinitializing of the imager stream mode. The regular user procedure is:

o Calling SCAN_SetImageStream function providing SCAN_IMAGE_STREAM_CMD_START and lpImgStreamParams parameters to initialize imager to work in stream mode.

o Calling SCAN_SetImageStream function providing SCAN_IMAGE_STREAM_CMD_READ, lpImgBuffer and lpdwBufferSize parameters to read pictures data.

o Calling SCAN_SetImageStream function providing SCAN_IMAGE_STREAM_CMD_STOP parameter to stop imager operation in stream mode.

lpImgBuffer [Out] This parameter contains the pointer to the buffer that receives the image data. lpdwBufferSize [In/Out] This parameter contains the pointer to DWORD with the size in bytes of buffer specified by lpImgBuffer. Upon return with E_SCN_BUFFERTOOSMALL error code, this variable will contains the necessary size to be allocated for the buffer. lpImgStreamParams This parameter defines the characteristics of the picture to be acquired from imager in stream mode. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 53: HC700 SDK Specification

Page 53 of 680

SCAN_IsImagePresent

Description The SCAN_IsImagePresent function is used to define if a target image is empty or not.

Function Prototype

DWORD SCAN_IsImagePresent(HANDLE hScanner, LPSCAN_IS_IMAGE_PRESENT lpIsImgPresent, LPSCAN_IS_IMAGE_PRESENT_PARAMS lpIsImgPresentParams, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. lpIsImgPresent [Out] Filled with the function result. This may be equal to one of the following values: • SCAN_IMAGE_PRESENTED – The image pointed by lpIsImgPresentParams parameter is not empty. • SCAN_IMAGE_NOT_PRESENTED – The image pointed by lpIsImgPresentParams parameter is

empty. lpIsImgPresenParams This parameter defines the image to be examined for blackness and blackness parameters. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example SCAN_IS_IMAGE_PRESENT IsImgPresent; SCAN_IS_IMAGE_PRESENT_PARAMS IsImgPresentParams; LPSCAN_IMAGE_DATA lpImageBuffer = (LPSCAN_IMAGE_DATA)bImageBuffer; LPBYTE lpImageData = (LPBYTE)lpImageBuffer + lpImageBuffer->dwImageDataOffset; IsImgPresentParams.dwImgWidth = lpImageBuffer->dwImageWidth; IsImgPresentParams.dwImgHeight = lpImageBuffer->dwImageHeight; IsImgPresentParams.dwImgDepth = 1; IsImgPresentParams.dwMinBlack = dwMinBlackness; // 300 - 30% blackness, 75 - 7.5% blackness IsImgPresentParams.lpImgData = lpImageData; DWORD dwResult = SCAN_IsImagePresent(hScanner, &IsImgPresent, &IsImgPresentParams, NULL); if( dwResult != E_SCN_SUCCESS ) { wsprintf(szString, TEXT("Unable to check this image for blackness. Error 0x%x"), dwResult); MessageBox(hDlg, szString, TEXT("Programm Error"), MB_OK | MB_ICONERROR); }

Page 54: HC700 SDK Specification

Page 54 of 680

else { if( IsImgPresent == SCAN_IMAGE_PRESENTED ) MessageBox(hDlg, TEXT("Valid signature"), TEXT("Success"), MB_OK); else MessageBox(hDlg, TEXT("Not valid signature"), TEXT("Programm Error"), MB_OK | MB_ICONERROR); }

Page 55: HC700 SDK Specification

Page 55 of 680

Data Types

SCAN_INTERNAL_PARAM_TYPE

Description

The SCAN_INTERNAL_PARAM_TYPE specifies the type of parameter to be retrieved or set on internal imager.

Structure Definition

typedef enum

{

SCAN_INTERNAL_PARAM_TYPE_DECODE_MODE = 0 ,

SCAN_INTERNAL_PARAM_TYPE_DECODE_CENTERING_WINDOW ,

SCAN_INTERNAL_PARAM_TYPE_PRINT_WEIGHT ,

SCAN_INTERNAL_PARAM_TYPE_GET_DECODE_TIME ,

SCAN_INTERNAL_PARAM_TYPE_VIDEO_REVERSE ,

SCAN_INTERNAL_PARAM_TYPE_DECODE_LIMIT_TIME ,

SCAN_INTERNAL_PARAM_TYPE_SET_LIGHTS_MODE ,

SCAN_INTERNAL_PARAM_TYPE_GET_IMAGER_INFO ,

SCAN_INTERNAL_PARAM_TYPE_EXPOSURE_PARAMS ,

SCAN_INTERNAL_PARAM_TYPE_ENABLE_SYMBOLOGY ,

SCAN_INTERNAL_PARAM_TYPE_ENGINE_CONFIGURATION,

SCAN_INTERNAL_PARAM_TYPE_GET_STATISTICS ,

SCAN_INTERNAL_PARAM_TYPE_SYMBOLOGY

} SCAN_INTERNAL_PARAM_TYPE;

Members SCAN_INTERNAL_PARAM_TYPE_DECODE_MODE

Specifies imager’s decode mode parameters. See SCAN_INTERNAL_DECODE_MODE_TYPE for further description.

SCAN_INTERNAL_PARAM_TYPE_DECODE_CENTERING_WINDOW

Specifies imager’s centering window parameters. See SCAN_INTERNAL_DECODE_CENTERING_WINDOW for further description.

SCAN_INTERNAL_PARAM_TYPE_PRINT_WEIGHT Specifies imager’s print weight parameters. See SCAN_INTERNAL_PRINT_WEIGHT for further description.

SCAN_INTERNAL_PARAM_TYPE_GET_DECODE_TYPE

Page 56: HC700 SDK Specification

Page 56 of 680

Specifies last time took for decode operation. See SCAN_INTERNAL_GET_DECODE_TYPE for further description.

SCAN_INTERNAL_PARAM_TYPE_VIDEO_REVERSE Specifies imager’s video reverse parameters. See SCAN_INTERNAL_VIDEO_REVERSE for further description.

SCAN_INTERNAL_PARAM_TYPE_DECODE_LIMIT_TIME Specifies imager’s decode limit times parameters. See SCAN_INTERNAL_DECODE_LIMIT_TIME for further description.

SCAN_INTERNAL_PARAM_TYPE_SET_LIGHTS_MODE Specifies imager’s ligths mode parameters. See SCAN_INTERNAL_SET_LIGHTS_MODE for further description.

SCAN_INTERNAL_PARAM_TYPE_GET_IMAGER_INFO Specifies to retrieve imager’s information. See SCAN_INTERNAL_IMAGER_INFO for further description.

SCAN_INTERNAL_PARAM_TYPE_EXPOSURE_PARAMS Specifies imager’s exposure parameters. See SCAN_INTERNAL_EXPOSURE_PARAMS for further description.

SCAN_INTERNAL_PARAM_TYPE_ENABLE_SYMBOLOGY Specifies imager’s enabled/disabled symbologies for internal imager. In this case lpParamData parameter of SCAN_Get/SetInternalImager function will point on array of LABELTYPE_ALL size with BOOL elements indicate the symbologies status (enabled or disabled), when the index of that array will according to LABELTYPE_xxx definitions below.

SCAN_INTERNAL_PARAM_TYPE_ENGINE_CONFIGURATION Specifies imager’s engine configuration. See SCAN_INTERNAL_ENGINE_CONFIGURATION for further description.

SCAN_INTERNAL_PARAM_TYPE_GET_STATISTICS

Retries imager’s statistics. SCAN_INTERNAL_GET_STATISTICS for further description. SCAN_INTERNAL_PARAM_TYPE_SYMBOLOGY

Specifies parameters of any single symbology on internal imager. See SCAN_INTERNAL_SYMBOLOGY_PARAMS for further description.

SCAN_IMAGER

Description

The SCAN_IMAGER data type specifies the internal imager type.

Structure Definition

typedef enum

{

SCAN_IMAGER_INTERNAL_HHP = 0

} SCAN_IMAGER;

Members

Page 57: HC700 SDK Specification

Page 57 of 680

SCAN_IMAGER_INTERNAL_HHP Specifies the type of internal imager is HHP imager.

SCAN_INTERNAL_DECODE_MODE_TYPE

Description

Specifies the decoding mode of internal imager.

Structure Definition

typedef enum

{

SCAN_INTERNAL_DECODE_MODE_TYPE_FULL_OMNI = 0 ,

SCAN_INTERNAL_DECODE_MODE_TYPE_ADVANCED_LINEAR ,

SCAN_INTERNAL_DECODE_MODE_TYPE_QUICK_OMNI

} SCAN_INTERNAL_DECODE_MODE_TYPE, *LPSCAN_INTERNAL_DECODE_MODE_TYPE;

Members SCAN_INTERNAL_DECODE_MODE_TYPE_FULL_OMNI

Specifies the full omni-directional decoding.

SCAN_INTERNAL_DECODE_MODE_ ADVANCED_LINEAR Specifies the linear decoding.

SCAN_INTERNAL_DECODE_MODE_TYPE_QUICK_OMNI Specifies the quick omni-directional decoding.

SCAN_INTERNAL_DECODE_MODE

Description

Specifies the decoding mode parameter of internal imager.

Structure Definition

typedef struct

{

WORD wLinearRange;

SCAN_INTERNAL_DECODE_MODE_TYPE DecodingMode

} SCAN_INTERNAL_DECODE_MODE, *LPSCAN_INTERNAL_DECODE_MODE;

Members wLinearRange

Specifies the linear range value in case of linear decoding mode.

DecodingMode Specifies the decoding mode

Page 58: HC700 SDK Specification

Page 58 of 680

SCAN_INTERNAL_DECODE_CENTERING_WINDOW

Description

Contains information for decode centering mode. In this mode, a decode call is only successful

if the area bounding the decoded symbol intersects a caller defined rectangle located about the center of the captured image.

Note: This functionality allows the imager to discriminate symbols that are located physically close to each other so only one symbol is captured during decode. Only the symbol intersecting the intersection rectangle is returned.

Structure Definition // Centering Box Min/Max Values #define SCAN_INTERNAL_DECODE_WINDOW_ULX_MIN 0 #define SCAN_INTERNAL_DECODE_WINDOW_ULX_MAX 319 #define SCAN_INTERNAL_DECODE_WINDOW_ULY_MIN 0 #define SCAN_INTERNAL_DECODE_WINDOW_ULY_MAX 239 #define SCAN_INTERNAL_DECODE_WINDOW_LRX_MIN 320 #define SCAN_INTERNAL_DECODE_WINDOW_LRX_MAX 639 #define SCAN_INTERNAL_DECODE_WINDOW_LRY_MIN 240 #define SCAN_INTERNAL_DECODE_WINDOW_LRY_MAX 479 // Centering Box Defaults Values #define SCAN_INTERNAL_DEFAULT_DECODE_WINDOW_ULX 290 #define SCAN_INTERNAL_DEFAULT_DECODE_WINDOW_ULY 210 #define SCAN_INTERNAL_DEFAULT_DECODE_WINDOW_LRX 350 #define SCAN_INTERNAL_DEFAULT_DECODE_WINDOW_LRY 270

typedef struct

{

BOOL bEnable;

RECT IntersactionRectangle;

} SCAN_INTERNAL_DECODE_CENTERING_WINDOW, *LPSCAN_INTERNAL_DECODE_ CENTERING_WINDOW;

Members bEnable

Specifies if decode centering windos feature is enabled. IntersactionRectangle

Specifies rectangular image region of which at least part of the decoded symbol must overlap to be considered a valid decode.

SCAN_INTERNAL_PRINT_WEIGHT

Description

Specifies the print weight parameter of internal imager.

Page 59: HC700 SDK Specification

Page 59 of 680

Structure Definition

typedef struct

{

WORD wPrintWeight;

} SCAN_INTERNAL_PRINT_WEIGHT, *LPSCAN_INTERNAL_PRINT_WEIGHT;

Members wPrintWeight

Specifies print weight (relative blackness) that the decoder expects to see when attempting to decode symbols or OCR text from an image. Changing this value can facilitate decoding of symbols with non-standard black on white contrast such as with etched metal on car parts or some soda cans.

SCAN_INTERNAL_GET_DECODE_TIME

Description

Specifies the time took to decode last barcode label.

Structure Definition

typedef struct

{

DWORD dwDecodeTime;

} SCAN_INTERNAL_GET_DECODE_TIME, *LPSCAN_INTERNAL_GET_DECODE_TIME;

Members dwDecodeTime

Specifies the time in milliseconds took to decode last barcode.

SCAN_INTERNAL_VIDEO_REVERSE

Description

Enable and disable the decoding of symbols that are inverted (white bars on black background)

Structure Definition

typedef struct

{

BOOL bEnable;

} SCAN_INTERNAL_VIDEO_REVERSE, *LPSCAN_INTERNAL_VIDEO_REVERSE;

Members bEnable

Specifies if decoding of inverted (white bars on black background) barcodes enabled

Page 60: HC700 SDK Specification

Page 60 of 680

SCAN_INTERNAL_DECODE_LIMIT_TIME

Description

Specifies the times limites for decoding barcodes.

Structure Definition

typedef struct

{ WORD wSearchLimitTime; WORD wDecodeLimitTime;

} SCAN_INTERNAL_DECODE_LIMIT_TIME, *LPSCAN_INTERNAL_DECODE_LIMIT_TIME;

Members wSearchLimitTime

Specifies the time limit that search process may use to look for potential labels in the current image.

wDecodeLimitTime Specifies the maximum amount of time the decoder may use to attempt a decode on the current image.

SCAN_INTERNAL_LIGHT_MODE_TYPE

Description

This structure specifies the light mode types.

Structure Definition

typedef enum {

SCAN_INTERNAL_LIGHTS_MODE_ILLUM_AIMER_OFF = 0 , SCAN_INTERNAL_LIGHTS_MODE_ILLUM_ONLY_ON , SCAN_INTERNAL_LIGHTS_MODE_AIMER_ONLY_ON , SCAN_INTERNAL_LIGHTS_MODE_ILLUM_AIMER_ON

} SCAN_INTERNAL_LIGHT_MODE_TYPE, *LPSCAN_INTERNAL_LIGHT_MODE_TYPE;

Members SCAN_INTERNAL_LIGHTS_MODE_ILLUM_AIMER_OFF

Specifies that during barcode and image acqusition both illumination and aimer lights will be off.

SCAN_INTERNAL_LIGHTS_MODE_ILLUM_ONLY_ON Specifies that during barcode and image acqusition only illumination lights will be on.

SCAN_INTERNAL_LIGHTS_MODE_AIMER_ONLY_ON Specifies that during barcode and image acqusition only aimer lights will be on.

Page 61: HC700 SDK Specification

Page 61 of 680

SCAN_INTERNAL_LIGHTS_MODE_ILLUM_AIMER_ON Specifies that during barcode and image acqusition both illumination and aimer lights will be on.

SCAN_INTERNAL_LIGHT_MODE

Description

This function set the light mode types.

Structure Definition

typedef enum {

BOOL bLeaveLigthsOn; SCAN_INTERNAL_LIGHTS_MODE_TYPE LigthsMode;

} SCAN_INTERNAL_LIGHT_MODE, *LPSCAN_INTERNAL_LIGHT_MODE;

Members bLeaveLigthsOn

Specifies is the lights will be continuously turned on or flashed (during the label scan only)

LigthsMode Specifies is the lights mode for both barcode scanning and image acqusition.

SCAN_INTERNAL_ENGINE_ID

Description

Specifies the imager engine types.

Structure Definition

typedef enum { SCAN_INTERNAL_ENGINE_ID_NONE = 0 , SCAN_INTERNAL_ENGINE_ID_IT4200 = 1 , SCAN_INTERNAL_ENGINE_ID_IT4000 = 5 , SCAN_INTERNAL_ENGINE_ID_IT4100 = 6 , SCAN_INTERNAL_ENGINE_ID_IT4300 = 7 } SCAN_INTERNAL_ENGINE_ID, *LPSCAN_INTERNAL_ENGINE_ID;

Members SCAN_INTERNAL_ENGINE_ID_NONE

No imager.

SCAN_INTERNAL_ENGINE_ID_IT4200 IT4200 imager type

Page 62: HC700 SDK Specification

Page 62 of 680

SCAN_INTERNAL_ENGINE_ID_IT4000

IT4000 imager type

SCAN_INTERNAL_ENGINE_ID_IT4100 IT4100 imager type

SCAN_INTERNAL_ENGINE_ID_IT4300 IT4300 imager type

SCAN_INTERNAL_ROTATION

Description

Specifies the imager rotation types.

Structure Definition

typedef enum { SCAN_INTERNAL_ENGINE_ROTATION_RIGHT_SIDE_UP = 0 , SCAN_INTERNAL_ENGINE_ROTATION_ROTATED_RIGHT , SCAN_INTERNAL_ENGINE_ROTATION_UPSIDE_DOWN , SCAN_INTERNAL_ENGINE_ROTATION_ROTATED_LEFT } SCAN_INTERNAL_ENGINE_ROTATION, *LPSCAN_INTERNAL_ENGINE_ROTATION;

Members SCAN_INTERNAL_ENGINE_ROTATION_RIGHT_SIDE_UP

Rotation right side up.

SCAN_INTERNAL_ENGINE_ROTATION_ROTATED_RIGHT Rotated right.

SCAN_INTERNAL_ENGINE_ROTATION_UPSIDE_DOWN Rotation upside down.

SCAN_INTERNAL_ENGINE_ROTATION_RIGHT_SIDE_UP Rotated left.

SCAN_INTERNAL_IMAGER_PROPERTIES

Description

Specifies the properties of internal imager device.

Structure Definition

typedef struct { DWORD dwSize; DWORD dwEngineID;

Page 63: HC700 SDK Specification

Page 63 of 680

DWORD dwImagerRows; DWORD dwImagerCols; DWORD dwBitsPerPixel; DWORD dwRotation; DWORD dwAimerXoffset; DWORD dwAimerYoffset; DWORD dwYDepth;

} SCAN_INTERNAL_IMAGER_PROPERTIES, *LPSCAN_INTERNAL_IMAGER_PROPERTIES;

Members dwSize

Specifies the size of this structure.

dwEngineID Specifies the imager engine types. See SCAN_INTERNAL_ENGINE_ID structure above.

dwImagerRows Specifies the count of imager rows.

dwImagerCols Specifies the count of imager columns.

dwBitsPerPixel Specifies the imager engine depth.

dwRotation Specifies the imager rotation. See SCAN_INTERNAL_ROTATION structure above.

SCAN_INTERNAL_IMAGER_INFO

Description

Specifies the information aboutinternal imager device and scanning software revision.

Structure Definition #defineSCAN_REVISION_STRING_MAX_SIZE 1000

typedef struct { SCAN_INTERNAL_IMAGER_PROPERTIES ImagerProperties; TCHAR szOemAPIRevision [SCAN_REVISION_STRING_MAX_SIZE]; TCHAR szDecoderRevision [SCAN_REVISION_STRING_MAX_SIZE]; TCHAR szScanDriverRevision [SCAN_REVISION_STRING_MAX_SIZE]; TCHAR szMotDriverRevision [SCAN_REVISION_STRING_MAX_SIZE];

} SCAN_INTERNAL_IMAGER_PROPERTIES, *LPSCAN_INTERNAL_IMAGER_PROPERTIES;

Page 64: HC700 SDK Specification

Page 64 of 680

Members ImagerProperties

Specifies the properties of internal imager device.

szOemAPIRevision Specifies the revision of OEM API software module

szDecoderRevision Specifies the revision of decoder library module

szScanDriverRevision Specifies the revision of scan driver

szMotDriverRevision Specifies the revision of Motorola driver

SCAN_INTERNAL_EXPOSURE_MODE

Description

Specifies an imager’s operation mode.

Structure Definition

typedef struct { SCAN_INTERNAL_EXPOSURE_MODE_FIXED , SCAN_INTERNAL_EXPOSURE_MODE_AUTOMATIC

} SCAN_INTERNAL_EXPOSURE_MODE, *LPSCAN_INTERNAL_EXPOSURE_MODE;

Members SCAN_INTERNAL_EXPOSURE_MODE_FIXED

This mode is intended for setting the fixed exposure mode. When this mode specified, the fixed gain, exposure time and frame rate values define the barcode and image acqusition operation. At fixed mode the single image capture performed when barcode scanned or image pictured (with no retries). Not recommended to use fixed mode for barcode scanning purposes.

SCAN_INTERNAL_EXPOSURE_MODE_AUTOMATIC This mode is intended for setting the automatic exposure mode. When this mode specified, the user will provide values for maximum gain and exposure time, the desired white value and possiblewhite window for image acquisition algorothm procedure. The imager will perform the multiple image captures with provided parameters till desired white value reached or retries number exceed. This mode of imager operation will provide mostly the better image quality. Also it is recommended for image acquisition and barcode scanning.

SCAN_INTERNAL_EXPOSURE_SETTINGS

Description

Specifies the parameters for image acquisition in fixed and automatic operation modes.

Page 65: HC700 SDK Specification

Page 65 of 680

Structure Definition

typedef struct { int Exposure; int MaxExposure; int Gain; int MaxGain; int TargetWhite; int TargetWhiteWindow; int ImageMustConform; int NumUpdates; int FrameRate; int SpecExclusion; int SpecSaturation; int SpecLimit; int FixedExposure; int FixedGain; int FixedFrameRate;

} SCAN_INTERNAL_EXPOSURE_SETTINGS, *LPSCAN_INTERNAL_EXPOSURE_SETTINGS;

Members Exposure

This parameter will apply only when in automatic mode. This is read only parameter. This value corresponds to an exposure time value that will be tried on first scan. The range of this value is Minimum of 1, maximum of 7874, where the value relates to exposure = Exposure*127us. Default value is 200 (25ms).

MaxExposure This parameter will apply only when in automatic mode and it specifies the maximum exposure value to be used by the auto exposure logic during image acquisition. The default value for this parameter is 200, the minimum value is 1 and the maximum value is 7874, in units of 127uS. It should be noted that this parameter would allow for the adjustment of the frame rate of the imager to achieve larger exposure times; therefore it will affect the speed at which the imager acquires an image. Default value is 200 (25ms).

MaxGain This specifies the maximum gain value to be used by the auto exposure logic during image acquisition. The default value for this parameter is 2, the range is 1 to 4

TargetWhite

This parameter will apply only when in automatic mode.

Page 66: HC700 SDK Specification

Page 66 of 680

The auto exposure algorithm tries to get a given percentile of all of the pixel values of the image, to fall at a target value. This parameter specifies the desired target value. The default value for this parameter is 150, with a minimum of 1 and a maximum of 255.

TargetWhiteWindow

This parameter will apply only when in automatic mode. This specifies the window of acceptance around the TargetWhite value. The resulting goal becomes TargetWhite +/- TargetWhiteWindow. The default value for this parameter is 10, the minimum value is 1 and the maximum value is 50. It should be noted however that as this value gets smaller, the time to acquire a conforming image might be lengthened.

ImageMustConform

This parameter will apply only when in automatic mode. As the goal of the auto exposure software is to achieve a TargetWhite value for a percentage of pixels before deeming an image acceptable for use, this parameter tells the image acquisition software that the acquired image must try until NumUpdates to meet those requirements (TargetWhite, TargetWhiteWindow). The default value for this parameter is 1 for true which means that it will strive to conform per those settings before accepting an image.

NumUpdates

This parameter will apply only when in automatic mode. This specifies the maximum number of attempts that the auto exposure logic can use while attempting to acquire an image that conforms to the target values set up for the auto exposure algorithm, before considering the image as conforming. This parameter is only valid when the ImageMustConform value is set to 1 or true. The default value for this parameter is 6, the minimum value is 1 and the maximum value is 8.

FrameRate

This parameter will apply only when in automatic mode. This parameter defines the starting frame rate to be used by the auto exposure logic during image acquisition. The default value for this parameter is 30, the minimum value is 1 and the maximum value is 30 (the settings available for the IT4000 are 30, 20, 15, 12, 10, 6, 5, 4, 3, 2 and 1)

SpecExclusion SpecSaturation SpecLimit

This parameter will apply only when in automatic mode. and define the specular settings

FixedExposure

This parameter will apply only when in automatic mode. It specifies the fixed exposure time for barcode and image aquciton.

FixedGain

This parameter will apply only when in automatic mode. It specifies the fixed gain value for barcode and image aquciton.

FixedFrameRate

This parameter will apply only when in automatic mode. It specifies the fixed frame rate value for barcode and image aquciton.

SCAN_INTERNAL_EXPOSURE_PARAMS

Description

Specifies the parameters for imager’s operation.

Structure Definition

Page 67: HC700 SDK Specification

Page 67 of 680

typedef struct { SCAN_INTERNAL_EXPOSURE_MODE ExposureMode; SCAN_INTERNAL_EXPOSURE_SETTINGS ExposureSettings;

} SCAN_INTERNAL_EXPOSURE_PARAMS, *LPSCAN_INTERNAL_EXPOSURE_PARAMS;

Members ExposureMode Defines current exposure mode of the imager: fixed or automatic.

ExposureSettings Defines additional exposure settings for corresponding mode.

SCAN_INTERNAL_GET_STATISTICS

Description

Contains different imager statistics.

Structure Definition

typedef struct { DWORD dwTtr;

} SCAN_INTERNAL_GET_STATISTICS, *LPSCAN_INTERNAL_GET_STATISTICS;

Members dwTtr Defines time to read: the amount of time the last barcode was read.

SCAN_INTERNAL_GET_STATISTICS

Description

Contains different imager statistics.

Structure Definition

typedef struct { DWORD dwTtr;

} SCAN_INTERNAL_GET_STATISTICS, *LPSCAN_INTERNAL_GET_STATISTICS;

Members dwTtr Defines time to read: the amount of time the last barcode was read.

SCAN_INTERNAL_ENGINE_CONFIGURATION

Page 68: HC700 SDK Specification

Page 68 of 680

Description

Specifies different imager engine parameters.

Structure Definition

typedef struct { DWORD dwStructSize; DWORD dwIlluminationType; DWORD dwLedControlMode; DWORD dwPixelFrequency; DWORD dwEngineId; DWORD dwFirmwareChecksum;

} SCAN_INTERNAL_ENGINE_CONFIGURATION, *LPSCAN_INTERNAL_ ENGINE_CONFIGURATION;

Members dwStructSize Set to sizeof(SCAN_INTERNAL_ENGINE_CONFIGURATION). dwIlluminationType Defines the type of illumination leds used when barcode scanned. 0 = Green, Non Zero = Red dwLedControlMode Read only parameter. dwPixelFrequency Read only parameter. dwEngineId Read only parameter. dwFirmwareChecksum Read only parameter. Defines the internal imager firmware version.

SCAN_INTERNAL_AZTEC_PARAMS

Description

Specifies the parameters for Aztec symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_AZTEC_PARAMS, *LPSCAN_INTERNAL_AZTEC_PARAMS;

Page 69: HC700 SDK Specification

Page 69 of 680

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are not reported by the engine. The maximum allowable value (as well as the default) is 3750.

SCAN_INTERNAL_CODABAR_PARAMS

Description

Specifies the parameters for Codabar symbology type.

Structure Definition

typedef struct { BOOL bSSXmit; BOOL bCheckCharOn; BOOL bXmitCheckChar; WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_CODABAR_PARAMS, *LPSCAN_INTERNAL_CODABAR_PARAMS;

Members bSSXmit

BOOL variable that determines if the start and stop characters are returned in the data string after a successful Codabar decode. If bSSXmit is TRUE, the start and stop characters are included. If FALSE, they are not included. The default value is FALSE.

bCheckCharOn

BOOL variable that determines if the engine will read Codabar bar codes with or without check characters. If TRUE, the engine only decodes Codabar codes with a check character. If FALSE, the decoder decodes codes with or without a check character. The default value is FALSE.

bXmitCheckChar

BOOL variable that determines if the engine will return the check character as part of the data string after a successful decode. If TRUE, the engine returns the check character. If FALSE the check character is not returned. The default value is FALSE.

dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 2.

dwMaxLength

Page 70: HC700 SDK Specification

Page 70 of 680

The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are not reported by the engine. The maximum allowable value (as well as the default) is 60.

SCAN_INTERNAL_CODE39_PARAMS

Description

Specifies the parameters for Code39 symbology type.

Structure Definition

typedef struct { BOOL bSSXmit; BOOL bCheckCharOn; BOOL bXmitCheckChar; BOOL bFullAscii; BOOL bAppend; WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_CODE39_PARAMS, *LPSCAN_INTERNAL_CODE39_PARAMS;

Members bSSXmit

BOOL variable that determines if the start and stop characters are returned in the data string after a successful Code39 decode. If bSSXmit is TRUE, the start and stop characters are included. If FALSE, they are not included. The default value is FALSE.

bCheckCharOn

BOOL variable that determines if the engine will read Code39 bar codes with or without check characters. If TRUE, the engine only decodes Code39 codes with a check character. If FALSE, the decoder decodes codes with or without a check character. The default value is FALSE.

bXmitCheckChar

BOOL variable that determines if the engine will return the check character as part of the data string after a successful decode. If TRUE, the engine returns the check character. If FALSE the check character is not returned. The default value is FALSE.

bFullAscii BOOL variable that determines if certain character pairs within the bar code symbol are interpreted and returned as a single character. If bFullAscii is TRUE, interpretation is enabled. If FALSE, no interpretation is attempted. The default value is FALSE.

bAppend This parameter is not supported, and must be set to FALSE. dwMinLength

Page 71: HC700 SDK Specification

Page 71 of 680

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value is 0. The default is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are not reported by the engine. The maximum allowable value (as well as the default) is 48.

SCAN_INTERNAL_EAN13_PARAMS

Description

Specifies the parameters for Ean13 symbology type.

Structure Definition

typedef struct { BOOL bXmitCheckChar; BOOL bAddenda2Digit; BOOL bAddenda5Digit; BOOL bAddendaReq; BOOL bAddendaSeparator;

} SCAN_INTERNAL_EAN13_PARAMS, *LPSCAN_INTERNAL_EAN13_PARAMS;

Members bXmitCheckChar

BOOL variable that determines if the engine will return the check character as part of the data string after a successful decode. If TRUE, the engine returns the check character. If FALSE the check character is not returned. The default value is FALSE.

bAddenda2Digit BOOL variable that determines if the engine will look for a 2 digit addenda at the end of the EAN bar code. If TRUE, and an addenda is present, the engine adds the two digit addenda data to the end of the message. If FALSE, the engine ignores addenda data. The default value is FALSE.

bAddenda5Digit BOOL variable that determines if the engine will look for a 5 digit addenda at the end of the EAN bar code. If TRUE, and an addenda is present, the engine adds the two digit addenda data to the end of the message. If FALSE, the engine ignores addenda data. The default value is FALSE.

bAddendaReq BOOL variable that determines if the engine will decode only EAN bar codes that have a 2 or 5 digit addenda. If TRUE, the engine decodes only EAN symbols with an addenda. If FALSE, the engine decodes all enabled EAN symbols. The default value is FALSE.

bAddendaSeparator

BOOL variable that determines if there is a space character between the data from the bar code and the data from the addenda. If TRUE, there is a space. If FALSE, there is no space. The default value is TRUE.

Page 72: HC700 SDK Specification

Page 72 of 680

SCAN_INTERNAL_EAN8_PARAMS

Description

Specifies the parameters for Ean8 symbology type.

Structure Definition

typedef struct { BOOL bXmitCheckChar; BOOL bAddenda2Digit; BOOL bAddenda5Digit; BOOL bAddendaReq; BOOL bAddendaSeparator;

} SCAN_INTERNAL_EAN8_PARAMS, *LPSCAN_INTERNAL_EAN8_PARAMS;

Members bXmitCheckChar

BOOL variable that determines if the engine will return the check character as part of the data string after a successful decode. If TRUE, the engine returns the check character. If FALSE the check character is not returned. The default value is FALSE.

bAddenda2Digit BOOL variable that determines if the engine will look for a 2 digit addenda at the end of the EAN bar code. If TRUE, and an addenda is present, the engine adds the two digit addenda data to the end of the message. If FALSE, the engine ignores addenda data. The default value is FALSE.

bAddenda5Digit BOOL variable that determines if the engine will look for a 5 digit addenda at the end of the EAN bar code. If TRUE, and an addenda is present, the engine adds the two digit addenda data to the end of the message. If FALSE, the engine ignores addenda data. The default value is FALSE.

bAddendaReq BOOL variable that determines if the engine will decode only EAN bar codes that have a 2 or 5 digit addenda. If TRUE, the engine decodes only EAN symbols with an addenda. If FALSE, the engine decodes all enabled EAN symbols. The default value is FALSE.

bAddendaSeparator

BOOL variable that determines if there is a space character between the data from the bar code and the data from the addenda. If TRUE, there is a space. If FALSE, there is no space. The default value is TRUE.

SCAN_INTERNAL_UPCA_PARAMS

Description

Specifies the parameters for Upca symbology type.

Structure Definition

Page 73: HC700 SDK Specification

Page 73 of 680

typedef struct { BOOL bXmitCheckChar; BOOL bXmitNumSys; BOOL bAddenda2Digit; BOOL bAddenda5Digit; BOOL bAddendaReq; BOOL bAddendaSeparator;

} SCAN_INTERNAL_UPCA_PARAMS, *LPSCAN_INTERNAL_UPCA_PARAMS;

Members bXmitCheckChar

BOOL variable that determines if the engine will return the check character as part of the data string after a successful decode. If TRUE, the engine returns the check character. If FALSE the check character is not returned. The default value is FALSE.

bXmitNumSys BOOL variable that determines if the engine will return the numeric system digit of the UPC label. If TRUE, the engine returns the number system digit. If FALSE, the number system digit is not returned. The default value is TRUE.

bAddenda2Digit BOOL variable that determines if the engine will look for a 2 digit addenda at the end of the UPC bar code. If TRUE, and an addenda is present, the engine adds the two digit addenda data to the end of the message. If FALSE, the engine ignores addenda data. The default value is FALSE.

bAddenda5Digit BOOL variable that determines if the engine will look for a 5 digit addenda at the end of the UPC bar code. If TRUE, and an addenda is present, the engine adds the two digit addenda data to the end of the message. If FALSE, the engine ignores addenda data. The default value is FALSE.

bAddendaReq BOOL variable that determines if the engine will decode only UPC bar codes that have a 2 or 5 digit addenda. If TRUE, the engine decodes only UPC symbols with an addenda. If FALSE, the engine decodes all enabled EAN symbols. The default value is FALSE.

bAddendaSeparator

BOOL variable that determines if there is a space character between the data from the bar code and the data from the addenda. If TRUE, there is a space. If FALSE, there is no space. The default value is TRUE.

SCAN_INTERNAL_UPCE_PARAMS

Description

Specifies the parameters for Upce symbology type.

Structure Definition

typedef struct {

Page 74: HC700 SDK Specification

Page 74 of 680

BOOL bXmitCheckChar; BOOL bXmitNumSys; BOOL bExpandVersionE; BOOL bAddenda2Digit; BOOL bAddenda5Digit; BOOL bAddendaReq; BOOL bAddendaSeparator;

} SCAN_INTERNAL_UPCE_PARAMS, *LPSCAN_INTERNAL_UPCE_PARAMS;

Members bXmitCheckChar

BOOL variable that determines if the engine will return the check character as part of the data string after a successful decode. If TRUE, the engine returns the check character. If FALSE the check character is not returned. The default value is FALSE.

bXmitNumSys BOOL variable that determines if the engine will return the numeric system digit of the UPC label. If TRUE, the engine returns the number system digit. If FALSE, the number system digit is not returned. The default value is TRUE.

bExpandVersionE BOOL variable that determines if the engine will expand UPC-E codes to the 12 digit UPC-A format after a successful decode. If TRUE, the engine expands the code. If FALSE, the engine does not expand the UPC-E code. The default value is FALSE.

bAddenda2Digit BOOL variable that determines if the engine will look for a 2 digit addenda at the end of the UPC bar code. If TRUE, and an addenda is present, the engine adds the two digit addenda data to the end of the message. If FALSE, the engine ignores addenda data. The default value is FALSE.

bAddenda5Digit BOOL variable that determines if the engine will look for a 5 digit addenda at the end of the UPC bar code. If TRUE, and an addenda is present, the engine adds the two digit addenda data to the end of the message. If FALSE, the engine ignores addenda data. The default value is FALSE.

bAddendaReq BOOL variable that determines if the engine will decode only UPC bar codes that have a 2 or 5 digit addenda. If TRUE, the engine decodes only UPC symbols with an addenda. If FALSE, the engine decodes all enabled EAN symbols. The default value is FALSE.

bAddendaSeparator

BOOL variable that determines if there is a space character between the data from the bar code and the data from the addenda. If TRUE, there is a space. If FALSE, there is no space. The default value is TRUE.

SCAN_INTERNAL_CODABLOCK_PARAMS

Description

Specifies the parameters for Codablock symbology type.

Page 75: HC700 SDK Specification

Page 75 of 680

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_CODABLOCK_PARAMS, *LPSCAN_INTERNAL_CODABLOCK_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 0.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are not reported by the engine. The maximum allowable value (as well as the default) is 2048.

SCAN_INTERNAL_IATA25_PARAMS

Description

Specifies the parameters for Iata25 symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_IATA25_PARAMS, *LPSCAN_INTERNAL_IATA25_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 4.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 80.

SCAN_INTERNAL_MATRIX25_PARAMS

Description

Specifies the parameters for Matrix25 symbology type.

Page 76: HC700 SDK Specification

Page 76 of 680

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_MATRIX25_PARAMS, *LPSCAN_INTERNAL_MATRIX25_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 4.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 80.

SCAN_INTERNAL_STRT25_PARAMS

Description

Specifies the parameters for Strt25 symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_STRT25_PARAMS, *LPSCAN_INTERNAL_STRT25_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 4.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 48.

SCAN_INTERNAL_PLESSEY_PARAMS

Description

Page 77: HC700 SDK Specification

Page 77 of 680

Specifies the parameters for Plessey symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_PLESSEY_PARAMS, *LPSCAN_INTERNAL_PLESSEY_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 4.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 48.

SCAN_INTERNAL_CODE16K_PARAMS

Description

Specifies the parameters for Code16k symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_CODE16K_PARAMS, *LPSCAN_INTERNAL_CODE16K_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 160.

SCAN_INTERNAL_TELEPEN_PARAMS

Description

Page 78: HC700 SDK Specification

Page 78 of 680

Specifies the parameters for Telepen symbology type.

Structure Definition

typedef struct { BOOL bOldStyle; WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_TELEPEN_PARAMS, *LPSCAN_INTERNAL_TELEPEN_PARAMS;

Members bOldStyle

BOOL variable that configures the engine to read Telepen labels that were encoded with either the original or the AIM specification. The default is FALSE.

dwMinLength The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 60.

SCAN_INTERNAL_POSICODE_PARAMS

Description

Specifies the parameters for Posicode symbology type.

Structure Definition

typedef struct { WORD nLimited; WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_POSICODE_PARAMS, *LPSCAN_INTERNAL_POSICODE_PARAMS;

Members nLimited

A WORD variable used to enable the decoding of either Posicode Limited A or Posicode Limited B labels. A value of 1 enables Posicode Limited A, and a value of 2 enables Posicode Limited B. A value of 0 disables decoding of both Limited A and Limited B. The default value is 0.

dwMinLength

Page 79: HC700 SDK Specification

Page 79 of 680

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 4.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 48.

SCAN_INTERNAL_KOREAPOST_PARAMS

Description

Specifies the parameters for KoreaPost symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_KOREAPOST_PARAMS, *LPSCAN_INTERNAL_KOREAPOST_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 4.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 48.

SCAN_INTERNAL_CHINAPOST_PARAMS

Description

Specifies the parameters for ChinaPost symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_CHINAPOST_PARAMS, *LPSCAN_INTERNAL_CHINAPOST_PARAMS;

Members

Page 80: HC700 SDK Specification

Page 80 of 680

dwMinLength The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 4.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 80.

SCAN_INTERNAL_INT25_PARAMS

Description

Specifies the parameters for Int25 symbology type.

Structure Definition

typedef struct { BOOL bCheckDigitOn; BOOL bXmitCheckDigit; WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_INT25_PARAMS, *LPSCAN_INTERNAL_INT25_PARAMS;

Members bCheckDigitOn

BOOL variable that determines if the engine will read Code39 bar codes with or without check characters. If TRUE, the engine only decodes Code39 codes with a check character. If FALSE, the decoder decodes codes with or without a check character. The default value is FALSE.

bXmitCheckDigit

BOOL variable that determines if the engine will return the check character as part of the data string after a successful decode. If TRUE, the engine returns the check character. If FALSE the check character is not returned. The default value is FALSE.

dwMinLength The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value is 4. The default is 6.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 80.

SCAN_INTERNAL_MAXICODE_PARAMS

Page 81: HC700 SDK Specification

Page 81 of 680

Description

Specifies the parameters for Maxicode symbology type.

Structure Definition

typedef struct { BOOL bCarrierMsgOnly; WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_MAXICODE_PARAMS, *LPSCAN_INTERNAL_MAXICODE_PARAMS;

Members bCarrierMsgOnly

BOOL variable that determines if the engine will return only the Structured Carrier Message portion of the decoded message. When TRUE, the engine only returns the Structured Carrier Message data. When FALSE, the engine returns the entire message. The default value is FALSE.

dwMinLength The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 150.

SCAN_INTERNAL_MSI_PARAMS

Description

Specifies the parameters for Msi symbology type.

Structure Definition

typedef struct { BOOL bXmitCheckChar; WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_MSI_PARAMS, *LPSCAN_INTERNAL_MSI_PARAMS;

Members bXmitCheckChar

Page 82: HC700 SDK Specification

Page 82 of 680

BOOL variable that determines if the engine will return the check character as part of the data string after a successful decode. If TRUE, the engine returns the check character. If FALSE the check character is not returned. The default value is FALSE.

dwMinLength The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value is 4. The default is 4.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 48.

SCAN_INTERNAL_MESA_PARAMS

Description

Specifies the parameters for Mesa symbology type.

Structure Definition

typedef struct { BOOL bUMSEnabled; BOOL bEMSEnabled; BOOL b3MSEnabled; BOOL b1MSEnabled; BOOL bIMSEnabled; BOOL b9MSEnabled;

} SCAN_INTERNAL_MSI_PARAMS, *LPSCAN_INTERNAL_MSI_PARAMS;

Members bUMSEnabled

BOOL variable that contains the enabled state of UPCA Mesa. TRUE = Enabled, FALSE = Disabled.

bEMSEnabled BOOL variable that contains the enabled state of EAN13 Mesa. TRUE = Enabled, FALSE = Disabled.

b3MSEnabled BOOL variable that contains the enabled state of Code 39 Mesa. TRUE = Enabled, FALSE = Disabled.

b1MSEnabled

BOOL variable that contains the enabled state of Code 128 Mesa. TRUE = Enabled, FALSE = Disabled. bIMSEnabled

BOOL variable that contains the enabled state of Interleaved 2 of 5 Mesa. TRUE = Enabled, FALSE = Disabled.

b9MSEnabled

BOOL variable that contains the enabled state of Code 93 Mesa. TRUE = Enabled, FALSE = Disabled.

Page 83: HC700 SDK Specification

Page 83 of 680

SCAN_INTERNAL_CODE49_PARAMS

Description

Specifies the parameters for Code49 symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_CODE49_PARAMS, *LPSCAN_INTERNAL_CODE49_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 81.

SCAN_INTERNAL_MICROPDF_PARAMS

Description

Specifies the parameters for Micropdf symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_MICROPDF_PARAMS, *LPSCAN_INTERNAL_MICROPDF_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength

Page 84: HC700 SDK Specification

Page 84 of 680

The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 2750.

SCAN_INTERNAL_PDF417_PARAMS

Description

Specifies the parameters for Pdf417 symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_PDF417_PARAMS, *LPSCAN_INTERNAL_PDF417_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 2750.

SCAN_INTERNAL_CODE128_PARAMS

Description

Specifies the parameters for Code128 symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_CODE128_PARAMS, *LPSCAN_INTERNAL_CODE128_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 0.

Page 85: HC700 SDK Specification

Page 85 of 680

dwMaxLength

The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 80.

SCAN_INTERNAL_COMPOSITE_EX_PARAMS

Description

Specifies the parameters for Code128 symbology type.

Structure Definition

typedef struct { BOOL bCompositeOnUpcEan; WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_COMPOSITE_EX_PARAMS, *LPSCAN_INTERNAL_COMPOSITE_EX _PARAMS;

Members bCompositeOnUpcEan

The UPC and EAN Composite message decoding enable flag. This is enabled separately from all other Composite codes.

dwMinLength The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 300.

SCAN_INTERNAL_DATAMATRIX_PARAMS

Description

Specifies the parameters for Datamatrix symbology type.

Structure Definition

typedef struct { WORD dwMinLength;

Page 86: HC700 SDK Specification

Page 86 of 680

WORD dwMaxLength;

} SCAN_INTERNAL_DATAMATRIX_PARAMS, *LPSCAN_INTERNAL_DATAMATRIX_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 1500.

SCAN_INTERNAL_QR_PARAMS

Description

Specifies the parameters for Qr symbology type.

Structure Definition

typedef struct { WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_QR_PARAMS, *LPSCAN_INTERNAL_QR_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 3500.

SCAN_INTERNAL_RSS_PARAMS

Description

Specifies the parameters for Rss symbology type.

Structure Definition

typedef struct {

Page 87: HC700 SDK Specification

Page 87 of 680

WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_RSS_PARAMS, *LPSCAN_INTERNAL_RSS_PARAMS;

Members dwMinLength

The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 80.

SCAN_INTERNAL_CODE11_PARAMS

Description

Specifies the parameters for Code11 symbology type.

Structure Definition

typedef struct { BOOL bTwoCheckDigits; WORD dwMinLength; WORD dwMaxLength;

} SCAN_INTERNAL_CODE11_PARAMS, *LPSCAN_INTERNAL_CODE11_PARAMS;

Members bTwoCheckDigits

If TRUE, the engine only decodes Code 11 bar codes printed with two check digits. Otherwise, the engine decodes Code 11 bar codes as if they were printed with only one check digit. The default value is TRUE.

dwMinLength The minimum length decoded symbology message the engine should return. Symbology messages smaller than this minimum length are not reported by the engine. The minimum allowable value (as well as the default) is 1.

dwMaxLength The maximum length decoded symbology message the engine should return. Symbology messages larger than this maximum length are reported by the engine. The maximum allowable value (as well as the default) is 80.

Page 88: HC700 SDK Specification

Page 88 of 680

SCAN_INTERNAL_PLANET_PARAMS

Description

Specifies the parameters for Planet symbology type.

Structure Definition

typedef struct { BOOL bXmitCheckChar;

} SCAN_INTERNAL_PLANET_PARAMS, *LPSCAN_INTERNAL_PLANET_PARAMS;

Members bXmitCheckChar

BOOL variable that determines if the engine will return the check digit as part of the data string after a successful decode. If TRUE, the engine returns the check digit. If FALSE, the check digit is not returned. The default value is FALSE.

SCAN_INTERNAL_POSTNET_PARAMS

Description

Specifies the parameters for Postnet symbology type.

Structure Definition

typedef struct { BOOL bXmitCheckChar;

} SCAN_INTERNAL_POSTNET_PARAMS, *LPSCAN_INTERNAL_POSTNET_PARAMS;

Members bXmitCheckChar

BOOL variable that determines if the engine will return the check digit as part of the data string after a successful decode. If TRUE, the engine returns the check digit. If FALSE, the check digit is not returned. The default value is FALSE.

SCAN_INTERNAL_SPECIFIC_SYMBOLOGY_PARAMS

Description

Specifies the parameters for Postnet symbology type.

Structure Definition

typedef union { SCAN_INTERNAL_AZTEC_PARAMS AztecParams;

Page 89: HC700 SDK Specification

Page 89 of 680

SCAN_INTERNAL_CODABAR_PARAMS CodabarParams; SCAN_INTERNAL_CODE39_PARAMS Code39Params; SCAN_INTERNAL_CODE128_PARAMS Code128Params; SCAN_INTERNAL_CODE49_PARAMS Code49Params; SCAN_INTERNAL_CODE11_PARAMS Code11Params; SCAN_INTERNAL_EAN8_PARAMS Ean8Params; SCAN_INTERNAL_EAN13_PARAMS Ean13Params; SCAN_INTERNAL_MESA_PARAMS MesaParams; SCAN_INTERNAL_PDF417_PARAMS Pdf417Params; SCAN_INTERNAL_MICROPDF_PARAMS MicropdfParams; SCAN_INTERNAL_DATAMATRIX_PARAMS DatamatrixParams; SCAN_INTERNAL_IATA25_PARAMS Iata25Params; SCAN_INTERNAL_INT25_PARAMS Int25Params; SCAN_INTERNAL_QR_PARAMS QrParams; SCAN_INTERNAL_RSS_PARAMS RssParams; SCAN_INTERNAL_KOREAPOST_PARAMS KoreapostParams; SCAN_INTERNAL_CHINAPOST_PARAMS ChinapostParams; SCAN_INTERNAL_PLANET_PARAMS PlanetParams; SCAN_INTERNAL_POSTNET_PARAMS PostnetParams; SCAN_INTERNAL_COMPOSITE_EX_PARAMS CompositeParams; SCAN_INTERNAL_CODE93_PARAMS Code93Params; SCAN_INTERNAL_OCR_PARAMS OcrParams; SCAN_INTERNAL_MSI_PARAMS MsiParams; SCAN_INTERNAL_POSICODE_PARAMS PosicodeParams; SCAN_INTERNAL_TELEPEN_PARAMS TelepenParams; SCAN_INTERNAL_PLESSEY_PARAMS PlesseyParams; SCAN_INTERNAL_UPCA_PARAMS UpcaParams; SCAN_INTERNAL_UPCE_PARAMS UpceParams; SCAN_INTERNAL_CODABLOCK_PARAMS CodablockParams; SCAN_INTERNAL_MATRIX25_PARAMS Matrix25Params; SCAN_INTERNAL_STRT25_PARAMS Strt25Params;

Page 90: HC700 SDK Specification

Page 90 of 680

SCAN_INTERNAL_CODE16K_PARAMS Code16kParams; SCAN_INTERNAL_MAXICODE_PARAMS MaxicodeParams;

} SCAN_INTERNAL_SPECIFIC_SYMBOLOGY_PARAMS, *LPSCAN_INTERNAL_SPECIFIC_SYMBOLOGY_PARAMS;

Members AztecParams

Defines Aztec parameters.

CodabarParams Defines Codabarparameters.

Code39Params Defines Code39parameters.

Code128Params Defines Code128parameters.

Code49Params Defines Code49parameters.

Code11Params Defines Code11 parameters.

Ean8Params Defines Ean8parameters.

Ean13Params Defines Ean13parameters.

MesaParams Defines Mesa parameters.

Pdf417Params Defines Pdf417parameters.

MicroPdfParams Defines MicroPdfparameters.

DatamatrixParams Defines Datamatrixparameters.

Iata25Params Defines Iata25parameters.

Page 91: HC700 SDK Specification

Page 91 of 680

Int25Params Defines Int25 parameters.

qrParams Defines Qr parameters.

RssParams Defines Rss parameters.

KoreapostParams Defines Koreapost parameters.

chinapostParams Defines chinapost parameters.

PlanetParams Defines Planet parameters.

PostnetParams Defines Posten parameters.

CompositeParams Defines Composite parameters.

Code93Params Defines Code93parameters.

OcrParams Defines OCR parameters.

MsiParams Defines Msi parameters.

PosicodeParams Defines Posicode parameters.

TelepenParams Defines Telepen parameters.

PlesseyParams Defines Plessey parameters.

UpcaParams Defines Upca parameters.

UpceParams Defines Upce parameters.

Page 92: HC700 SDK Specification

Page 92 of 680

CodablockParams Defines Codablock parameters.

matrix25Params Defines matrix25 parameters.

Strt25Params Defines strt25 parameters.

Code16kParams Defines Code16k parameters.

MaxicodeParams Defines Maxicode parameters.

SCAN_INTERNAL_SYMBOLOGY_PARAMS

Description

Specifies the parameters for Postnet symbology type.

Structure Definition

typedef struct { DWORD SymbologyId;

SCAN_INTERNAL_SPECIFIC_SYMBOLOGY_PARAMS SpecificSymbology;

} SCAN_INTERNAL_SYMBOLOGY_PARAMS, *LPSCAN_INTERNAL_SYMBOLOGY_PARAMS;

Members SymbologyId

Specifies the symbology which parameters included at SpecificSymbology parameter.

SpecificSymbology Specifies the symbology’s.

SCAN_VERSION_INFO

Description

Page 93: HC700 SDK Specification

Page 93 of 680

The SCAN_VERSION_INFO data type holds the version information for a scanner driver. Each driver component has a major and minor version stored in the HIWORD and LOWORD respectively.

Structure Definition

typedef struct tagSCAN_VERSION_INFO

{

STRUCT_INFO StructInfo;

DWORD dwHardwareVersion;

DWORD dwDecoderVersion;

DWORD dwPddVersion;

DWORD dwMddVersion;

DWORD dwCAPIVersion;

} SCAN_VERSION_INFO;

Members StructInfo

Sub-structure describing memory allocated and used by this structure. dwHardwareVersion

The scanner hardware version. dwDecoderVersion

The decoder module version. Derived from ASCI string from the scanner. dwPddVersion

The physical device driver version. dwMddVersion

The model device driver version. dwCAPIVersion

The C API version.

SCAN_FINDINFO

Description

The SCAN_FINDINFO data type is used to enumerate available scanner devices. The structure gives information about a scanner driver available on the system.

Page 94: HC700 SDK Specification

Page 94 of 680

Structure Definition

typedef struct tagSCAN_FINDINFO

{

STRUCT_INFO StructInfo;

TCHAR szDeviceName[MAX_DEVICE_NAME];

TCHAR szPortName[MAX_DEVICE_NAME];

TCHAR szFriendlyName[MAX_PATH];

TCHAR szRegistryBasePath[MAX_PATH];

} SCAN_FINDINFO;

Members StructInfo

Sub-structure describing memory allocated and used by this structure. szDeviceName

The name of the scanner device. This name is used in SCAN_Open to obtain a handle to the scanner driver.

szPortName

The name of the serial port used by the driver, if any. szFriendlyName

User readable name for the scanner driver. szRegistryBasePath

Registry path of this driver’s registry entries.

SCAN_BUFFER Description The SCAN_BUFFER data type holds information describing a completed read request. The scan data is stored in a buffer starting immediately after this structure and described by dwDataBuffSize and dwOffsetDataBuff.

Page 95: HC700 SDK Specification

Page 95 of 680

Structure Definition typedef struct tagSCAN_BUFFER

{

STRUCT_INFO StructInfo;

DWORD dwDataBuffSize;

DWORD dwOffsetDataBuff;

DWORD dwDataLength;

DWORD dwTimeout;

DWORD dwStatus;

BOOL bText;

LABELTYPE dwLabelType;

DWORD dwRequestID;

SYSTEMTIME TimeStamp;

DWORD dwDirection;

TCHAR szSource[MAX_SRC];

} SCAN_BUFFER;

Members StructInfo

Sub-structure describing memory allocated and used by this structure. dwDataBuffSize

Size of data buffer in bytes. dwOffsetDataBuff

Offset from start of this structure to the data buffer. dwDataLength

Length of the data placed into the data buffer. dwTimeout

Read timeout in milliseconds. A value of 0 means infinite timeout. dwStatus

Status of the read request. The value is:

E_SCN_SUCCESS if successfully completed E_SCN_DEVICEFAILURE if the scanner failed E_SCN_READPENDING if still pending E_SCN_READCANCELLED if canceled, or some other error if appropriate.

Page 96: HC700 SDK Specification

Page 96 of 680

bText

Flag telling if the data is text or binary. dwLabelType

LABELTYPE of the bar code if successfully read. dwRequestID

Request ID assigned to the read. Since the scanner driver supports only one opening ,this parameter has no meaning. TimeStamp

System time when the read completed. dwDirection

Direction the label was scanned: DIR_FORWARD ( =1 ) means scanned in the forward direction. DIR_REVERSE ( =2 ) means scanned in the reverse direction.

szSource[MAX_SRC] String containing the scanner name followed by a human readable form of the label type (i.e. "SCN1:UPCE0" )

Remarks macros to access the SCAN_BUFFER structure easier:

SCNBUF_ALLOC(size) – Allocates a SCAN_BUFFER with a data buffer of size size.

SCNBUF_GETDATA(ptr) – Returns a BYTE pointer to the data buffer following the SCAN_BUFFER pointed to by ptr.

SCNBUF_GETSTAT(ptr) – Returns the status of the SCAN_BUFFER pointed to by ptr.

SCNBUF_GETREQID(ptr) – Returns the request ID of the SCAN_BUFFER pointed to by ptr.

SCNBUF_GETSRC(ptr) – Returns the source string of the SCAN_BUFFER pointed to by ptr.

SCNBUF_GETLBLTYP(ptr) – Returns the label type of the SCAN_BUFFER pointed to by ptr.

SCNBUF_GETTIMEOUT(ptr) – Returns the read timeout of the SCAN_BUFFER pointed to by ptr.

SCNBUF_GETSIZE(ptr) – Returns the size of the data buffer following the SCAN_BUFFER pointed to by ptr.

SCNBUF_GETOFFSET(ptr) – Returns the offset to the data buffer following the SCAN_BUFFER pointed to by ptr.

SCNBUF_ISTEXT(ptr) – Returns the text flag of the SCAN_BUFFER pointed to by ptr

SCNBUF_GETLEN(ptr) – Returns the data length of the SCAN_BUFFER pointed to by ptr.

SCAN_STATUS

Description

The SCAN_STATUS structure contains the status of the scan driver.

Structure Definition

typedef struct tagSCAN_STATUS

Page 97: HC700 SDK Specification

Page 97 of 680

{

STRUCT_INFO StructInfo;

BOOL bEnabled;

DWORD dwStatus;

DWORD dwKlasseEinsTimeUsed;

DWORD dwKlasseEinsTimeLeft;

} SCAN_STATUS;

Members StructInfo

Sub-structure describing memory allocated and used by this structure. bEnabled

Flag telling enable status of the scanner. dwStatus

Describes the status of the scan driver. Possible values are:

SCAN_STATUS_STOPPED ( = 1 ) – Scanner is not enabled; SCAN_STATUS_IDLE ( = 2 ) – Scanner is enabled but no reads are pending; SCAN_STATUS_WAITING ( = 3 ) – The scanner is waiting to complete its current operation .SCAN_STATUS_SCANNING ( = 4 ) – Beam is on and acquiring data; SCAN_STATUS_AIMING ( = 5 ) – Beam is on for aiming; (Not supported) SCAN_STATUS_EMPTY ( = 6 ) – Beam is off waiting for Klasse Eins Gas Tank to recover. (Not supported) dwKlasseEinsTimeUsed

Klasse Eins time used in milliseconds. Not supported

dwKlasseEinsTimeLeft

Klasse Eins time left in milliseconds. Not supported

LABELTYPE

Description

The LABELTYPE data type defines a type of bar code label that can be returned from a successful read request. Each label type can be decoded by one or more DECODERs. The individual label types are defined as follows.

Page 98: HC700 SDK Specification

Page 98 of 680

Structure Definition

typedef DWORD LABELTYPE;

typedef LABELTYPE FAR LPLABELTYPE;

#define LABELTYPE_UPCE0 0x30

#define LABELTYPE_UPCE1 0x31

#define LABELTYPE_UPCA 0x32

#define LABELTYPE_MSI 0x33

#define LABELTYPE_EAN8 0x34

#define LABELTYPE_EAN13 0x35

#define LABELTYPE_CODABAR 0x36

#define LABELTYPE_CODE39 0x37

#define LABELTYPE_D2OF5 0x38

#define LABELTYPE_I2OF5 0x39

#define LABELTYPE_CODE11 0x3A

#define LABELTYPE_CODE93 0x3B

#define LABELTYPE_CODE128 0x3C

#define LABELTYPE_IATA2OF5 0x3E

#define LABELTYPE_EAN128 0x3F

#define LABELTYPE_PDF417 0x40

#define LABELTYPE_ISBT128 0x41

#define LABELTYPE_TRIOPTIC39 0x42

#define LABELTYPE_COUPON 0x43

#define LABELTYPE_BOOKLAND 0x44

#define LABELTYPE_MICROPDF 0x45

#define LABELTYPE_CODE32 0x46

#define LABELTYPE_UNKNOWN 0xFF

#define LABELTYPE_AZTEC 0x60

#define LABELTYPE_MESA 0x61

#define LABELTYPE_CODE49 0x62

#define LABELTYPE_COMPOSITE 0x63

#define LABELTYPE_DATAMATRIX 0x64

#define LABELTYPE_MAXICODE 0x65

Page 99: HC700 SDK Specification

Page 99 of 680

#define LABELTYPE_OCR 0x66

#define LABELTYPE_POSTNET 0x67

#define LABELTYPE_QR 0x68

#define LABELTYPE_RSS 0x69

#define LABELTYPE_BPO 0x6A

#define LABELTYPE_CANPOST 0x6B

#define LABELTYPE_AUSPOST 0x6C

#define LABELTYPE_CODABLOCK 0x6D

#define LABELTYPE_JAPOST 0x6E

#define LABELTYPE_PLANET 0x6F

#define LABELTYPE_DUTCHPOST 0x70

#define LABELTYPE_TLCODE39 0x71

#define LABELTYPE_STRT25 0x72

#define LABELTYPE_MATRIX25 0x73

#define LABELTYPE_PLESSEY 0x74

#define LABELTYPE_CHINAPOST 0x75

#define LABELTYPE_KOREAPOST 0x76

#define LABELTYPE_TELEPEN 0x77

#define LABELTYPE_CODE16K 0x78

#define LABELTYPE_POSICODE 0x79

#define LABELTYPE_USPS4CB 0x7A

#define LABELTYPE_IDTAG 0x7B

#define LABELTYPE_ALL 0x100

SCAN_EVENT Description

The SCAN_EVENT data type is used to describe an event that can occur in the scan driver. These events are passed to an application that has registered via the SCAN_RegisterScan Message function. The event code is passed as the wParam parameter of the window message, and an event-specific value is passed as the lParam parameter.

Structure Definition

enum tagSCAN_EVENT_CODE {

Page 100: HC700 SDK Specification

Page 100 of 680

SCAN_EVENT_ERROR = 0, SCAN_EVENT_STATE_CHANGE, SCAN_EVENT_ACTIVITY, SCAN_EVENT_IMAGE_CAPTURE, SCAN_EVENT_IMAGE_ERROR, SCAN_EVENT_START_SEQUENCE, SCAN_EVENT_SEQUENCE_CONTINUE, SCAN_EVENT_SEQUENCE_FAIL, SCAN_EVENT_SEQUENCE_ERROR, };

Members

SCAN_EVENT_ERROR

An error occurred while trying to wait for an event.

SCAN_EVENT_STATE_CHANGE

The state of the scan driver has changed. The lParam parameter contains the current state (dwStatus).

dwStatus describes the status of the scan driver. Possible values are:

SCAN_STATUS_STOPPED ( = 1 ) - Scanner is not enabled; SCAN_STATUS_IDLE ( = 2 ) - Scanner is enabled but no reads are pending; SCAN_STATUS_WAITING ( = 3 ) - One or more reads are pending, waiting for trigger event; SCAN_STATUS_SCANNING ( = 4 ) - Beam is on and acquiring data; SCAN_STATUS_AIMING ( = 5 ) - Beam is on for aiming; (Not supported) SCAN_STATUS_EMPTY (= 6) - Beam is off waiting for Klasse Eins Gas Tank to recover. (Not supported.)

SCAN_EVENT_ACTIVITY

The scanner driver is busy / active. This event is used for image downloading activity and 2D hand-raster activity. This event is only sent to the open scanner that causes the event. The lParam parameter contains the dwRequestID for the corresponding read, or zero (0) if not applicable.

Not supported.

SCAN_EVENT_IMAGE_CAPTURE

The PDD has captured an image and begun download. This event is only sent to the open scanner that submitted the read, and the lParam parameter contains the dwRequestID of that read.

Not supported.

SCAN_EVENT_IMAGE_ERROR

The PDD has encountered a fatal error downloading an image. This event is only sent to the open scanner that submitted the read, and the lParam parameter contains the dwRequestID of that read.

Not supported

SCAN_EVENT_START_SEQUENCE

The MDD has captured the first barcode in a concatenation sequence. This event is only sent to the open scanner that submitted the read, and the lParam parameter contains the dwRequestID of that read.

Not supported.

Page 101: HC700 SDK Specification

Page 101 of 680

SCAN_EVENT_SEQUENCE_CONTINUE

The MDD has captured another barcode in a concatenation sequence. This event is only sent to the open scanner that submitted the read, and the lParam parameter contains the dwRequestID of that read.

Not supported.

SCAN_EVENT_SEQUENCE_FAIL

The MDD has encountered a fatal concatenation error. This event is only sent to the open scanner that submitted the read, and the lParam parameter contains the dwRequestID of that read.

Not supported.

SCAN_EVENT_SEQUENCE_ERROR

The MDD has encountered a non-fatal concatenation error. This event is only sent to the open scanner that submitted the read, and the lParam parameter contains the dwRequestID of that read. Not supported.

DECODER_PARAMS Description

The DECODER_PARAMS structure holds the parameters for one DECODER type. Decoder specific parameters are stored in the dec_specific substructure defined by cDecoder.

Structure Definition

typedef struct tagDECODER_PARAMS

{

STRUCT_INFO StructInfo;

DECODER cDecoder;

DWORD dwMinLength;

DWORD dwMaxLength;

DECODER_SPECIFIC dec_specific;

Page 102: HC700 SDK Specification

Page 102 of 680

} DECODER_PARAMS

Members StructInfo

Sub-structure describing memory allocated and used by this structure. cDecoder

DECODER type which tells which decoder these parameters apply to. This value determines the structure of the dec_specific sub-structure.

dwMinLength

The minimum allowable decode length. See remarks below. dwMaxLength

The maximum allowable decode length. See remarks below. dec_specific

Sub-structure containing decoder specific parameters. See remarks below. Remarks

Allowable decode lengths are specified by dwMinLength and dwMaxLength as follows:

Variable length – dwMinLength = dwMaxLength = 0

Range (from a to b, including a and b) – dwMinLength = a, dwMaxLength = b

Two Discrete Lengths (either a or b, given a<b) – dwMinLength = b, dwMaxLength = a

One Discrete Length (only a) – dwMinLength = dwMaxLength = a

The valid range of lengths differs for each decoder type:

Fixed length codes (DECODER_UPCE0, DECODER_UPCE1, DECODER_UPCA, DECODER_EAN8, DECODER_EAN13, and DECODER_TRIOPTIC39) only accept dwMinLength = dwMaxLength = 0.

DECODER_PDF accepts lengths ranging from 0 to 2710.

All Postal codes (DUTCH, US, UK, JAPANESE, AUSTRALIA) are not fixed length codes. Their length must be 0 for these symbologies.

The DECODER_CODE128 accept lenghts ranging from 0 to 55 and it may not be changed

All other decoder types accept lengths ranging from 0 to 55.

The dec_specific sub-structure holds parameters for one decoder type. The structure of dec_specific depends on the DECODER type in cDecoder. The DECODER_SPECIFIC structure is defined as follows:

typedef union tagDECODER_SPECIFIC

{

Page 103: HC700 SDK Specification

Page 103 of 680

DWORD dwUntyped[20];

UPCE0_PARAMS upce0_params;

UPCE1_PARAMS upce1_params;

UPCA_PARAMS upca_params;

MSI_PARAMS msi_params;

EAN8_PARAMS ean8_params;

CODABAR_PARAMS codabar_params;

CODE39_PARAMS code39_params;

D2OF5_PARAMS d2of5_params;

I2OF5_PARAMS i2of5_params;

CODE11_PARAMS code11_params;

CODE93_PARAMS code93_params;

CODE128_PARAMS code128_params;

TRIOPTIC39_PARAMS trioptic39_params;

} DECODER_SPECIFIC;

NOTE: The functions SCAN_GetDecoderParams/ SCAN_SetDecoderParams support setting/getting parameters for the following decoders:

DECODER_CODABAR, DECODER_CODE39, DECODER_I2OF5, DECODER_CODE93, DECODER_CODE128

CODABAR_PARAMS

Description

The CODABAR_PARAMS structure holds the CODABAR specific parameters. These parameters control the decoding and processing of CODABAR bar codes.

Structure Definition

typedef struct tagCODABAR_PARAMS

{

BOOL bRedundancy;

BOOL bClsiEditing;

BOOL bNotisEditing;

Page 104: HC700 SDK Specification

Page 104 of 680

} CODABAR_PARAMS;

Members bRedundancy

Flag to enable redundancy. If this flag is set, the bar code must be decoded twice before being accepted.

Note: This flag is only considered if LASER_SPECIFIC.dwLinearSecurityLevel = SECURITY_REDUNDANCY_AND_LENGTH ( = 0 )

Not supported

bClsiEditing Flag to enable CLSI formatting.

bNotisEditing Flag to enable NOTIS formatting.

CODE39_PARAMS

Description

The CODE39_PARAMS structure holds the CODE39 specific parameters. These parameters control the decoding and processing of CODE39 bar codes.

Structure Definition

typedef struct tagCODE39_PARAMS

{

BOOL bVerifyCheckDigit;

BOOL bReportCheckDigit;

BOOL bConcatenation;

BOOL bFullAscii;

BOOL bRedundancy;

Page 105: HC700 SDK Specification

Page 105 of 680

BOOL bConvertToCode32;

BOOL bCode32Prefix;

} CODE39_PARAMS;

Members bVerifyCheckDigit

Flag to enable verification of the bar code check digit. bReportCheckDigit

Flag to enable reporting the bar code check digit. bConcatenation

Flag to enable Code 39 bar code concatenation. –The HC700 scan engine does not support this option.

bFullAscii

Flag to enable full ASCII conversion of the bar code. bRedundancy

Flag to enable redundancy. If this flag is set, the bar code must be decoded twice before being accepted.

Note: This flag is only considered if LASER_SPECIFIC.dwLinearSecurityLevel = SECURITY_REDUNDANCY_AND_LENGTH ( = 0 ).

Not supported

bConvertToCode32 Flag to enable conversion of Code 39 bar codes to Code 32.

bCode32Prefix

Flag to enable reporting the Code 32 prefix when a Code 39 bar code is converted.

I2OF5_PARAMS

Description

The I2OF5_PARAMS structure holds the I2OF5 specific parameters. These parameters control the decoding and processing of I2OF5 bar codes.

Structure Definition

typedef struct tagI2OF5_PARAMS

{

Page 106: HC700 SDK Specification

Page 106 of 680

BOOL bRedundancy;

DWORD dwVerifyCheckDigit;

BOOL bReportCheckDigit;

BOOL bConvertToEAN13;

} I2OF5_PARAMS;

Members

bRedundancy

Flag to enable redundancy. If this flag is set, the bar code must be decoded twice before being accepted.

Note: This flag is only considered if LASER_SPECIFIC.dwLinearSecurityLevel = SECURITY_REDUNDANCY_AND_LENGTH ( = 0 ).

Not supported dwVerifyCheckDigit

Describes the check digit type to verify. Possible values are:

I2OF5_NO_CHECK_DIGIT ( = 0 ) – no check digit; I2OF5_USS_CHECK_DIGIT ( = 1 ) – USS check digit; I2OF5_OPCC_CHECK_DIGIT ( = 2 ) – OPCC check digit.

bReportCheckDigit Flag to enable reporting the bar code check digit.

bConvertToEAN13 Flag to enable conversion from I2OF5 to EAN13 bar code. If this flag is set, the bar code is converted to EAN13, and EAN13 parameters are used.

CODE93_PARAMS

Description

The CODE93_PARAMS structure holds the CODE93 specific parameters. These parameters control the decoding and processing of CODE93 bar codes.

Structure Definition

typedef struct tagCODE93_PARAMS

{

BOOL bRedundancy;

Page 107: HC700 SDK Specification

Page 107 of 680

} CODE93_PARAMS;

Members bRedundancy

Flag to enable redundancy. If this flag is set, the bar code must be decoded twice before being accepted.

Note: This flag is only considered if LASER_SPECIFIC.dwLinearSecurityLevel = SECURITY_REDUNDANCY_AND_LENGTH ( = 0 ).

Not supported .

CODE128_PARAMS

Description

The CODE128_PARAMS structure holds the CODE128 specific parameters. These parameters control the decoding and processing of CODE128 bar codes.

Structure Definition

typedef struct tagCODE128_PARAMS

{ BOOL bRedundancy; BOOL bEAN128; BOOL bISBT128; BOOL bOther128;

} CODE128_PARAMS;

Members bRedundancy

Flag to enable redundancy. If this flag is set, the bar code must be decoded twice before being accepted.

Note: This flag is only considered if LASER_SPECIFIC.dwLinearSecurityLevel = SECURITY_REDUNDANCY_AND_LENGTH ( = 0 ).

Not supported .

Page 108: HC700 SDK Specification

Page 108 of 680

bEAN128

Flag to enable EAN128 subtype. bISBT128

Flag to enable ISBT128 subtype. bOther128

Flag to enable other (non EAN or ISBT) 128 subtype. Remarks

At least one subtype must be enabled. The default is all subtypes enabled.

DEVICE_INFO

Description The DEVICE_INFO structure holds information describing the capabilities of a remote imager.

Structure Definition

typedef struct tagDEVICE_INFO

{ STRUCT_INFO StructInfo; DECODERS Decoders; BOOL bBeamWidth; BOOL bAimMode; BOOL bDirection; BOOL bFeedback; } DEVICE_INFO;

Members StructInfo

Sub-structure describing memory allocated and used by this structure. Decoders

List of decoders supported by this device. See DECODER_LIST. bBeamWidth

Flag telling if the device supports narrow beam width. bAimMode

Flag telling if the device supports aiming.

Page 109: HC700 SDK Specification

Page 109 of 680

bDirection

Flag telling if the device supports scan direction reporting. bFeedback

Flag telling if the device supports remote (non-local) feedback.

DECODER_LIST

Description

The DECODER_LIST structure holds a list of DECODER types. It is used for listing enabled and supported decoders.

Structure Definition

typedef struct tagDECODER_LIST

{

STRUCT_INFO StructInfo;

DECODERS Decoders;

}DECODER_LIST;

Members StructInfo

Sub-structure describing memory allocated and used by this structure. Decoders

A list of DECODER types. See remarks below. Remarks

The Decoders field contains a DECODERS structure. This structure holds a list of decoders and is defined as follows:

typedef struct tagDECODERS

{

DWORD dwDecoderCount;

Page 110: HC700 SDK Specification

Page 110 of 680

BYTE byList[DECODERS_BUFLEN];

} DECODERS;

The dwDecoderCount field holds the number of decoders in the byList field. The byList field is a byte array of decoders. The DECODER type is defined as a two-character array. It can also be considered a one-character, null terminated ASCII string. Several DECODER types can be combined into a longer string consisting of one byte per DECODER and a terminating NULL character. The one-byte DECODER representation is equivalent to the LABELTYPE definition. The byList field can be considered an array of LABELTYPE values corresponding to DECODER types. For example:

byList = 34 40 00

Corresponds to a list consisting of DECODER_EAN8 (34) and DECODER_PDF417 (40).

The following LABELTYPES values are supported in SE-923 :

LABELTYPE_CODE39; LABELTYPE_TRIOPTIC39; LABELTYPE_CODABAR; LABELTYPE_CODE128; LABELTYPE_I2OF5; LABELTYPE_CODE93; LABELTYPE_D2OF5; LABELTYPE_UPCA; LABELTYPE_UPCE0; LABELTYPE_EAN8; LABELTYPE_EAN13; LABELTYPE_MSI; LABELTYPE_UPCE1; LABELTYPE_BOOKLAND; LABELTYPE_COUPON; LABELTYPE_PDF417

SCAN_PARAMS

Description The SCAN_PARAMS structure defines scan type and post-read-completion activities. Structure Definition

typedef struct tagSCAN_PARAMS

{ STRUCT_INFO StructInfo;

DWORD dwCodeIdType;

DWORD dwScanType;

BOOL bLocalFeedback;

DWORD dwDecodeBeepTime;

DWORD dwDecodeBeepFrequency;

Page 111: HC700 SDK Specification

Page 111 of 680

DWORD dwDecodeLedTime;

TCHAR szWaveFile[MAX_PATH];

DWORD dwStartBeepTime;

DWORD dwStartBeepFrequency;

DWORD dwStartLedTime;

TCHAR szStartWaveFile[MAX_PATH];

DWORD dwIntermedBeepTime;

DWORD dwIntermedBeepFrequency;

DWORD dwIntermedLedTime;

TCHAR szIntermedWaveFile[MAX_PATH];

DWORD dwFatalBeepTime;

DWORD dwFatalBeepFrequency;

DWORD dwFatalLedTime;

TCHAR szFatalWaveFile[MAX_PATH];

DWORD dwNonfatalBeepTime;

DWORD dwNonfatalBeepFrequency;

DWORD dwNonfatalLedTime;

TCHAR szNonfatalWaveFile[MAX_PATH];

DWORD dwActivityBeepTime;

DWORD dwActivityBeepFrequency;

DWORD dwActivityLedTime;

TCHAR szActivityWaveFile[MAX_PATH];

} SCAN_PARAMS; Members StructInfo

Sub-structure describing memory allocated and used by this structure. dwCodeIdType

Describes the type of Code ID to be reported. Possible values are:

CODE_ID_TYPE_NONE ( = 0 ) – no code ID; CODE_ID_TYPE_SYMBOL ( = 1 ) – Symbol Technologies code ID; CODE_ID_TYPE_AIM ( = 2 ) – AIM code ID.

dwScanType

Describes the type of scan request. Possible values are:

SCAN_TYPE_FOREGROUND ( = 0 ) – foreground read; SCAN_TYPE_BACKGROUND ( = 1 ) – background read; SCAN_TYPE_MONITOR ( = 2 ) – monitor read.

Page 112: HC700 SDK Specification

Page 112 of 680

This parameters is not supported

bLocalFeedback

Flag to enable local feedback. If reset, feedback is only done on the scanner device. This parameters is not supported

dwDecodeBeepTime Flag to enable beep upon successful decode. Possible values are: Enable (=1) Disable(=0)

dwDecodeBeepFrequency

Frequency to beep upon successful decode. Possible values are: HIGH (= 0) MEDIUM( =1) LOW(=2

dwDecodeLedTime

Time to light decode LED upon successful decode. This parameters is not supported szWaveFile

Name of .WAV file to play as feedback upon successful decoding.

szErrorWaveFile Name of .WAV file to play as feedback upon NOT successful decoding.

SCAN_IMAGE_PARAMS

Description The SCAN_IMAGE_PARAMS structure defines the properties of image to be taked by SCAN_GetImage function. Structure Definition

typedef struct

{ WORD wImageTop;

WORD wImageLeft;

WORD wImageRight;

Page 113: HC700 SDK Specification

Page 113 of 680

WORD wImageBottom;

WORD wSkipPizel;

WORD wImageDepth;

SCAN_IMAGE_FORMAT ImageFormat;

WORD wWhiteValue;

WORD wExposureAttempts;

WORD wGap;

BOOL bInvertImage;

DWORD dwReserved1;

DWORD dwReserved2;

} SCAN_IMAGE_PARAMS; Members wImageTop , wImageLeft

Coordinates relative to the image engine's pixel grid for first pixel of the transferred image. The upper left pixel has both an nLeft and an nTop value of 0.

wImageRight , wImageBottom

Coordinates relative to the image engine's pixel grid for last pixel of the transferred image. wSkipPizel

When transferring an image, transfer every nSkip pixel.

wImageDepth The color depth for the transferred image. Valid values are typically only 8 or 1, but this depends on the engine hardware. Independent of the bits used, a lower value is darker than a higher value. For example, if 8 bits are chosen, then a pixel value of 255 indicates pure white, and a pixel value of 0 indicates pure black. Values in between are to be interpreted as incremental levels of gray. Actually only the value of 8 is supported.

ImageFormat Specifies the desired image format. Only two formats supported for SCAN_GetImage function: SCAN_FORMAT_RAW_BINARY and SCAN_FORMAT_RAW_GRAY. wWhiteValue

The target white value when performing auto exposure control.

wExposureAttempts The number of attempts the unit makes to get the image to the correct exposure level.

wGap How close the white value of the image must be to the nWhiteValue for the image to be accepted. A value of 0 (zero) can be passed in to cause the unit to use its pre-defined value. For example, if you want to use 10 for the nGap, and the default value for nWhiteValue, then pass in 10 for nGap, and 0 for nWhite.

bInvertImage The image is rotated 180° (upside down). This allows you to invert images for platforms where the imager is mounted upside down.

dwReserved1, dwReserved2 Reserved. Must be NULL

Page 114: HC700 SDK Specification

Page 114 of 680

SCAN_IMAGE_FORMAT Description

The SCAN_IMAGE_FORMAT enumerator defines the list of supported image formats.

Structure Definition

typedef enum

{

SCAN_FORMAT_RAW_BINARY = 0 ,

SCAN_FORMAT_RAW_GRAY ,

SCAN_FORMAT_TIFF_BINARY ,

SCAN_FORMAT_TIFF_COMPRESSED ,

SCAN_FORMAT_TIFF_GRAY ,

SCAN_FORMAT_JPEG_GRAY ,

SCAN_FORMAT_BMP_GRAY

} SCAN_IMAGE_FORMAT;

Members SCAN_FORMAT_RAW_BINARY

Raw binary image format. Only white and black pixels present on unformatted image.

SCAN_FORMAT_RAW_GRAY Raw gray image format. The grayscale pixels present on unformatted image.

SCAN_FORMAT_TIFF_BINARY Tiff format image file. Only white and black pixels present.

SCAN_FORMAT_TIFF_COMPRESSED Tiff format image compressed file. Only white and black pixels present.

SCAN_FORMAT_TIFF_GRAY Tiff format image file. The grayscale pixels present on image data.

SCAN_FORMAT_JPEG_GRAY Jpeg format image file. The grayscale pixels present on image data.

SCAN_FORMAT_BMP_GRAY Bmp format image file. The grayscale pixels present on image data.

SCAN_IS_IMAGE_PRESENT Description

The SCAN_IS_IMAGE_PRESENT enumerates the result values for SCAN_IsImagePresent function.

Structure Definition

typedef enum

{

Page 115: HC700 SDK Specification

Page 115 of 680

SCAN_IMAGE_PRESENTED ,

SCAN_IMAGE_NOT_PRESENTED ,

} SCAN_IS_IMAGE_PRESENT;

Members SCAN_IMAGE_PRESENTED

Provided image meets blacness requirement SCAN_IMAGE_NOT_PRESENTED

Provided image does not meet blacness requirement SCAN_IS_IMAGE_PRESENT_PARAMS Description

The SCAN_IS_IMAGE_PRESENT_PARAMS defines parameters for SCAN_IsImagePresent function.

Structure Definition

typedef struct

{

DWORD dwImgWidth;

DWORD dwImgHeight;

DWORD dwImgDepth;

DWORD dwMinBlack;

LPBYTE lpImgData;

DWORD dwReserved;

} SCAN_IS_IMAGE_PRESENT_PARAMS;

Members dwImgWidth

The width of the image provided by lpImgData in pixels.

dwImgHeight The height of the image provided by lpImgData in pixels.

dwImgDepth The depth of the image provided by lpImgData. Only value of 1 is supported

lpImgData

The image data array for which this check is required

SCAN_IMAGE_DATA Description

The SCAN_IMAGE_DATA structure contains an captured image.

Structure Definition

Page 116: HC700 SDK Specification

Page 116 of 680

typedef struct

{

DWORD dwStructSize;

DWORD dwImageHeight;

DWORD dwImageWidth;

SCAN_IMAGE_FORMAT ImageFormat;

DWORD dwImageDataOffset;

DWORD dwImageDataSize;

} SCAN_IMAGE_DATA;

Members dwStructSize

Equal to the size of this structure in bytes. dwImageHeight

The height of resulting image in pixels. dwImageWidth

The width of resulting image in pixels. ImageFormat

Image data format. dwImageDataOffset

The offset that defines where the image data starts after SCAN_IMAGE_DATA buffer from the beginning of the structure.

dwImageDataSizet The size of image data.

SCAN_IQ_IMG_PARAMS Description

The SCAN_IQ_IMG_PARAMS structure contains parameters for capturing intelliligent image.

Structure Definition

typedef struct

{

DWORD dwAspectRatio;

int nCenterXoffset;

int nCenterYoffset;

DWORD dwImageHeight;

DWORD dwImageWidth;

DWORD dwResolution;

DWORD dwReserved1;

DWORD dwReserved2;

SCAN_IMAGE_FORMAT SignatureFormat;

Page 117: HC700 SDK Specification

Page 117 of 680

} SCAN_IQ_IMG_PARAMS;

Members dwAspectRatio

This number defines the coefficient that must be multiplied to the intelligent barcode unit size to get the height of the barcode label. The intelligent barcode unit size is the width of the narrowest bar in the barcode.

nCenterXoffset The offset (in intelligent barcode units) on X of desired image’s center from the center of the barcode label.

nCenterYoffset The offset (in intelligent barcode units) on Y of desired image’s center from the center of the barcode label.

dwImageHeight The height of desired image in intelligent barcode units.

dwImageWidth The width of desired image in intelligent barcode units.

dwResolution The number of pixels per intelligent barcode unit.

SignatureFormat

Defines the format of signature image to acquire (SCAN_FORMAT_RAW_BINARY or SCAN_FORMAT_RAW_GRAY).

SCAN_IMG_ROI_PARAMS Description

The SCAN_IMG_ROI_PARAMS structure contains parameters for capturing intelliligent image.

Structure Definition

typedef struct

{

DWORD dwXdimension;

DWORD dwBarcodeHeight;

int XDistanceFromCenterBarcodeToCenterROI;

int YDistanceFromCenterBarcodeToCenterROI;

DWORD dwRoiWidth;

DWORD dwRoiHeight;

DWORD dwNaturalDpi;

DWORD dwRoiDpi;

DWORD dwRoiWidthInPixels;

DWORD dwRoiHeightInPixels;

int ZoomLimit;

SCAN_IMAGE_FORMAT SignatureFormat;

} SCAN_IMG_ROI_PARAMS;

Page 118: HC700 SDK Specification

Page 118 of 680

Members xDimension

Defines width of nominal (1X) X dimension in 1000s of mils, best measured by taking using bar/space pair / 2 to compensate for ink spread..

dwBarcodeHeight Barcode height in mils. (1000 mils = 1 inch)

XDistanceFromCenterBarcodeToCenterROI The delta distance in mils.

YDistanceFromCenterBarcodeToCenterROI The delta distance in mils.

dwRoiWidth The width of desired image in mils.

dwRoiHeight The height of desired image in mils.

dwNaturalDpi The real DPI value of source image retrieved before interpolation (zooming) operation.

dwRoiDpi DPI value required for image to be retuned.

If this value is not equal to 0, the resulting image will have dwRoiDpi DPI but its sizes in mils will not be equal to dwRoiWidth and dwRoiHeight. If this value is equal to 0, the resulting image will be of size dwRoiWidthInPixels * dwRoiHeightInPixels. dwRoiWidthInPixels

This value definethe width of the image to be retuned in pixels when dwRoiDpi is equal to 0.. dwRoiHeightInPixels

This value define the height of the image to be retuned in pixels when dwRoiDpi is equal to 0.. ZoomLimit

Limits the amount of interpolation to be done (effectively limits DOF) to maintain a certain quality of image. Note ZoomLimit of 0 and 1 are unreasonable in most applications and even 2 will likely unnecessarily limit performance. Recommended values are 3 to 4 as minimum..

SignatureFormat Defines the format of signature image to acquire (SCAN_FORMAT_RAW_BINARY or SCAN_FORMAT_RAW_GRAY).

Page 119: HC700 SDK Specification

Page 119 of 680

Barcode Reader API Return Values

E_SCN_SUCCESS 0x0 The function completed successfully E_SCN_OPENINGACTIVEKEY 0xA0000001 An error occurred opening the active driver registry key. E_SCN_READINGACTIVEKEY 0xA0000002 An error occurred reading the active driver registry key.

E_SCN_OPENINGPARAMKEY 0xA0000003 An error occurred opening the registry key containing the driver's settings.

E_SCN_READINGPARAMKEY 0xA0000004 An error occurred reading the registry key containing the driver's settings.

E_SCN_NOTENOUGHMEMORY 0xA0000005 An attempt to allocate memory failed. E_SCN_INVALIDDVCCONTEXT 0xA0000006 An invalid device context ID was used. E_SCN_INVALIDOPENCONTEXT 0xA0000007 An attempt was made to access an invalid open context. E_SCN_NOTINITIALIZED 0xA0000008 The driver was accessed before a successful initialization. E_SCN_CANTLOADDEVICE 0xA0000009 The physical device driver (PDD) could not be loaded.

E_SCN_INVALIDDEVICE 0xA000000A The physical device driver (PDD) DLL did not contain the required entry points.

E_SCN_DEVICEFAILURE 0xA000000B Required device is not present, already in use or not functioning properly.

E_SCN_CANTSTARTDEVICE 0xA000000C The device could not be started.

E_SCN_CANTGETDEFAULTS 0xA000000D The default parameters could not be obtained from the physical device driver (PDD).

E_SCN_NOTSTARTED 0xA000000E An attempt was made to use or stop the scanner device and it was not started.

E_SCN_ALREADYSTARTED 0xA000000F An attempt was made to start the device when the device was already started.

E_SCN_NOTENABLED 0xA0000010 An attempt was made to access the scanner device and it was not enabled.

E_SCN_ALREADYENABLED 0xA0000011 An attempt was made to enable scanning when scanning was already enabled.

E_SCN_INVALIDIOCTRL 0xA0000012 The control code passed to DeviceIoControl is invalid. E_SCN_NULLPTR 0xA0000013 A NULL pointer was passed for a required argument. E_SCN_INVALIDARG 0xA0000014 A passed argument is out of range.

E_SCN_BUFFERSIZEIN 0xA0000015 The size of the buffer passed as an input to DeviceIoControl is less than sizeof(STRUCT_INFO) or is less than the size specified in StructInfo.dwUsed.

E_SCN_BUFFERSIZEOUT 0xA0000016 The size of the buffer passed as an output to DeviceIoControl is less than sizeof(STRUCT_INFO) or is less than the size specified in StructInfo.dwAllocated.

E_SCN_STRUCTSIZE 0xA0000017 A STRUCT_INFO structure field is invalid. Either dwAllocated or dwUsed is less than the size of STRUCT_INFO or dwUsed is greater than dwAllocated.

E_SCN_MISSINGFIELD 0xA0000018 The size of a structure specified in a StructInfo is too small to contain a required field.

Page 120: HC700 SDK Specification

Page 120 of 680

E_SCN_INVALIDHANDLE 0xA0000019 An invalid handle was passed to a function.

E_SCN_INVALIDPARAM 0xA000001A The value of a parameter either passed as an argument to a function or as a member of a structure is out of range or conflicts with other parameters.

E_SCN_CREATEEVENT 0xA000001B Unable to create a required event. E_SCN_CREATETHREAD 0xA000001C Unable to create a required thread. E_SCN_READCANCELLED 0xA000001D A read request was cancelled. E_SCN_READTIMEOUT 0xA000001E A read request timed out. E_SCN_READNOTPENDING 0xA000001F Attempt to cancel a read that is not pending. E_SCN_READPENDING 0xA0000020 Attempt to start a read when one is pending. E_SCN_BUFFERTOOSMALL 0xA0000021 Data buffer is too small for incoming data. E_SCN_INVALIDSCANBUFFER 0xA0000022 Attempt to access fields of an invalid scan buffer.

E_SCN_READINCOMPATIBLE 0xA0000023 Attempt to submit a read that is incompatible with reads already queued.

E_SCN_NOFEEDBACK 0xA0000024 Attempt to perform physical device driver (PDD) feedback with no feedback capabilities.

E_SCN_NOTSUPPORTED 0xA0000026 Version of function not supported (e.g. ANSI vs. UNICODE).

E_SCN_WRONGSTATE 0xA0000027 The requested operation is inconsistent with the current state of the device.

E_SCN_NOMOREITEMS 0xA0000028 No more items are available to be returned from SCAN_FindFirst/SCAN_FindNext.

E_SCN_CANTOPENREGKEY 0xA0000029 A required registry key could not be opened. E_SCN_CANTREADREGVAL 0xA000002A A required registry value could not be read.

E_SCN_EXCEPTION 0xA000002B An exception occurred while trying to call the scanner driver.

E_SCN_WIN32ERROR 0xA000002C A scanner API function failed with a non-scanner API error code. Call GetLastError to get extended error code.

E_SCN_ALREADYINUSE 0xA000002D A requested scanner resource is already in use. E_SCN_NOTINUSE 0xA000002E The specified scanner resource was not allocated E_SCN_INVALIDRESULT 0xA0000036 Operation invalid result was received from imager

E_SCN_INTERNALERROR 0xA000003A Internal software error occured

E_SCN_DRIVER 0xA000003C An image was requested using an invalid image region.

E_SCN_FILEINVALID 0xA000003D The file was not a valid firmware upgrade file.

E_SCN_NOIMAGE 0xA000003E The API function was unable to return with valid image data.

E_SCN_BADREGION 0xA000003F An image was requested using an invalid image region.

E_SCN_BADSMARTIMAGE 0xA0000040 Internal error in signature capture function: code id of symbology is not supported by this feature, there is no resulting image, etc.

E_SCN_SMARTIMAGETOOLARGE 0xA0000041 The resulting image is bigger than 700*500 pixels

E_SCN_TOO_MUCH_INTERPOLATION 0xA0000042 The resulting image was zoomed more than required by ZoomLimit parameter.

Page 121: HC700 SDK Specification

Page 121 of 680

E_SCN_PDD_EXCEPTION 0xA0000043 An exception occurred in underlaying imager driver

Page 122: HC700 SDK Specification

Page 122 of 680

Example

Scanner Sample Application using SCAN Key trigger #define WM_SCAN_TRIGGER (WM_APP + 0x001) LRESULT CALLBACK WndProc (HWND, UINT, WPARAM, LPARAM); HANDLE Scanner; // scanner handle LPSCAN_BUFFER Buff; // buffer data HANDLE hEvent; // event handle DWORD cIO; // read id DWORD WINAPI dwBCROpenAndRegister(...) { DWORD Status; ... // open Scanner Handle Status = SCAN_Open (TEXT("SCN1:"), &Scanner); if (Status != E_SCN_SUCCESS) { MessageBox(hWnd, L"Unable to Open", L"SCAN Error", MB_OK | MB_ICONERROR); exit(1); } // allocate memory for scan buffer Buff = SCAN_AllocateBuffer (TRUE, 1000); // enable beam laser SCAN_Enable(Scanner); .... // register to the Scan Key notification with WM_SCAN_TRIGGER massage to winproc KBD_RegisterKeyStateNotification (hWnd, WM_SCAN_TRIGGER); // create event to wait scanner data hEvent = CreateEvent(0, FALSE, FALSE, NULL); .... } DWORD WINAPI dwBCRClose(...) { .... // unregister the Scan Key notification KBD_UnregisterKeyStateNotification (hWnd, WM_SCAN_TRIGGER); // close "SCN1:" scanner SCAN_Close(Scanner); ... // close read label event CloseHandle(hEvent); ....

Page 123: HC700 SDK Specification

Page 123 of 680

} LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) { DWORD status; switch (message) { case WM_SCAN_TRIGGER: // check if Scan key is down if(((USHORT)wParam) & SCAN_DOWN) { .... // start a beam and read decoded data status=SCAN_ReadLabelEvent(Scanner, Buff, hEvent, 0, &cIO); WaitForSingleObject(hEvent, INFINITE); //The scanner finished reading and the buffer is valid } // check if Scan key is up if(((USHORT)wParam) & SCAN_UP) { ..... } .... } }

Page 124: HC700 SDK Specification

Page 124 of 680

3. Wireless Imager Scanning API Overview A Wireless Imager Scanning API provides applications with the ability to read bar code labels by external imager device that is connected to the host terminal via BlueTooth. It exposes applications with a Win32 "C" callable interface.

A Wireless Imager Scanning API supports 1D and 2D barcode labels scanning.

Functions List Function Description

SCAN_Open Opens the specified wireless imager device and creates a handle to be used for all subsequent accesses to this imager.

SCAN_Close Closes the previously opened access to wireless imager device obtained by a call to SCAN_Open function.

SCAN_Enable Enables read label and image capture operations by remote imager.

SCAN_Disable Disables read label and image capture operations by remote scanner device.

SCAN_FindFirst Finds the first available scanner and creates a find handle for use by SCAN_FindNext.

SCAN_FindNext Finds the next available scanner in the search specified by hFindHandle.

SCAN_FindClose Closes the find handle used by SCAN_FindFirst and SCAN_FindNext.

SCAN_RegisterNotifications Signals to Wireless Imager Scanning API that user’s application is ready to receive notification events from remote imager scanner.

SCAN_DeRegisterNotifications Signals to Wireless Imager Scanning API that user’s application is no more interested to receive notification events from remote imager scanner.

SCAN_GetNotificationResult Obtains the type of received notification event from Wireless Imager API. It also obtains the data received by Wireless Imager Scanning API from remote scanner.

SCAN_AcknowledgeResponse Notifies remote scanner about validity of scanning process.

SCAN_SetSoftTrigger Triggers remote imager, specifying that user is interested to read labels in continuous or single modes. It also used to turn off the trigger of remote imager.

SCAN_RemoteConfig Provides Wireless Imager driver a set of identification parameters of remote scanner imager to try to connect to this imager.

SCAN_GetEnabledSymbologies Getd the list of currently enabled symbologies on remote Imager device.

SCAN_SetEnabledSymbologies Sets the desired list of currently enabled symbologies on remote Imager device.

SCAN_GetImagerParams Gets current parameters set of specified configuration item from remote Imager device.

SCAN_SetImagerParams Sets desired parameters set of specified configuration item to remote Imager device.

SCAN_RemoteDisconnect Causes remote imager device to initialize disconnection session. After remote imager device will disconnect, a host terminal will be ready to be connected to any other remote imager device.

SCAN_GetRemoteBDAddress retrieves BD address of currently connected remote scanner device.

SCAN_UpgradeFirmware Upgrads different firmware types (bootloader, main

Page 125: HC700 SDK Specification

Page 125 of 680

application and Zeevo BT) on remote imager. SCAN_IsRemoteUpgradeRequired Determines if the supplied firmware needs to be updated

on remote imager. SCAN_BeepLed Performsbuzzer beeps and LED turns on remote imager

device. SCAN_GetRemoteImage Captures and get an image from remote imager device. SCAN_GetRemoteLastImage Gets a last captured image from remote imager device. SCAN_GetRemoteIntelligentImage Gets a signature captured image from remote imager

device.

• Example • Data Types • Return Values

Page 126: HC700 SDK Specification

Page 126 of 680

SCAN_Open

Description The SCAN_Open function opens the specified wireless imager device and creates a handle to be used for all subsequent accesses to this imager.

Function Prototype

DWORD SCAN_Open(LPCTSTR lpszDeviceName, LPHANDLE lphScanner )

Parameters lpszDeviceName [In]

Pointer to a string containing the name of the scanner to open. The name can be obtained via a call to SCAN_FindFirst or SCAN_FindNext. To access the wireless imager device the “BT_Server” name will be used as the scanner name passed to this function. (The name “SCN1:” is used to access the internal scanner).

lphScanner [Out] Pointer to a handle created for all subsequent accesses to this scanner.

Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is E_SCN_NULLPTR or E_SCN_INVALIDDEVICE. If Scanner driver is already opened, the E_SCN_INVALIDDEVICE error is returned. If E_SCN_INVALIDDEVICE is returned, the caller can get a more specific error code by calling GetLastError. GetLastError could return a Win32 error code or any one of the following error codes: E_SCN_INVALIDARG, E_SCN_NOTINITIALIZED, E_SCN_NOTENOUGHMEMORY, E_SCN_CANTGETDEFAULTS, E_SCN_CANTSTARTDEVICE.

Comments None

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example HANDLE hScanner; DWORD dwResult; // Open scanner dwResult = SCAN_Open(TEXT("BT_Server"), &hScanner); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 127: HC700 SDK Specification

Page 127 of 680

SCAN_Close

Description The SCAN_Close function closes the previously opened access to wireless imager device obtained by a call to SCAN_Open function.

Function Prototype

DWORD SCAN_Close(HANDLE hScanner)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. Return Values If the function succeeds, the return value is E_SCN_SUCCESS If the function fails, the return value is E_SCN_INVALIDHANDLE

Comments None

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult; dwResult = SCAN_Close( hScanner ); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 128: HC700 SDK Specification

Page 128 of 680

SCAN_RegisterNotifications

Description The SCAN_RegisterNotifications function signals to Wireless Imager Scanning API that user’s application is ready to receive notification events from remote imager scanner.

Function Prototype

DWORD SCAN_RegisterNotifications(HANDLE hScanner, HANDLE hEvent, HWND hWnd, UINT iMsg)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. hEvent [In] The handle to an opened automatic(only) Win32 event that will be set by Wireless Imager Scanning API when imager’s notification occurs. hWnd [In] The handle to an existing window that will receive iMsg window message by Wireless Imager Scanning API when imager’s notification occurs. iMsg[In] The window message that will be sent by Wireless Imager Scanning API when imager’s notification occurs. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. If the function submits invalid hScanner or hEvent parameters, the return value is E_SCN_INVALIDHANDLE. If the function submits invalid parameters set, the return value is E_SCN_INVALIDPARAM

Comments The user can call this function providing one or two methods of receiving notification events. It can be signaled via hEvent event or received by hWnd window. The user can specify also both notification types. If hWnd specified, the iMsg that is not equal to 0 must be specified also.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult; HANDLE hEvent = CreateEvent(NULL, FALSE, FALSE, NULL); dwResult = SCAN_RegisteNotificationsr(hScanner, hEvent, NULL, NULL ); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 129: HC700 SDK Specification

Page 129 of 680

SCAN_DeRegisterNotifications

Description The SCAN_DeRegisterNotifications function signals to Wireless Imager Scanning API that user’s application is no more interested to receive notification events from remote imager scanner.

Function Prototype

DWORD SCAN_DeRegisterNotifications(HANDLE hScanner)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. If the function submits invalid hScanner parameter, the return value is E_SCN_INVALIDHANDLE.

Comments After this function is called the user application will no longer receive notification events by Wireless Imager API.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult; dwResult = SCAN_DeRegisteNotificationsr(hScanner ); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 130: HC700 SDK Specification

Page 130 of 680

SCAN_GetNotificationResult

Description The SCAN_GetNotificationResult function is used to obtain the type of received notification event from Wireless Imager API. It also obtains the data received by Wireless Imager Scanning API from remote scanner.

Function Prototype

DWORD SCAN_GetNotificationResult( HANDLE hScanner,

LPSCAN_NOTIFICATION_TYPE pNotifyType, LPBYTE pBuffer, LPDWORD lpdwBufferSize)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. pNotifyType [Out] The pointer to SCAN_NOTIFICATION_TYPE enumeration that identifies the type of occurred event. pBuffer [Out] The pointer to the buffer receives notification event’s data. For example: If the notification event is the scanned label, pBuffer will contain the label scanned by remote imager. lpdwBufferSize [In,Out] The pointer to DWORD variable specifies the size of pBuffer. The Wireless Imager Scanning API fills this variable with the size of data returned within pBuffer. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of next errors: E_SCN_INVALIDHANDLE, E_SCN_NULLPTR, E_SCN_INVALIDPARAM, E_SCN_NONOTIFICATION. If the size of allocated pBuffer is not sufficient to retrieve the data, the function returns E_SCN_NOTENOUGHMEMORY when lpdwBufferSize will contain a memory count that must be allocated for successful read of notification’s data. E_SCN_NONOTIFICATION is returned after calling SCAN_GetNotificationResult twice or more to read the same notification message that was already read by calling to SCAN_GetNotificationResult.

Comments None.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult; SCAN_NOTIFICATION_TYPE notifyType; DWORD dwBufferSize = 4096; LPBYTE pBuffer = malloc(4096); dwResult = SCAN_GetNotificationResult(hScanner, &notifyType, pBuffer, &dwBufferSize); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 131: HC700 SDK Specification

Page 131 of 680

SCAN_AcknowledgeResponse

Description The SCAN_AcknowledgeResponse function is used to notify remote scanner about validity of scanning process.

Function Prototype

DWORD SCAN_AcknowledgeResponse( HANDLE hScanner,

SCAN_ACKNOWLEDGE AckResponse)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. AckResponse [In] The acknowledge that will be sent back to remote imager device. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments The remote imager will not read barcode labels or pictures until receives an appropriate acknowledge by application. The connection-oriented events will still occur even if this function not called by user.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult; SCAN_ACKNOWLEDGE Ack; dwResult = SCAN_AcknowledgeResponse(hScanner, Ack); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 132: HC700 SDK Specification

Page 132 of 680

SCAN_SetSoftTrigger

Description The SCAN_SetSoftTrigger function is used for triggering remote imager, specifying that user is interested to read labels in continuous or single modes. It also used to turn off the trigger of remote imager.

Function Prototype

DWORD SCAN_SetSoftTrigger(HANDLE hScanner, SCAN_SOFT_TRIGGER SoftTrigger)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. SoftTrigger [In] The pointer to the SCAN_SOFT_TRIGGER variable specifying the trigger operation to be performed by remote scanner: turn trigger for single read, for continuous read or turn trigger off (SCAN_TRIGGER_SINGLE, SCAN_TRIGGER_CONTINUOUS and SCAN_TRIGGER_OFF appropriately). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments The user must call SCAN_RegisterNotifications function before this function to be ready to receive the scanning notification results.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult; SCAN_SOFT_TRIGGER softTrigger = SCAN_TRIGGER_SINGLE; dwResult = SCAN_SetSoftTrigger(hScanner, softTrigger); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 133: HC700 SDK Specification

Page 133 of 680

SCAN_RemoteConfig

Description The SCAN_RemoteConfig function used to provide Wireless Imager driver a set of identification parameters of remote scanner imager to try to connect to this imager.

Function Prototype

DWORD SCAN_RemoteConfig(HANDLE hScanner,

SCAN_REMOTE_PARAMS RemoteParams )

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. remoteParams [In] Specifies the previously known parameters of remote scanner to connect to. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments This fallback function will be used for initiating “Terminal to scanner” connection. When remote device is unable to connect to the host, this function will cause the terminal to try to connect to remote scanner, which parameters passed as arguments to this function. The user application must call SCAN_Open and SCAN_RegisterNotification functions before calling this function to be ready to receive “Connect” notification event.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult; SCAN_REMOTE_PARAMS remoteScanner;; wsccpy( remoteScanner.BdAdress, TEXT(33:33:33:33:33:33“”)); dwResult = SCAN_RemoteConfig(hScanner, remoteScanner); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 134: HC700 SDK Specification

Page 134 of 680

SCAN_GetEnabledSymbologies

Description The SCAN_GetEnabledSymbologies function used to get the list of currently enabled symbologies on remote Imager device.

Function Prototype

DWORD SCAN_GetEnabledSymbologies(HANDLE hScanner, LPBOOL lpbSymStatus)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. lpbSymStatus [Out] The pointer to an array of symbologies with a size of SCAN_MAX_SYMBOLOGIES. Upon return, this array will contain the enable/disable status of each symbology that is represented by index of this array. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments This function returns the current set of enabled symbologies by remote imagers. Only enabled symbologies will be readable by remote scanner.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult; BOOL symbologyStatus[SCAN_MAX_SYMBOLOGIES]; dwResult = SCAN_GetEnabledSymbologies(hScanner, symbologyStatus); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; } if( symbologyStatus[SYM_CODE39] ) MessageBox( “Code 39 enabled” );

Page 135: HC700 SDK Specification

Page 135 of 680

SCAN_SetEnabledSymbologies

Description The SCAN_SetEnabledSymbologies function used to set the desired list of currently enabled symbologies on remote Imager device.

Function Prototype

DWORD SCAN_SetEnabledSymbologies(HANDLE hScanner, LPBOOL lpbSymStatus)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. lpbSymStatus [Out] The pointer to an array of symbologies with a size of SCAN_MAX_SYMBOLOGIES. This array must be cleared when created by application. Those elements equal to TRUE represent enabled symbologies. Those elements equal to FALSE represent disabled symbologies. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments This function sets the current list of enabled symbologies by remote imagers. Only enabled symbologies will be readable by remote scanner. When disconnected from host terminal, a remote device will set its default parameters back as active parameters and all previously enabled or disabled symbologies configuration will be lost.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example BOOL symbologyStatus[SCAN_MAX_SYMBOLOGIES]; // Clear the array first memset(symbologyStatus, 0, sizeof(symbologyStatus)); // Enable only two symbologies symbologyStatus[SYM_CODE39] = TRUE; symbologyStatus[SYM_UPCA] = TRUE; dwResult = SCAN_SetEnabledSymbologies(hScanner, symbologyStatus); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 136: HC700 SDK Specification

Page 136 of 680

SCAN_GetImagerParams

Description The SCAN_GetImagerParams function used to get current parameters set of specified configuration item from remote Imager device.

Function Prototype

DWORD SCAN_GetImagerParams(HANDLE hScanner, SCAN_PARAM_TYPE ParamType,

LPVOID lpParamData, LPDWORD lpdwParamSize)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. ParamType [In] Specifies the type of parameter to be retrieved by this function. lpParamData [Out] The pointer to data structure will be filled with retrieved parameter data. ldwpParamSize [In/Out] The pointer to the DWORD variable contains the size of the data pointed by lpParamData parameter. If this size is insufficient for reading desired parameter, upon return this variable will contain the required size. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments This function returns the current configuration and parameters of remote imagers.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult, dwParamSize; SCAN_PARAM_TYPE paramType = SCAN_PARAM_TYPE_SYMBOLOGY; SCAN_SYM_CONFIG SymbologyParams; dwParamSize = sizeof(SCAN_SYM_CONFIG); memset(&SymbologyParams, 0, sizeof(SymbologyParams) ); // Read code 39 symbology flags SymbologyParams. code39. dwMask = SCAN_SYM_MASK_FLAGS; dwResult = SCAN_GetImagerParams(hScanner, paramType, &SymbologyParams, &dwParamSize ); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; } if( SymbologyParams.code39.dwFlags & SCAN_SYMBOLOGY_ENABLE ) {

// Symbology enabled }

Page 137: HC700 SDK Specification

Page 137 of 680

else { // Symbology disabled }

Page 138: HC700 SDK Specification

Page 138 of 680

SCAN_SetImagerParams

Description The SCAN_SetImagerParams function used to set desired parameters set of specified configuration item to remote Imager device.

Function Prototype

DWORD SCAN_SetImagerParams(HANDLE hScanner, SCAN_PARAM_TYPE ParamType,

LPVOID lpParamData, LPDWORD lpdwParamSize)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. ParamType [In] Specifies the type of parameter to be set by this function. lpParamData [Out] The pointer to appropriate data structure contains desired parameter. ldwpParamSize [In] The pointer to the DWORD variable contains the size of the data pointed by lpParamData parameter. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments This function sets the current configuration parameters of remote imagers. When disconnected from host terminal, a remote device will set its default parameters back as active parameters.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example DWORD dwResult, dwParamSize; SCAN_PARAM_TYPE paramType = SCAN_PARAM_TYPE_SYMBOLOGY; SCAN_SYM_CONFIG SymbologyParams; dwParamSize = sizeof(SCAN_SYM_CONFIG); // Must to clear the structure before calling SCAN_SetImagerParams memset(&SymbologyParams, 0, sizeof(SymbologyParams) ); SymbologyParams. code39. dwMask = SCAN_SYM_MASK_FLAGS; SymbologyParams. code39. dwFlagsk &= ~SCAN_SYMBOLOGY_ENABLE; dwResult = SCAN_SetImagerParams(hScanner, paramType, &SymbologyParams, &dwParamSize ); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 139: HC700 SDK Specification

Page 139 of 680

SCAN_RemoteDisconnect

Description The SCAN_RemoteDisconnect function is used to cause remote imager device to initialize disconnection session. After remote imager device will disconnect, a host terminal will be ready to be connected to any other remote imager device.

Function Prototype

DWORD SCAN_RemoteDisconnect(HANDLE hScanner)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments When remote imager device disconnects from terminal, the last one will receive the notification about the disconnection.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example dwResult = SCAN_RemoteDisconnect(hScanner) if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 140: HC700 SDK Specification

Page 140 of 680

SCAN_GetRemoteBDAddress

Description The SCAN_GetRemoteBDAddress function retrieves BD address of currently connected remote scanner device.

Function Prototype

DWORD SCAN_GetRemoteBDAdress(HANDLE hScanner, LPTSTR szRemoteBDAddress,

LPDWORD lpdwRemoteBDAddressSize)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. szRemoteBDAddress [Out] The pointer to UNICODE string that will be filled with remote scanner’s BD address. lpdwRemoteBDAddressSize [In/Out] The pointer to DWORD variable specifies the size in bytes of szRemoteBDAddress string. Upon return this pointer will specify the actual size of data filled in szRemoteBDAddress. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments If the size specified by szRemoteBDAddress parameter is not sufficient, the function will fail and lpdwRemoteBDAddressSize will return the required size.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example TCHAR szRemoteBDAdress[20]; DWORD dwSize = sizeof(szRemoteBDAdress); dwResult = SCAN_GetRemoteCDAddress(hScanner, szRemoteBDAdress, &dwSize) if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 141: HC700 SDK Specification

Page 141 of 680

SCAN_Enable

Description The SCAN_Enable function enables read label and image capture operations by remote imager.

Function Prototype

DWORD SCAN_Enable(HANDLE hScanner)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments Upon connected to remote imager device (connected notification received), the application must call this function to enable scanning barcodes. This function may be called also before remote imager is connected but not before SCAN_Open was called. Actually this function may be called at any time during application running and it is intended for use as a flag for working with imager.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example dwResult = SCAN_Enable(hScanrre) if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 142: HC700 SDK Specification

Page 142 of 680

SCAN_Disable

Description The SCAN_Disable function disables read label and image capture operations by remote scanner device.

Function Prototype

DWORD SCAN_Disable(HANDLE hScanner)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments An application must call this function each time it wants to disable scanning barcodes. This function may be called also before remote imager is connected but not before SCAN_Open was called. Actually this function may be called at any time during application running and it is intended for use as a flag for working with imager.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example dwResult = SCAN_Disable(hScanrre) if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 143: HC700 SDK Specification

Page 143 of 680

SCAN_UpgradeFirmware

Description The SCAN_UpgradeFirmware function is used for upgrading different firmware types (bootloader, main application and Zeevo BT) on remote imager.

Function Prototype

DWORD SCAN_UpgradeFirmware(HANDLE hScanner, LPCTSTR szFirmwareFilename)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. szFirmwareFilename [In] The absolute file name of the new firmware to upgrade. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments An application must call this function each time it wants to upgrade a firmware on remote imager. This function initialises upgrading mechanism and exits immediately with appropriate result. An application will receive a remote notifications about progressing and status of both transferring and programming of new firmware. To receive remote notifications an application must call SCAN_RegisterNotifications function. The only three following functions may be used by application after SCAN_UpgradeFirmware was called and before SCAN_TRANSFER_COMPLETED status received by SCAN_GetNotificationResult: SCAN_RegisterNotifications, SCAN_DeRegisterNotifications, SCAN_GetNotificationResult.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example dwResult = SCAN_UpgradeFirmware(hScanrre, TEXT(“c:\Application.bin”)) if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 144: HC700 SDK Specification

Page 144 of 680

SCAN_IsRemoteUpgradeRequired

Description The SCAN_IsRemoteUpgradeFirmware function is used to determine if the supplied firmware needs to be updated on remote imager.

Function Prototype

DWORD SCAN_IsRemoteUpgradeRequired(HANDLE hScanner, LPCTSTR szFirmwareFilename, LPSCAN_FIRMWARE_UPGRADE_STATUS lpIsUpgradeRequired)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. szFirmwareFilename [In] The absolute file name of the new firmware candidate to upgrade. lpIsUpgradeRequired [Out] Upon return this parameter will contain the status describing the necessary to upgrade the firmware provided by szFirmwareFilename parameter on remote imager. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments An application must call this function each time it wants to determine if a remote imager firmware versions are not equal to provided firmware. This function allows application to save the time when upgrading imager by asking currently running versions, instead of transferring that firmware to remote imager. Upon completition of that function user application will decide to perform the upgrade by calling SCAN_UpgradeFirmware. If SCAN_FIRMWARE_UPGRADE_NOT_REQUIRED is filled out by SCAN_IsRemoteUpgradeFirmware, this mean that all firmware types contained within the firmware provided by szFirmwareFilename parameter are identical to the current ones running on the remote imager. If SCAN_FIRMWARE_UPGRADE_REQUIRED is filled out, this mean that there is at least one firmware type contained within the firmware provided by szFirmwareFilename parameter that is not identical to the one currently running on the remote imager. If SCAN_FIRMWARE_CONTAINS_RAW_DATA is filled out, this mean that all firmware types contained within the firmware provided by szFirmwareFilename parameter are identical to the current ones running on the remote imager, but the firmware provided by szFirmwareFilename parameter contains also a custom data file that may be upgraded on remote imager.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example LPSCAN_FIRMWARE_UPGRADE_STATUS IsUpgradeRequired; dwResult = SCAN_IsRemoteUpgradeFirmware (hScanrre, TEXT(“c:\Firmware.bin”), &IsUpgradeRequired) if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 145: HC700 SDK Specification

Page 145 of 680

SCAN_BeepLed

Description The SCAN_BeepLed function is used to perform buzzer beeps and LED turns on remote imager device.

Function Prototype

DWORD SCAN_BeepLed(HANDLE hScanner, LPCTSTR szCommadString,

LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. szCommandString [In] The null-terminated string contains the command to perform by remote buzzer and led. This string must by provided with known format. lpReserved This parameter is reserved and must not be used. Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

Comments An application must call this function each time it wants to beep or turn LED on remote imager. This describes the format of the string, provided by szCommandString parameter: LED indication: · “L[R/G/A]“ R means Red, G means Green, A means Amber. · “I[milliseconds]” Specifies the interval for led on and off lengths in milliseconds, if interval is 0 (or absent) then the LED will be steady on. · “C[amount]” Specifies the amount of blinks, if count is 0 (or absent), then the LED will blink forever. Sound Indication: · “V[1-4]” Sets the buzzer volume for the current sound. Absent or 0 - is a default level (currently 4) · “D[milliseconds]” Specifies the sounds duration, if duration is 0 (or absent), then the sound will play forever. · “F[Hrz.]” Specifies the frequency of the sound, if frequency is less than 100, then the buzzer is silent. · “P” marks the end of single sound definition (V, D and F may be written in any order before P). “R” means reset the indication queue, removing and stopping all the previous indications. LED indication is single per call, sound indications may be entered up to 50. LED indication starts together with the first beep. For example: "RF1000D200V3PF2000D100V1PF3000D300V4PLRI250C10” Buzzer will reset queue, then play 1000 Hrz. for 200 milliseconds at volume 3, then play 2000 Hrz. for 100 milliseconds at volume 1, then play 3000 Hrz. for 300 milliseconds at volume 4 and show a red blinking LED (10 blinks with 250 milliseconds between on and of state).

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 146: HC700 SDK Specification

Page 146 of 680

Example wcscpy(szCmd, TEXT(“RF1000D200V3PF2000D100V1PF3000D300V4PLRI250C10”)); dwResult = SCAN_BeepLed(hScanrre,szCmd, 0); if ( dwResult != E_SCN_SUCCESS ) { // Report an error return; }

Page 147: HC700 SDK Specification

Page 147 of 680

SCAN_GetRemoteImage

Description The SCAN_GetRemoteImage function is used to capture and get an image from remote imager device.

Function Prototype

DWORD SCAN_GetRemoteImage(HANDLE hScanner,BOOL bWait, LPSCAN_IMAGE_ACQUISITION lpImageAcquisitionParams, LPSCAN_IMAGE_TRANSFER lpImageTransferParams, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. bWait [In] Only FALSE is supported. This value will define the notification mechanism for getting resulting image. When this value is equal to FALSE, this function is not-blocked. It will start image processing and will exit. The image itself will be received asynchronously (after SCAN_RegisterNotifications was called) by SCAN_GetNotificationResult with SCAN_NOTIFY_REMOTE_IMAGE notification type. lpImageAcquisitionParams [In] This parameter defines the parameters the image will be captured with. lpImageTransferParams [In] This parameter defines the parameters the image will be transferred with. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example // read image with current image parameters dwResult = SCAN_GetRemoteImage(g_hRemoteScanner, FALSE, NULL, NULL, NULL); if( dwResult != E_SCN_SUCCESS ) { DestroyWindow(hProgressWnd); hProgressWnd = NULL; wsprintf(String, TEXT("Failed take a picture. Error 0x%x"), dwResult); MessageBox(hwnd, String, TEXT("Program Error"), MB_OK | MB_ICONERROR); return 0; }

Page 148: HC700 SDK Specification

Page 148 of 680

SCAN_GetRemoteLastImage

Description The SCAN_GetRemoteLastImage function is used to get a last captured image from remote imager device.

Function Prototype

DWORD SCAN_GetRemoteLastImage(HANDLE hScanner,BOOL bWait, LPSCAN_IMAGE_TRANSFER lpImageTransferParams, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. bWait [In] Only FALSE is supported. This value will define the notification mechanism for getting resulting image. When this value is equal to FALSE, this function is not-blocked. It will start image processing and will exit. The image itself will be received asynchronously (after SCAN_RegisterNotifications was called) by SCAN_GetNotificationResult with SCAN_NOTIFY_REMOTE_IMAGE notification type. lpImageTransferParams [In] This parameter defines the parameters the image will be transferred with. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example // read image with current image parameters dwResult = SCAN_GetRemoteLastImage(g_hRemoteScanner, FALSE, NULL, NULL); if( dwResult != E_SCN_SUCCESS ) { DestroyWindow(hProgressWnd); hProgressWnd = NULL; wsprintf(String, TEXT("Failed take a picture. Error 0x%x"), dwResult); MessageBox(hwnd, String, TEXT("Program Error"), MB_OK | MB_ICONERROR); return 0; }

Page 149: HC700 SDK Specification

Page 149 of 680

SCAN_GetRemoteIntelligentImage

Description The SCAN_GetRemoteIntelligentImage function is used to get a signature captured image from remote imager device.

Function Prototype

DWORD SCAN_GetRemoteIntelligentImage(HANDLE hScanner,BOOL bWait, SCAN_REMOTE_IQ_IMG_PARAMS SignatureParams, LPVOID lpReserved)

Parameters hScanner [In] The handle to the open scanner obtained by SCAN_Open. bWait [In] Only FALSE is supported. This value will define the notification mechanism for getting resulting image. When this value is equal to FALSE, this function is not-blocked. It will start image processing and will exit. The image itself will be received asynchronously (after SCAN_RegisterNotifications was called) by SCAN_GetNotificationResult with SCAN_NOTIFY_REMOTE_IMAGE notification type. SignatureParams [In] This parameter configures the taking of signature capting image. lpReserved This parameter is reserved and must not be used (set to NULL). Return Values If the function succeeds, the return value is E_SCN_SUCCESS. In case of error this function will return with one of exists error codes.

QuickInfo Windows CE: Version 4.2 or later. Header: Declared in ScanCAPI.h. Import Library: Use ScnAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example // read signature image with current image parameters SignatureParams.dwAspectRatio = 18; SignatureParams.nCenterXoffset = 2; SignatureParams.nCenterYoffset = -43; SignatureParams.dwImageWidth = 190; SignatureParams.dwImageHeight = 50; SignatureParams.dwResolution = 1; SignatureParams.dwReserved1 = 0; SignatureParams.dwReserved2 = 0; dwResult = SCAN_GetRemoteIntelligentImage(g_hRemoteScanner, FALSE, & SignatureParams, NULL); if( dwResult != E_SCN_SUCCESS ) { DestroyWindow(hProgressWnd); hProgressWnd = NULL; wsprintf(String, TEXT("Failed take a picture. Error 0x%x"), dwResult); MessageBox(hwnd, String, TEXT("Program Error"), MB_OK | MB_ICONERROR); return 0; }

Page 150: HC700 SDK Specification

Page 150 of 680

Data Types

SCAN_NOTIFICATION_TYPE Description

The SCAN_NOTIFICATION_TYPE enumeration is used to specify the kind of notification event received from remote imager.

Structure Definition

typedef enum

{

SCAN_NOTIFY_REMOTE_CONNECT ,

SCAN_NOTIFY_REMOTE_DISCONNECT ,

SCAN_NOTIFY_REMOTE_BARCODE ,

SCAN_NOTIFY_REMOTE_IMAGE ,

SCAN_NOTIFY_REMOTE_TRANSFER_FIRMWARE_PROGRESS ,

SCAN_NOTIFY_REMOTE_PROGRAMM_FIRMWARE_PROGRESS

} SCAN_NOTIFICATION_TYPE ;

Members SCAN_NOTIFY_REMOTE_CONNECT

User application will receive this notification when remote imager will establish the connection with the host.

SCAN_NOTIFY_REMOTE_DISCONNECT

User application will receive this notification when remote imager will be disconnected from the host. SCAN_NOTIFY_REMOTE_BARCODE

User application will receive this notification when remote imager has finished transmitting barcode label read.

SCAN_NOTIFY_REMOTE_IMAGE User application will receive this notification when remote imager has finished transmitting captured image.

SCAN_NOTIFY_REMOTE_TRANSFER_FIRMWARE_PROGRESS User application will receive this notification when a new firmware is transferred to remote imager.

SCAN_NOTIFY_REMOTE_PROGRAMM_FIRMWARE_PROGRESS User application will receive this notification while a new firmware is programmed on remote imager.

Page 151: HC700 SDK Specification

Page 151 of 680

SCAN_FIRMWARE_UPGRADE_STATUS Description

The SCAN_FIRMWARE_UPGRADE_STATUS enumeration is used to determine if the firmware need to be upgraded on remote imager.

Structure Definition

typedef enum

{

SCAN_FIRMWARE_UPGRADE_NOT_REQUIRED,

SCAN_FIRMWARE_UPGRADE_REQUIRED,

SCAN_FIRMWARE_CONTAINS_RAW_DATA,

} SCAN_FIRMWARE_UPGRADE_STATUS;

Members SCAN_FIRMWARE_UPGRADE_NOT_REQUIRED

This status is filled out by SCAN_IsRemoteUpgradeFirmware and means that all firmware types contained within the firmware provided by szFirmwareFilename parameter are identical to the current ones running on the remote imager.

SCAN_FIRMWARE_UPGRADE_REQUIRED

This status is filled out by SCAN_IsRemoteUpgradeFirmware and means that there is at least one firmware type contained within the firmware provided by szFirmwareFilename parameter that is not identical to the one currently running on the remote imager.

SCAN_FIRMWARE_CONTAINS_RAW_DATA This status is filled out by SCAN_IsRemoteUpgradeFirmware and mean that all firmware types contained within the firmware provided by szFirmwareFilename parameter are identical to the current ones running on the remote imager, but the firmware provided by szFirmwareFilename parameter contains also a custom data file that may be upgraded on remote imager.

Page 152: HC700 SDK Specification

Page 152 of 680

SCAN_ACKNOWLEDGE Description

The SCAN_ACKNOWLEDGE enumeration is used to specify the kind of acknowledge response to be sent to remote imager.

Structure Definition

typedef enum

{

SCAN_ACKNOWLEDGE_TYPE_1 ,

SCAN_ACKNOWLEDGE_TYPE_2

} SCAN_ACKNOWLEDGE;

Members These acknowledge types will be defined by user application as way to configure a remote scanner to have desired behavior. SCAN_REMOTE_PARAMS Description

The SCAN_REMOTE_PARAMS structure is used to specify the identification parameters of remote imager.

Structure Definition

#define SCAN_BD_ADDRESS_SIZE 17

typedef struct

{

TCHAR szBDAdress[SCAN_BD_ADDRESS_SIZE] ;

} SCAN_REMOTE_PARAMS;

Members szBDAdress

User application will fill this string with BlueTooth BD address of remote imager the host to try to connect to.

SCAN_BARCODE_MESSAGE Description

The SCAN_BARCODE_MESSAGE structure contains barcode label read information.

Structure Definition

#define SCAN_MAX_MESSAGE_LEN 5000

typedef struct

Page 153: HC700 SDK Specification

Page 153 of 680

{

DWORD dwStructSize;

TCHAR szBarcodeMsg[SCAN_MAX_MESSAGE_LEN] ;

DWORD SymbologyID;

DWORD nLength;

} SCAN_BARCODE_MESSAGE;

Members dwStructSize

Equal to the size of this structure in bytes. szBarcodeMsg

Null terminated string that filled with barcode label read. SymbologyID

Equal to one of the symbology’s identifiers and specifies the type of a symbology read (for example SCAN_SYM_CODE128).

nLength Specifies the length of barcode message in szBarcodeMsg.

SCAN_FIRMWARE_TYPE

Description

The SCAN_FIRMWARE_TYPE enumeration is used to specify the type of updated firmware on remote imager.

Structure Definition

typedef enum

{

SCAN_FIRMWARE_APPLICATION ,

SCAN_FIRMWARE_BOOTLOADER,

SCAN_FIRMWARE_BLUETOOTH ,

SCAN_FIRMWARE_RAW_DATA

} SCAN_FIRMWARE_TYPE;

Members SCAN_FIRMWARE_APPLICATION

This specifies that user tries to update the remote scanner’s application software. SCAN_FIRMWARE_BOOTLOADER

This specifies that user tries to update the remote scanner’s bootcode software. SCAN_FIRMWARE_BLUETOOTH

This specifies that user tries to update the remote scanner’s bluetooth firmware.

Page 154: HC700 SDK Specification

Page 154 of 680

SCAN_FIRMWARE_RAW_DATA This specifies that user tries to burn custom data file on remote imager.

SCAN_SOFT_TRIGGER

Description

The SCAN_SOFT_TRIGGER enumeration is used to define a trigger mode of remote imager.

Structure Definition

typedef enum

{

SCAN_TRIGGER_OFF,

SCAN_TRIGGER_SINGLE ,

SCAN_TRIGGER_CONTINIOUS ,

} SCAN_SOFT_TRIGGER;

Members SCAN_TRIGGER_OFF

The remote imager will turn its trigger off. SCAN_TRIGGER_SINGLE

The remote imager will perform single label read. SCAN_TRIGGER_CONTINUOUS

The remote imager will perform continious label read Scan_Decode_Msg

Description

The Scan_Decode_Msg structure is used to keep information about barcode read performed by remote imager.

Structure Definition

typedef struct

{

DWORD dwStructSize;

TCHAR pchMessage[MAX_MESSAGE_LEN];

Scan_Symbology SymbologyType;

DWORD dwLength;

} Scan_Decode_Msg;

Members

Page 155: HC700 SDK Specification

Page 155 of 680

dwStructSize The sizeof Scan_Decode_Msg structure.

pchMessage

Barcode label message read by remote imager. SymbologyType

The type of symbology read. SCAN_PARAM_TYPE

Description

The SCAN_PARAM_TYPE enumeration is used to specify the type of parameter to be retrieved or set by SCAN_GetImagerParams function.

Structure Definition

typedef enum

{

SCAN_PARAM_TYPE_SYMBOLOGY,

SCAN_PARAM_TYPE_VERSION_INFO,

SCAN_PARAM_TYPE_TIMEOUTS,

SCAN_PARAM_TYPE_HISTORY, SCAN_PARAM_TYPE_DECODE_MODE , SCAN_PARAM_TYPE_DECODE_CENTERING_WINDOW , SCAN_PARAM_TYPE_LIGHTS_MODE , SCAN_PARAM_TYPE_IMAGE_ACQUISITION_INFO , SCAN_PARAM_TYPE_IMAGE_TRANSFER_INFO , SCAN_PARAM_TYPE_DECODE_LIMIT_TIME

} SCAN_PARAM_TYPE;

Members SCAN_PARAM_TYPE_SYMBOLOGY

The application will read or write specific symbology’s parameters. When editing symbology parameters, the dwMask field of that symbology specifies the parameters to read/write.On read operation the dwFlags field of that symbology specifies current parameter's values. dwFlags must be masked with pre-defined mask values in SDK to define current parameters settings. On write operation the dwFlags field of that symbology must specify new parameter's values by setting one of the pre-defined mask values in SDK. See example using this parameter in the samples of SCAN_GetImagerParams and SCAN_GetImagerParams functions.

SCAN_PARAM_TYPE_VERSION_INFO

The application will read version information from remote imager.

Page 156: HC700 SDK Specification

Page 156 of 680

SCAN_PARAM_TYPE_TIMEOUTS The application will configure different timeout values of remote imager. See SCAN_REMOTE_TIMEOUTS structure definition to view all configurable timeouts.

SCAN_PARAM_TYPE_HISTORY

The application will configure the number of last barcodes that were read and will be ignored again by remote imager. An application configures this number using SCAN_REMOTE_HISTORY structure. The dwHistoryLength member of this structure determines the number of last barcodes that were read and will be ignored again. The default value for this variable is equal to 0. This means the remote imager will decode and send all barcodes to the host. If dwHistoryLength is greater than 0 (5 for example) the imager will decode but not report 5 last scanned barcodes to the host.

SCAN_PARAM_TYPE_DECODE_MODE

Specifies imager’s decode mode parameters. See SCAN_REMOTE_DECODE_MODE_ for further description.

SCAN_PARAM_TYPE_DECODE_CENTERING_WINDOW

Specifies imager’s centering window parameters. See SCAN_REMOTE_DECODE_CENTERING_WINDOW for further description.

SCAN_PARAM_TYPE_LIGHTS_MODE Specifies imager’s lights operation. See SCAN_REMOTE_LIGHTS_MODE for further description.

SCAN_PARAM_TYPE_IMAGE_ACQUISITION_INFO Specifies imager’s capture parameters. See SCAN_IMAGE_ACQUISITION for further description.

SCAN_PARAM_TYPE_IMAGE_TRANSFER_INFO Specifies imager’s transfer parameters. See SCAN_IMAGE_TRANSFER for further description.

SCAN_PARAM_TYPE_DECODE_LIMIT_TIME Specifies imager’s decode limit times parameters. See SCAN_REMOTE_DECODE_LIMIT_TIME for further description.

SCAN_SYMBOLOGY

Description

The SCAN_SYMBOLOGY enumeration is used for identification of different symbologies used for scanning be remote imager.

Structure Definition

typedef enum

{

SCAN_SYM_AZTEC = 0, SCAN_SYM_MESA, SCAN_SYM_CODABAR, SCAN_SYM_CODE11, SCAN_SYM_CODE128, SCAN_SYM_CODE39, SCAN_SYM_CODE49, SCAN_SYM_CODE93, SCAN_SYM_COMPOSITE, SCAN_SYM_DATAMATRIX, SCAN_SYM_EAN8,

Page 157: HC700 SDK Specification

Page 157 of 680

SCAN_SYM_EAN13, SCAN_SYM_INT25, SCAN_SYM_MAXICODE, SCAN_SYM_MICROPDF, SCAN_SYM_OCR, SCAN_SYM_PDF417, SCAN_SYM_POSTNET, SCAN_SYM_QR, SCAN_SYM_RSS, SCAN_SYM_UPCA, // 20 SCAN_SYM_UPCE0, // 21 SCAN_SYM_UPCE1, SCAN_SYM_ISBT, SCAN_SYM_BPO, SCAN_SYM_CANPOST, SCAN_SYM_AUSPOST, SCAN_SYM_IATA25, SCAN_SYM_CODABLOCK, SCAN_SYM_JAPOST, SCAN_SYM_PLANET, SCAN_SYM_DUTCHPOST, SCAN_SYM_MSI, // 32 SCAN_SYM_TLCODE39, SCAN_SYM_MATRIX25, SCAN_SYM_KORPOST, SCAN_SYM_TRIOPTIC39, SCAN_SYM_COUPONCODE, SCAN_NUM_SYMBOLOGIES, SCAN_SYM_ALL=100

} SCAN_SYMBOLOGY;

#define SCAN_MAX_SYMBOLOGIES SCAN_SYM_ALL

Members Each enumerator represents single symbology. SCAN_REMOTE_TIMEOUTS

Description

The SCAN_REMOTE_TIMEOUTS structure is used to keep different timeout values of remote imager.

Structure Definition

typedef struct

{

DWORD dwConnectTimeout;

DWORD dwNoBarcodeTimeout;

DWORD dwSuspendTimeout;

DWORD dwNoAckTimeout;

DWORD dwReserved1;

Page 158: HC700 SDK Specification

Page 158 of 680

DWORD dwReserved2;

} SCAN_REMOTE_TIMEOUTS;

Members dwConnectTimeout

This value determines the time in milliseconds a remote imager will try to connect to the host (by scanning BD address label). This value must be between 0 and 60000 (0-60 secs). The default value is 20000 (20 seconds).

dwNoBarcodeTimeout

This value determines the time in milliseconds a remote imager will turn trigger on and try to decode a barcode label. This value must be between 0 and 300000 (0-300 secs). The default value is 5000 (5 seconds).

dwSuspendTimeout

This value determines the time in milliseconds a remote imager will enter its sleep mode after user inactivity (no trigger pressed/no command received). This value must be between 0 and 300000 (0-300 secs). The value of 0 indicates do not enter susped state. The default value is 1000 (1 second). Note: Entering remote imager to suspend state allows its battery to supply power longer.

dwNoAckTimeout

This value determines the time in milliseconds a remote imager will wait for a host acknowledge before enabling barcode reading continuation. The default value is 10000 (10 seconds).

dwReserved1

This value is reserved for future use and may not be used. dwReserved2

This value is reserved for future use and may not be used. SCAN_REMOTE_HISTORY

Description

The SCAN_REMOTE_HISTORY structure is used to configure the number of last barcodes that were read and will not be decoded again by remote imager.

Structure Definition

typedef struct

{

DWORD dwHistoryLength;

DWORD dwReserved1;

DWORD dwReserved2;

} SCAN_REMOTE_HISTORY;

Members dwHistoryLength

This value determines the number of last barcodes that were read and will be ignored from to be read again by remote imager. This value maybe any integer from range 0 - 20. The default value is 0.

Page 159: HC700 SDK Specification

Page 159 of 680

dwReserved1

This value is reserved for future use and may not be used. dwReserved2

This value is reserved for future use and may not be used. SCAN_REMOTE_DECODE_MODE

Description

The SCAN_REMOTE_DECODE_MODE structure is used to configure a decoding mode (algorithm) by remote imager.

Structure Definition

typedef struct

{

SCAN_REMOTE_DECODE_MODE_TYPE DecodingMode;

WORD wLinearRange;

} SCAN_REMOTE_DECODE_MODE;

Members DecodingMode

Specifies the decoding mode value to be used by remote imager.

wLinearRange Specifies the linear range value in case of linear decoding mode.

SCAN_REMOTE_DECODE_MODE_TYPE

Description

The SCAN_REMOTE_DECODE_MODE_TYPE union represents different decoding mode (algorithm) for remote imager.

Structure Definition

typedef union

{

SCAN_REMOTE_DECODE_MODE_TYPE_STANDARD = 0 ,

SCAN_REMOTE_DECODE_MODE_TYPE_QUICK_OMNI ,

SCAN_REMOTE_DECODE_MODE_TYPE_NONOMNI_ALD ,

SCAN_REMOTE_DECODE_MODE_TYPE_OMNI_LINEAR ,

} SCAN_REMOTE_DECODE_MODE_TYPE;

Members SCAN_REMOTE_DECODE_MODE_TYPE_STANDARD

Searches for bar code features beginning at the center of an image, and searches to the image’s limits. This mode reads all

Page 160: HC700 SDK Specification

Page 160 of 680

symbologies, in any orientation. The Full Omnidirectional search is very thorough which may slow performance time.

SCAN_REMOTE_DECODE_MODE_TYPE_QUICK_OMNI This is an abbreviated search for bar code features around the center region of an image. This mode quickly reads all symbologies in any orientation. The Quick Omnidirectional mode may miss some off-center symbols, as well as larger Data Matrix and QR Code symbols.

SCAN_REMOTE_DECODE_MODE_TYPE_NONOMNI_ALD Performs quick horizontal linear scans in a center band of the image. This mode is not omnidirectional, but does quickly read linear and stacked bar codes. Advanced Linear Decoding cannot read 2D, OCR, or Postal symbols.

SCAN_REMOTE_DECODE_MODE_TYPE_OMNI_LINEAR Performs quick horizontal and omnidirectional linear scans in a center band of the image.

SCAN_REMOTE_VERSION

Description

The SCAN_REMOTE_VERSION structure specifies versions for different software components for remote imager.

Structure Definition #define SCAN_MAX_HARDWARE_MESSAGE_LENGTH 5 #define SCAN_MAX_SOFTWARE_VERSION_MESSAGE_LENGTH 20 #define SCAN_MAX_FACTORY_FILE_MESSAGE_LENGTH 100 #define SCAN_MAX_APPLICATION_TIME_STAMP_LENGTH 100

typedef struct

{ TCHAR szRemoteHardwareVersion [SCAN_MAX_HARDWARE_MESSAGE_LENGTH];

TCHAR szRemoteApplicationVersion [SCAN_MAX_SOFTWARE_VERSION_MESSAGE_LENGTH];

TCHAR szRemoteBootloaderVersion [SCAN_MAX_SOFTWARE_VERSION_MESSAGE_LENGTH]; TCHAR szRemoteBluetoothVersion [SCAN_MAX_SOFTWARE_VERSION_MESSAGE_LENGTH]; TCHAR szRemoteApplicationDecoderVersion [SCAN_MAX_SOFTWARE_VERSION_MESSAGE_LENGTH]; TCHAR szRemoteApplicationScanDriverVersion [SCAN_MAX_SOFTWARE_VERSION_MESSAGE_LENGTH]; TCHAR szRemoteApplicationTimeStamp [SCAN_MAX_APPLICATION_TIME_STAMP_LENGTH];

Page 161: HC700 SDK Specification

Page 161 of 680

TCHAR szRemoteProductManufactureDate [SCAN_MAX_FACTORY_FILE_MESSAGE_LENGTH]; TCHAR szRemoteProductSerialNumber [SCAN_MAX_FACTORY_FILE_MESSAGE_LENGTH]; TCHAR szRemoteProductType [SCAN_MAX_FACTORY_FILE_MESSAGE_LENGTH]; DWORD dwRawFactoryFileDataOffset; DWORD dwRawFactoryFileDataSize;

} SCAN_REMOTE_VERSION;

Members szRemoteHardwareVersion

Specifies the hardware version used by remote imager.

szRemoteApplicationVersion Specifies the current application version running on remote imager.

szRemoteBootloaderVersion Specifies the current bootloader version running on remote imager.

szRemoteBluetoothVersion Specifies the current bluetooth version running on remote imager.

szRemoteApplicationDecoderVersion Specifies the current version of decoder library running on remote imager.

szRemoteScanDriverVersion Specifies the current version of scanning driver library running on remote imager.

szRemoteApplicationTimeStamp Specifies the time stamp when current application was built.

szRemoteProductManufactureDate Specifies the manufacter date of main board of remote imager.

szRemoteProductSerialNumber Specifies the serial number of remote imager.

szRemoteProductType Specifies the type of remote imager.

dwRawFactoryFileDataOffset Specifies the offset in bytes where the factory file of remote imager is copied after this data structure.

dwRawFactoryFileDataSize Specifies the size in bytes of factory file of remote imager that is copied after this data structure.

SCAN_REMOTE_DECODE_CENTERING_WINDOW Description Contains information for decode centering mode. In this mode, a decode call is only successful if the area bounding the decoded symbol intersects a caller defined rectangle located about the center of the captured image.

Page 162: HC700 SDK Specification

Page 162 of 680

Note: This functionality allows the imager to discriminate symbols that are located physically close to each other so only one symbol is captured during decode. Only the symbol intersecting the intersection rectangle is returned.

Structure Definition // Centering Box Min/Max Values #define SCAN_REMOTE_DECODE_WINDOW_ULX_MIN 0 #define SCAN_REMOTE_DECODE_WINDOW_ULX_MAX 100 #define SCAN_REMOTE_DECODE_WINDOW_ULY_MIN 0 #define SCAN_REMOTE_DECODE_WINDOW_ULY_MAX 100 #define SCAN_REMOTE_DECODE_WINDOW_LRX_MIN 0 #define SCAN_REMOTE_DECODE_WINDOW_LRX_MAX 100 #define SCAN_REMOTE_DECODE_WINDOW_LRY_MIN 0 #define SCAN_REMOTE_DECODE_WINDOW_LRY_MAX 100 // Centering Box Defaults Values #define SCAN_REMOTE_DEFAULT_DECODE_WINDOW_ULX 40 #define SCAN_REMOTE_DEFAULT_DECODE_WINDOW_ULY 40 #define SCAN_REMOTE_DEFAULT_DECODE_WINDOW_LRX 60 #define SCAN_REMOTE_DEFAULT_DECODE_WINDOW_LRY 60

typedef struct

{

BOOL bEnable;

RECT IntersactionRectangle;

} SCAN_REMOTE_DECODE_CENTERING_WINDOW;

Members bEnable

Specifies if decode centering windos feature is enabled. IntersactionRectangle

Specifies rectangular image region of which at least part of the decoded symbol must overlap to be considered a valid decode.

SCAN_REMOTE_LIGHTS_MODE

Description

Specifies the light mode type used by remote imager to get barcodes.

Structure Definition

typedef enum {

SCAN_REMOTE_AIM_MODE_TYPE AimMode; SCAN_REMOTE_ILLUMINATION_MODE_TYPE IlluminationMode;

} SCAN_REMOTE_LIGHTS_MODE;

Members AimMode

Specifies is the lights mode for aiming.

Page 163: HC700 SDK Specification

Page 163 of 680

IlluminationMode Specifies is the lights mode for illumination.

SCAN_REMOTE_AIM_MODE_TYPE

Description

Specifies the valid light mode types used by aimer on remote imager.

Structure Definition

typedef enum {

SCAN_REMOTE_AIM_MODE_OFF = 0, SCAN_REMOTE_AIM_MODE_CONCURENT, SCAN_REMOTE_AIM_MODE_INTERLACED

} SCAN_REMOTE_AIM_MODE_TYPE;

Members SCAN_REMOTE_AIM_MODE_OFF

Specifies no aiming when scan label.

SCAN_REMOTE_AIM_MODE_CONCURENT Specifies Aiming and Illumination allowed to be on at the same time (if Illumination is on) when scan label.

SCAN_REMOTE_AIM_MODE_INTERLACED Specifies Aiming and Illumination don't allowed to be on at the same time when scan label.

SCAN_REMOTE_ILLUMINATION_MODE_TYPE

Description

Specifies the valid light mode types used by illumination on remote imager.

Structure Definition

typedef enum {

SCAN_REMOTE_ILLUMINATION_MODE_OFF = 0, SCAN_REMOTE_ILLUMINATION_MODE_ON

} SCAN_REMOTE_ILLUMINATION_MODE_TYPE;

Members SCAN_REMOTE_ILLUMINATION_MODE_OFF

Specifies no illumination when scan label.

SCAN_REMOTE_ILLUMINATION_MODE_ON Specifies illumination on when scan label.

Page 164: HC700 SDK Specification

Page 164 of 680

SCAN_AUTOEXPOSURE

Description

Specifies possible capture mode for acquiring images by remote imager.

Structure Definition

typedef enum {

SCAN_AUTOEXPOSURE_BARCODE = 0, SCAN_AUTOEXPOSURE_PHOTO , SCAN_AUTOEXPOSURE_MANUAL

} SCAN_AUTOEXPOSURE;

Members SCAN_AUTOEXPOSURE_BARCODE

Selecting this option results in a darker image with less noise.

SCAN_AUTOEXPOSURE_PHOTO Selecting this option results in a brighter image with longer capture times. This selection also allows you to specify how the lights and aimers behave during capture. When this mode selected remote imager will apply automatic algoritm for definition of image quality acceptance.

SCAN_AUTOEXPOSURE_MANUAL Selecting this option requires all image acquisition parameters to be configured manually.

SCAN_IMAGE_ACQUISITION

Description

The SCAN_REMOTE_ACQUSITION structure is used to configure the image properties to ba captured by remote imager.

Structure Definition // Image Acquisition bit masks #define WHITE_VALUE_MASK 0x00001 Description: dwWhiteValue in SCAN_IMAGE_ACQUISITION structure specifies desired White value for image. #define WHITE_WINDOW_MASK 0x00002 Description: dwWhiteWindow in SCAN_IMAGE_ACQUISITION structure specifies desired White window for image. #define MAX_CAPTURE_RETRIES_MASK 0x00004 Description: dwMaxNumExposures in SCAN_IMAGE_ACQUISITION structure specifies desired maximum count of retries for image. #define ILLUMINATION_DUTY_CYCLE_MASK 0x00008

Page 165: HC700 SDK Specification

Page 165 of 680

Description: illuminatCycle in SCAN_IMAGE_ACQUISITION structure specifies desired illumination param for image. #define LIGHTS_DUTY_CYCLE_MASK 0x00008 Description: aimerCycle in SCAN_IMAGE_ACQUISITION structure specifies desired aimer param for image. #define AIMER_DUTY_CYCLE_MASK 0x00010 Description: aimerCycle in SCAN_IMAGE_ACQUISITION structure specifies desired aimer param for image. #define FIXED_GAIN_MASK 0x00020 Description: fixedGain in SCAN_IMAGE_ACQUISITION structure specifies desired gain for image. #define FIXED_EXPOSURE_MASK 0x00040 Description: fixedGain in SCAN_IMAGE_ACQUISITION structure specifies desired exposure for image. #define FRAME_RATE_MASK 0x00080 Description: frameRate in SCAN_IMAGE_ACQUISITION structure specifies desired frame rate for image. #define AUTOEXPOSURE_MODE_MASK 0x00100 #define IMAGE_CAPTURE_MODE_MASK 0x00100 Description: captureMode in SCAN_IMAGE_ACQUISITION structure specifies desired gain for image. #define WAIT_FOR_TRIGGER_MASK 0x00200 Description: not supported #define PREVIEW_MODE_IMAGE_MASK 0x00400 Description: bPreviewImage in SCAN_IMAGE_ACQUISITION structure specifies desired parameter for preview modefor image. #define CAPTURE_MASK_CONFIG_ALL 0x001ff Description: all fields in SCAN_IMAGE_ACQUISITION structure specifies desired parameters for image. #define CAPTURE_MASK_FIXED_AGC 0x00180 Description: not supported #define CAPTURE_MASK_ALL 0x007ff Description: not supported

typedef struct

{

DWORD dwStructSize; DWORD dwMask; DWORD dwWhiteValue; DWORD dwWhiteWindow; DWORD dwMaxNumExposures; SCAN_DUTY_CYCLE illuminatCycle;

Page 166: HC700 SDK Specification

Page 166 of 680

SCAN_DUTY_CYCLE aimerCycle; // Capture time only, not real configuration items SCAN_GAIN fixedGain; DWORD dwFixedExposure; SCAN_FRAME_RATE frameRate; SCAN_AUTOEXPOSURE captureMode; BOOL bWaitForTrigger; BOOL bPreviewImage; } SCAN_IMAGE_ACQUISITION;

Members dwStructureSize

The size of this structure. dwMask

This mask value contains one or more image acquisition masks appropriate to below parameters that are set. See possible mask values above SCAN_IMAGE_ACQUISITION description.

dwWhiteValue

The auto exposure algorithm tries to get a given white value of all of the pixel values of the image, to fall at a target value. This parameter specifies the desired target value. This parameter apply only for automatic capture mode (captureMode=SCAN_AUTOEXPOSURE_PHOTO).

dwWhiteWindow This specifies the window of acceptance around the dwWhiteValue value. The resulting goal becomes dwWhiteValue +/- dwWhiteWindow. This parameter apply only for automatic capture mode (captureMode=SCAN_AUTOEXPOSURE_PHOTO).

illuminatCycle Specifies if illumination will be On/Off during the image capture. This parameter apply only for automatic and manual capture modes (captureMode=SCAN_AUTOEXPOSURE_PHOTO or captureMode=SCAN_AUTOEXPOSURE_MANUAL).

dwMaxNumExposures Specifies the maximum number the imager will capture image in auto-exposure mode. This parameter apply only for automatic capture mode (captureMode=SCAN_AUTOEXPOSURE_PHOTO).

aimerCycle Specifies if aimers will be On/Off during the image capture. This parameter apply only for automatic and manual capture modes (captureMode=SCAN_AUTOEXPOSURE_PHOTO or captureMode=SCAN_AUTOEXPOSURE_MANUAL).

fixedGain Specifies the fixed gain value for image acquisition. This parameter apply only for manual capture mode (captureMode=SCAN_AUTOEXPOSURE_MANUAL).

Page 167: HC700 SDK Specification

Page 167 of 680

fixedExposure Specifies the fixed explosure value for image acquisition. This parameter apply only for manual capture mode (captureMode=SCAN_AUTOEXPOSURE_MANUAL).

frameRate This parameter defines the starting frame rate to be used by the auto exposure logic during image acquisition. This parameter apply only for manual capture mode (captureMode=SCAN_AUTOEXPOSURE_MANUAL).

captureMode Specifies an explosure mode to be used for taken image.

bWaitForTrigger Not supported.

bPreviewImage Specifies to get low quality image for faster transfer.

SCAN_DUTY_CICLE

Description

The SCAN_DUTY_CYCLE union represents different power modes use by illumination and aimer ligts in remote imager.

Structure Definition

typedef union

{

SCAN_DUTY_CYCLE_OFF = 0 ,

SCAN_DUTY_CYCLE_ON

} SCAN_DUTY_CICLE;

Members SCAN_DUTY_CYCLE_OFF

The lights are off. SCAN_DUTY_CYCLE_ON

The lights are on. SCAN_GAIN

Description

The SCAN_GAIN union represents valid gain value for fixed gain.

Structure Definition

typedef union

{

Page 168: HC700 SDK Specification

Page 168 of 680

SCAN_GAIN_1x = 1 ,

SCAN_GAIN_2x ,

SCAN_GAIN_4x = 4

} SCAN_DUTY_CICLE;

Members SCAN_GAIN_1x

Usual gain. SCAN_GAIN_2x

Usual gain * 2.

SCAN_GAIN_4x Usual gain * 4..

SCAN_FRAME_RATE

Description

The SCAN_FRAME_RATE union represents the valid values for fixed frame rate.

Structure Definition

typedef union

{

SCAN_1_FRAMES_PER_SEC = 1 ,

SCAN_2_FRAMES_PER_SEC ,

SCAN_3_FRAMES_PER_SEC ,

SCAN_4_FRAMES_PER_SEC ,

SCAN_5_FRAMES_PER_SEC ,

SCAN_6_FRAMES_PER_SEC ,

SCAN_10_FRAMES_PER_SEC = 10,

SCAN_12_FRAMES_PER_SEC = 12,

SCAN_15_FRAMES_PER_SEC = 15,

SCAN_20_FRAMES_PER_SEC = 20,

SCAN_30_FRAMES_PER_SEC = 30,

} SCAN_FRAME_RATE;

Members SCAN_X_FRAMES_PER_SEC

Specifies X frames per seconds. SCAN_AUTOEXPLOSURE

Page 169: HC700 SDK Specification

Page 169 of 680

Description

The SCAN_AUTOEXPLOSURE union represents.

Structure Definition

typedef union

{

SCAN_AUTOEXPLOSURE_BARCODE = 0 ,

SCAN_AUTOEXPLOSURE_PHOTE ,

SCAN_AUTOEXPLOSURE_MANUAL

} SCAN_AUTOEXPLOSURE;

Members SCAN_AUTOEXPLOSURE_BARCODE

Applies auto explosure algorithm for barcode capturing. SCAN_AUTOEXPLOSURE_PHOTE

Applies auto explosure algorithm for image capturing.

SCAN_AUTOEXPLOSURE_MANUAL Applies manual explosure mode.

SCAN_IMAGE_TRANSFER

Description

The SCAN_IMAGE_TRANSFER structure is used to configure a transfer image settings used to transfer captured image.

//Transfer image bitmask values: #define BITS_PER_PIXEL_MASK 0x00001 Description: dwBitsPerPixel in SCAN_IMAGE_TRANSFER structure specifies desired value for bit per pixel of transferred image. #define SUBSAMPLE_VALUE 0x00002 #define SUBSAMPLE_VALUE_MASK 0x00002 Description: dwSubSample in SCAN_IMAGE_TRANSFER structure specifies desired value for subsamplaning of transferred image. #define BOUNDING_RECTANGLE_MASK 0x00004 Description: boundingRect in SCAN_IMAGE_TRANSFER structure specifies desired value for bounding rectangle of transferred image. #define COMPRESSION_MODE_MASK 0x00008 Description: compressionMode in SCAN_IMAGE_TRANSFER structure specifies desired value for compression format of transferred image. #define HISTOGRAM_STRETCH_MASK 0x00010 Description: bHistogrammStrech in SCAN_IMAGE_TRANSFER structure specifies desired value for enhanced contrast of transferred image. #define COMPRESSION_FACTOR_MASK 0x00020

Page 170: HC700 SDK Specification

Page 170 of 680

Description: dwCompressionFactor in SCAN_IMAGE_TRANSFER structure specifies desired value for JPEG compression of transferred image. #define TRANSFER_UPDATE_HWND 0x00040 Description: hTransferNotifyHwnd in SCAN_IMAGE_TRANSFER structure specifies desired window handle for image transfer percent notifications. #define TRANSFER_UPDATE_DWORD 0x00080 Description: pdwTransferPercent in SCAN_IMAGE_TRANSFER structure specifies desired variable pointer for image transfer percent notifications. #define TRANSFER_MASK_ALL 0x000ff Description: all fields in SCAN_IMAGE_TRANSFER structure specify desired parameters. #define TRANSFER_MASK_ALL_NO_NOTIFY 0x0003f Description: all fields besides of hTransferNotifyHwnd and pdwTransferPercent in SCAN_IMAGE_TRANSFER structure specify desired parameters.

Structure Definition

typedef struct

{

DWORD dwStructSize; DWORD dwMask; DWORD dwBitsPerPixel; DWORD dwSubSample; RECT boundingRect; BOOL bHistogrammStrech; SCAN_COMPRESSION_MODE compressionMode; DWORD dwCompressionFactor; HWND hTransferNotifyHwnd; LPDWORD pdwTransferPercent;

} SCAN_IMAGE_TRANSFER;

Members dwStructureSize

The size of this structure. dwMask

This value contains one or more image transfer mask appropriate to below parameters that are set. dwBitsPerPixel

Specifies to get B/W image if equal to 1 or grayscable image if equal to 8.

dwSubSample Image data within the image window can be subsampled. For example, a subsample of 2 means that every other column or every other row is sampled.

Page 171: HC700 SDK Specification

Page 171 of 680

The valid range is 1-10, with 1 equaling no subsample.

boundingRect Specifies the upper left and lower right x and y coordinates bounding the area within the image to transmit (before subsampling).

bHistogrammStretch When Histo Stretch is enabled, the image contrast is enhanced (histogram stretch and median value shift)

compressionMode Specifies the way an image will be transferred. An image can be transferred three ways: uncompressed (None), losslessly compressed (Adaptive Huffman Encoding), or JPEG lossy compressed. The drop down dialog box allows you to indicate the type of transfer compression to use.

dwCompressionFactor Specifies the JPEG compression ratio in case of JPEG compression mode.

hTransferNotifyHwnd Specifies the window handle to receive transferring rate.

pdwTransferPercent Specifies the pointer to DWORD variable to receive transferring rate.

SCAN_COMPRESSION_MODE

Description

The SCAN_COMPRESSION_MODE union represents valid compression mode for image transffering.

Structure Definition

typedef union

{

SCAN_COMPRESSION_MODE_NONE = 0 ,

SCAN_COMPRESSION_MODE_LOSSLES ,

SCAN_COMPRESSION_MODE_LOSSY ,

} SCAN_COMPRESSION_MODE;

Members SCAN_COMPRESSION_MODE_NONE

Transfer image in uncompressed format. SCAN_COMPRESSION_MODE_LOSSLES

Transfer image in grayAdaptiveHuffmanEncoding format.

SCAN_COMPRESSION_MODE_LOSSY Transfer image in JPEG format.

SCAN_REMOTE_DECODE_LIMIT_TIME

Description

Page 172: HC700 SDK Specification

Page 172 of 680

The SCAN_REMOTE_DECODE_LIMIT_TIME structure is used to configure barcode decoder searching times by remote imager.

Structure Definition

typedef struct

{

DWORD dwSearchLimitTime;

DWORD dwDecodeLimitTime;

} SCAN_REMOTE_DECODE_LIMIT_TIME;

Members dwSearchLimitTime

The amount of milliseconds the imager will look for the barcode in captured image. dwDecodeLimitTime

The amount of milliseconds the imager will try to decode the barcode. SCAN_REMOTE_IMAGE_DATA

Description

The SCAN_REMOTE_IMAGE_DATA structure is used to configure properties of remote image to be captured by remote imager.

Structure Definition

typedef struct

{

DWORD dwStructSize;

DWORD dwImageHeight;

DWORD dwImageWidth; SCAN_IMAGE_FORMAT ImageFormat;

DWORD dwCapturedFrames;

DWORD dwGain; DWORD dwExposureTime; DWORD dwUnderexposedPixels; DWORD dwOverexposedPixels; DWORD dwImageDataOffset; DWORD dwImageDataSize;

} SCAN_REMOTE_IMAGE_DATA;

Members

Page 173: HC700 SDK Specification

Page 173 of 680

dwStructSize; \

The size of that structure

dwImageHeight; Height of received image in pixels

dwImageWidth;

Width of received image in pixels ImageFormat;

Format of received image dwCapturedFrames;

Number of frames captured prior to this image dwGain;

Gain value used to capture this image dwExposureTime;

Exposure time used to capture this image dwUnderexposedPixels;

Number of underexposed pixels in image dwOverexposedPixels;

Number of overexposed pixels in image dwImageDataOffset;

The offset of received image data from starting address of this structure dwImageDataSize

The size of received image data SCAN_REMOTE_IQ_IMG_PARAMS

Description

The SCAN_REMOTE_IQ_IMG_PARAMS structure is used to configure properties of remote image to be captured by remote imager.

Structure Definition

typedef struct

{

DWORD dwAspectRatio;

int nCenterXOffset; int nCenterYOffset;

DWORD dwImageHeight; DWORD dwImageWidth;

Page 174: HC700 SDK Specification

Page 174 of 680

DWORD dwResolution; DWORD dwReserved1; DWORD dwReserved2;

} SCAN_REMOTE_IQ_IMG_PARAMS;

Members

dwAspectRatio The ratio of the bar code height to the narrow element width. In the example, the narrow element width is .010 inches and the bar code height is 0.400 inches, resulting in a value of S = 0.4/0.01 = 40.

nCenterXOffset The offset (in intelligent barcode units) on X of desired image's center from the center of the barcode label

nCenterYOffset

The offset (in intelligent barcode units) on Y of desired image's center from the center of the barcode label

dwImageHeight The height of desired image in intelligent barcode units

dwImageWidth

The width of desired image in intelligent barcode units dwResolution

The number of pixels per intelligent barcode unit. SCAN_PROGRESS

Description

The SCAN_PROGRESS structure is used for progress indication during image transfer or firmware upgrade operations.

Structure Definition

typedef struct

{

SCAN_FIRMWARE_TYPE ProgrammingFirmwareType; DWORD dwTransferProgress;

SCAN_TRANSFER_STATUS dwTransferStatus;

DWORD dwProgrammingProgress;

SCAN_PROGRAMM_STATUS dwProgrammingStatus;

} SCAN_PROGRESS;

Members

Page 175: HC700 SDK Specification

Page 175 of 680

ProgrammingFirmwareType

This parameter provides the firmware type that is being upgraded now. dwTransferProgress

This value contains the number from 0 to 100 and represents the percent of imager’s firmware or image transfer.

dwTransferStatus

This value indicates the current imager’s firmware or image transfer status. dwProgrammingProgress

This value contains the number from 0 to 100 and represents the percent of programming imager’s firmware.

dwProgrammingStatus

This value indicates the current imager’s firmware programming status. Upon new firmware will be programmed completely on remote imager, this variable will be equal to SCAN_PROGRAMM_COMPLETED value.

SCAN_TRANSFER_STATUS

Description

The SCAN_TRANSFER_STATUS enumeration is used to determine the status of imager’s firmware or image transfer to/from remote imager.

Structure Definition

typedef enum

{

SCAN_TRANSFER_COMPLETED = 0, SCAN_TRANSFER_NOTSTARTED, SCAN_TRANSFER_INPROGRESS, SCAN_TRANSFER_ERROR_FILE, SCAN_TRANSFER_ERROR_FORMAT, SCAN_TRANSFER_ERROR_SIZE, SCAN_TRANSFER_ERROR_COMM,

} SCAN_TRANSFER_STATUS;

Members SCAN_TRANSFER_COMPLETED

An imager firmware or image was transferred successfully.

SCAN_TRANSFER_NOTSTARTED An imager firmware or image transfer process was not started yet.

SCAN_TRANSFER_INPROGRESS An imager firmware or image transfer process is in progress.

SCAN_TRANSFER_ERROR_FILE An imager firmware file that is provided can not be opened or read.

SCAN_TRANSFER_ERROR_FORMAT An imager firmware provided does not match real firmware format and structure.

Page 176: HC700 SDK Specification

Page 176 of 680

SCAN_TRANSFER_ERROR_SIZE An imager firmware provided has incorrect size.

SCAN_TRANSFER_ERROR_COMM Communication error occured.

SCAN_PROGRAMM_STATUS

Description

The SCAN_PROGRAMM_STATUS enumeration is used to determine the status of imager’s firmware programming on remote imager.

Structure Definition

typedef enum

{

SCAN_PROGRAMM_COMPLETED = 0, SCAN_PROGRAMM_NOTSTARTED, SCAN_PROGRAMM_INPROGRESS, SCAN_PROGRAMM_ERROR_HEADER , SCAN_PROGRAMM_ERROR_MISMATCH , SCAN_PROGRAMM_ERROR_DOWNLOAD , SCAN_PROGRAMM_ERROR_PROGRAMMING , SCAN_PROGRAMM_ERROR_BATTERY_LOW , SCAN_PROGRAMM_ERROR_PASSKEY

} SCAN_PROGRAMM_STATUS;

Members SCAN_PROGRAMM_COMPLETED

An imager firmware was programmed successfully.

SCAN_PROGRAMM_NOTSTARTED An imager firmware programming process was not started yet.

SCAN_PROGRAMM_INPROGRESS An imager firmware programming process is in progress.

SCAN_PROGRAMM_ERROR_HEADER An imager firmware file has erroneous header.

SCAN_PROGRAMM_ERROR_MISMATCH Provided application firmware file is to large.

SCAN_PROGRAMM_ERROR_DOWNLOAD The firmware was not transferred successfully.

SCAN_PROGRAMM_ERROR_PROGRAMMING The firmware was not programmed successfully.

SCAN_PROGRAMM_ERROR_BATTERY_LOW The programming process disallowed because of imager's battery in low power.

SCAN_PROGRAMM_ERROR_PASSKEY

Page 177: HC700 SDK Specification

Page 177 of 680

BlueTooth passkey error.

SCAN_SYM_CONFIG

Description

The SCAN_SYM_CONFIG structure is used to keep symbologie’s parameters.

Structure Definition

typedef struct

{

DWORD dwStructSize;

SCAN_CODABAR_CFG codabar;

SCAN_CODE11_CFG code11;

SCAN_CODE128_CFG code128;

SCAN_CODE39_CFG code39;

SCAN_CODE49_CFG code49;

SCAN_CODE93_CFG code93;

SCAN_COMPOSITE_CFG composite;

SCAN_DATAMATRIX_CFG datamatrix;

SCAN_EAN8_CFG ean8;

SCAN_EAN13_CFG ean13;

SCAN_IATA25_CFG iata25;

SCAN_INT25_CFG int2of5;

SCAN_ISBT_CFG isbt;

SCAN_UCCEAN128_CFG uccean128;

SCAN_MSI_CFG msi;

SCAN_UPCA_CFG upcA;

SCAN_UPCE_CFG upcE;

SCAN_AUSPOST_CFG australiaPost;

SCAN_BPO_CFG britishPost;

SCAN_CANPOST_CFG canadaPost;

SCAN_DUTCHPOST_CFG dutchPost;

SCAN_JAPOST_CFG japanPost;

Page 178: HC700 SDK Specification

Page 178 of 680

SCAN_PLANET_CFG usPlanet;

SCAN_POSTNET_CFG usPostnet;

SCAN_AZTEC_CFG aztec;

SCAN_MESA_CFG aztecMesa;

SCAN_CODABLOCK_CFG codablock;

SCAN_MAXICODE_CFG maxicode;

SCAN_MICROPDF_CFG microPDF;

SCAN_PDF417_CFG pdf417;

SCAN_QR_CFG qr;

SCAN_RSS_CFG rss;

SCAN_TLCODE39_CFG tlCode39;

SCAN_MATRIX25_CFG matrix25;

SCAN_KORPOST_CFG koreaPost;

SCAN_TRIOPTIC39_CFG trioptic39;

SCAN_COUPONCODE_CFG CouponCode;

} SCAN_SYM_CONFIG;

Members dwStructSize

The size of SCAN_SYM_CONFIG structure. Codabar

The codabar symbology’s parameters. Code11

The code11 symbology’s parameters. Code128

The code128 symbology’s parameters. Code39

The code39 symbology’s parameters. Code49

The code49 symbology’s parameters. Code93

The code93 symbology’s parameters. Composite

The composite symbology’s parameters. Datamatrix

The datamatrix symbology’s parameters. Ean8

The Ean8 symbology’s parameters. Ean13

The Ean13 symbology’s parameters. iata25

The iata25 symbology’s parameters. int2of5

The int2of5 symbology’s parameters.

Page 179: HC700 SDK Specification

Page 179 of 680

isbt The isbt symbology’s parameters.

msi The msi symbology’s parameters.

upcA The upcA symbology’s parameters.

upcE The upcE symbology’s parameters.

australiaPost The australiaPost symbology’s parameters.

britishPost The britishPost symbology’s parameters.

canadaPost The canadaPost symbology’s parameters.

dutchPost The dutchPost symbology’s parameters.

japanPost The japanPost symbology’s parameters.

usPlanet The usPlanet symbology’s parameters.

usPostnet The usPostnet symbology’s parameters.

aztec The Aztec symbology’s parameters.

aztecMesa The aztecMesasymbology’s parameters.

codablock The codablock symbology’s parameters.

maxicode The maxicode symbology’s parameters.

microPDF The microPDF symbology’s parameters.

pdf417 The pdf417symbology’s parameters.

qr The qr symbology’s parameters.

rss The rss symbology’s parameters.

tlCode39 The tlCode39 symbology’s parameters.

matrix25 The matrix25 symbology’s parameters.

koreaPost The koreaPost symbology’s parameters.

trioptic39 The trioptic39 symbology’s parameters.

CouponCode The CouponCode symbology’s parameters.

ScanSymFlagsOnly

Description

Page 180: HC700 SDK Specification

Page 180 of 680

The ScanSymFlagsOnly structure is used to contains symbology parameters without supported symbologies lengths.

Structure Definition

typedef enum

{

DWORD dwStructSize;

DWORD dwMask;

DWORD dwFlags;

} ScanSymFlagsOnly;

Members dwStructSize

Equal to sizeof of ScanSymFlagsOnly structure. dwMask

Specifies the parameters to be retrieved or set. dwFlags

Specifies the parameters itself.

ScanSymFlagsLength

Description

The ScanSymFlagsLength structure is used to contains symbology parameters with supported symbologies lengths.

Structure Definition

typedef enum

{

DWORD dwStructSize;

DWORD dwMask;

DWORD dwFlags;

DWORD dwMinLen;

DWORD dwMaxLen;

} ScanSymFlagsLength;

Members dwStructSize

Equal to sizeof of ScanSymFlagsOnly structure. dwMask

Specifies the parameters to be retrieved or set. dwFlags

Specifies the parameters itself. dwMinLen

Page 181: HC700 SDK Specification

Page 181 of 680

Minimum enabled length of symbology. dwMaxLen

Maximum enabled length of symbology. ScanSymCodeOcr

Description

The ScanSymCodeOcr structure defines the Optical Charater Recognitions (OCR) params.

Structure Definition

typedef struct

{

DWORD dwStructSize;

DWORD dwMask;

SCAN_OCRMode_t ocrMode;

SCAN_OCRDirection_t ocrDirection;

TCHAR tcTemplate [MAX_TEMPLATE_LEN];

TCHAR tcGroupG [MAX_TEMPLATE_LEN];

TCHAR tcGroupH [MAX_TEMPLATE_LEN];

TCHAR tcCheckChar [MAX_CHECK_CHAR_LEN];

} ScanSymCodeOcr;

Members dwStructSize

Equal to sizeof of ScanSymCodeOcr structure. dwMask

This value contains one or more OCR option mask appropriate to below parameters that are set. ocrMode

Specifies which OCR fonts (if any ) are selected for decoding. ocrDirection

This parameter is not supported. tcTemplate

A null-terminated string that indicates one or more template patterns for the OCR decode. tcGroupG

A null-terminated string that represents a list of characters that can be substituted for the lower-case 'g' in the template strings.

tcGroupH A null-terminated string that represents a list of characters that can be substituted for the lower-case 'h' in the template strings.

tcCheckChar A null-terminated string that represents a check character position in the template strings.

ScanOCRMode_t

Description

Page 182: HC700 SDK Specification

Page 182 of 680

The ScanOCRMode_t specifies which OCR fonts (if any) are selected for decoding.

Structure Definition

typedef enum

{

SCAN_OCR_DISABLED = 0,

SCAN_OCR_A,

SCAN_OCR_B,

SCAN_OCR_MONEY,

SCAN_OCR_MICR_UNSUPPORTED,

} ScanOCRMode_t;

Members SCAN_OCR_DISABLED

OCR font disabled. SCAN_OCR_A

A font enabled. SCAN_OCR_B

B font enabled. SCAN_OCR_MONEY

Money font enabled. SCAN_OCR_MICR_UNSUPPORTED

MICR_UNSUPPORTED font enabled.

ScanOCRDirection_t

Description The ScanOCRDirectione_t enumerated integer identifying OCR character orientation.

Structure Definition

typedef enum

{

SCAN_LeftToRight = 0,

SCAN_TopToBottom,

SCAN_RightToLeft,

SCAN_BottomToTop,

} ScanOCRDirection_t;

Members SCAN_LeftToRight

Left to Right character orientation SCAN_TopToBottom

Top to Bottom character orientation SCAN_RightToLeft

Right to Left character orientation

Page 183: HC700 SDK Specification

Page 183 of 680

SCAN_BottomToTop Bottom to Top character orientation

API definitions and macros Aliases for each symbology structure #define SCAN_AZTEC_CFG ScanSymFlagsLength #define SCAN_MESA_CFG ScanSymFlagsOnly #define SCAN_CODABAR_CFG ScanSymFlagsLength #define SCAN_CODE11_CFG ScanSymFlagsLength #define SCAN_CODE128_CFG ScanSymFlagsLength #define SCAN_CODE39_CFG ScanSymFlagsLength #define SCAN_TRIOPTIC39_CFG ScanSymFlagsOnly #define SCAN_COUPONCODE_CFG ScanSymFlagsOnly #define SCAN_CODE49_CFG ScanSymFlagsLength #define SCAN_CODE93_CFG ScanSymFlagsLength #define SCAN_COMPOSITE_CFG ScanSymFlagsLength #define SCAN_DATAMATRIX_CFG ScanSymFlagsLength #define SCAN_EAN8_CFG ScanSymFlagsOnly #define SCAN_EAN13_CFG ScanSymFlagsOnly #define SCAN_INT25_CFG ScanSymFlagsLength #define SCAN_MAXICODE_CFG ScanSymFlagsLength #define SCAN_MICROPDF_CFG ScanSymFlagsLength #define SCAN_OCR_CFG SymCodeOCR_t #define SCAN_PDF417_CFG ScanSymFlagsLength #define SCAN_POSTNET_CFG ScanSymFlagsOnly #define SCAN_QR_CFG ScanSymFlagsLength #define SCAN_RSS_CFG ScanSymFlagsLength #define SCAN_UPCA_CFG ScanSymFlagsOnly #define SCAN_UPCE_CFG ScanSymFlagsOnly #define SCAN_ISBT_CFG ScanSymFlagsOnly #define SCAN_UCCEAN128_CFG ScanSymFlagsOnly #define SCAN_BPO_CFG ScanSymFlagsOnly #define SCAN_CANPOST_CFG ScanSymFlagsOnly #define SCAN_AUSPOST_CFG ScanSymFlagsOnly #define SCAN_IATA25_CFG ScanSymFlagsLength #define SCAN_CODABLOCK_CFG ScanSymFlagsLength #define SCAN_JAPOST_CFG ScanSymFlagsOnly #define SCAN_PLANET_CFG ScanSymFlagsOnly #define SCAN_DUTCHPOST_CFG ScanSymFlagsOnly #define SCAN_MSI_CFG ScanSymFlagsLength #define SCAN_CFGLCODE39_CFG ScanSymFlagsOnly #define SCAN_MATRIX25_CFG ScanSymFlagsLength #define SCAN_KORPOST_CFG ScanSymFlagsLength Configuration definitions for each symbology #define SCAN_SYMBOLOGY_ENABLE 0x00000001 // Enable Symbology bit #define SCAN_SYMBOLOGY_CHECK_ENABLE 0x00000002 // Enable usage of check character #define SCAN_SYMBOLOGY_CHECK_TRANSMIT 0x00000004 // Send check character

Page 184: HC700 SDK Specification

Page 184 of 680

#define SCAN_SYMBOLOGY_START_STOP_XMIT 0x00000008 // Include the start and stop characters in the decoded result string #define SCAN_SYMBOLOGY_ENABLE_APPEND_MODE 0x00000010 // Code39 append mode #define SCAN_SYMBOLOGY_ENABLE_FULLASCII 0x00000020 // Enable Code39 Full ASCII #define SCAN_SYMBOLOGY_NUM_SYS_TRANSMIT 0x00000040 // UPC-A/UPC-e Send Num Sys #define SCAN_SYMBOLOGY_2_DIGIT_ADDENDA 0x00000080 // Enable 2 digit Addenda (UPC & EAN) #define SCAN_SYMBOLOGY_5_DIGIT_ADDENDA 0x00000100 // Enable 5 digit Addenda (UPC & EAN) #define SCAN_SYMBOLOGY_ADDENDA_REQUIRED 0x00000200 // Only allow codes with addenda (UPC & EAN) #define SCAN_SYMBOLOGY_ADDENDA_SEPARATOR 0x00000400 // Include Addenda separator space in returned string. #define SCAN_SYMBOLOGY_EXPANDED_UPCE 0x00000800 // Extended UPC-E #define SCAN_SYMBOLOGY_UPCE1_ENABLE 0x00001000 // UPC-E1 enable (use SCAN_SYMBOLOGY_ENABLE for UPC-E0) #define SCAN_SYMBOLOGY_COMPOSITE_UPC 0x00002000 // Enable UPC composite codes #define SCAN_SYMBOLOGY_AZTEC_RUNE 0x00004000 // Enable Aztec Run #define SCAN_SYMBOLOGY_MAXICODE_SCM_ONLY 0x00008000 // Maxicode send SCM only. #define SCAN_SYMBOLOGY_AUSTRALIAN_BAR_WIDTH 0x00010000 // Include australian postal bar data in string // We reuse flags for MESA since MESA has no addenda, Extended UPC-E or UPC-E1 enable flags #define SCAN_SCAN_SYMBOLOGY_ENABLE_MESA_IMS 0x00020000 // Mesa IMS enable #define SCAN_SYMBOLOGY_ENABLE_MESA_1MS 0x00040000 // Mesa 1MS enable #define SCAN_SYMBOLOGY_ENABLE_MESA_3MS 0x00080000 // Mesa 3MS enable #define SCAN_SYMBOLOGY_ENABLE_MESA_9MS 0x00100000 // Mesa 9MS enable #define SCAN_SYMBOLOGY_ENABLE_MESA_UMS 0x00200000 // Mesa UMS enable #define SCAN_SYMBOLOGY_ENABLE_MESA_EMS 0x00400000 // Mesa EMS enable #define SCAN_SYMBOLOGY_ENABLE_MESA_MASK 0x007E0000 // For RSE,RSL,RSS there is only one symbology ID so we use 3 flags for enable #define SCAN_SYMBOLOGY_RSE_ENABLE 0x00800000 // Enable RSE Symbology bit #define SCAN_SYMBOLOGY_RSL_ENABLE 0x01000000 // Enable RSL Symbology bit #define SCAN_SYMBOLOGY_RSS_ENABLE 0x02000000 // Enable RSS Symbology bit #define SCAN_SYMBOLOGY_RSX_ENABLE_MASK 0x03800000 // For OCR we reuse flags since none of the other flags apply to OCR #define SCAN_SYMBOLOGY_ENABLE_OCR_A 0x00000001 // OCR-A enable. #define SCAN_SYMBOLOGY_ENABLE_OCR_B 0x00000002 // OCR-B enable. #define SCAN_SYMBOLOGY_ENABLE_OCR_MONEY 0x00000004 // OCR-Money enable. #define SCAN_SYMBOLOGY_ENABLE_OCR_MICR 0x00000008 // OCR-Micr enable. // Symbology structure set masks #define SCAN_SYM_MASK_FLAGS 0x00000001 // Flags are valid #define SCAN_SYM_MASK_MIN_LEN 0x00000002 // Min Length valid #define SCAN_ SYM_MASK_MAX_LEN 0x00000004 // Max Length valid #define SCAN_SYM_MASK_OCR_MODE 0x00000008 // OCR mode valid #define SCAN_SYM_MASK_TEMPLATE 0x00000020 // OCR template valid. #define SCAN_SYM_MASK_GROUP_H 0x00000040 // OCR group H valid. #define SCAN_SYM_MASK_GROUP_G 0x00000080 // OCR group H valid. #define SCAN_SYM_MASK_CHECK_CHAR 0x00000100 // OCR check char valid. #define SCAN_SYM_MASK_ALL 0xffffffff

Page 185: HC700 SDK Specification

Page 185 of 680

Example #include <ScanCApi.h> ... #define BUFFER_SIZE (24*1024) ... HANDLE hScanner; DWORD dwResult; dwResult = SCAN_Open(TEXT("BT_Server"), &hScanner); if( dwResult != E_SCN_SUCCESS ) { ReportError("Error opening remote imager"); return; } CreateThread(... , ProcessWorkingThread, &hScanner , ...); ... ... ... SCAN_Close(hScanner); ... ... ... DWORD WINAPI ProcessWorkingThread(LPVOID lpParameter) { HANDLE hEvent; DWORD dwRes; LPScan_Decode_Msg lpScnBuffer; LPSCAN_PICTURE lpScnPicture; HANDLE hEvent; HANDLE hScanner = *(LPHANDLE)lpParameter; // Create automatic event to wait for notifications hEvent = CreateEvent(NULL, FALSE, FALSE, NULL); if( ! hEvent ) { ReportError("Win32 error"); return 0; } // Allocate buffer for notifucation data LPBYTE pBuffer = malloc(BUFFER_SIZE); if( ! pBuffer ) {

Page 186: HC700 SDK Specification

Page 186 of 680

ReportError("Out of memory"); CloseHandle(hEvent); return 0; } // Register for waiting notifications on event dwRes = SCAN_RegisterNotifications(hScanner, hEvent, NULL, NULL); if( dwRes != E_SCN_SUCCESS ) { ReportError("SCAN_RegisterNotifications", dwRes); CloseHandle(hEvent); free(pBuffer); return 0; } // Enable barcode scaning dwRes = SCAN_Enable(hScanner); if( dwRes != E_SCN_SUCCESS ) { ReportError("SCAN_Enable", dwRes); CloseHandle(hEvent); free(pBuffer); return 0; } while( ! g_bStop ) { // Wait for notification events from remote imager dwRes = WaitForSingleObject(hEvent, 1000); // Implement not forever blocking mechanism if( dwRes != WAIT_OBJECT_0 ) { if( g_bStop ) break; else continue; } // Scanner notification received // Read notification type and data SCAN_NOTIFICATION_TYPE notifyType; dwRes = SCAN_GetNotificationResult(hScanner, &notifyType, pBuffer, BUFFER_SIZE); if( dwRes != E_SCN_SUCCESS ) { ReportError("SCAN_GetNotificationResult failed", dwRes); continue; } // Recognize notification type switch( notifyType )

Page 187: HC700 SDK Specification

Page 187 of 680

{ case SCAN_NOTIFY_REMOTE_CONNECT: ... ShowMessage("Remote imager connected"); ... // Send set of desired parameters

DWORD dwResult, dwParamSize; SCAN_PARAM_TYPE paramType =

SCAN_PARAM_TYPE_SYMBOLOGY; SCAN_SYM_CONFIG SymbologyParams;

dwParamSize = sizeof(SCAN_SYM_CONFIG);

memset(&SymbologyParams, 0, sizeof(SymbologyParams) );

// Disable code 39

SymbologyParams. code39. dwMask = SCAN_SYM_MASK_FLAGS;

SymbologyParams. code39. dwFlags &=

~SCAN_SYMBOLOGY_ENABLE;

dwResult = SCAN_SetImagerParams(hScanner, paramType, &SymbologyParams, &dwParamSize );

… break; case SCAN_NOTIFY_REMOTE_DISCONNECT: ... ShowMessage("Remote imager disconnected"); ... break; case SCAN_NOTIFY_REMOTE_BARCODE: // Perform casting to SCAN_BUFFER structure lpScnBuffer = (LPScan_Decode_Msg)pBuffer; // Print the barcode PrintBarcodeMessage(lpScnBuffer-> pchMessage); ... // Send acknoledge to remote scanner to proceed SCAN_AcknowledgeResponse(hScanner,

SCAN_ACKNOWLEDGE_TYPE_1); ... break; case SCAN_NOTIFY_REMOTE_IMAGE: // Perform casting to SCAN_IMAGE_DATA structure

Page 188: HC700 SDK Specification

Page 188 of 680

lpScnPicture = (LPSCAN_IMAGE_DATA)pBuffer; ... ShowPicture(lpScnPicture+lpScnPicture. DwImageDataOffset,

lpScnPicture. DwImageDataSize); ... break; } } SCAN_DeRegisterNotifications(hScanner); free(pBuffer); CloseHandle(hEvent); }

Page 189: HC700 SDK Specification

Page 189 of 680

Wireless Imager Return Values

E_SCN_SUCCESS 0x0 The function completed successfully E_SCN_NOTENOUGHMEMORY 0xA0000005 An attempt to allocate memory failed. E_SCN_NOTINITIALIZED 0xA0000008 The driver was accessed before a successful initialization.

E_SCN_INVALIDDEVICE 0xA000000A The physical device driver (PDD) DLL did not contain the required entry points.

E_SCN_DEVICEFAILURE 0xA000000B Required device is not present, already in use or not functioning properly.

E_SCN_NOTENABLED 0xA0000010 An attempt was made to access the scanner device and it was not enabled.

E_SCN_NULLPTR 0xA0000013 A NULL pointer was passed for a required argument.

E_SCN_STRUCTSIZE 0xA0000017 A STRUCT_INFO structure field is invalid. Either dwAllocated or dwUsed is less than the size of STRUCT_INFO or dwUsed is greater than dwAllocated.

E_SCN_INVALIDHANDLE 0xA0000019 An invalid handle was passed to a function.

E_SCN_INVALIDPARAM 0xA000001A The value of a parameter either passed as an argument to a function or as a member of a structure is out of range or conflicts with other parameters.

E_SCN_CREATETHREAD 0xA000001C Unable to create a required thread. E_SCN_READCANCELLED 0xA000001D A read request was cancelled. E_SCN_READTIMEOUT 0xA000001E A read request timed out. E_SCN_BUFFERTOOSMALL 0xA0000021 Data buffer is too small for incoming data.

E_SCN_NOTSUPPORTED 0xA0000026 Version of function not supported (e.g. ANSI vs. UNICODE).

E_SCN_NOMOREITEMS 0xA0000028 No more items are available to be returned from SCAN_FindFirst/SCAN_FindNext.

E_SCN_CANTOPENREGKEY 0xA0000029 A required registry key could not be opened. E_SCN_CANTREADREGVAL 0xA000002A A required registry value could not be read.

E_SCN_EXCEPTION 0xA000002B An exception occurred while trying to call the scanner driver.

E_SCN_WIN32ERROR 0xA000002C A scanner API function failed with a non-scanner API error code. Call GetLastError to get extended error code.

E_SCN_ALREADYINUSE 0xA000002D A requested scanner resource is already in use. E_SCN_COMPRESSION 0xA000002F An error occurred during the image compression.

E_SCN_DECOMPRESSION 0xA0000030 An error occurred during the image decompression.

E_SCN_NOTCONNECTED 0xA0000031 A imager device does not connected to host

E_SCN_BOOTCONNECTED 0xA0000032 A imager was connected to host and runs in boot code

E_SCN_UNKNOWNEVENTTYPE 0xA0000033 Unknown event type received from imager device

E_SCN_UNKNOWNSYMBOLOGYTYPE 0xA0000034 Unknown symbology type received from imager device

E_SCN_UPGRADE 0xA0000035 Imager device upgrade operation faied

E_SCN_INVALIDRESULT 0xA0000036 Operation invalid result was received from imager

Page 190: HC700 SDK Specification

Page 190 of 680

E_SCN_CAPTUREIMAGE 0xA0000037 Capture image failed by imager device

E_SCN_SHIPIMAGE 0xA0000038 Shipping image failed by imager device

E_SCN_ALREADYREGISTERED 0xA0000039 Specified handle or windows is already registered

E_SCN_INTERNALERROR 0xA000003A Internal software error occured

E_SCN_NONOTIFICATION 0xA000003B No notification received

E_SCN_DRIVER 0xA000003C An image was requested using an invalid image region.

E_SCN_FILEINVALID 0xA000003D The file was not a valid firmware upgrade file.

Page 191: HC700 SDK Specification

P

4. Wireless Imager Usage Scenario Signature Capturing Scenarios

• For internal imager:

Call SCAN_ReadLabelEvent(hEvent) to read a barcode.

Wait for barcode on event provided by SCAN_ReadLabelEvent

Start signature capture screen. bSignatureCapture = TRUE;

bSignatureCapture == TRUE

Pr

Call SCAN_GetIntelligentImage(TRUE)

Process Signature Capture received

No

Yes

age 191 of 680

rocess Barcode label eceived.

Page 192: HC700 SDK Specification

• For wireless imager:

Start signature capture screen. bSignatureCapture = TRUE;

Call SCAN_RegisterNotifications(hEvent) to register to receive all notifications from imager.

P

Wait for barcode notification on event provided by SCAN_RegisterNotifications

bSignatureCapture == TRUE

Pr

Call SCAN_GetIntelligentImage(FALSE)

Call SCAN_SetSoftTrigger to scan the barcode label

Wait for image notification on event provided by SCAN_RegisterNotifications

Process signature capture received.

No

Yes

age 192 of 680

rocess Barcode label eceived.

Page 193: HC700 SDK Specification

Page 193 of 680

5. Wireless imager specifications

Wireless Imager States

B.T Security Mode 3

Connection Scenarios

Scanning Scenarios

Wireless Imager Led/Beep

Page 194: HC700 SDK Specification

Page 194 of 680

Wireless Imager States

SSttaarrttuupp

IIDDLLEE

CCoonnnneeccttiinngg……

SSccaannnniinngg// ccoommmmaannddss……

CClleeaannuupp

BT Connection

Fatal BT Fail

Temporary BT Fail

Trigger + BD_ADDR

Trigger + PassKey For changing Passkey only

BT Remote Connection

BT Disconnect from Terminal

Page 195: HC700 SDK Specification

Page 195 of 680

B.T Security mode 3

The HC700 and HFI are configured for Bluetooth Security mode 3 and encryption by default.

A single static up to 16 characters Passkey will be supported.

The HFI will have a Motorola factory default Passkey. The user can define a customer PasskKey by reading a special label. Following the passkey change all-new connection will use the new Passkey The Passkey can be updated only when not connected to HC700.

The special label will be Code 128 /Code 39/ Aztec label with the following syntax: P<New Passkey>-

i.e: For passkey ABCDEFGH12345678 the label will contain text PABCDEFGH12345678-

The Motorola default Passkey will be 1234.

The label for it is as follows:

User perspective for replacing a Passkey:

• Reset the HFI, by removing and inserting the battery

• Read Passkey label, for updating Passkey in flash

• Read B.T address, for B.T connection using the saved pass key.

Page 196: HC700 SDK Specification

Page 196 of 680

Connection Scenario The first step prior to scanning is to connect HC700 and the Wireless imager. The user can know if the devices are connected or not by the Wireless Imager led indication as described in section 5. The connection can be initiated by the Wireless imager or by the HC700.

Option 1: Connection is initiated by Wireless imager

Following are the steps for connection:

1. HC700 application should get ready for connection, by calling an API SCAN_OPEN(“BT_Server:“).

3. HC700 application should register for a notifications by calling SCAN_RegisterNotifications()

4. HC700 application enable scanning by calling SCAN_Enable()

5. The user should manually Reset Wireless Imager by taking the battery out and then in. The yellow Led will blink indicating that the wireless imager is not connected.

6. Wireless Imager reads HC700 BD_Address from a label placed on the HC700.

7. The user waits until HC700 and Wireless Imager are connected, yellow led will stop blinking and a beep on Wireless imager will be sound.

8. HC700 Application waits for SCAN_NOTIFY_REMOTE_CONNECT event.

Following are failure scenarios :

1. In case the wireless Imager fails to read a BD Address label, after a timeout of 5 seconds the wireless Imager will stop trying to read a label (The Wireless imager indicates a bed label read by beep sound).

3. In case that the label is not a valid BD_Address then the connection will fail after a timeout of 20 seconds.

4. Note: Timeouts can be changed by the application, for details see Wireless Imager SDK.

Option 2: Connection is initiated by HC700 (As a fallback, if HC700 does not have BD_Address label.)

Following are steps for connection:

1. The user should reset Wireless Imager by taking the battery out and then in.

2. The user should find out Wireless imager BD_Address

3. HC700 application should get ready for connection, by calling an API SCAN_OPEN(“BT_Sever:”).

4. HC700 application should register to a notification by calling SCAN_RegisterNotifications()

Page 197: HC700 SDK Specification

Page 197 of 680

5. HC700 application enable scanning by calling SCAN_Enable()

6. HC700 Application connect to Wireless Imager by calling SCAN_RemoteConfig() API, with wireless Imager BD_Address

7. The user waits until HC700 and Wireless Imager are connected, yellow led will stop blinking and a beep will be sound on the wireless imager.

8. HC700 Application waits for SCAN_NOTIFY_REMOTE_CONNECT event.

Following are failure scenarios :

1. If the BD address provided by SCAN_RemoteConfig() is not legal then SCAN_RemoteConfig() will return an error.

2. If the BD address provided by SCAN_RemoteConfig() is legal but device is not accesable then after a timeout the SCAN_RemoteConfig() will return an error. In the timeout period the SCAN_RemoteConfig() will be blocked.

Page 198: HC700 SDK Specification

Page 198 of 680

Scanning Scenarios After the Wireless Imager and HC700 are connected the Wireless imager can scan a labels. There are two types of scanning: a single label read or continues labels read. There are two types of scan initiator: software command or hardware trigger (hardware function key or proximity) as described in the following scenarios.

Option 1: Single Mode/Software Trigger from the HC700 In this mode the HC700 application initiate one single scanning. An example of such implementation can be as follows: HC700 application waits until the user press on HC700 SCAN key and then call SCAN_SetSoftTrigger(“Single Scan”) to start scanning. The following diagram describes the steps that the HC700 and the Wireless imager are doing for single scanning. Following are the steps for Single mode/Software trigger:

1. HC700 Application start a label read by calling SCAN_SetSoftTrigger(“Single Scan”) 2. Wireless Imager reads a barcode

HC700 Wireless Imager

“47644”

ACK1/ACK2…

Good/Bad Read indication

ACK Timeout indication No Barcode

SCAN_Get Notification Result

SCAN_Acknowledge Response

Set Soft Trigger()

Start Scan

Page 199: HC700 SDK Specification

Page 199 of 680

3. Wireless Imager send the barcode to HC700 4. HC700 Application get the event notification: SCAN_NOTIFY_REMOTE_BARCODE. 5. HC700 Application gets the label by calling SCAN_Get Notification Result() API 7. HC700 Application sends acknowledge to wireless imager by calling

SCAN_AcknowledgeResponse() 8. Wireless imager indicate the result to the user by LED/Beep

Following are failure scenarios

• In case the wireless Imager fails to read a label after a timeout of 5 seconds the wireless Imager will stop trying to read a label.

• In case the HC700 does not send acknowledge to the Wireless Imager, then after timeout the Wireless Imager will stop waiting for acknowledge and will be ready for another scanning.

• In case of B.T disconnection, HC700 Application will get a disconnect event SCAN_NOTIFY_REMOTE_DISCONNECT. In this case the HC700 application can wait for connect event SCAN_NOTIFY_REMOTE_CONNECT or Notify the user. In any case the HC700 application should not call SCAN_RemoteConfig() because the Wireless imager is trying to automatically reconnect for about 20-25 seconds.

Page 200: HC700 SDK Specification

Option 2: Continues Mode/Software Trigger from the HC700 In this mode the HC700 application initiate continues scanning.

HC700 Wireless Imager

“47644”

ACK1/ACK2…

Good/Bad Read indication

SCAN_Get Notification Result

N

ACK Timeout indication

Set Soft Trigger()

Start Scan

o Barcode

Page 200 of 680

Page 201: HC700 SDK Specification

Page 201 of 680

Following are steps for Continues mode/Software trigger:

1. HC700 Application start a label read by calling SCAN_SetSoftTrigger(“Continues Scan”) 2. Wireless Imager reads a barcode 3. Wireless Imager send the barcode to HC700 4. HC700 Application get the event notification SCAN_NOTIFY_REMOTE_BARCODE 5. HC700 Application gets the label by calling SCAN_Get Notification Result() API 7. HC700 Application sends acknowledge to wireless imager by calling

SCAN_AcknowledgeResponse() 8. Wireless imager indicate the result to the user by LED/Beep 9. Wireless imager start scanning the next label.

Following are failure scenarios

1. In case the wireless Imager fails to read a label after a timeout the wireless Imager will stop trying to read a label and will stop the continues mode.

2. In case the HC700 does not send acknowledge to the Wireless Imager, the Wireless Imager will stop waiting for acknowledge and will continue to the next scanning. In this case the continues mode is not stopped.

3. In case of B.T disconnect HC700 Application will get a disconnect event SCAN_NOTIFY_REMOTE_DISCONNECT. In this case the HC700 application can wait for connect event SCAN_NOTIFY_REMOTE_CONNECT or Notify the user. In any case the HC700 application should not call SCAN_RemoteConfig() because the Wireless imager is trying to reconnect for about 20-25 seconds. After the reconnection the Wireless imager stops the continues mode and it is the HC700 responsibility to set again the continues mode.

Page 202: HC700 SDK Specification

Option 3: Single Mode/Hardware Trigger from the Wireless Imager In this mode the Wireless imager initiate one scanning. The Wireless imager can initiate a scanning by the user pressing the function key on the wireless imager, or by the proximity sensor in the wireless imager indicating that an object is in front of the imager and it will start scanning.

HC700 Wireless Imager

“47644”

ACK1/ACK2…

Good/

ACK TimNo

SCAN_Get Notification Result

SCAN_Acknowledge Response

F

unction Key

Page 202 of 680

Bad Read indication

eout indication Barcode

Page 203: HC700 SDK Specification

Page 203 of 680

Following are steps for Single mode/Hardware trigger:

1. The user press the function key on the wireless imager or set the wireless imager in front of the label. 2. Wireless Imager reads a barcode 3. Wireless Imager send the barcode to HC700 4. HC700 Application get the event notification SCAN_NOTIFY_REMOTE_BARCODE. 5. HC700 Application gets the label by calling SCAN_Get Notification Result() API 7. HC700 Application sends acknowledge to wireless imager by calling

SCAN_AcknowledgeResponse() 8. Wireless imager indicate the result to the user by LED/Beep

Following are failure scenarios

1. In case the wireless Imager fails to read a label after a timeout the wireless Imager will stop trying to read a label.

2. In case the HC700 does not send acknowledge to the Wireless Imager, then after timeout the Wireless Imager will stop waiting for acknowledge and will be ready for another scanning.

3. In case of B.T disconnection, HC700 Application will get a disconnect event SCAN_NOTIFY_REMOTE_DISCONNECT. In this case the HC700 application can wait for connect event SCAN_NOTIFY_REMOTE_CONNECT or notify the user. In any case the HC700 application should not call SCAN_RemoteConfig() because the Wireless imager is trying to automatically reconnect for about 20-25 seconds.

Page 204: HC700 SDK Specification

Option 4: Continues Mode/Hardware Trigger from the Wireless Imager In this mode the Wireless imager initiate continues scanning. The wireless imager can initiate a scanning by the user double pressing the function key on the wireless imager.

HC700 Wireless Imager

“47644”

ACK1/ACK2…

Good/Bad

SCAN_Get Notification Result

SCAN_Acknowledge Response

ACK Time

Function Key

Read indication

out indication

No Barcode

Page 204 of 680

Page 205: HC700 SDK Specification

Page 205 of 680

Following are steps for Continues mode/Hardware trigger:

1. The user double click on the function key on the wireless imager. 2. Wireless Imager reads a barcode 3. Wireless Imager send the barcode to HC700 4. HC700 Application get the event notification 5. HC700 Application gets the label by calling SCAN_Get Notification Result() API 7. HC700 Application sends acknowledge to wireless imager by calling

SCAN_AcknowledgeResponse() 8. Wireless imager indicate the result to the user by LED/Beep 9. Wireless imager start scanning the next label.

Following are failure scenarios

1. In case the wireless Imager fails to read a label after a timeout the wireless Imager will stop trying to read a label and will stop the continues mode.

2. In case the HC700 does not send acknowledge to the Wireless Imager, the Wireless Imager will stop waiting for acknowledge and will continue to the next scanning. In this case the continues mode is not stopped.

3. In case of B.T disconnect HC700 Application will get a disconnect event SCAN_NOTIFY_REMOTE_DISCONNECT. In this case the HC700 application can wait for connect event SCAN_NOTIFY_REMOTE_CONNECT or Notify the user. In any case the HC700 application should not call SCAN_RemoteConfig() because the Wireless imager is trying to reconnect for about 20-25 seconds. After the reconnection the Wireless imager stops continues mode.

Page 206: HC700 SDK Specification

Page 206 of 680

Wireless Imager Led/Beep Indication

Description Led Buzzer B.T Disconnected Blink Yellow Beep0 – Every 8 seconds B.T is connecting Steady Yellow B.T connect

Beep1 (100 mili,1350 Hz)(100mili,1800Hz)

B.T is connected B.T Disconnecting blink Red once

Beep2 (100ms,1800Hz) (100 ms,1350 Hz)

B.T connected failed timeout blink Red once Beep3 (160ms,1500Hz)

Successfully scan based on Host indication

blink Green once Beep4 (80ms,3250Hz)

Scan Timeout expired Beep5 (200ms,300Hz)

Unsuccessful scan based on Host indication

blink Red once

Beep6 (80ms,2000Hz)

No host acknowledge after timeout

Red 2 times Beep7 (70ms,120Hz) (70ms,140Hz)(70ms,160Hz

When the Wireless imager and the HC700 are in a B.T connection process then the Wireless imager will be at the following states:

• First the wireless imager is in B.T Disconnected

• After pressing the function key on the wireless imager and reading HC700 B.T label, it will be in B.T is connecting

• After the connection is established the wireless imager will be in B.T connect

• When the connection is successful, the wireless imager will be in B.T is connected states.

Note: The beep duration and frequency can not be configured.

Page 207: HC700 SDK Specification

Page 207 of 680

6. RCM API - Scan Trigger Key Notification Overview The Resource Coordinator Management (RCM) API enables applications to register and to get notification upon a Scan-keys pressing. The registration can be done on up to four (4) different Scan-Keys, where the notification may be delivered either via a windows Event or Window Message.

Note that pressing the ‘Scan trigger Keys’, does not turn on the Scanner beam. Application, when notified, starts and performs the Scan procedure. Following is a typical usage scenario:

• Application registers itself on the Trigger(s) key for either Message - RCM_RegisterTriggerMessage or Event - RCM_RegisterTriggerEvent notification.

• Wait for a Notification either on the event (WaitForSingleObject) or within a Windows Message Loop

• When being notified, examine the state of the Scan trigger (Key) by using - RCM_GetTriggerStatus and RCM_GetLastTriggerStatus

• Typically activate a Scan API to perform a Scan operation The HC700 Device is equipped with three special Scan Trigger keys dedicated for Label Scanning; therefore, the Trigger Mask to be used in all RCM APIs should be TRIG1_STAGE1, TRIG2_STAGE1 or TRIG3_STAGE1 See RCM Trigger Bit Definitions

Functions List Function Description

RCM_RegisterTriggerEvent Triggers notifications, using the specified named event. When the Resource Coordinator detects trigger state changes for the specified triggers, it signals the specified named event.

RCM_RegisterTriggerMessage Triggers notifications, using the specified window handle and message. When the Resource Coordinator detects trigger state changes for the specified triggers, it will post the specified message to the specified window.

RCM_DeregisterTrigger Removes a trigger notification registration. The handle passed by this method identifies a previously registered trigger notification. Once de-registered, notifications are no longer issued.

RCM_GetTriggerRegistration Retrieves the current exclusive trigger registrations. The returned DWORD is a bit-mask indicating which triggers are

RCM_GetTriggerStatus The RCM_GetTriggerStatus function retrieves the current status of the triggers.

Page 208: HC700 SDK Specification

Page 208 of 680

RCM_GetLastTriggerStatus Retrieves the trigger status that caused the previous notification on a registered trigger handle.

RCM_GetVersion Gets the version information for the Resource Coordination API.

RCM_Examples

RCM Error Codes

Data Types

Page 209: HC700 SDK Specification

Page 209 of 680

RCM_RegisterTriggerEvent

Description The RCM_RegisterTriggerEvent function is used by an application to request trigger notifications, using the specified named event. When the Resource Coordinator detects trigger state changes for the specified triggers, it signals the specified named event.

Function Prototype DWORD RCM_RegisterTriggerEvent( DWORD dwTriggerMask BOOL bExclusive, LPTSTR lpszEventName, LPHANDLE lphHandle );

Parameters

dwTriggerMask – [in] A DWORD bit-mask describing the triggers to register for notification. See RCM Trigger Bit Definitions.

BExclusive - [in] A flag indicating that exclusive use of the specified triggers is requested.

LpszEventName - [in]

The name of the event to signal, when the specified trigger state changes.

LphHandle – [out]

A pointer to the returned handle. This handle must be used to deregister the trigger.

Return Values If the function succeeds, the return value is E_RCM_SUCCESS. If the function fails, the return value is a Resource Coordinator specific error code.

Quick Info Windows NT: Unsupported. Windows: Unsupported. Windows CE: Version 2.11 or later. Header: Declared in RcmCAPI.h. Import Library: Use RcmAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example RCM_RegisterTriggerEvent Example

Page 210: HC700 SDK Specification

Page 210 of 680

RCM_RegisterTriggerMessage

Description

The RCM_RegisterTriggerMessage function is used by an application to request trigger notifications, using the specified window handle and message. When the Resource Coordinator detects trigger state changes for the specified triggers, it will post the specified message to the specified window.

Function Prototype DWORD RCM_RegisterTriggerMessage( DWORD dwTriggerMask, BOOL bExclusive, HWND hWnd, UINT uiMessage );

Parameters

dwTriggerMask – [in] A DWORD bit-mask that describing the triggers to register for notification. See RCM Trigger Bit Definitions.

BExclusive - [in] A flag indicating that exclusive use of the specified triggers is requested.

HWnd - [in]

The window handle to which uiMessage will be posted.

UiMessage - [in]

The message ID to be posted to hWnd to notify the application of the specified trigger state change.

LphHandle – [out]

A pointer to the returned handle. This handle must be used to deregister the trigger.

Return Values If the function succeeds, the return value is E_RCM_SUCCESS. If the function fails, the return value is a Resource Coordinator specific error code.

Quick Info Windows NT: Unsupported. Windows: Unsupported. Windows CE: Version 2.11 or later. Header: Declared in RcmCAPI.h. Import Library: Use RcmAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 211: HC700 SDK Specification

Page 211 of 680

RCM_DeregisterTrigger

Description

The RCM_DeregisterTrigger removes a trigger notification registration. The handle passed by this method identifies a previously registered trigger notification. Once de-registered, notifications are no longer issued.

Function Prototype DWORD RCM_DeregisterTrigger( HANDLE hHandle );

Parameters

hHandle – [in]

Handle of a trigger to deregister. This handle must have been returned by a call to RCM_RegisterTriggerEvent or RCM_RegisterTriggerMessage.

Return Values If the function succeeds, the return value is E_RCM_SUCCESS. If the function fails, the return value is a Resource Coordinator specific error code.

Quick Info Windows NT: Unsupported. Windows: Unsupported. Windows CE: Version 2.11 or later. Header: Declared in RcmCAPI.h. Import Library: Use RcmAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example RCM_DeregisterTrigger Example

Page 212: HC700 SDK Specification

Page 212 of 680

RCM_GetTriggerRegistration

Description The RCM_GetTriggerRegistration function retrieves the current exclusive trigger registrations. The returned DWORD is a bit-mask indicating which triggers are exclusively registered for notification.

Function Prototype DWORD RCM_GetTriggerRegistration( LPDWORD lpdwStatus );

Parameters

LpdwStatus – [out]

A pointer to a DWORD bit-mask that, upon function returns, it is being filled with the current

exclusive trigger registration status. See RCM Trigger Bit Definitions.

Return Values If the function succeeds, the return value is E_RCM_SUCCESS. If the function fails, the return value is a Resource Coordinator specific error code.

Quick Info Windows NT: Unsupported. Windows: Unsupported. Windows CE: Version 2.11 or later. Header: Declared in RcmCAPI.h. Import Library: Use RcmAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 213: HC700 SDK Specification

Page 213 of 680

RCM_GetTriggerStatus

Description

The RCM_GetTriggerStatus function retrieves the current status of the triggers.

Function Prototype DWORD RCM_GetTriggerStatus( LPDWORD lpdwTriggerStatus );

Parameters

LpdwTriggerStatus – [out]

A pointer to a DWORD bit-mask that, upon function returns, it is being filled with the current trigger

status. See RCM Trigger Bit Definitions.

Return Values If the function succeeds, the return value is E_RCM_SUCCESS. If the function fails, the return value is a Resource Coordinator specific error code.

Quick Info Windows NT: Unsupported. Windows: Unsupported. Windows CE: Version 2.11 or later. Header: Declared in RcmCAPI.h. Import Library: Use RcmAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 214: HC700 SDK Specification

Page 214 of 680

RCM_GetLastTriggerStatus

Description

The RCM_GetLastTriggerStatus function retrieves the trigger status that caused the previous notification on a registered trigger handle.

Function Prototype DWORD RCM_GetLastTriggerStatus( HANDLE hHandle LPDWORD lpdwTriggerStatus );

Parameters

HHandle – [in]

Handle of a register trigger. This handle must have been returned by a call to RCM_RegisterTriggerEvent or RCM_RegisterTriggerMessage.

LpdwTriggerStatus – [out]

A pointer to a DWORD bit-mask that, upon function returns, it is being filled with the current trigger status.

Return Values If the function succeeds, the return value is E_RCM_SUCCESS. If the function fails, the return value is a Resource Coordinator specific error code.

Quick Info Windows NT: Unsupported. Windows: Unsupported. Windows CE: Version 2.11 or later. Header: Declared in RcmCAPI.h. Import Library: Use RcmAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 215: HC700 SDK Specification

Page 215 of 680

RCM_GetVersion

Description

The RCM_GetVersion function gets the version information for the Resource Coordination API.

Function Prototype DWORD KBD_GetVersion( LPRCM_VERSION_INFO lpVersionInfo );

Parameters lpVersionInfo

[out] Pointer to a RCM_VERSION structure, this pointer is being filed with the version information.

(See RCM_VERSION structure define downstairs)

Return Values If the function succeeds, the return value is E_RCM_SUCCESS. If the function fails, the return value is a Resource Coordinator specific error code.

Quick Info Windows NT: Unsupported. Windows: Unsupported. Windows CE: Version 2.11 or later. Header: Declared in RcmCAPI.h. Import Library: Use RcmAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also RCM_VERSION:

// Version information structure typedef struct tagRCM_VERSION_INFO { STRUCT_INFO StructInfo; // Information about structure extents // HIWORD = major, LOWORD = minor DWORD dwCAPIVersion; DWORD dwResCoordVersion; DWORD dwUUIDVersion; DWORD dwTemperatureVersion; } RCM_VERSION_INFO;

Page 216: HC700 SDK Specification

Page 216 of 680

Examples – RCM API

RCM_RegisterTriggerEvent Example // Create event for hard trigger hTrigEvent = CreateEvent ( 0, FALSE, FALSE, lpszEventName); // Register the event dwStatus = RCM_RegisterTriggerEvent ( dwTriggerMask, bExclusive, lpszEventName, &hTrigger); if (dwStatus != E_RCM_SUCCESS ) MessageBox ( hWindow, _T("RegisterTriggerEvent failed"), _T("Scanner Error"),MB_OK | MB_ICONERROR ); // Wait for signal event WaitForSingleObject ( hTrigEvent, INFINITE );

RCM_DeregisterTrigger Example dwStatus = RCM_DeregisterTrigger( hTrigger ); if (dwStatus != E_RCM_SUCCESS ) MessageBox ( hWindow, T(" DeregisterTrigger failed"),

_T("Scanner Error"),MB_OK | MB_ICONERROR );

Page 217: HC700 SDK Specification

Page 217 of 680

Data Types

RCM Trigger Bit Definitions

Description Trigger Bit Definitions define all trigger bit-masks used by the resource coordinator. Trigger bit-masks are used for reporting trigger status, holding a 1 in the bit position corresponding to each pressed trigger. They are also used for defining which triggers to register or which triggers are already registered for notification.

Structure Definition

#define TRIGGER_STAGE1_MASK 0x000000ff

#define TRIG1_STAGE1 0x00000001

#define TRIG2_STAGE1 0x00000002

#define TRIG3_STAGE1 0x00000004

#define TRIG4_STAGE1 0x00000008

Members None

See Also RCM_GetTriggerRegistration, RCM_GetTriggerStatus, RCM_RegisterTriggerMessage

Page 218: HC700 SDK Specification

Page 218 of 680

UNITID

Description The UNITID structure holds an 8-byte unique unit identification number.

Structure Definition typedef BYTE UNITID[8]; typedef UNITID FAR * LPUNITID;

Members None

RCM_VERSION_INFO // Version information structure typedef struct tagRCM_VERSION_INFO {

STRUCT_INFO StructInfo; // Information about structure extents // HIWORD = major, LOWORD = minor

DWORD dwCAPIVersion;

DWORD dwResCoordVersion;

DWORD dwUUIDVersion;

DWORD dwTemperatureVersion;

} RCM_VERSION_INFO; typedef RCM_VERSION_INFO FAR * LPRCM_VERSION_INFO;

Page 219: HC700 SDK Specification

Page 219 of 680

RCM Error Codes

#define ERROR_BIT 0x80000000 // Use bit 31 to indicate errror #define USER_BIT 0x20000000 // Bit 29 means not Win32 error #define RCM_ERROR(code) (ERROR_BIT | USER_BIT | (WORD) code) #define E_RCM_SUCCESS 0 #define E_RCM_ALREADYINITIALIZED RCM_ERROR(0x0001) #define E_RCM_CREATEEVENTFAILED RCM_ERROR(0x0002) #define E_RCM_CREATETHREADFAILED RCM_ERROR(0x0003) #define E_RCM_NOTENOUGHMEMORY RCM_ERROR(0x0004) #define E_RCM_NOTINITIALIZED RCM_ERROR(0x0005) #define E_RCM_INVALIDDVCCONTEXT RCM_ERROR(0x0006) #define E_RCM_INVALIDOPNCONTEXT RCM_ERROR(0x0007) #define E_RCM_CANTREADREGVALUE RCM_ERROR(0x0008) #define E_RCM_CANTOPENREGKEY RCM_ERROR(0x0009) #define E_RCM_INVALIDIOCTRL RCM_ERROR(0x000A) #define E_RCM_NULLPTR RCM_ERROR(0x000B) #define E_RCM_BADSTRUCTINFO RCM_ERROR(0x000C) #define E_RCM_PARAMMISSING RCM_ERROR(0x000D) #define E_RCM_BUFFERTOOSMALL RCM_ERROR(0x000E) #define E_RCM_MISSINGFIELD RCM_ERROR(0x000F) #define E_RCM_INVALIDHANDLE RCM_ERROR(0x0010) #define E_RCM_INVALIDPARAM RCM_ERROR(0x0011) #define E_RCM_INVALIDDEVICENAME RCM_ERROR(0x0012) #define E_RCM_TRIGGERINUSE RCM_ERROR(0x0013) #define E_RCM_NOTIFYERROR RCM_ERROR(0x0014) #define E_RCM_NOTSUPPORTED RCM_ERROR(0x0015) #define E_RCM_INVALIDCONFIGTYPE RCM_ERROR(0x0016) #define E_RCM_EXCEPTION RCM_ERROR(0x0017) #define E_RCM_WIN32ERROR RCM_ERROR(0x0018)

Page 220: HC700 SDK Specification

Page 220 of 680

7. Display API Overview The Display Driver API manages the display backlight. An application can read the supported terminal’s backlight attribute and use levels to adjust the backlight. Backlight support Get, Set, and Get Levels functions, and Get/Set Backlight State functions. In addition, The DISPLAY_GetVersion function retrieves the version information for the Display API.

Functions List Function Description

DISPLAY_GetBacklightState Returns the current display backlight state information. The valid backlight states are: BACKLIGHT_OFF, BACKLIGHT_ON.

DISPLAY_GetVersion Gets the version information for the Display API.

DISPLAY_SetBacklightState Sets current backlight intensity.

DISPLAY_GetBacklightIntensityLevels This function is called to query the number of supported backlight intensity levels.

DISPLAY_GetBacklightIntensity Returns the current backlight intensity.

DISPLAY_SetBacklightIntensity Sets current backlight intensity.

DISPLAY_GetBacklightTimeout This function is called to query the display backlight timeout value. The display backlight is automatically turned off when the device is idle for more than backlight timeout.

DISPLAY_SetBacklightTimeout Sets the display backlight timeout. The display backlight is automatically turned off when the device is idle for more than backlight timeout.

DISPLAY_EnableTouchPanel Enables or Disables the device Touch Panel (Digitizer). After Device Boot (Warm or Cold) the Touch Panel is enabled.

• Examples • Display Error Codes

• Data Types

Page 221: HC700 SDK Specification

Page 221 of 680

Page 222: HC700 SDK Specification

Page 222 of 680

DISPLAY_GetBacklightState

Description

The DISPLAY_GetBacklightState function returns the current display backlight state information. The valid backlight states are: BACKLIGHT_OFF, BACKLIGHT_ON.

Function Prototype DWORD DISPLAYAPI DISPLAY_GetBacklightState(LPDWORD lpdwBacklightState);

Parameters lpdwBacklightState

Pointer to the DWORD to be filled in with the backlight state.

Return Values

If the function succeeds, the return value is E_DSP_SUCCESS.

If the function fails, the return value is E_DSP_NULLPTR or E_DSP_PWRFAILED.

Comments None

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in DispCAPI.h. Import Library: Use DispAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

dwResult = DISPLAY_GetBacklightState(&dwState);

Click here for complete example

Page 223: HC700 SDK Specification

Page 223 of 680

DISPLAY_SetBacklightState

Description

The DISPLAY_SetBacklightState function sets new backlight state for display only. The valid backlight states are: BACKLIGHT_OFF, BACKLIGHT_ON.

Function Prototype DWORD DISPLAYAPI DISPLAY_SetBacklightState(DWORD dwBacklightState);

Parameters dwBacklightState

The DWORD represents the new device’s backlight state.

Return Values

If the function succeeds, the return value is E_DSP_SUCCESS.

If the function fails, the return value is E_DSP_NULLPTR or E_DSP_PWRFAILED.

Comments

None

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in DispCAPI.h. Import Library: Use DispAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

dwResult = DISPLAY_SetBacklightState(dwState);

Click here for complete example

Page 224: HC700 SDK Specification

Page 224 of 680

DISPLAY_GetVersion

Description

The DISPLAY_GetVersion function gets the version information for the Display API.

Function Prototype DWORD DISPLAYAPI DISPLAY_GetVersion(LPDISPLAY_VERSION_INFO lpDisplayVersionInfo);

Parameters

lpDisplayVersionInfo Pointer to the DISPLAY_VERSION_INFO structure to be filled in with the version info.

Return Values

If the function succeeds, the return value is E_DSP_SUCCESS. If the function fails, the return value is E_DSP_NULLPTR, E_DSP_STRUCTINFO, or E_DSP_MISSINGFIELD.

Comments

None

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in DispCAPI.h. Import Library: Use DispAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.Example

Page 225: HC700 SDK Specification

Page 225 of 680

Example

LPDISPLAY_VERSION_INFO l_lpDisplayVersionInfo; DWORD dwResult;

l_lpDisplayVersionInfo = (DISPLAY_VERSION_INFO*)LocalAlloc(LMEM_FIXED,sizeof(DISPLAY_VERSION_INFO));

SI_ALLOC_ALL(l_lpDisplayVersionInfo); l_lpDisplayVersionInfo->StructInfo.dwUsed = 0; dwResult = DISPLAY_GetVersion(l_lpDisplayVersionInfo); if ( dwResult != E_DSP_SUCCESS) { ReportError(TEXT("DISPLAY_GetVersion Error"),dwResult); } else { TEXTSPRINTF(szMsg,TEXT("%02X.%02X"),HIWORD(l_lpDisplayVersionInfo- >dwCAPIVersion),LOWORD(l_lpDisplayVersionInfo->dwCAPIVersion)); } LocalFree(l_lpDisplayVersionInfo);

Click here for complete example

Page 226: HC700 SDK Specification

Page 226 of 680

DISPLAY_GetBacklightIntensityLevels

Description

This function is called to query the number of supported backlight intensity levels.

Function Prototype DWORD DISPLAYAPI DISPLAY_GetBacklightIntensityLevels (LPDWORD lpdwLevels) ;

Parameters lpdwLevels – Pointer to the DWORD to receive the number of supported backlight levels.

Return Values

If the function succeeds, the return value is E_DSP_SUCCESS.

If the function fails, the return value is E_DSP_ERROR.

Comments The function will always return 1 level.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in DispCAPI.h. Import Library: Use DispAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example dwResult = DISPLAY_ GetBacklightIntensityLevels (&dwLevels);

Click here for complete example

Page 227: HC700 SDK Specification

Page 227 of 680

DISPLAY_GetBacklightIntensity

Description

The DISPLAY_GetBacklightIntensity function returns the current backlight intensity.

Function Prototype DWORD DISPLAYAPI DISPLAY_GetBacklightIntensity(LPDWORD lpdwBacklightIntensity);

Parameters lpdwBacklightIntensity

Pointer to the DWORD to be filled in with the backlight intensity.

Return Values

If the function succeeds, the return value is E_DSP_SUCCESS.

If the function fails, the return value is E_DSP_NULLPTR or E_DSP_PWRFAILED.

Comments

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in DispCAPI.h. Import Library: Use DispAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

dwResult = DISPLAY_GetBacklightIntensity (&dwBacklightIntensity);

Click here for complete example

Page 228: HC700 SDK Specification

Page 228 of 680

DISPLAY_SetBacklightIntensity

Description

The DISPLAY_SetBacklightIntensity function sets current backlight intensity.

Function Prototype DWORD DISPLAYAPI DISPLAY_SetBacklightIntensity(DWORD dwBacklightIntensity);

Parameters dwBacklightIntensity

Double word containing the desired backlight intensity from 0 to the maximum levels returned by DISPLAY_GetBacklightIntensityLevels minus 1.

Return Values

If the function succeeds, the return value is E_DSP_SUCCESS.

If the function fails, the return value is E_DSP_ERROR.

Comments

None

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in DispCAPI.h. Import Library: Use DispAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

dwResult = DISPLAY_SetBacklightState (dwBacklightState);

Click here for complete example

Page 229: HC700 SDK Specification

Page 229 of 680

DISPLAY_GetBacklightTimeout

Description This function is called to query the display backlight timeout value. The display backlight is automatically turned off when the device is idle for more than backlight timeout.

Function Prototype DWORD DISPLAYAPI DISPLAY_GetBacklightTimeout ( PDISPLAY_BACKLIGHT_TIMEOUT lpTimeout )

Parameters

lpTimeout [out] Pointer to a DISPLAY_BACKLIGHT_TIMEOUT structure to receive the current backlight timeout settings.

Return Values

E_DSP_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in Disperr.h.

Comments None.

See Also DISPLAY_SetBacklightTimeout

Page 230: HC700 SDK Specification

Page 230 of 680

DISPLAY_SetBacklightTimeout

Description This function sets the display backlight timeout. The display backlight is automatically turned off when the device is idle for more than backlight timeout.

Function Prototype DWORD DISPLAYAPI DISPLAY_SetBacklightTimeout ( PDISPLAY_BACKLIGHT_TIMEOUT lpTimeout )

Parameters

lpTimeout [in] Pointer to a DISPLAY_BACKLIGHT_TIMEOUT structure that defines the backlight timeout.

Return Values

E_DSP_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in Disperr.h.

Comments None.

See Also DISPLAY_GetBacklightTimeout

Page 231: HC700 SDK Specification

Page 231 of 680

DISPLAY_EnableTouchPanel

Description This function Enables or Disables the device Touch Panel (Digitizer). After Device Boot (Warm or Cold) the Touch Panel is enabled.

Function Prototype DWORD DISPLAYAPI DISPLAY_EnableTouchPanel ( BOOL bTouchPanelEnabled )

Parameters

bTouchPanelEnabled [in] Boolean, set TRUE/FALSE to Enable/Disable the Device Touch Panel.

Return Values

E_DSP_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in Disperr.h.

Comments The Touch Panel can be either disabled or enabled (Toggle) via the Device Keyboard by pressing the TBD key combination.

See Also

Page 232: HC700 SDK Specification

Page 232 of 680

DISPLAY API Examples The examples below demonstrate how to work with the Display APIs.

//------------------------------------------------------------------ // Function: DWORD GetInitialBacklightIntensity (LPDWORD // lpdwMaxIntensity); // // Parameter: lpdwMaxIntensity -- pointer to the DWORD to hold the // maximum supported intensity level // Return: 0 if failed, current intensity level if succeeded // //------------------------------------------------------------------ DWORD GetInitialBacklightIntensity(LPDWORD lpdwMaxIntensity) { DWORD dwResult; DWORD dwIntensity; dwResult = DISPLAY_GetBacklightIntensityLevels(lpdwMaxIntensity); if ( dwResult != E_DSP_SUCCESS ) { return(0); } dwResult = DISPLAY_GetBacklightIntensity(&dwIntensity); if ( dwResult != E_DSP_SUCCESS ) { return(0); } return(dwIntensity);

}

DISPLAY_GetBacklightTimeout and DISPLAY_SetBacklightTimeout Example DWORD dwRetVal; DISPLAY_BACKLIGHT_TIMEOUT timeout; // Get the current backlight timeout dwRetVal = DISPLAY_GetBacklightTimeout(&timeout); if (dwRetVal == E_DSP_SUCCESS) {

// Set the AC backlight timeout value to 30 seconds. timeout.dwACTimeout = 30; dwRetVal = DISPLAY_SetBacklightTimeout(&timeout); …

}

Data Types

DISPLAY_VERSION_INFO

Page 233: HC700 SDK Specification

Page 233 of 680

Description

The DISPLAY_VERSION_INFO data type holds the version information for the display driver. It has a major and minor version stored in the HIWORD and LOWORD respectively.

Structure Definition

typedef struct tagDISPLAY_VERSION_INFO { STRUCT_INFO StructInfo; DWORD dwCAPIVersion; } DISPLAY_VERSION_INFO;

typedef DISPLAY_VERSION_INFO FAR * LPDISPLAY_VERSION_INFO;

Members StructInfo

Sub-structure describing memory allocated and used by this structure dwCAPIVersion

The C API version

Remarks

None

STRUCT_INFO Description The STRUCT_INFO structure enables extensibility of API structures. A STRUCT_INFO structure is embedded in each structure of the API to describe the memory allocated and used by that structure. If the structure grows in future revisions of the API, the STRUCT_INFO information can be used to determine which fields are valid for use.

Structure Definition typedef struct tagSTRUCT_INFO { DWORD dwAllocated; DWORD dwUsed;

} STRUCT_INFO;

Members dwAllocated

Size of the allocated structure, in bytes. dwUsed

Amount of memory the structure actually uses, in bytes.

Remarks The STRUCT_INFO structure is designed to allow interoperability between components based on different revisions of an API. In order to accomplish this, all components must use the STRUCT_INFO structure in a standard way. When a structure is allocated in memory, the dwAllocated field should be set to the amount of memory allocated, and the dwUsed field should be set to zero. When filling in fields of a structure, do not add a field whose extent (offset plus size) is larger than dwAllocated and, after adding the field, update dwUsed to be equal to the extent of the field (unless it is already larger). When reading fields from a structure, the field is

Page 234: HC700 SDK Specification

Page 234 of 680

invalid if dwUsed is less than the extent of the field. A structure is invalid if dwAllocated is less than the size of STRUCT_INFO or dwUsed is greater than dwAllocated.

Several macros have been defined to make use of the STRUCT_INFO structure easier: SI_FIELD_OFFSET(ptr,fld) – Returns the offset of field fld in the structure pointed to by ptr.

SI_FIELD_SIZE(ptr,fld) – Returns the size of field fld in the structure pointed to by ptr.

SI_FIELD_EXTENT(ptr,fld) – Returns the extent of field fld in the structure pointed to by ptr.

SI_FIELD_VALID(ptr,fld) – Returns flag describing validity (contains data) of field fld in the structure pointed to by ptr.

SI_FIELD_EXISTS(ptr,fld) – Returns flag describing existence (field allocated) of field fld in the structure pointed to by ptr.

SI_ALLOC_ALL(ptr) – Sets the dwAllocated field of the structure pointed to by ptr to the size of the structure.

SI_GET_POINTER(ptr,fld,type) – Returns a pointer of type type to field fld in the structure pointed to by ptr.

SI_SET_USED(ptr,fld) – Sets the dwUsed field of the structure pointed to by ptr to the extent of field fld.

SI_SET_FIELD(ptr,fld,src) – Sets the value of field fld in the structure pointed to by ptr to value src if the field exists.

SI_GET_FIELD(ptr,fld,dst) – Sets the value of dst to the value of field fld in the structure pointed to by ptr if the field is valid.

SI_SET_IF_CHANGED(ptr,fld,src) – Sets the value of field fld in the structure pointed to by ptr to value src if the field exists and src is not equal to PARAMETER_NO_CHANGE ( = 0xFFFFFFFF ).

SI_SET_STRING(ptr,fld,src) – Sets the value of string field fld in the structure pointed to by ptr to string value src if the field exists.

SI_GET_STRING(ptr,fld,dst) – Sets the string value of dst to the value of string field fld in the structure pointed to by ptr if the field is valid.

Page 235: HC700 SDK Specification

Page 235 of 680

DISPLAY_BACKLIGHT_TIMEOUT

Description The DISPLAY_BACKLIGHT_TIMEOUT data type defines the display backlight timeout for the battery and external power source. The display backlight is automatically turned off when the device is idle for more than backlight timeout.

Structure Definition

typedef structDISPLAY_BACKLIGHT_TIMEOUT { DWORD dwBattTimeout; BOOL bBattBacklightOnUserActivity; DWORD dwACTimeout; BOOL bACBacklightOnUserActivity; } DISPLAY_BACKLIGHT_TIMEOUT, *PDISPLAY_BACKLIGHT_TIMEOUT;

Members dwBattTimeout

Backlight timeout in seconds when the device uses battery power. If dwBattTimeout is 0, the backlight is never turned off due to timeout expiration.

bBattBacklightOnUserActivity If TRUE, then the backlight is automatically turned on when a user activity is detected and the device uses battery power.

dwACTimeout Backlight timeout in seconds when the device uses external power. If dwACTimeout is 0, the backlight is never turned off due to timeout expiration.

bACBacklightOnUserActivity If TRUE, then the backlight is automatically turned on when a user activity is detected and the device uses external power.

Remarks

None

Page 236: HC700 SDK Specification

Page 236 of 680

DISPLAY Error Codes

#define ERROR_BIT 0x80000000 // Use bit 31 to indicate errror #define USER_BIT 0x20000000 // Bit 29 means not Win32 error #define DISPLAY_ERROR(code) (ERROR_BIT | USER_BIT | (WORD) code) // The function completed successfully. #define E_DSP_SUCCESS 0 #define E_DSP_ERROR DISPLAY_ERROR(0x0001) #define E_DSP_NULLPTR DISPLAY_ERROR(0x0002) // A STRUCT_INFO structure field is invalid. Either // dwAllocated or dwUsed is less than the size of // STRUCT_INFO or dwUsed is greater than dwAllocated #define E_DSP_STRUCTINFO DISPLAY_ERROR(0x0003) // The size of a structure specified in a StructInfo // is too small to contain a required field #define E_DSP_MISSINGFIELD DISPLAY_ERROR(0x0004) #define E_DSP_PWRFAILED DISPLAY_ERROR(0x0005) // Returns this error if Keyboard and Display backlight states // are different #define E_DSP_CONFLICT DISPLAY_ERROR(0x0006)

Page 237: HC700 SDK Specification

Page 237 of 680

8. Keyboard API Overview The Keyboard API provides the application the capability to manage the keyboard backlight and to register and to be notified on a variety of keyboard events. For Registration purpose application may use the KBD_RegisterEvent where the notification may be either via a Window message, Application event or both. In addition, Application may use the KBD_RegisterKeyStateNotification to get notification upon special key state change e.g., Shift key.

For Keyboard Backlight management the application can get and Set the Keyboard Backlight State, Level, and Timeouts.

Functions List Function Description

KBD_RegisterEvent Registers an application to a desire keyboard event. Applications use this function whenever there is a need to receive a notification on any changes in keyboard activity or any desired key combination occurrence with or without duration.

KBD_UnRegisterEvent This function deregisters a keyboard event.

KBD_RegisterKeyStateNotification Applications call this function to receive notification about changes in key states.

KBD_UnregisterKeyStateNotification Un registers key state notification for the provided window.

KBD_RegisterKeyboardNotification Applications call this function to receive notification about changes in keyboard mode (Alpha, Numeric or Function).

KBD_UnregisterKeyboardNotification Un registers keyboard mode change notification for the provided window.

KBD_GetKeyState Returns the current status of the keyboard mode.

KBD_SetKeyState Provides the Application the ability to set the Keyboard to either ALPHA or Numeric mode of operation.

KBD_GetVersion Return the keyboard version read at the initialize phase.

KBD_GetBacklightIntensity Gets the current backlight intensity.

KBD_SetBacklightIntensity Sets the current backlight intensity.

KBD_GetBacklightIntensityLevels Gets the maximum number of supported backlight intensity levels.

KBD_GetBacklightState Gets the current backlight state.

KBD_SetBacklightState sets the current backlight state to on/off.

KBD_GetBacklightTimeout This function is called to query the keyboard backlight timeout value.

KBD_SetBacklightTimeout This function sets the keyboard backlight timeout.

Page 238: HC700 SDK Specification

Page 238 of 680

KBD_EnableKeyCombination Provide a mean to re-enable the key combination mechanism (by default the Key Combinations are enabled).

KBD_DisableKeyCombination Provide a mean to disable the key combination mechanism (by default the Key Combinations are enabled).

KBD_GetLayoutKey Provides a mean to query the desired layout (e.g., ALPH or Numeric) by passing the Scan Key Code and getting the correspond Virtual Key Code.

KBD_SetLayoutKey Provides a mean to modify the desired layout (e.g., ALPHA or Numeric) by passing the Scan Key Code and the Virtual Key Code that will replace the correspond one.

KBD_SetFunctionKeyMode The Motorola OEM keyboard input system provides the user with the capabilities to modify the keyboard Function mode of operation.

1 Shift key – is used for changing keyboard state from Alpha mode to Numeric mode and vice versa. Mode change is performed only if key is pressed for time long then debounce time. If key is pressed for shorter period of time it is treated as regular SHIFT key press and standard WM_KEYDOWN and WM_KEYUP events are sent.

Examples

Keyboard Error Codes Data Types

Page 239: HC700 SDK Specification

Page 239 of 680

KBD_RegisterEvent

Description This function registers an application to a desire keyboard event. Applications use this function whenever there is a need to receive a notification on any changes in keyboard activity or any desired key combination occurrence with or without duration.

Function Prototype HANDLE KBD_RegisterEvent (LPKEYPAD_SERVICES_INFO lpKbdEvent);

Parameters

lpKbdEvent [in] Pointer to a LPKEYPAD_SERVICES_INFO structure. This structure defines any keyboard event the user might be needed.

Return Values

Handle to a registration action, indicates success. If the function returns NULL it indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_UnRegisterEvent

Page 240: HC700 SDK Specification

Page 240 of 680

KBD_UnRegisterEvent

Description This function deregisters a keyboard event.

Function Prototype DWORD KBD_UnRegisterEvent (HANDLE hEventHandle);

Parameters

hEventHandle

[in] Handle to a keyboard registration event. This handle was been received from the keyboard registration event action.

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments

None.

See Also KBD_RegisterEvent

Page 241: HC700 SDK Specification

Page 241 of 680

KBD_RegisterKeyStateNotification

Description Applications call the RegisterKeyStateNotification routine to receive notification about changes in key states. The hWnd parameter specifies the window to be notified and the Msg parameter specifies the message to be sent (WM_APP+x). When a key state change occurs, the keyboard driver will notify registered callers by posting a message.

Function Prototype DWORD KBD_RegisterKeyStateNotification(HWND hWnd, UINT32 uMsg)

Parameters

hWnd [In] The window handle of the application that is to receive the message.

uMsg [In] The message value that is to be sent when a keyboard state occurs.

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments Upon notification the Windows Message associated wParam contains the current keyboard state (e.g. SHIFT, UN_SHIFTED, etc.)

See KBD_RegisterKeyStateNotification Example for further information

None.

See Also KBD_UnregisterKeyStateNotification

KBD_RegisterKeyStateNotification Example

Page 242: HC700 SDK Specification

Page 242 of 680

KBD_UnregisterKeyStateNotification

Description This function Un registers key state notification for the provided window.

Function Prototype DWORD KBD_UnregisterKeyStateNotification(HWND hWnd)

Parameters

hWnd [In] The window handle of the application that is to receive the message..

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_RegisterKeyStateNotification

Page 243: HC700 SDK Specification

Page 243 of 680

KBD_RegisterKeyboardNotification

Description Applications call the KBD_RegisterKeyboardNotification routine to receive notification about changes in keyboard mode (Alpha, Numeric or Function). The hWnd parameter specifies the window to be notified and the Msg parameter specifies the message to be sent (WM_APP+x). When a keyboard mode change occurs, the keyboard driver will notify registered callers by posting a message.

Function Prototype DWORD KBD_RegisterKeyboardNotification (HWND hWnd, UINT32 uMsg)

Parameters

hWnd [In] The window handle of the application that is to receive the message.

uMsg [In] The message value that is to be sent when a keyboard state occurs.

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments Upon notification the Windows Message associated wParam contains the current keyboard state (e.g. ALPHA, NUM, FUNC)

See Also KBD_UnregisterKeyboardNotification

Page 244: HC700 SDK Specification

Page 244 of 680

KBD_UnregisterKeyboardNotification

Description This function Un registers keyboard mode change notification for the provided window.

Function Prototype DWORD KBD_UnregisterKeyboardNotification (HWND hWnd)

Parameters

hWnd [In] The window handle of the application that is to receive the message..

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_RegisterKeyboardNotification

Page 245: HC700 SDK Specification

Page 245 of 680

KBD_SetKeyState

Description The KBD_SetKeyState function provides the Application the ability to set the Keyboard to either ALPHA or Numeric mode of operation.

Function Prototype DWORD KBDAPI KBD_SetKeyState( DWORD dwState)

Parameters DwState KEYBOARD_FUNCTION_MODE or KEYBOARD_NUMERIC_MODE

or KEYBOARD_ALPHA_MODE

Return Values If the function succeeds, the return value is E_KBD_SUCCESS. else the return value is E_KBD_NOTENOUGHMEMORY.

Comments ALPHA mode enables the ALPHA keys of the Device keyboard; Numeric Mode enables all the yellow labels in keyboard (0-9,ALL,BK-SP,HELP, . ).

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in KbdApi.h. Import Library: Use KbdApi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 246: HC700 SDK Specification

Page 246 of 680

KBD_GetKeyState

Description The KBD_GetKeyState function returns the current status of the keyboard mode.

Function Prototype DWORD KBDAPI KBD_GetKeyState (LPDWORD dwState)

Parameters DwState

Pointer to dwState to be filled with KEYBOARD_FUNCTION_MODE or KEYBOARD_NUMERIC_MODE or KEYBOARD_ALPHA_MODE

Return Values If the function succeeds, the return value is E_KBD_SUCCESS. If the function fails, the return value is E_KBD_NOTENOUGHMEMORY.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in KbdApi.h. Import Library: Use KbdApi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 247: HC700 SDK Specification

Page 247 of 680

KBD_GetVersion

Description This function is return the keyboard version read at the initialize phase.

Function Prototype DWORD KBD_GetVersion(LPKBD_VERSION lpVersionInfo)

Parameters lpVersionInfo

[out] Pointer to a KBD_VERSION structure to receive the current Keyboard version. (KBD_VERSION structure define downstairs)

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_VERSION:

typedef struct tagKBD_VERSION { // HIWORD = major, LOWORD = minor DWORD dwCAPIVer; DWORD dwKbdVer; } KBD_VERSION, *LPKBD_VERSION;

Page 248: HC700 SDK Specification

Page 248 of 680

KBD_GetBacklightIntensity

Description This function get the current backlight intensity.

Function Prototype DWORD KBD_GetBacklightIntensity (LPDWORD lpdwBacklightIntensity)

Parameters

lpdwBacklightIntensity [out] Pointer to a DWORD that defines the current backlight intensity level.

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_SetBacklightIntensity

KBD_GetBacklightIntensityLevels

Page 249: HC700 SDK Specification

Page 249 of 680

KBD_GetBacklightIntensityLevels

Description This function gets the maximum number of supported backlight intensity levels.

Function Prototype DWORD KBD_GetBacklightIntensityLevels (LPDWORD lpdwBacklightIntensityLevels)

Parameters

LpdwBacklightIntensityLevels [out] Pointer to a DWORD that defines the supported backlight intensity level.

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_SetBacklightIntensity

KBD_GetBacklightIntensity

Page 250: HC700 SDK Specification

Page 250 of 680

KBD_GetBacklightState

Description This function get the current backlight state. The KBD_GetBacklightState function returns the current keyboard backlight state as either KBD_BACKLIGHT_STATE_OFF or KBD_BACKLIGHT_STATE_OFF.

Function Prototype DWORD GetBacklightState (LPDWORD lpdwBacklightState)

Parameters

lpdwBacklightState [out] Pointer to a DWORD that defines the CURRENT backlight state.

Backlight state: KBD_BACKLIGHT_STATE_OFF or KBD_BACKLIGHT_STATE_OFF.

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_SetBacklightState

Page 251: HC700 SDK Specification

Page 251 of 680

KBD_SetBacklightIntensity

Description This function set the current backlight intensity.

Function Prototype DWORD KBD_SetBacklightIntensity (DWORD dwBacklightIntensity)

Parameters

dwBacklightIntensity [in] DWORD value, backlight intensity level (1-32).

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_GetBacklightIntensity

KBD_GetBacklightIntensityLevels

Page 252: HC700 SDK Specification

Page 252 of 680

KBD_SetBacklightState

Description This function sets the current backlight state to on/off.

Function Prototype DWORD KBD_SetBacklightState (DWORD dwBacklightState)

Parameters

dwBacklightState [in] DWORD value to value to set the backlight state to On/Off.

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_GetBacklightState

Page 253: HC700 SDK Specification

Page 253 of 680

KBD_GetBacklightTimeout

Description This function is called to query the keyboard backlight timeout value. The keyboard backlight is automatically turned off when the device is idle for more than backlight timeout.

Function Prototype DWORD KBD_GetBacklightTimeout ( PKBD_BACKLIGHT_TIMEOUT lpTimeout )

Parameters

lpTimeout [out] Pointer to a KBD_BACKLIGHT_TIMEOUT structure to receive the current backlight timeout settings.

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_SetBacklightTimeout

Page 254: HC700 SDK Specification

Page 254 of 680

KBD_SetBacklightTimeout

Description This function sets the keyboard backlight timeout. The keyboard backlight is automatically turned off when the device is idle for more than backlight timeout.

Function Prototype DWORD KBD_SetBacklightTimeout ( PKBD_BACKLIGHT_TIMEOUT lpTimeout )

Parameters

lpTimeout [in] Pointer to a KBD_BACKLIGHT_TIMEOUT structure that defines the backlight timeout.

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_GetBacklightTimeout

Page 255: HC700 SDK Specification

Page 255 of 680

KBD_EnableKeyCombination

Description The Motorola OEM keyboard input system provides the user with the capabilities to be notified upon variety of key combination (e.g., pressing Shift+Space+C launch the touch panel alignment screen). The KBD_EnableKeyCombination function provide a mean to re-enable the key combination mechanism (by default the Key Combinations are enabled).

Function Prototype DWORD KBD_EnableKeyCombination( )

Parameters None.

Return Values E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments

None.

See Also KBD_DisableKeyCombination

KBD_DisableKeyCombination

Description The Motorola OEM keyboard input system provides the user with the capabilities to be notified upon variety of key combination (e.g., pressing Shift+Space+C launch the touch panel alignment screen). The KBD_DisableKeyCombination function provide a mean to disable the key combination mechanism (by default the Key Combinations are enabled).

Function Prototype DWORD KBD_DisableKeyCombination( )

Parameters

None.

Return Values E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments

None.

See Also KBD_EnableKeyCombination

Page 256: HC700 SDK Specification

Page 256 of 680

KBD_GetLayoutKey

Description The Motorola OEM keyboard input system provides the user with the capabilities to modify dynamically the keyboard layouts. The input system is equipped with few different layouts, one per a keyboard mode (i.e., ALPHA or Numeric modes). Each layout represents the relationship between the physical keys press (Scan key Codes), and the corresponding Virtual key codes that are typically communicated to the application layer. The KBD_GetLayoutKey function provides a mean to query the desired layout (e.g., ALPH or Numeric) by passing the Scan Key Code and getting the correspond Virtual Key Code.

Function Prototype DWORD KBD_GetLayoutKey( UINT32 ScanKeyCode, UINT32 *pVirtualkeyCode, UINT KbdMode)

Parameters

ScanKeyCode - Input Scan Key code.

VirtualKeyCode - Output Virtual Key code.

Keyboard Mode - Input (KEYBOARD_FUNCTION_MODE, KEYBOARD_NUMERIC_MODE,

KEYBOARD_ALPHA_MODE)

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_SetLayoutKey

Page 257: HC700 SDK Specification

Page 257 of 680

KBD_SetLayoutKey

Description The Motorola OEM keyboard input system provides the user with the capabilities to modify dynamically the keyboard layouts. The input system is equipped with few different layouts, one per a keyboard mode (i.e., ALPHA or Numeric modes). Each layout represents the relationship between the physical keys pressing (Scan key Codes), and the corresponding Virtual key codes that are typically communicated to the application layer. The KBD_SetLayoutKey function provide a mean to modify the desired layout (e.g., ALPHA or Numeric) by passing the Scan Key Code and the Virtual Key Code that will replace the correspond one.

Function Prototype DWORD KBD_SetLayoutKey ( UINT32 ScanKeyCode, UINT32 VirtualkeyCode, UINT KbdMode)

Parameters

ScanKeyCode - Input Scan Key code.

VirtualKeyCode - Input Virtual Key code.

Keyboard Mode - Input (KEYBOARD_FUNCTION_MODE, KEYBOARD_NUMERIC_MODE,

KEYBOARD_ALPHA_MODE)

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_GetLayoutKey

Page 258: HC700 SDK Specification

Page 258 of 680

KBD_SetFunctionKeyMode

Description The Motorola OEM keyboard input system provides the user with the capabilities to modify the keyboard Function mode of operation. The user can decide how the function key will operate. The function key can act normally which means that when a user press on Function key and then press on VK_Fx the keyboard will return to the previous mode of operation (Numeric/Alpha). The user may configure the function key to be toggle. This means that only when the user press on shift key the keyboard will change the mode of operation to Numeric or Alpha. The user can configure the function mode to be disabled.

Function Prototype DWORD KBD_SetFunctionKeyMode (DWORD eFuncMode)

Parameters

eFuncMode- Input Function mode of operation (Normal, Toggle or Disable)

Return Values

E_KBD_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in KbdErr.h.

Comments None.

See Also KBD_GetKeyState

Page 259: HC700 SDK Specification

Page 259 of 680

Examples – Keyboard API

The example below demonstrates how to work with Keyboard APIs: KBD_GetBacklightTimeout and KBD_SetBacklightTimeout Example DWORD dwRetVal; KBD_BACKLIGHT_TIMEOUT timeout; // Get the current backlight timeout dwRetVal = KBD_GetBacklightTimeout(&timeout); if (dwRetVal == E_KBD_SUCCESS) {

// Set the AC backlight timeout value to 30 seconds. timeout.dwACTimeout = 30; dwRetVal = KBD_SetBacklightTimeout(&timeout);

} /* Keyboard event Registration Samples: 1) Or event ======== KbdEventType = OR_EVENT KbdRegistryEvent = REG_NO_EVENT NumOfKeys = 2 // (for instance) Keys = {0x37,0x38} UpDownEvent = BOTH_KEYS hWnd = NULL // No window uMsg = 0 // No window MinDuration = 0 // No duration MaxDuration = 0 // No duration DurationWithRepetition = 0; // No Repetition AppEventHandle = 0x0c15ce7d 2) Key Combination with no duration event ====================================== KbdEventType = KEY_COMB_NO_DURATION KbdRegistryEvent = REG_NO_EVENT NumOfKeys = 3 // (for instance) Keys = {0x37,0x38,0x39} UpDownEvent = KEY_DOWN hWnd = NULL // No window uMsg = 0 // No window MinDuration = 0 // No duration MaxDuration = 0 // No duration DurationWithRepetition = 0; // No Repetition AppEventHandle = 0x0c15ce7d

Page 260: HC700 SDK Specification

Page 260 of 680

3) Key Combination with duration event =================================== KbdEventType = KEY_COMB_WITH_DURATION KbdRegistryEvent = REG_NO_EVENT NumOfKeys = 3 // (for instance) Keys = {0x37,0x38,0x39} UpDownEvent = KEY_DOWN hWnd = NULL // No window uMsg = 0 // No window MinDuration = 2 // Duration of 2 sec. MaxDuration = 0 // No duration DurationWithRepetition = 1; // Repetition event, every 2 sec,

// if the key combination is stay //press, a notification will be generate.

AppEventHandle = 0x0c15ce7d 4) Any Key press event =================== KbdEventType = ANY_KEY_PERESS KbdRegistryEvent = REG_NO_EVENT NumOfKeys = 0 Keys = {} UpDownEvent = KEY_DOWN hWnd = NULL // No window uMsg = 0 // No window MinDuration = 0 // No duration MaxDuration = 0 // No duration DurationWithRepetition = 0; // No Repetition AppEventHandle = 0x0c15ce7d // Application Event Handle 5) Register on registry event ========================== KbdEventType = KEY_COMB_WITH_DURATION KbdRegistryEvent = REG_KEYBOARD_BL_INTENSITY_UP NumOfKeys = 0 Keys = {} UpDownEvent = KEY_DOWN hWnd = NULL // No window uMsg = 0 // No window MinDuration = 0 // No duration MaxDuration = 0 // No duration DurationWithRepetition = 0; // No Repetition AppEventHandle = 0x0c15ce7d // Application Event Handle */

Page 261: HC700 SDK Specification

Page 261 of 680

/* ************************************************************************ * Description: Insert a desire key combination sequence and capture it * three times. * Input : None * * Return: Boolean (true/false) * ***********************************************************************/ BOOL KbdTest_InsertKeyComb() { HANDLE tmpHandle; LPKEYPAD_SERVICES_INFO lpKbdEvent; UINT8 indexEvent=0; UINT8 Keys[]={0x34,0x35,0x36}; lpKbdEvent = new(KEYPAD_SERVICES_INFO); memset(lpKbdEvent,0,sizeof(KEYPAD_SERVICES_INFO)); lpKbdEvent->KbdEventType = KEY_COMBINATION_EVENT; lpKbdEvent->KbdRegistryEvent = REGISTRY_NONE; lpKbdEvent->NumOfKeys = 3; memcpy(&lpKbdEvent->Keys[0],&Keys[0],MAX_KEYS_PER_ONE_COMBINATION); lpKbdEvent->MinDuration = 0; lpKbdEvent->MaxDuration = 0;

lpKbdEvent->DurationWithRepetition = 1; lpKbdEvent->AppEventHandle = CreateEvent(NULL,FALSE,FALSE,NULL);

tmpHandle = KBD_RegisterEvent(lpKbdEvent); if (!tmpHandle) return FALSE; while (indexEvent < 3) { if (tmpHandle) WaitForSingleObject(lpKbdEvent->AppEventHandle,INFINITE); indexEvent++; RETAILMSG(1, (TEXT("Capture Key CombNotification time: %d\r\n"),indexEvent)); } if (KBD_UnRegisterEvent(tmpHandle)) return TRUE; return FALSE; }

Page 262: HC700 SDK Specification

Page 262 of 680

KBD_RegisterKeyStateNotification Example #include <KbdApi.h> #define UM_KEYSTATENOTIFICATION WM_USER+101 int WINAPI WinMain( HINSTANCE hInstance,HINSTANCE hPrevInstance, LPTSTR lpCmdLine, int nCmdShow) { HWND hWnd; MSG msg; HACCEL hAccelTable; // Perform application initialization: if (!InitInstance (hInstance, nCmdShow)) { return FALSE; } hAccelTable = LoadAccelerators(hInstance, (LPCTSTR)IDC_Q); //key registration: KBD_RegisterKeyStateNotification (hWnd, UM_KEYSTATENOTIFICATION); // Main message loop: while (GetMessage(&msg, NULL, 0, 0)) { if (!TranslateAccelerator(msg.hwnd, hAccelTable, &msg)) { TranslateMessage(&msg); DispatchMessage(&msg); } } return msg.wParam; }

Page 263: HC700 SDK Specification

Page 263 of 680

LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) { int wmId, wmEvent; static HWND hwndEdit; switch (message) { case UM_KEYSTATENOTIFICATION: // wParam => keystate, lParam = active modifier //Keyboard state bit field(s). if (wParam == SHIFT) {

MessageBox(hWnd,TEXT("SHIFT"),TEXT("SHIFT Key is pressed"),MB_OK);

} else if (wParam & UN_SHIFTED) {

MessageBox(hWnd,TEXT("UNSHIFTED "),TEXT("SHIFT Key is released"),MB_OK);

} else if (wParam & SCAN_DOWN_KEY) {

MessageBox(hWnd,TEXT("SCAN_DOWN_KEY "),TEXT("& SCAN_DOWN_KEY "),MB_OK);

} else

MessageBox(hWnd,TEXT("Other "),TEXT("Other Key was Pressed"),MB_OK);

break; case WM_DESTROY: KBD_UnRegisterKeyStateNotification (hWnd) ; //remove window key notification PostQuitMessage(0); break; default: return DefWindowProc(hWnd, message, wParam, lParam); } return 0; }

Page 264: HC700 SDK Specification

Page 264 of 680

Data Types

KBD_BACKLIGHT_TIMEOUT

Description The KBD_BACKLIGHT_TIMEOUT data type defines the keyboard backlight timeout for the battery and external power source. The keyboard backlight is automatically turned off when the device is idle for more than backlight timeout. Structure Definition typedef structKBD_BACKLIGHT_TIMEOUT { DWORD dwBattTimeout; DWORD dwACTimeout; BOOL bBattBacklightOnKeyPress; BOOL bACBacklightOnKeyPress; } KBD_BACKLIGHT_TIMEOUT, *PKBD_BACKLIGHT_TIMEOUT;

Members dwBattTimeout

Backlight timeout in seconds when the device uses battery power. If dwBattTimeout is 0, the backlight is never turned off due to timeout expiration.

dwACTimeout Backlight timeout in seconds when the device uses external power. If dwACTimeout is 0, the backlight is never turned off due to timeout expiration.

bBattBacklightOnKeyPress If TRUE, then the backlight is automatically turned on when a key is pressed and the device uses battery power.

bACBacklightOnKeyPress If TRUE, then the backlight is automatically turned on when a key is pressed and the device uses external power.

Remarks

None

KEYPAD_SERVICES_INFO

Description The KEYPAD_SERVICES_INFO data type defines the keyboard events properties. Applications use this structure to register on a required keyboard event. Structure Definition typedef struct tagKEYPAD_SERVICES_INFO { KEYBOARD_EVENT_TYPE KbdEventType; KEYBOARD_REG_EVENT KbdRegistryEvent;

Page 265: HC700 SDK Specification

Page 265 of 680

UINT8 NumOfKeys; UINT8 Keys[MAX_KEYS_PER_ONE_COMBINATION]; UP_DOWN_BOTH UpDownEvent; HWND hWnd; UINT uMsg; DWORD MinDuration; DWORD MaxDuration;

BOOL DurationWithRepetition; HANDLE AppEventHandle; } *LPKEYPAD_SERVICES_INFO, KEYPAD_SERVICES_INFO;Members KbdEventType

Event Type (Or event, key combination, key combination with duration, any key press)

KbdRegistryEvent Registry Event (keyboard event which is written in the registry.)

NumOfKeys Num of keys comprise the key combination event.

Keys: The Virtual keys array

UpDownEvent Setting the event when a Key is up, down or both.

HWnd: Window handle to be notified (Window Message) upon Key combination even

UMsg: Window message

MinDuration Min Duration period the event should expire.

MaxDuration Max Duration period the event is no longer valid.

DurationWithRepetition Determine whether a duration event repeat itself, whenever key combination stay press.

AppEventHandle Application Event Handle to be signaled upon Key combination event, this handle delivered by the application to the keyboard APIs. And the application must take care of closing this Handle.

Page 266: HC700 SDK Specification

Page 266 of 680

Keyboard_Events_Type

Description The keyboard events were divided into three categories: OR Events – if one key, which defined in the key combination group, has been press, the registered event will be sent. For instance we will use such event to work with the scan triggers key. Key Combination – at any type of key combination with/without duration, all and only the key comprise the key combination must be hold press together in order to set the registered event. Any Key Press – on any keyboard activity a registered event will be set. #define MAX_KEYS_PER_ONE_COMBINATION 4 typedef enum { KEY_ONE_OF_GROUP_EVENT = 0, KEY_COMBINATION_EVENT = 1, KEY_ANYKEY_EVENT = 2, KEY_LAST_TYPE_EVENT } KEYBOARD_EVENT_TYPE;

Keyboard_Reg_Event.

Description The keyboard has the following built in keyboard events defined at the registry. typedef enum { REGISTRY_NONE, REGISTRY_KEYBOARD_BL_STATE_ON, REGISTRY_KEYBOARD_BL_STATE_OFF, REGISTRY_KEYBOARD_BL_INTENSITY_UP, REGISTRY_KEYBOARD_BL_INTENSITY_DOWN, REGISTRY_DISPLAY_BL_STATE_ON, REGISTRY_DISPLAY_BL_STATE_OFF, REGISTRY_DISPLAY_BL_INTENSITY_UP, REGISTRY_DISPLAY_BL_INTENSITY_DOWN, REGISTRY_KEYBOARD_AND_DISPLAY_BL_CONTROL, REGISTRY_LAST } KEYBOARD_REG_EVENT;

Keyboard_Up_Down_Both.

Description The keyboard will send notification upon keys up events or down or both. (use at or event only). typedef enum tagUP_DOWN_BOTH { KEY_UP_EVENT, KEY_DOWN_EVENT, BOTH_KEYS_EVENT }UP_DOWN_BOTH;

Page 267: HC700 SDK Specification

Page 267 of 680

// AVAIL_STATE 11101111b ; 9 8 7 6 5 4 3 2 1 0 // : : : : : : : : '- unshifted // : : : : : : : : ---- shifted // : : : : : : : ------ cntrl // : : : : : : -------- alt // : : : : : ---------- Alpha lock // : : : : ------------ num lock // : : : -------------- caps lock // : : :---------------- function // : :------------------ scan-down // :-------------------- scan-up // // Alpha lock and Num lock together define the three states of the keyboard. // The keyboard can either be in control mode, num lock mode or alpha lock // mode. If neither ALPHA_LOCK nor NUM_LOCK bits are set, then the keyboard // is in control mode. #define UN_SHIFTED 0x01 #define SHIFT 0x02 #define CONTROL 0x04 #define ALT 0x08 #define ALPHA_LOCK 0x10 #define NUM_LOCK 0x20 #define CAPS_LOCK 0x40 #define FUNCTION 0x80 // Support in 'SCAN' key state notification, "RegisterKeyStateNotification". #define SCAN_DOWN_KEY 0x100 #define SCAN_UP_KEY 0x200 #define NO_KEY 0 // Keyboard modes bits #define ALPHA_MODE 0x00 #define NUM_MODE 0x40 #define FUNC_MODE 0x80 #define MAX_KEYBOARD_EVENT 100 #define MAX_RCM_TRIGGERS 4 #define MAX_KEYS_PER_ONE_COMBINATION 4

Page 268: HC700 SDK Specification

Page 268 of 680

KEYBOARD Error Codes

#define ERROR_BIT 0x80000000 // Use bit 31 to indicate errror #define USER_BIT 0x20000000 // Bit 29 means not Win32 error #define KBD_ERROR(code) (ERROR_BIT|USER_BIT|(WORD) code) // The function completed successfully. #define E_KBD_SUCCESS 0 // A required registry value could not be read #define E_KBD_CANTREADREGVALUE KBD_ERROR(0x0001) // A required registry key could not be opened #define E_KBD_CANTOPENREGKEY KBD_ERROR(0x0002) // A null pointer was passed as a required parameter #define E_KBD_NULLPTR KBD_ERROR(0x0003) // A STRUCT_INFO structure field is invalid. dwAllocated is less or greater than the size of STRUCT_INFO #define E_KBD_BADSTRUCTINFO KBD_ERROR(0x0004) // A input parameter value is missing. #define E_KBD_PARAMMISSING KBD_ERROR(0x0005) // The system image not supported in this function. #define E_KBD_NOTSUPPORTED KBD_ERROR(0x0006) // An attempt to allocate memory failed. #define E_KBD_NOTENOUGHMEMORY KBD_ERROR(0x0007) // A registry entry is not found. #define E_KBD_REGNOTFOUND KBD_ERROR(0x0008) // A structure field value is missing. #define E_KBD_MISSINGFIELD KBD_ERROR(0x0009) // StructInfo error #define E_KBD_STRUCTINFO KBD_ERROR(0x000A) // Invalid parameter was passed like type of keyboard event, num of virtual keys, etc. #define E_KBD_INVALIDPARAM KBD_ERROR(0x000B) // The function failed to perform the operation. #define E_KBD_ERROR KBD_ERROR(0x000C)

Page 269: HC700 SDK Specification

Page 269 of 680

9. Notification API The Notification API provides the ability for applications to control the notification device - LED

Functions List Function Description

NOTIFY_FindClose Closes the handle used by NOTIFY_FindFirst and NOTIFY_FindNext.

NOTIFY_FindFirst Finds the first notification object and fills in the NOTIFY_FINDINFO structure with information about this notification object available in the system.

NOTIFY_FindNext Finds and fills in the structure about the next notification object available in the system.

NOTIFY_GetCycleInfo Gets the cycle information for an object indexed by dwIndex.

NOTIFY_GetState Gets the current state of the specified notification object.

NOTIFY_GetVersion Gets the version information for the Notification API.

NOTIFY_SetCycleInfo Sets the cycle information for a specified notification object.

NOTIFY_SetState Sets the state of the specified notification object.

NOTIFY_GetLedExInfo Returns the Setting of the notification LED device.

NOTIFY_SetLedEx Configuresthe setting of the notification LED.

• Examples

• Data Types

Comments

The user can obtain information about supported notification objects by calling NOTIFY_FindFirst and NOTIFY_FindNext, or can get/set notification object’s specific parameters or state by calling NOTIFY_GetCycleInfo, NOTIFY_GetState, NOTIFY_SetCycleInfo and NOTIFT_SetState. The sequence of notification objects return by NOTIFY_FindFirst and NOTIFY_FindNext is important and should be saved by the application. The sequential number of the notification object (also called index) is passed to other Notification API functions.

A typical usage of the Notification APIs includes:

Allocating a structure of data (for example NOTIFY_FINDINFO),

Initializing the StructInfo field of the NOTIFY_FINDINFO structure (for example by SI_INIT macro),

Calling the required function (for example NOTIFY_FindFirst),

Note: The user, who calls Notification APIs, must include NtfyCAPI.h and import NtfyApi32.lib.

Page 270: HC700 SDK Specification

Page 270 of 680

Page 271: HC700 SDK Specification

Page 271 of 680

NOTIFY_FindClose

Description The NOTIFY_FindClose function closes the handle used by NOTIFY_FindFirst and NOTIFY_FindNext.

Function Prototype

DWORD NOTIFYAPI NOTIFY_FindClose(

HANDLE hFindHandle);

Parameters

hFindHandle [in] A handle returned by NOTIFY_FindFirst.

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR indicates failure. Error Codes: Declared in NtfyErr.h.

Comments

None.

See Also

NOTIFY_FindFirst, NOTIFY_FindNext.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_FindClose Example

Page 272: HC700 SDK Specification

Page 272 of 680

NOTIFY_FindFirst

Description

The NOTIFY_FindFirst function finds the first notification object and fills in the NOTIFY_FINDINFO structure with information about this notification object available in the system.

Function Prototype

DWORD NOTIFYAPI NOTIFY_FindFirst(

LPNOTIFY_FINDINFO lpNotifyFindInfo,

LPHANDLE lphFindHandle

);

Parameters

lpNotifyFindInfo [out] Pointer to the NOTIFY_FINDINFO structure that the function fills with notification object information.

lphFindHandle [out] Pointer to where the findhandle will be stored.

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR, E_NTFY_NOTENOUGHMEMORYand E_NTFY_NOMOREITEMS indicate failure. Error Codes: Declared in NtfyErr.h.

Comments

Before calling this function the user should allocate the NOTIFY_FINDINFO and initialize the StructInfo field.

See Also

NOTIFY_FindClose, NOTIFY_FindNext, NOTIFY_FINDINFO.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_FindFirst Example

Page 273: HC700 SDK Specification

Page 273 of 680

Page 274: HC700 SDK Specification

Page 274 of 680

NOTIFY_FindNext

Description

The NOTIFY_FindNext function finds and fills in the structure about the next notification object available in the system.

Function Prototype

DWORD NOTIFYAPI NOTIFY_FindNext (

LPNOTIFY_FINDINFO lpNotifyFindInfo,

HANDLE hFindHandle

);

Parameters

lpNotifyFindInfo [out] Pointer to the NOTIFY_FINDINFO structure that the function fills with notification object information.

hFindHandle [in] Handle returned by NOTIFY_FindFirst.

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR, E_NTFY_NOTENOUGHMEMORYand E_NTFY_NOMOREITEMS indicate failure. Error Codes: Declared in NtfyErr.h.

Comments

Before calling this function the user should allocate the NOTIFY_FINDINFO and initialize the StructInfo field.

See Also

NOTIFY_FindClose, NOTIFY_FindFirst, NOTIFY_FINDINFO.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_FindNext Example

Page 275: HC700 SDK Specification

Page 275 of 680

Page 276: HC700 SDK Specification

Page 276 of 680

NOTIFY_GetCycleInfo

Description

The NOTIFY_GetCycleInfo function gets the cycle information for an object indexed by dwIndex.

Function Prototype

DWORD NOTIFYAPI NOTIFY_GetCycleInfo (

DWORD dwIndex,

LPCYCLE_INFO lpCycleInfo

);

Parameters

dwIndex [in] The sequential number of the notification object.

lpCycleInfo [out] Pointer to the CYCLE_INFO structure.

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR, E_NTFY_BADINDEX, E_NTFY_CANTMAKEMUTEX and E_NTFY_BUSY indicate failure. Error Codes: Declared in NtfyErr.h.

Comments

Before calling this function the user should allocate the CYCLE_INFO and initialize the StructInfo field.

See Also

NOTIFY_SetCycleInfo, CYCLE_INFO.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_GetCycleInfo Example

Page 277: HC700 SDK Specification

Page 277 of 680

Page 278: HC700 SDK Specification

Page 278 of 680

NOTIFY_GetState

Description

The NOTIFY_GetState function gets the current state of the specified notification object.

Function Prototype

DWORD NOTIFYAPI NOTIFY_GetState (

DWORD dwIndex,

LPDWORD lpdwState

);

Parameters

dwIndex [in] The sequential number of the notification object.

lpdwState [out] Pointer to a DWORD to receive the current state of the specified notification object. Valid states are: NOTIFY_STATE_OFF, NOTIFY_STATE_ON, NOTIFY_STATE_CYCLE and NOTIFY_STATE_UNKNOWN.

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR, E_NTFY_BADINDEX, E_NTFY_CANTMAKEMUTEX and E_NTFY_BUSY indicate failure. Error Codes: Declared in NtfyErr.h.

Comments

Before calling this function the user should allocate the lpdwState.

See Also

NOTIFY_SetState.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_GetState Example

Page 279: HC700 SDK Specification

Page 279 of 680

NOTIFY_GetVersion

Description The NOTIFY_GetVersion function gets the version information for the Notification API.

Function Prototype

DWORD NOTIFYAPI NOTIFY_GetVersion (

LPNOTIFY_VERSION_INFO lpNotifyVersionInfo );

Parameters

lpNotifyVersionInfo [out] Pointer to the NOTIFY_VERSION_INFO structure to be filled in with the version info.

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR, E_NTFY_STRUCTINFO and E_NTFY_MISSINGFIELD indicate failure. Error Codes: Declared in NtfyErr.h.

Comments

Before calling this function the user should allocate the NOTIFY_VERSION_INFO and initialize the StructInfo field.

See Also

NOTIFY_VERSION_INFO.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_GetVersion Example

Page 280: HC700 SDK Specification

Page 280 of 680

NOTIFY_SetCycleInfo

Description The NOTIFY_SetCycleInfo function sets the cycle information for a specified notification object.

Function Prototype

DWORD NOTIFYAPI NOTIFY_SetCycleInfo (

DWORD dwIndex,

LPCYCLE_INFO lpCycleInfo

);

Parameters

dwIndex [in] The sequential number of the notification object.

lpCycleInfo [in] Pointer to the CYCLE_INFO structure.

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR, E_NTFY_BADINDEX, E_NTFY_CANTMAKEMUTEX and E_NTFY_BUSY indicate failure. Error Codes: Declared in NtfyErr.h.

Comments

Before calling this function the user should allocate the CYCLE_INFO, initialize the StructInfo field and fill the other fields with notification object specific parameters to be set.

See Also

NOTIFY_GetCycleInfo, CYCLE_INFO.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_SetCycleInfo Example

Page 281: HC700 SDK Specification

Page 281 of 680

NOTIFY_SetState

Description The NOTIFY_SetState function sets the state of the specified notification object.

Function Prototype

DWORD NOTIFYAPI NOTIFY_SetState (

DWORD dwIndex,

DWORD dwState

);

Parameters

dwIndex [in] The sequential number of the notification object.

dwState [in] DWORD to set the state of the specified notification object. Valid states are: NOTIFY_STATE_OFF, NOTIFY_STATE_ON, NOTIFY_STATE_CYCLE.

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR, E_NTFY_BADINDEX, E_NTFY_CANTMAKEMUTEX and E_NTFY_BUSY indicate failure. Error Codes: Declared in NtfyErr.h.

Comments

None.

See Also

NOTIFY_GetState.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_SetState Example

Page 282: HC700 SDK Specification

Page 282 of 680

NOTIFY_SetLedEx

Description The NOTIFY_SetLedEx function Configure the setting of the notification LED.

Function Prototype

DWORD NOTIFYAPI NOTIFY_SetLedEx(

TRICOLOR_LED_SPECIFIC *pInput,

NOTIFY_OBJECT_STATES State);

Parameters pInput

[in] Defines LED ON and OFF Durations and repitition counter. See TRICOLOR_LED_SPECIFIC

State

[in] Defines LED State: NOTIFY_STATE_OFF, NOTIFY_STATE_ON, NOTIFY_STATE_CYCLE. See NOTIFY_OBJECT_STATES

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR, E_NTFY_BADINDEX, E_NTFY_CANTMAKEMUTEX and E_NTFY_BUSY indicate failure. Error Codes: Declared in NtfyErr.h.

Comments

None.

See Also

NOTIFY_SetBuzzerEx, NOTIFY_GetLedExInfo

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_SetLedEx Example

Page 283: HC700 SDK Specification

Page 283 of 680

NOTIFY_GetLedExInfo

Description The NOTIFY_GetLedExInfo function returns the Setting of the notification LED device.

Function Prototype

DWORD NOTIFYAPI NOTIFY_GetLedExInfo(TRICOLOR_LED_SPECIFIC *pOutput,

NOTIFY_OBJECT_STATES *pState );

Parameters pOutput

[Out] Points to a TRICOLOR_LED_SPECIFIC enumeration to be updated.

pState [Out] Points to a NOTIFY_OBJECT_STATES enumeration to be updated.

Return Values

E_NTFY_SUCCESS indicates success. E_NTFY_NULLPTR, E_NTFY_BADINDEX, E_NTFY_CANTMAKEMUTEX and E_NTFY_BUSY indicate failure. Error Codes: Declared in NtfyErr.h.

Comments

None.

See Also

NOTIFY_GetBuzzerExInfo, NOTIFY_SetLedEx

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in NtfyCAPI.h. Import Library: Use NtfyAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

NOTIFY_GetLedExInfo Example

Page 284: HC700 SDK Specification

Page 284 of 680

Examples The examples below demonstrate how to work with the Notification APIs.

NOTIFY_FindClose Example

NOTIFY_FindFirst Example

NOTIFY_FindNext Example

NOTIFY_GetCycleInfo Example

NOTIFY_GetState Example

NOTIFY_GetVersion Example

NOTIFY_SetCycleInfo Example

NOTIFY_SetState Example

Complete Example

Page 285: HC700 SDK Specification

Page 285 of 680

NOTIFY_FindFirst, NOTIFY_FindNext and NOTIFY_FindClose Example // This function finds tri-color LED index, saves them in the g_dwLEDIndex global variable.

BOOL FindAll()

{

#define MAXOBJECTCOUNT 20

INT nNotifyCount = 0;

DWORD dwResult;

HANDLE hFindHandle;

NOTIFY_FINDINFO NotifyObject;

// Find tri-color LED indexe

for (nNotifyCount = 0; nNotifyCount < MAXOBJECTCOUNT; nNotifyCount++)

{

if ((g_dwBeeperIndex != -1) && (g_dwLEDIndex != -1))

break;

SI_INIT (&NotifyObject);

if ( nNotifyCount == 0 )

dwResult = NOTIFY_FindFirst(&NotifyObject, &hFindHandle);

else

dwResult = NOTIFY_FindNext(&NotifyObject, hFindHandle);

if ( dwResult != E_NTFY_SUCCESS )

break;

// Is the object beeper

if (NotifyObject.dwObjectType == NOTIFY_TYPE_BEEPER)

g_dwBeeperIndex = nNotifyCount;

else

{

// Is the object tri-color LED

if (NotifyObject.dwObjectType == NOTIFY_TYPE_TRICOLOR_LED)

g_dwLEDIndex = nNotifyCount;

Page 286: HC700 SDK Specification

Page 286 of 680

}

}

NOTIFY_FindClose(hFindHandle);

if ((g_dwBeeperIndex != -1) && (g_dwLEDIndex != -1))

return TRUE;

return FALSE;

}

Complete Example

Page 287: HC700 SDK Specification

Page 287 of 680

NOTIFY_GetState Example DWORD dwState, dwResult;

// Get the current LED state

dwResult = NOTIFY_GetState(g_dwLEDIndex, &dwState);

if (dwResult != E_NTFY_SUCCESS)

return FALSE;

if (dwState != NOTIFY_STATE_OFF)

{

// Turn off the LED

dwResult = NOTIFY_SetState(g_dwLEDIndex, NOTIFY_STATE_OFF);

if (dwResult != E_NTFY_SUCCESS)

return FALSE;

}

Complete Example

Page 288: HC700 SDK Specification

Page 288 of 680

NOTIFY_GetVersion Example BOOL GetVersion(TCHAR* szVersion)

{

NOTIFY_VERSION_INFO version;

DWORD dwResult;

if (szVersion == NULL)

return FALSE;

SI_INIT(&version);

// Get the version

dwResult = NOTIFY_GetVersion(&version);

if (dwResult != E_NTFY_SUCCESS)

return FALSE;

_stprintf(szVersion, TEXT("%02X.%02X"), HIWORD(version.dwCAPIVersion),

LOWORD(version.dwCAPIVersion));

return TRUE;

}

Complete Example

Page 289: HC700 SDK Specification

Page 289 of 680

Complete Example #include <NtfyCAPI.h>

DWORD g_dwLEDIndex = -1;

DWORD g_dwBeeperIndex = -1;

/********************************************************************

* FUNCTION: FindAll

* PARAMETERS: None

* DESCRIPTION: Finds tri-color LED and beeper indexes,

* saves them in the g_dwLEDIndex and g_dwBeeperIndex global variables.

* RETURNS: TRUE – success FALSE - failure

**********************************************************************/

BOOL FindAll()

{

#define MAXOBJECTCOUNT 20

INT nNotifyCount = 0;

DWORD dwResult;

HANDLE hFindHandle;

NOTIFY_FINDINFO NotifyObject;

// Find LED and beeper indexes

for (nNotifyCount = 0; nNotifyCount < MAXOBJECTCOUNT; nNotifyCount++)

{

if ((g_dwBeeperIndex != -1) && (g_dwLEDIndex != -1))

break;

SI_INIT (&NotifyObject);

if ( nNotifyCount == 0 )

dwResult = NOTIFY_FindFirst(&NotifyObject, &hFindHandle);

else

dwResult = NOTIFY_FindNext(&NotifyObject, hFindHandle);

Page 290: HC700 SDK Specification

Page 290 of 680

if ( dwResult != E_NTFY_SUCCESS )

break;

// Is the object beeper

if (NotifyObject.dwObjectType == NOTIFY_TYPE_BEEPER)

g_dwBeeperIndex = nNotifyCount;

else

{

// Is the object tri-color LED

if (NotifyObject.dwObjectType == NOTIFY_TYPE_TRICOLOR_LED)

g_dwLEDIndex = nNotifyCount;

}

}

NOTIFY_FindClose(hFindHandle);

if ((g_dwBeeperIndex != -1) && (g_dwLEDIndex != -1))

return TRUE;

return FALSE;

}

/********************************************************************

* FUNCTION: Beep

* PARAMETERS: dwFrequency – beeper frequency

* dwVolume - beeper volume

* dwDuration - beep duration

* DESCRIPTION: Activates beeper with the specified frequency, volume and duration.

* RETURNS: TRUE – success FALSE - failure

**********************************************************************/

BOOL Beep(DWORD dwFrequency, DWORD dwVolume, DWORD dwDuration)

{

DWORD dwResult;

CYCLE_INFO CycleInfo;

SI_INIT (&CycleInfo);

Page 291: HC700 SDK Specification

Page 291 of 680

// Get current beeper settings

dwResult = NOTIFY_GetCycleInfo(g_dwBeeperIndex, &CycleInfo);

if ( dwResult != E_NTFY_SUCCESS )

return FALSE;

CycleInfo.ObjectTypeSpecific.BeeperSpecific.dwFrequency = dwFrequency;

CycleInfo.ObjectTypeSpecific.BeeperSpecific.dwVolume = dwVolume;

CycleInfo.ObjectTypeSpecific.BeeperSpecific.dwDuration = dwDuration;

// Set the required beeper settings

dwResult = NOTIFY_SetCycleInfo(g_dwBeeperIndex, &CycleInfo);

if ( dwResult != E_NTFY_SUCCESS )

return FALSE;

// Beep for the specified duration (dwDuration).

dwResult = NOTIFY_SetState(g_dwBeeperIndex, NOTIFY_STATE_CYCLE);

if ( dwResult != E_NTFY_SUCCESS )

return FALSE;

return TRUE;

}

/********************************************************************

* FUNCTION: LEDOn

* PARAMETERS: dwColor – LED color

* DESCRIPTION: Turns on LED with the specified color.

* RETURNS: TRUE – success FALSE - failure

**********************************************************************/

BOOL LEDOn(DWORD dwColor)

{

DWORD dwResult;

CYCLE_INFO CycleInfo;

Page 292: HC700 SDK Specification

Page 292 of 680

SI_INIT (&CycleInfo);

// Get current LED settings

dwResult = NOTIFY_GetCycleInfo(g_dwLEDIndex, &CycleInfo);

if ( dwResult != E_NTFY_SUCCESS )

return FALSE;

CycleInfo.ObjectTypeSpecific.TricolorLedSpecific.dwColor = dwColor;

// Set the required LED color

dwResult = NOTIFY_SetCycleInfo(g_dwLEDIndex, &CycleInfo);

if ( dwResult != E_NTFY_SUCCESS )

return FALSE;

// Turn on the LED

dwResult = NOTIFY_SetState(g_dwLEDIndex, NOTIFY_STATE_ON);

if ( dwResult != E_NTFY_SUCCESS )

return FALSE;

return TRUE;

}

/********************************************************************

* FUNCTION: LEDOff

* PARAMETERS: None

* DESCRIPTION: Turns off LED.

* RETURNS: TRUE – success FALSE - failure

**********************************************************************/

BOOL LEDOff()

{

DWORD dwResult;

// Turn off the LED

dwResult = NOTIFY_SetState(g_dwLEDIndex, NOTIFY_STATE_OFF);

if ( dwResult != E_NTFY_SUCCESS )

Page 293: HC700 SDK Specification

Page 293 of 680

return FALSE;

return TRUE;

}

/********************************************************************

* FUNCTION: LEDBlink

* PARAMETERS: dwColor – LED color

* dwOn - on duration

* dwOff - off duration

* dwCycles - number of cycles to blink (on + off duration is one cycle)

* DESCRIPTION: Blinks the LED.

* RETURNS: TRUE – success FALSE - failure

**********************************************************************/

BOOL LEDBlink(DWORD dwColor, DWORD dwOn, DWORD dwOff, DWORD dwCycles)

{

DWORD dwResult;

CYCLE_INFO CycleInfo;

SI_INIT (&CycleInfo);

// Get current LED settings

dwResult = NOTIFY_GetCycleInfo(g_dwLEDIndex, &CycleInfo);

if ( dwResult != E_NTFY_SUCCESS )

return FALSE;

CycleInfo.ObjectTypeSpecific.TricolorLedSpecific.dwOnDuration = dwOn;

CycleInfo.ObjectTypeSpecific.TricolorLedSpecific.dwOffDuration = dwOff;

CycleInfo.ObjectTypeSpecific.TricolorLedSpecific.dwCount = dwCycles;

CycleInfo.ObjectTypeSpecific.TricolorLedSpecific.dwColor = dwColor;

// Set the required LED settings

dwResult = NOTIFY_SetCycleInfo(g_dwLEDIndex, &CycleInfo);

if ( dwResult != E_NTFY_SUCCESS )

return FALSE;

Page 294: HC700 SDK Specification

Page 294 of 680

// Blink the LED

dwResult = NOTIFY_SetState(g_dwLEDIndex, NOTIFY_STATE_CYCLE);

if ( dwResult != E_NTFY_SUCCESS )

return FALSE;

return TRUE;

}

/********************************************************************

* FUNCTION: LEDTest

* PARAMETERS: None

* DESCRIPTION: Tests the LED.

* RETURNS: None

**********************************************************************/

void LEDTest()

{

DWORD dwState, dwColor, dwOn, dwOff, dwCycles;

TCHAR entr, color;

_tprintf(_T("LED test is started.\r\n"));

_tprintf(_T("Please enter new LED state:\r\n0 - off, 1 - on, 2 - blink\r\n"));

_tscanf(_T("%d%lc"), &dwState, &entr);

switch (dwState)

{

case NOTIFY_STATE_OFF:

if(!LEDOff())

_tprintf(_T("LED test is failed.\r\n"));

break;

case NOTIFY_STATE_ON:

case NOTIFY_STATE_CYCLE:

_tprintf(_T("Please enter LED color:\r\nr - red, g - green, o - orange\r\n"));

_tscanf(_T("%lc%lc"), &color, &entr);

Page 295: HC700 SDK Specification

Page 295 of 680

if (_tcsncmp(&color, _T("r"), 1) == 0)

dwColor = NOTIFY_COLOR_RED;

else

{

if (_tcsncmp(&color, _T("g"), 1) == 0)

dwColor = NOTIFY_COLOR_GREEN;

else

{

if (_tcsncmp(&color, _T("o"), 1) == 0)

dwColor = NOTIFY_COLOR_ORANGE;

else

{

_tprintf(_T("Unsupported LED color.\r\n"));

break;

}

}

}

if (dwState == NOTIFY_STATE_ON)

{

if (!LEDOn(dwColor))

_tprintf(_T("LED test is failed.\r\n"));

}

else //NOTIFY_STATE_CYCLE

{

_tprintf(_T("Please enter on duration(msec).\r\n"));

_tscanf(_T("%d%lc"), &dwOn, &entr);

_tprintf(_T("Please enter off duration(msec).\r\n"));

_tscanf(_T("%d%lc"), &dwOff, &entr);

_tprintf(_T("Please enter # of blink cycles.\r\n"));

_tscanf(_T("%d%lc"), &dwCycles, &entr);

Page 296: HC700 SDK Specification

Page 296 of 680

if (!LEDBlink(dwColor, dwOn, dwOff, dwCycles))

_tprintf(_T("LED test is failed.\r\n"));

}

break;

default:

_tprintf(_T("Unknown LED state.\r\n"));

}

_tprintf(_T("End of LED test.\r\n"));

}

/********************************************************************

* FUNCTION: BeeperTest

* PARAMETERS: None

* DESCRIPTION: Tests the beeper.

* RETURNS: None

**********************************************************************/

void BeeperTest()

{

DWORD dwFrequency, dwVolume, dwDuration;

TCHAR entr;

_tprintf(_T("Beeper test is started.\r\n"));

_tprintf(_T("Please enter beeper frequency(Hz).\r\n"));

_tscanf(_T("%d%lc"), &dwFrequency, &entr);

_tprintf(_T("Please enter beeper volume:\r\n0 - low, 1 - high.\r\n"));

_tscanf(_T("%d%lc"), &dwVolume, &entr);

_tprintf(_T("Please enter beep duration(msec).\r\n"));

_tscanf(_T("%d%lc"), &dwDuration, &entr);

if (!Beep(dwFrequency, dwVolume, dwDuration))

_tprintf(_T("Beeper test is failed.\r\n"));

_tprintf(_T("End of beeper test.\r\n"));

}

Page 297: HC700 SDK Specification

Page 297 of 680

// This function is called by the system as the initial entry point.

int WINAPI WinMain( HINSTANCE hInstance,

HINSTANCE hPrevInstance,

LPTSTR lpCmdLine,

int nCmdShow)

{

// Find tri-color LED and beeper indexes

if (!FindAll())

_tprintf(_T("Unable to find tri-color LED and beeper indexes.\r\n"));

else

{

// Test the beeper

BeeperTest();

// Test the LED

LEDTest();

}

_tprintf(_T("Press ENTR to exit."));

_gettchar();

return 0;

}

Page 298: HC700 SDK Specification

Page 298 of 680

Data Types NOTIFY_FINDINFO

CYCLE_INFO

OBJECT_TYPE_SPECIFIC

LED_SPECIFIC

TRICOLOR_LED_SPECIFIC

BEEPER_SPECIFIC

VIBRATOR_SPECIFIC

NOTIFY_VERSION_INFO

STRUCT_INFO

Page 299: HC700 SDK Specification

Page 299 of 680

NOTIFY_FINDINFO typedef struct tagNOTIFY_FINDINFO{

STRUCT_INFO StructInfo; // Sub-structure describing structure extents

WCHAR szObjectName[MAX_OBJECT_NAME]; // Name of the notification object

DWORD dwObjectType; // Type of the notification object. The type can be any one of

// the following: NOTIFY_TYPE_LED,

// NOTIFY_TYPE_TRICOLOR_LED,

// NOTIFY_TYPE_BEEPER, NOTIFY_TYPE_VIBRATOR

// and NOTIFY_TYPE_UNKNOWN

DWORD dwObjectIndex; // Low level driver index used by Notification API

} NOTIFY_FINDINFO;

CYCLE_INFO typedef struct tagCYCLE_INFO{

STRUCT_INFO StructInfo; // Sub-structure describing structure extents

DWORD dwObjectType; // Notification object type

// The type can be any one of the following:

// NOTIFY_TYPE_LED

// NOTIFY_TYPE_TRICOLOR_LED

// NOTIFY_TYPE_BEEPER

// NOTIFY_TYPE_VIBRATOR

// NOTIFY_TYPE_UNKNOWN

OBJECT_TYPE_SPECIFIC ObjectTypeSpecific;

} CYCLE_INFO;

OBJECT_TYPE_SPECIFIC typedef union tagOBJECT_TYPE_SPECIFIC{

DWORD dwUntyped[20]; // For init and anonymous access

LED_SPECIFIC LedSpecific; // Object type is LED -NA in HC700 Project

BEEPER_SPECIFIC BeeperSpecific; // Object type is beeper

VIBRATOR_SPECIFIC VibratorSpecific; // Object type is vibrator -NA in HC700 Project

TRICOLOR_LED_SPECIFIC TricolorLedSpecific; // Object type is tri color LED

} OBJECT_TYPE_SPECIFIC;

Page 300: HC700 SDK Specification

Page 300 of 680

/* NA in HC700 Project*/

LED_SPECIFIC typedef struct tagLED_SPECIFIC{

DWORD dwOnDuration; // On duration of LED in milliseconds

DWORD dwOffDuration; // Off duration of LED in milliseconds

DWORD dwCount; // Number of cycles (on+off) to generate

} LED_SPECIFIC;

TRICOLOR_LED_SPECIFIC typedef struct tagTRICOLOR_LED_SPECIFIC{

DWORD dwOnDuration; // On duration of tri color LED in milliseconds.

// On duration range is 10msec – 2550msec

DWORD dwOffDuration; // Off duration of tri color LED in milliseconds

// Off duration range is 10msec – 2550msec

DWORD dwCount; // Number of cycles (on+off) to generate

DWORD dwColor; // The color can be one of the following: NOTIFY_COLOR_RED,

// NOTIFY_COLOR_GREEN or NOTIFY_COLOR_ORANGE

} TRICOLOR_LED_SPECIFIC;

BEEPER_SPECIFIC typedef struct tagBEEPER_SPECIFIC{

DWORD dwFrequency; // Frequency of beep in Hertz. – recommended 2300

DWORD dwVolume; // Volume of beep. 2 levels are supported (0 - 1).

DWORD dwDuration; // Duration of beep in milliseconds

} BEEPER_SPECIFIC;

/* NA in HC700 Project*/

VIBRATOR_SPECIFIC typedef struct tagVIBRATOR_SPECIFIC{

DWORD dwDuration; // Duration of vibration in milliseconds

} VIBRATOR_SPECIFIC;

Page 301: HC700 SDK Specification

Page 301 of 680

NOTIFY_VERSION_INFO typedef struct tagNOTIFY_VERSION_INFO{

STRUCT_INFO StructInfo; // Sub-structure describing structure extents

DWORD dwCAPIVersion; // The API version. It has a major and minor version

// stored in the HIWORD and LOWORD, respectively.

} NOTIFY_VERSION_INFO;

STRUCT_INFO typedef struct tagSTRUCT_INFO{

DWORD dwAllocated; // Size of the allocated structure, in bytes

DWORD dwUsed; // Amount of memory the structure actually uses, in bytes

} STRUCT_INFO;

NOTIFY_OBJECT_TYPES

enum tagNOTIFY_OBJECT_TYPES{

NOTIFY_TYPE_LED = 0,

NOTIFY_TYPE_BEEPER = 1

NOTIFY_TYPE_VIBRATOR = 2,

NOTIFY_TYPE_TRICOLOR_LED = 3,

NOTIFY_TYPE_UNKNOWN = -1

} NOTIFY_OBJECT_TYPES;

NOTIFY_OBJECT_STATES typedef enum tag_NOTIFY_OBJECT_STATES{

NOTIFY_STATE_OFF = 0,

NOTIFY_STATE_ON = 1,

NOTIFY_STATE_CYCLE = 2,

NOTIFY_STATE_UNKNOWN = -1 }NOTIFY_OBJECT_STATES;

Page 302: HC700 SDK Specification

Page 302 of 680

Page 303: HC700 SDK Specification

Page 303 of 680

10. Product Parameters Service API Overview The Product Parameters Service, hereinafter PPS, provides for the user, a means to retrieve information related to the platform configuration and characterization. This information is grouped to the following categories:

• Hardware Information

FPGA Scanner Firmware and Hardware versions, PIC Firmware version, Scanner Firmware version, Board version, Board Serial Number, CPU version, Manufacturing Dates, Board ECN.

• Software Information

Platform SW version, Platform SW Build time stamp, OS version, XIPs versions and time stamp

• Physical Memories Information

Linear Flash Size, RAM Size, IDE flash size (N/A)

• Product Serial Number Information

UUID – Universal uniqe ID.

• BlueTooth Information

BD address, Bluetooth Firmware version, Bluetooth Chip version, Bluetooth Stack version.

• Imager Information

ImagerOemApiVersion, ImagerOemDecoderVersion, ImagerOemScanDriverVersion, ImagerOemHwInterfaceVersion, ImagerHardwareType.

• WLAN Information

Information about WLAN software/hardware modules versions .

Functions List Function Description

PPS_GetVersion The PPS_GetVersion function obtains information about the PPS modules versions.

PPS_GetPlatformHwInfo Obtains information about the platform hardware parameters.

PPS_GetPlatformSwInfo Obtains information about the platform software parameters.

PPS_GetProductUuidInfo Obtains information about the Product Universal Unique ID.

PPS_GetPhysicalMemoryInfo Obtains information about the physical memory size in the platform.

PPS_GetBlueToothInfo Obtains the information about the BlueTooth Address (BD_ADDR).

PPS_GetImagerInfo Obtains the information about the Imager component (ex. modules versions).

PPS_GetWlanInfo Otains the information about the WLAN component (ex. modules versions).

PPS_GetProductParametersInfo Obtains information about all the product parameters.

PPS_GetFactoryFileInfo Obtains information about factory file.

Page 304: HC700 SDK Specification

Page 304 of 680

PPS_ReadFactoryFile Reads raw data from the factory file.

• Examples

• Data Types

Comments The user can obtain information about either a specific group of information, like Hardware Information by calling PPS_GetPlatformHwInfo, or can retrieve information about the whole product parameters by calling PPS_GetProductParametersInfo. The PPS_GetFactoryFileInfo and PPS_ReadFactoryFile are intended for testing usage only.

A typical usage of the PPS APIs includes:

1. Checking the version of the PPS modules (PPS_GetVersion), if needed, 2. Allocating a structure of data (for example PPS_PLATFORM_HW_INFO), 3. Setting the STRUCT_INFO structure with valid data, 4. Calling the function to retrieve the information (for example PPS_GetPlatformHwInfo), 5. Using the information, 6. Releasing the pre-allocated memory.

Note: The user, who calls PPS APIs, must include ppscapi.h.

Page 305: HC700 SDK Specification

Page 305 of 680

PPS_GetVersion

Description

The PPS_GetVersion function obtains information about the PPS modules versions.

Function Prototype

DWORD PPS_GetVersion(

LPPPS_VERSION_INFO lpPpsVersionInfo);

Parameters

lpPpsVersionInfo [in/out] Pointer to an PPS_VERSION_INFO data structure that the function fills with PPS version information.

Return Values Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments Before calling this function the user should allocate the PPS_VERSION_INFO and set the STRUCT_INFO structure with valid data.

See Also None.

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetVersion Example

Page 306: HC700 SDK Specification

Page 306 of 680

PPS_GetPlatformHwInfo

Description The PPS_GetPlatformHwInfo function obtains information about the platform hardware parameters.

Function Prototype

DWORD PPS_GetPlatformHwInfo (

LPPPS_PLATFORM_HW_INFO lpPlatformHwInfo);

Parameters

LpPlatformHwInfo [in/out] Pointer to an PPS_PLATFORM_HW_INFO data structure that the function fills with platform hardware parameters.

Return Values Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments Before calling this function the user should allocate the PPS_PLATFORM_HW_INFO and set the STRUCT_INFO with valid data.

See Also None.

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetPlatformHwInfo Example

Page 307: HC700 SDK Specification

Page 307 of 680

PPS_GetPlatformSwInfo

Description The PPS_GetPlatformSwInfo function obtains information about the platform software parameters.

Function Prototype

DWORD PPS_GetPlatformSwInfo (

LPPPS_PLATFORM_SW_INFO lpPlatformSwInfo);

Parameters

lpPlatformHwInfo [in/out] Pointer to an PPS_PLATFORM_SW_INFO data structure that the function fills with platform software parameters.

Return Values

Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments Before calling this function the user should allocate the PPS_PLATFORM_SW_INFO and set the STRUCT_INFO with valid data.

See Also None.

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetPlatformSwInfo Example

Page 308: HC700 SDK Specification

Page 308 of 680

PPS_GetProductUuidInfo

Description The PPS_GetProductUuidInfo function obtains information about the Product Universal Unique ID.

Function Prototype

DWORD PPS_GetProductUuidInfo( LPPPS_PRODUCT_UUID_INFO lpProductUuidInfo);

Parameters

lpProductUuidInfo [in/out] Pointer to an PPS_PRODUCT_UUID_INFO data structure that the function fills with Product Universal Unique ID information.

Return Values Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments Before calling this function the user should allocate the PPS_PRODUCT_UUID_INFO and set the STRUCT_INFO with valid data.

See Also None.

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetProductUuidInfo Example

Page 309: HC700 SDK Specification

Page 309 of 680

PPS_GetPhysicalMemoryInfo

Description The PPS_GetPhysicalMemoryInfo function obtains information about the physical memory size in the platform.

Function Prototype

DWORD PPS_GetPhysicalMemoryInfo (

LPPPS_PHYSICAL_MEMORY_INFO lpPhysicalMemInfo);

Parameters

lpPhysicalMemInfo [in/out] Pointer to an PPS_PHYSICAL_MEMORY_INFO data structure that the function fills with physical memories size information.

Return Values

Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments

Before calling this function the user should allocate the PPS_PHYSICAL_MEMORY_INFO and set the STRUCT_INFO with valid data.

See Also

None.

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetPhysicalMemoryInfo Example

Page 310: HC700 SDK Specification

Page 310 of 680

PPS_GetBlueToothInfo

Description

The PPS_GetBlueToothInfo function obtains the information about the BlueTooth Address (BD_ADDR).

Function Prototype

DWORD PPS_GetBlueToothInfo( LPPPS_BLUETOOTH_INFO lpBlueToothInfo);

Parameters

lpBlueToothInfo [in/out] Pointer to an PPS_BLUETOOTH_INFO data structure that the function fills with BlueTooth information.

Return Values Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments Before calling this function the user should allocate the PPS_BLUETOOTH_INFO and set the STRUCT_INFO with valid data.

See Also None.

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetBlueToothInfo Example

Page 311: HC700 SDK Specification

Page 311 of 680

PPS_GetImagerInfo

Description

The PPS_GetImagerInfo function obtains the information about the Imager component (ex. modules versions).

Function Prototype

DWORD PPS_GetImagerInfo( LPPPS_IMAGER_INFO lpImagerInfo);

Parameters

lpImagerInfo [in/out] Pointer to an PPS_IMAGER_INFO data structure that the function fills with Imager information.

Return Values Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments Before calling this function the user should allocate the PPS_IMAGER_INFO and set the STRUCT_INFO with valid data.

See Also None.

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetImagerInfo Example

Page 312: HC700 SDK Specification

Page 312 of 680

PPS_GetWlanInfo

Description

The PPS_GetWlanInfo function obtains the information about the WLAN component (ex. modules versions).

Function Prototype

DWORD PPS_GetWlanInfo( LPPPS_WLAN_INFO lpWlanInfo);

Parameters

lpWlanInfo [in/out] Pointer to an PPS_WLAN_INFO data structure that the function fills with WLAN information.

Return Values Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments Before calling this function the user should allocate the PPS_WLAN_INFO and set the STRUCT_INFO with valid data.

See Also None.

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetWlanInfo Example

Page 313: HC700 SDK Specification

Page 313 of 680

PPS_GetProductParametersInfo

Description The PPS_GetProductParametersInfo function obtains information about all the product parameters.

Function Prototype

DWORD PPS_GetProductParametersInfo(

LPPPS_PRODUCT_PARAMETERS_INFO lpProductParamsInfo);

Parameters

lpProductParamsInfo [in/out] Pointer to an PPS_PRODUCT_PARAMETERS_INFO data structure that the function fills with all the product parameters information.

Return Values Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments Before calling this function the user should allocate the PPS_PRODUCT_PARAMETERS_INFO and set the STRUCT_INFO with valid data.

See Also None.

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetProductParametersInfo Example

Page 314: HC700 SDK Specification

Page 314 of 680

PPS_GetFactoryFileInfo

Description The PPS_GetFactoryFileInfo function obtains information about factory file.

Function Prototype

DWORD PPS_GetFactoryFileInfo(

LPPPS_FACTORY_FILE_INFO lpFactoryFileInfo);

Parameters

lpFactoryFileInfo [in/out] Pointer to an PPS_FACTORY_FILE_INFO data structure that the function fills with the factory file information.

Return Values

Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments

This function intended to be used for testing only. Before calling this function the user should allocate the PPS_FACTORY_FILE_INFO and set the STRUCT_INFO with valid data.

See Also

PPS_ReadFactoryFile

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_GetFactoryFileInfo Example

Page 315: HC700 SDK Specification

Page 315 of 680

PPS_ReadFactoryFile

Description The PPS_ReadFactoryFile function reads raw data from the factory file.

Function Prototype

DWORD PPS_ReadFactoryFile(

LPBYTE lpBuffer,

DWORD nNumberOfBytesToRead,

LPDWORD lpNumberOfBytesRead,

);

Parameters

lpBuffer [in/out] Pointer to the buffer that receives the data read from the factory file.

nNumberOfBytesToRead [in] Number of bytes to be read from the factory file.

lpNumberOfBytesRead [out] Pointer to the number of bytes read. ReadFactoryFile sets this value to zero before doing any work or error checking.

Return Values Zero indicates success. Nonzero indicates failure. To get extended error information, call GetLastError. Error Codes: Declared in ppserr.h.

Comments The caller to this function should allocate the proper memory size. If the nNumberOfBytesToRead is big then the factory file length the function will obtain the maximum available data. In order to retrieve information about the actual factory file data size, use the PPS_GetFactoryFileInfo.

See Also

PPS_GetFactoryFileInfo, PPS_FACTORY_FILE_INFO

QuickInfo

Header: Declared in ppscapi.h. Import Library: Use ppsapi32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example See PPS_ ReadFactoryFile Example

Page 316: HC700 SDK Specification

Page 316 of 680

Examples The examples below demonstrate how to work with the PPS APIs.

• PPS_GetVersion Example

• PPS_GetPlatformHwInfo Example

• PPS_GetPlatformSwInfo Example

• PPS_GetProductUuidInfo Example

• PPS_GetPhysicalMemoryInfo Example

• PPS_GetBlueToothInfo Example

• PPS_GetImagerInfo Example

• PPS_GetWlanInfo Example

• PPS_GetProductParametersInfo Example

• PPS_GetFactoryFileInfo Example

• PPS_ReadFactoryFile Example

Page 317: HC700 SDK Specification

Page 317 of 680

PPS_GetVersion Example // Variables definitions

DWORD dwError;

WCHAR Msg[100];

PPS_VERSION_INFO pps_ver_info;

// Initialize the Struct Info.

pps_ver_info.StructInfo.dwAllocated = sizeof(PPS_VERSION_INFO);

pps_ver_info.StructInfo.dwUsed = sizeof(PPS_VERSION_INFO);

// Invoke the service to get the PPS software version.

dwError = PPS_GetVersion(&pps_ver_info);

// If the service succeded.

if (dwError == E_PPS_SUCCESS){

// Find out the major part of the version.

WORD MajorVer = (WORD)( pps_ver_info. dwCAPIVersion >> 16);

// Find out the minor part of the version.

WORD MinorVer = (WORD)( pps_ver_info.dwCAPIVersion & 0x0000FFFF);

// Build a message to the inform the user.

swprintf(Msg,TEXT(“%x,%x”), MajorVer, MinorVer);

// Inform the user.

MessageBox(hDlg,Msg,TEXT("PPS Version"),MB_OK);

}

// If the service failed.

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%x”), dwError);

// Inform the user.

MessageBox(hDlg,Msg,TEXT("PPS Version"),MB_OK);

}

Page 318: HC700 SDK Specification

Page 318 of 680

PPS_GetPlatformHwInfo Example // Variables definitions

DWORD dwError;

WCHAR Msg[100];

PPS_PLATFORM_HW_INFO pps_plat_hw_info;

// Initialize the Struct Info.

pps_plat_hw_info.StructInfo.dwAllocated = sizeof(PPS_PLATFORM_HW_INFO);

pps_plat_hw_info.StructInfo.dwUsed = sizeof(PPS_PLATFORM_HW_INFO);

// Invoke the service to get the PPS hardware information.

dwError = PPS_GetPlatformHwInfo(&pps_plat_hw_info);

// If the service succeded or partially succeded.

if ( (dwError == E_PPS_SUCCESS) ||

((dwError == E_PPS_PARTIAL_SUCCESS) && (pps_plat_hw_info. BoardRevision != -1))) {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“%d”), pps_plat_hw_info. BoardRevision);

// Inform the user.

MessageBox(hDlg,Msg,TEXT("Board Revision "),MB_OK);

}

// If the service failed.

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg,Msg,TEXT("Board Revision "),MB_OK);

}

Page 319: HC700 SDK Specification

Page 319 of 680

PPS_GetPlatformSwInfo Example // Variables definitions

DWORD dwError;

WCHAR Msg[100];

PPS_PLATFORM_SW_INFO pps_plat_sw_info;

// Initialize the Struct Info.

pps_plat_sw_info.StructInfo.dwAllocated = sizeof(PPS_PLATFORM_SW_INFO);

pps_plat_sw_info.StructInfo.dwUsed = sizeof(PPS_PLATFORM_SW_INFO);

// Invoke the service to get the PPS software information.

dwError = PPS_GetPlatformSwInfo(&pps_plat_sw_info);

// If the service succeded or partially succeded.

if ( (dwError == E_PPS_SUCCESS) ||

((dwError == E_PPS_PARTIAL_SUCCESS) && (pps_plat_sw_info.OsysSoftwareVersion !=0 )) ) {

// Inform the user.

MessageBox(hDlg, pps_plat_sw_info.OsysSoftwareVersion ,TEXT("OS SoftwareVersion"),MB_OK);

}

// If the service failed.

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg,Msg,TEXT("OS SoftwareVersion "),MB_OK);

}

Page 320: HC700 SDK Specification

Page 320 of 680

PPS_GetProductUuidInfo Example // Variables definitions

DWORD dwError;

WCHAR Msg[100];

PPS_PRODUCT_UUID_INFO pps_uuid_info;

// Initialize the Struct Info.

pps_uuid_info.StructInfo.dwAllocated = sizeof(PPS_PRODUCT_UUID_INFO);

pps_uuid_info.StructInfo.dwUsed = sizeof(PPS_PRODUCT_UUID_INFO);

// Invoke the service to get the PPS UUID information.

dwError = PPS_GetProductUuidInfo (&pps_uuid_info);

// If the service succeded.

if (dwError == E_PPS_SUCCESS)

// Inform the user.

MessageBox(hDlg, pps_uuid_info.ProductUuid, TEXT("Product S/N"),MB_OK);

Else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg,Msg,TEXT("Product S/N"),MB_OK);

}

Page 321: HC700 SDK Specification

Page 321 of 680

PPS_GetPhysicalMemoryInfo Example // Variables definitions

DWORD dwError;

WCHAR Msg[100];

PPS_PHYSICAL_MEMORY_INFO pps_mem_info;

// Initialize the Struct Info.

pps_mem_info.StructInfo.dwAllocated = sizeof(PPS_PHYSICAL_MEMORY_INFO);

pps_mem_info.StructInfo.dwUsed = sizeof(PPS_PHYSICAL_MEMORY_INFO);

// Invoke the service to get the information.

dwError = PPS_GetPhysicalMemoryInfo(&pps_mem_info);

// If the service succeded or partially succeded.

if ( (dwError == E_PPS_SUCCESS) ||

((dwError == E_PPS_PARTIAL_SUCCESS) && (pps_mem_info.Linear_FlashSize != -1 )) ) {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“%x”), pps_mem_info.Linear_FlashSize);

// Inform the user.

MessageBox(hDlg, Msg, TEXT("Linear Flash Size"),MB_OK);

}

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg, Msg, TEXT("Linear Flash Size"),MB_OK);

}

Page 322: HC700 SDK Specification

Page 322 of 680

PPS_GetBlueToothInfo Example // Variables definitions

DWORD dwError;

WCHAR Msg[100];

PPS_BLUETOOTH_INFO bt_info;

// Initialize the Struct Info.

bt_info.StructInfo.dwAllocated = sizeof(PPS_BLUETOOTH_INFO);

bt_info.StructInfo.dwUsed = sizeof(PPS_BLUETOOTH_INFO);

// Invoke the service to get the information.

dwError = PPS_GetBlueToothInfo (&bt_info);

// If the service succeded or partially succeded.

if ( (dwError == E_PPS_SUCCESS) ||

((dwError == E_PPS_PARTIAL_SUCCESS) && (bt_info.BD_Addr != 0 )) ) {

// Inform the user.

MessageBox(hDlg, bt_info.BD_Addr, TEXT("BD Address"),MB_OK);

}

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg, Msg, TEXT("BD Address "),MB_OK);

}

Page 323: HC700 SDK Specification

Page 323 of 680

PPS_GetImagerInfo Example // Variables definitions

DWORD dwError;

TCHAR Msg[100];

PPS_IMAGER_INFO imager_info;

// Initialize the Struct Info.

imager_info.StructInfo.dwAllocated = sizeof(PPS_IMAGER_INFO);

imager_info.StructInfo.dwUsed = sizeof(PPS_IMAGER_INFO);

// Invoke the service to get the information.

dwError = PPS_GetImagerInfo (&imager_info);

// If the service succeded or partially succeded.

if ( (dwError == E_PPS_SUCCESS) ||

((dwError == E_PPS_PARTIAL_SUCCESS) && (imager_info. ImagerHardwareType != 0 )) ) {

// Inform the user.

MessageBox(hDlg, imager_info. ImagerHardwareType, TEXT("ImagerHardwareType"),MB_OK);

}

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg, Msg, TEXT("ImagerHardwareType"),MB_OK);

}

Page 324: HC700 SDK Specification

Page 324 of 680

PPS_GetWlanInfo Example // Variables definitions

DWORD dwError;

TCHAR Msg[100];

PPS_WLAN_INFO wlan_info;

// Initialize the Struct Info.

wlan_info.StructInfo.dwAllocated = sizeof(PPS_WLAN_INFO);

wlan_info.StructInfo.dwUsed = sizeof(PPS_WLAN_INFO);

// Invoke the service to get the information.

dwError = PPS_GetWlanInfo (&wlan_info);

// If the service succeded or partially succeded.

if ( (dwError == E_PPS_SUCCESS) ||

((dwError == E_PPS_PARTIAL_SUCCESS) && (wlan_info.WlanDriverVersion != 0 )) ) {

// Inform the user.

MessageBox(hDlg, wlan_info. WlanDriverVersion, TEXT("WlanDriverVersion "),MB_OK);

}

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg, Msg, TEXT("WlanDriverVersion"),MB_OK);

}

Page 325: HC700 SDK Specification

Page 325 of 680

PPS_GetProductParametersInfo Example // Variables definitions

DWORD dwError;

WCHAR Msg[100];

PPS_PRODUCT_PARAMETERS_INFO pps_params_info;

// Initialize the Struct Info.

pps_params_info.StructInfo.dwAllocated = sizeof(PPS_PRODUCT_PARAMETERS_INFO);

pps_params_info.StructInfo.dwUsed = sizeof(PPS_PRODUCT_PARAMETERS_INFO);

// Invoke the service to get the information.

dwError = PPS_GetProductParametersInfo (&pps_params_info);

// If the service succeded or partially succeded.

if ( (dwError == E_PPS_SUCCESS) ||

((dwError == E_PPS_PARTIAL_SUCCESS) && (pps_params_info.PlatformHwInfo. OSysSoftwareVersion != 0 )) ) {

// Inform the user.

MessageBox(hDlg, pps_params_info.PlatformHwInfo.OSysSoftwareVersion, TEXT("OS Software Version "),MB_OK);

}

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg, Msg, TEXT("OS Software Version"),MB_OK);

}

Page 326: HC700 SDK Specification

Page 326 of 680

PPS_GetFactoryFileInfo Example // Variables definitions

DWORD dwError;

WCHAR Msg[100];

PPS_FACTORY_FILE_INFO pps_factory_info;

// Initialize the Struct Info.

pps_factory_info.StructInfo.dwAllocated = sizeof(PPS_FACTORY_FILE_INFO);

pps_factory_info.StructInfo.dwUsed = sizeof(PPS_FACTORY_FILE_INFO);

// Invoke the service to get the information.

dwError = PPS_GetFactoryFileInfo(&pps_factory_info);

// If the service succeded or partially succeded.

if ( (dwError == E_PPS_SUCCESS) ||

((dwError == E_PPS_PARTIAL_SUCCESS) && (pps_factory_info.FactoryFileActualSize != -1 )) ) {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“%x”), pps_factory_info.FactoryFileActualSize);

// Inform the user.

MessageBox(hDlg, Msg, TEXT("Factory File Actual Size"),MB_OK);

}

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg, Msg, TEXT("Factory File Actual Size"),MB_OK);

}

Page 327: HC700 SDK Specification

Page 327 of 680

PPS_ReadFactoryFile Example // Variables definitions

DWORD dwError;

DWORD NumberOfBytesRead;

PPS_FACTORY_FILE_INFO PPS_factory_info;

// Initialize the Struct Info.

PPS_factory_info.StructInfo.dwAllocated = sizeof(PPS_FACTORY_FILE_INFO);

PPS_factory_info.StructInfo.dwUsed = sizeof(PPS_FACTORY_FILE_INFO);

// Invoke the service to get the information.

dwError = PPS_GetFactoryFileInfo(&PPS_factory_info);

// If the service succeded or partially succeded.

if ( (dwError == E_PPS_SUCCESS) ||

((dwError == E_PPS_PARTIAL_SUCCESS) && (pps_factory_info.FactoryFileActualSize != -1 )) ) {

HLOCAL lpBuffer = LocalAlloc(LMEM_FIXED,PPS_factory_info.FactoryFileActualSize);

If (lpBuffer != NULL) {

dwError = PPS_ReadFactoryFile((LPBYTE)lpBuffer, PPS_factory_info.FactoryFileActualSize,&NumberOfBytesRead);

// Processing the data …

}

else {

// Inform the user.

MessageBox(hDlg, TEXT(“Memory allocation failure”), TEXT("Read Factory File Content"),MB_OK);

}

}

else {

// Build a message to the inform the user.

swprintf(Msg,TEXT(“ERROR:%d”), dwError);

// Inform the user.

MessageBox(hDlg, Msg, TEXT("Read Factory File Content"),MB_OK);

}

Page 328: HC700 SDK Specification

Page 328 of 680

Data Types • PPS_VERSION_INFO

• PPS_PLATFORM_HW_INFO

• PPS_PLATFORM_SW_INFO

• PPS_PRODUCT_UUID_INFO

• PPS_PHYSICAL_MEMORY_INFO

• PPS_BLUETOOTH_INFO

• PPS_IMAGER_INFO

• PPS_WLAN_INFO

• PPS_PRODUCT_PARAMETERS_INFO

• PPS_FACTORY_FILE_INFO

• STRUCT_INFO

Page 329: HC700 SDK Specification

Page 329 of 680

PPS_VERSION_INFO // PPS Module SW Versions information structure

typedef struct tagPPS_VERSION_INFO{

[in] STRUCT_INFO StructInfo;

[out] PPS_SOFTWARE_VERSION_T dwCAPIVersion;

[out] PPS_SOFTWARE_VERSION_T dwLLSVersion;

} PPS_VERSION_INFO, FAR * LPPPS_VERSION_INFO;

typedef DWORD PPS_SOFTWARE_VERSION_T ;

PPS_PLATFORM_HW_INFO // Platform hardware parameters information structure

typedef struct tagPPS_PLATFORM_HW_INFO{

[in] STRUCT_INFO StructInfo;

[out] FPGA_FIRMWARE_VERSION_T FpgaFirmwareVersion ;

[out] FPGA_HARDWARE_VERSION_T FpgaHardwareVersion ;

[out] SCANNER_FIRMWARE_VERSION_T ScannerFirmwareVersion ;

[out] PIC_FIRMWARE_VERSION_T PicFirmwareVersion ;

[out] CPU_REVISION_T CPURevision ;

[out] BOARD_REVISION_T BoardRevision ;

[out] BOARD_SERIAL_NUMBER_T BoardSerialNumber ;

[out] MANUFACTURING_DATE_T BoardManufacuringDate ;

[out] MANUFACTURING_DATE_T ProductManufacuringDate ;

[out] BOARD_ECN_T BoardLastECN ;

[out] CPLD_VERSION_T CpldFirmwareVersion ;

[out] CPLD_PRODUCT_T CpldProductType ;

} PPS_PLATFORM_HW_INFO, FAR * LPPPS_PLATFORM_HW_INFO;

typedef USHORT BOARD_REVISION_T;

typedef USHORT FPGA_FIRMWARE_VERSION_T;

typedef USHORT FPGA_HARDWARE_VERSION_T;

typedef TCHAR SCANNER_FIRMWARE_VERSION_T [SCANNER_FIRMWARE_VERSION_STR_SIZE];

typedef USHORT PIC_FIRMWARE_VERSION_T;

typedef TCHAR CPU_REVISION_T [CPU_REVISION_STR_SIZE];

Page 330: HC700 SDK Specification

Page 330 of 680

typedef TCHAR BOARD_SERIAL_NUMBER_T [BOARD_SERIAL_NUMBER_STR_SIZE];

typedef TCHAR BOARD_ECN_T [BOARD_ECN_STR_SIZE];

typedef USHORT CPLD_PRODUCT_T;

#define BOARD_SERIAL_NUMBER_STR_SIZE 26

#define CPU_REVISION_STR_SIZE 26

#define BOARD_ECN_STR_SIZE (sizeof("AA0000ZZ00000000"))

#define SCANNER_FIRMWARE_VERSION_STR_SIZE 20

PPS_PLATFORM_SW_INFO // Platform software parameters information structure

typedef struct tagPPS_PLATFORM_SW_INFO{

[in] STRUCT_INFO StructInfo;

[out] PLATFORM_SOFTWARE_VERSION_T PlatformSoftwareVersion ;

[out] PLATFORM_BUILD_TIME_STAMP_T PlatformBuildTimeStamp ;

[out] PLATFORM_SOFTWARE_VERSION_T KernelXipSoftwareVersion ;

[out] PLATFORM_BUILD_TIME_STAMP_T KernelXipBuildTimeStamp ;

[out] PLATFORM_SOFTWARE_VERSION_T MiscXipSoftwareVersion ;

[out] PLATFORM_BUILD_TIME_STAMP_T MiscXipBuildTimeStamp ;

[out] PLATFORM_SOFTWARE_VERSION_T MiscappsXipSoftwareVersion ;

[out] PLATFORM_BUILD_TIME_STAMP_T MiscappsXipBuildTimeStamp ;

[out] PLATFORM_OS_VERSION_T OSysSoftwareVersion ;

[out] BL_SOFTWARE_VERSION_T BootloaderSoftwareVersion ;

[out] MICRSOFT_XIP_VERSION_T OsXipSoftwareVersion ;

[out] MICRSOFT_XIP_VERSION_T CoreappsXipSoftwareVersion ;

[out] MICRSOFT_XIP_VERSION_T SyncXipSoftwareVersion ;

[out] MICRSOFT_XIP_VERSION_T ShellXipSoftwareVersion ;

[out] MICRSOFT_XIP_VERSION_T BrowsingXipSoftwareVersion ;

[out] FFS_IPSM_VERSION_T FFSIpsmVersion;

} PPS_PLATFORM_SW_INFO, FAR * LPPPS_PLATFORM_SW_INFO;

typedef TCHAR PLATFORM_SOFTWARE_VERSION_T [PLATFORM_SOFTWARE_VERSION_STR_SIZE];

typedef TCHAR PLATFORM_BUILD_TIME_STAMP_T [PLATFORM_BUILD_TIME_STAMP_STR_SIZE];

typedef TCHAR PLATFORM_OS_VERSION_T [PLATFORM_OS_SW_VERSION_STR_SIZE];

Page 331: HC700 SDK Specification

Page 331 of 680

typedef TCHAR BL_SOFTWARE_VERSION_T [BL_SOFTWARE_VERSION_STR_SIZE];

typedef TCHAR MICRSOFT_XIP_VERSION_T [MICRSOFT_XIP_VERSION_STR_SIZE];

typedef TCHAR FFS_IPSM_VERSION_T [IPSM_VERSION_STR_SIZE];

#define PLATFORM_OS_SW_VERSION_STR_SIZE 26

#define PLATFORM_SOFTWARE_VERSION_STR_SIZE (sizeof("Ann.nn.nn"))

#define PLATFORM_BUILD_TIME_STAMP_STR_SIZE (sizeof("Sep 28 07:24 1999"))

#define BL_SOFTWARE_VERSION_STR_SIZE (sizeof("Ann.nn.nn"))

#define MICRSOFT_XIP_VERSION_STR_SIZE 20

#define IPSM_VERSION_STR_SIZE 20

PPS_PRODUCT_UUID_INFO // Product UUID information structure

typedef struct tagPPS_PRODUCT_UUID_INFO{

[in] STRUCT_INFO StructInfo;

[out] PRODUCT_SERIAL_NUMBER_T ProductUuid;

} PPS_PRODUCT_UUID_INFO, FAR * LPPPS_PRODUCT_UUID_INFO;

typedef TCHAR PRODUCT_SERIAL_NUMBER_T [PRODUCT_SERIAL_NUMBER_STR_SIZE];

#define PRODUCT_SERIAL_NUMBER_STR_SIZE 13

PPS_PHYSICAL_MEMORY_INFO // Platform physical memories information structure

typedef struct tagPPS_PRODUCT_UUID_INFO{

[in] STRUCT_INFO StructInfo;

[out] MEMORY_SIZE_T IDE_FlashSize ;

[out] MEMORY_SIZE_T Linear_FlashSize ;

[out] MEMORY_SIZE_T RAMSize ;

} PPS_PHYSICAL_MEMORY_INFO, FAR * LPPPS_PHYSICAL_MEMORY_INFO;

typedef DWORD MEMORY_SIZE_T;

PPS_BLUETOOTH_INFO // BlueTooth information structure typedef struct tagPPS_BLUETOOTH_INFO{

Page 332: HC700 SDK Specification

Page 332 of 680

[in] STRUCT_INFO StructInfo; [out] BD_ADDRESS_T BD_Addr ; [out] BT_VERSION_T BtFirmwareVersion; [out] BT_VERSION_T BtChipVersion; [out] BT_VERSION_T BtStackVersion; } PPS_BLUETOOTH_INFO, FAR * LPPPS_BLUETOOTH_INFO;

#define BD_ADDRESS_STR_SIZE (sizeof("ZZ.ZZ.ZZ.ZZ.ZZ.ZZ")) typedef TCHAR BD_ADDRESS_T [BD_ADDRESS_STR_SIZE] ; #define BT_VERSION_STR_SIZE 20

typedef TCHAR BT_VERSION_T [BT_VERSION_STR_SIZE] ;

PPS_IMAGER_INFO // Imager information structure typedef struct tagPPS_IMAGER_INFO { [in] STRUCT_INFO StructInfo; [out] IMAGER_VERSION_T ImagerOemApiVersion ; [out] IMAGER_VERSION_T ImagerOemDecoderVersion ; [out] IMAGER_VERSION_T ImagerOemScanDriverVersion ; [out] IMAGER_VERSION_T ImagerOemHwInterfaceVersion ; [out] IMAGER_VERSION_T ImagerHardwareType ; [out] IMAGER_VERSION_T ImagerFunctionalityOption ; } PPS_IMAGER_INFO, FAR * LPPPS_IMAGER_INFO; typedef TCHAR IMAGER_VERSION_T [IMAGER_VERSION_STR_SIZE] ;

#define IMAGER_VERSION_STR_SIZE 50 Where ImagerFunctionalityOption values are:

0x01 imaging only 0x03 imaging with Linear scanning 0x05 imaging with One PDF and Linear 0x07 imaging with All PDF scanning 0x09 imaging with Linear, PDF and 2D scanning

PPS_WLAN_INFO // WLAN information structure typedef struct tagPPS_WLAN_INFO{ [in] STRUCT_INFO StructInfo; [out] WLAN_VERSION_T WlanDriverVersion;

Page 333: HC700 SDK Specification

Page 333 of 680

[out] WLAN_VERSION_T WlanFirmwareVersion; [out] WLAN_VERSION_T WlanLibraryVersion; [out] WLAN_VERSION_T WlanVendorName; [out] WLAN_VERSION_T WlanAdaptorName; [out] WLAN_VERSION_T WlanMacAddress; [out] WLAN_VERSION_T WlanChannelDomain; } PPS_WLAN_INFO, FAR * LPPPS_WLAN_INFO; #define WLAN_VERSION_STR_SIZE 50 typedef TCHAR WLAN_VERSION_T [WLAN_VERSION_STR_SIZE] ;

PPS_PRODUCT_PARAMETERS_INFO // Platform physical memories information structure

typedef struct tagPPS_PRODUCT_PARAMETERS_INFO{

[in] STRUCT_INFO StructInfo;

[in/out] PPS_PLATFORM_HW_INFO PlatformHwInfo ;

[in/out] PPS_PLATFORM_SW_INFO PlatformSwInfo ;

[in/out] PPS_PRODUCT_UUID_INFO ProductUuidInfo ;

[in/out] PPS_PHYSICAL_MEMORY_INFO PhysicalMemoryInfo ;

[in/out] PPS_BLUETOOTH_INFO BlueToothInfo;

[in/out] PPS_IMAGER_INFO ImagerInfo;

[in/out] PPS_WLAN_INFO WlanInfo;

} PPS_PRODUCT_PARAMETERS_INFO, FAR * LPPPS_PRODUCT_PARAMETERS_INFO;

PPS_FACTORY_FILE_INFO // Platform physical memories information structure

typedef struct tagPPS_FACTORY_FILE_INFO{

[in] STRUCT_INFO StructInfo;

[out] FACTORY_FILE_SIZE_T FactoryFileActualSize ;

[out] FACROTRY_FILE_VERSION_T FactoryFileVersion ;

} PPS_FACTORY_FILE_INFO, FAR * LPPPS_FACTORY_FILE_INFO;

typedef TCHAR FACROTRY_FILE_VERSION_T [FACTORY_FILE_VERSION_STR_SIZE];

typedef DWORD FACTORY_FILE_SIZE_T;

#define FACTORY_FILE_VERSION_STR_SIZE (sizeof("nn.nn"))

Page 334: HC700 SDK Specification

Page 334 of 680

11. Docking API Overview The Dock API provides the application ability to get notifications when a power source is changed (In/Out of Office Dock/Mobile Dock/Auxiliary connector). The API also provides information about the current docking type (Office Dock/Mobile Dock/Auxiliary connector).

Functions List Function Description

DOCK_GetStatusEx Gets the current dock status.

DOCK_RegisterEx Provides the application ability to get notifications when a power source is changed (In/Out of Office Dock/Mobile Dock/Auxiliary connector). Meaning this function registers the application window handle to receive an application-defined message/s when a power source is changed.

DOCK_UnRegister Unregisters the application window from receiving message/s when a power source is changed.

DOCK_GetDiagnostic Gets the current dock diagnostic data.

DOCK_GetVersion Gets versions of the Dock API and Dock driver.

DOCK_GetStatus Gets the current dock status. This function is obsolete. Applications should call DOCK_GetStatusEx instead.

DOCK_Register Registers the application window handle to receive an application-defined message when a power source is changed.This function is obsolete. Applications should call DOCK_RegisterEx instead.

Examples

Dock Error Codes Data Types

Page 335: HC700 SDK Specification

Page 335 of 680

DOCK_GetStatusEx

Description This function is called to get the current dock status.

Function Prototype DWORD DOCK_GetStatusEx ( LPDWORD lpdwDockStateFlags, LPDWORD lpdwDockChangeFlags )

Parameters

lpdwDockStateFlags [out] Pointer to a DWORD to receive the current dock state. This parameter can be a combination of the following types: DOCK_OFFICE, DOCK_MOBILE, DOCK_AUX or DOCK_UNKNOWN.

lpdwDockChangeFlags [out] Pointer to a DWORD to receive the last dock change. This parameter can be a combination of the following types: DOCK_OFFICE, DOCK_MOBILE or DOCK_AUX.

Return Values

E_DOCK_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in DockErr.h.

Comments None.

See Also DOCK_RegisterEx

Page 336: HC700 SDK Specification

Page 336 of 680

DOCK_RegisterEx

Description This function provides the application ability to get notifications when a power source is changed (In/Out of Office Dock/Mobile Dock/Auxiliary connector). Meaning this function registers the application window handle to receive an application-defined message/s when a power source is changed. The current dock state is indicated in wParam of the registered message. The current dock change is indicated in lParam of the registered message.

Function Prototype DWORD DOCK_RegisterEx ( HWND hWnd, UINT Msg, DWORD dwDockChangeFlags )

Parameters

hWnd [in] Handle to the application window that will receive a message when a power source is changed.

Msg [in] Message that should be sent when a power source change is detected.

dwDockChangeFlags [in] Notification type. This parameter can be a combination of the following types: DOCK_OFFICE, DOCK_MOBILE or DOCK_AUX.

Return Values

E_DCK_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in DockErr.h.

Comments None.

See Also DOCK_UnRegister

Page 337: HC700 SDK Specification

Page 337 of 680

DOCK_UnRegister

Description This function unregisters the application window from receiving message/s when a power source is changed.

Function Prototype DWORD DOCK_UnRegister ( HWND hWnd )

Parameters

hWnd [in] Handle to the application window.

Return Values

E_DCK_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in DockErr.h.

Comments None.

See Also DOCK_RegisterEx

Page 338: HC700 SDK Specification

Page 338 of 680

DOCK_GetDiagnostic

Description This function is called to get the current dock diagnostic data.

Function Prototype DWORD DOCK_GetDiagnostic ( LPDOCK_APIDIAGNOSE lpDockDiagnose )

Parameters

lpDockDiagnose [in/out] Pointer to a DOCK_APIDIAGNOSE structure.

Return Values

E_DCK_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in DockErr.h.

Comments Warm Boot or Cold Boot resets the diagnostic data.

See Also DOCK_GetStatusEx, DOCK_RegisterEx

Page 339: HC700 SDK Specification

Page 339 of 680

DOCK_GetVersion

Description This function is called to get versions of the Dock API and Dock driver.

Function Prototype DWORD DOCK_GetVersion ( LPDOCK_VERSION_INFO lpDOCKVersionInfo )

Parameters

lpDOCKVersionInfo [out] Pointer to a DOCK_VERSION_INFO structure to receive the Dock API and driver versions.

Return Values

E_DOCK_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in DockErr.h.

Comments None.

See Also DOCK_GetStatusEx, DOCK_RegisterEx

Page 340: HC700 SDK Specification

Page 340 of 680

DOCK_GetStatus

Description This function is called to get the current dock status. This function is obsolete. Applications should call DOCK_GetStatusEx instead.

Function Prototype DWORD DOCK_GetStatus ( LPDOCK_STATUS lpDockStatus )

Parameters

lpDockStatus [out] Pointer to a DOCK_STATUS structure to receive the current dock state.

Return Values

E_DOCK_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in DockErr.h.

Comments This function is obsolete. DOCK_GetStatusEx should be called instead.

See Also DOCK_GetStatusEx

Page 341: HC700 SDK Specification

Page 341 of 680

DOCK_Register

Description This function registers the application window handle to receive an application-defined message when a power source is changed. The current dock state is indicated in wParam of the registered message. The current dock type is indicated in lParam of the registered message. This function is obsolete. Applications should call DOCK_RegisterEx instead.

Function Prototype DWORD DOCK_Register ( HWND hWnd, UINT Msg )

Parameters

hWnd [in] Handle to the application window that will receive a message when a power source is changed.

Msg [in] Message that should be sent when a power source change is detected.

Return Values

E_DCK_SUCCESS indicates success. Other values indicate failure. Error Codes: Declared in DockErr.h.

Comments This function is obsolete. Applications should call DOCK_RegisterEx instead.

See Also DOCK_RegisterEx

Page 342: HC700 SDK Specification

Page 342 of 680

Examples The examples below demonstrate how to work with Dock APIs:

DOCK_GetStatusEx Example DWORD dwRetVal, dwDockStateFlags, dwDockChangeFlags; // Get the current dock status dwRetVal = DOCK_GetStatusEx(&dwDockStateFlags, &dwDockChangeFlags); if (dwRetVal == E_DCK_SUCCESS) {

if (dwDockStateFlags == NO_DOCK) { // There is no external power.

// The device is working from the battery. } else {

if (dwDockStateFlags & DOCK_OFFICE) { // The device is in the Office Dock … } if (dwDockStateFlags & DOCK_MOBILE) { // The device is in the Mobile Dock … } if (dwDockStateFlags & DOCK_AUX) { // Auxiliary connector is connected … } if (dwDockStateFlags & DOCK_UNKNOWN) { // External power source is unknown … }

}

}

Page 343: HC700 SDK Specification

Page 343 of 680

DOCK_RegisterEx and DOCK_UnRegister Example #define UM_DOCK_EVENT_OCCURRED WM_APP+106 #define UM_AUX_EVENT_OCCURRED WM_APP+107 #define UM_OFFICE_DOCK_EVENT_OCCURRED WM_APP+108 #define UM_MOBILE_DOCK_EVENT_OCCURRED WM_APP+109 LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) { DWORD dwFlags; UINT Msg; switch (message) {

case WM_COMMAND: wmId = LOWORD(wParam); wmEvent = HIWORD(wParam); // Parse the menu selections: switch (wmId) { case ID_FILE_REGISTER_ALLCHANGES: dwFlags = DOCK_AUX | DOCK_OFFICE | DOCK_MOBILE; Msg = UM_DOCK_EVENT_OCCURRED;

/* Register hWnd with UM_DOCK_EVENT_OCCURRED message to receive all the power source changes */

DOCK_RegisterEx(hWnd, Msg, dwFlags); break; case ID_FILE_REGISTER_OFFICEDOCKCHANGE: dwFlags = DOCK_OFFICE; Msg = UM_OFFICE_DOCK_EVENT_OCCURRED;

/* Register hWnd with UM_OFFICE_DOCK_EVENT_OCCURRED message in order to receive the message when a Office Dock is connected/disconnected */

DOCK_RegisterEx(hWnd, Msg, dwFlags); break; case ID_FILE_REGISTER_MOBILEDOCKCHANGE: dwFlags = DOCK_MOBILE; Msg = UM_MOBILE_DOCK_EVENT_OCCURRED;

/* Register hWnd with UM_MOBILE_DOCK_EVENT_OCCURRED message in order to receive the message when a Mobile Dock is connected/disconnected */

DOCK_RegisterEx(hWnd, Msg, dwFlags); break; case ID_FILE_REGISTER_AUXCHANGE: dwFlags = DOCK_AUX; Msg = UM_AUX_EVENT_OCCURRED;

/* Register hWnd with UM_AUX_EVENT_OCCURRED message in order to receive the message when an Auxiliary is connected/disconnected */

DOCK_RegisterEx(hWnd, Msg, dwFlags); break; case ID_FILE_UNREGISTER: // Unregister all hWnd registrations

Page 344: HC700 SDK Specification

Page 344 of 680

DOCK_UnRegister(hWnd); } case UM_DOCK_EVENT_OCCURRED:

// There is power source change if (lParam & DOCK_AUX) /* AUX state change */

{ if (wParam & DOCK_AUX) // Auxiliary has been connected … else // Auxiliary has been disconnected … } if (lParam & DOCK_OFFICE) /* Office dock state change */ { if (wParam & DOCK_OFFICE) // Office Dock has been connected … else // Office Dock has been disconnected … } if (lParam & DOCK_MOBILE) /* Mobile dock state change */ { if (wParam & DOCK_MOBILE) // Mobile Dock has been connected … else // Mobile Dock has been disconnected … } break; case UM_OFFICE_DOCK_EVENT_OCCURRED: // Office dock state change if (wParam & DOCK_OFFICE) // Office Dock has been connected … else // Office Dock has been disconnected … break; case UM_MOBILE_DOCK_EVENT_OCCURRED: // Mobile dock state change if (wParam & DOCK_MOBILE) // Mobile Dock has been connected … else // Mobile Dock has been disconnected … break; case UM_AUX_EVENT_OCCURRED: // AUX state change if (wParam & DOCK_AUX)

Page 345: HC700 SDK Specification

Page 345 of 680

// Auxiliary has been connected else // Auxiliary has been disconnected break; … } return 0;

}

DOCK_GetDiagnostic Example DOCK_APIDIAGNOSE diag; // Get Office Dock diagnostic data memset(&diag, 0, sizeof(DOCK_APIDIAGNOSE)); diag.opCode = DOCK_DIAG_OFFICE_NUMB_INOUT; DOCK_GetDiagnostic(&diag); diag.opCode = DOCK_DIAG_OFFICE_LAST_INOUT; DOCK_GetDiagnostic(&diag); … DOCK_GetVersion Example DOCK_VERSION_INFO version; // Get Dock API and Dock driver versions DOCK_GetVersion(&version); … Obsolete DOCK_GetStatus DOCK_Register API Example //------------------------------------------------------------------ // DOCKTEST.cpp : Defines the entry point for the application. // #include "stdafx.h" #include "resource.h" #include <DockCApi.h> //------------------------------------------------------- #define MAX_LOADSTRING 100 #define DOCKING_MESSAGE (WM_USER+100) // Global Variables: HWND v_hWndMain;

Page 346: HC700 SDK Specification

Page 346 of 680

HINSTANCE hInst; //--------------------------------------------------------------- int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPTSTR lpCmdLine, int nCmdShow) { // TODO: Place code here. MSG msg; HACCEL hAccelTable; // Perform application initialization: if (!InitInstance (hInstance, nCmdShow)) { return FALSE; } hAccelTable = LoadAccelerators(hInstance, (LPCTSTR)IDC_DOCKTEST); //---------------------------------------------------------------------- if (!DOCK_Register (v_hWndMain , DOCKING_MESSAGE))

MessageBox(NULL,TEXT("FAIL DOCK_Register "),TEXT("DOCKAPI"),MB_OK); //-------------- DOCK_GetStatus API ---------- if (DOCK_GetStatus (lpDockStatus) ==E_DOCK_SUCCESS) RETAILMSG(1, (TEXT("Dock_GetStatus ok, = %d, type= %d\r\n"), lpDockStatus->status, lpDockStatus->type)); else RETAILMSG(1, (TEXT("Dock_GetStatus failed"))); // Main message loop: while (GetMessage(&msg, NULL, 0, 0)) { if (!TranslateAccelerator(msg.hwnd, hAccelTable, &msg)) { TranslateMessage(&msg); DispatchMessage(&msg); } } return msg.wParam; } //-------------------------------------------------------------------- LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) { PAINTSTRUCT ps; HDC hdc; switch (message) { case WM_DESTROY: DOCK_UnRegister (v_hWndMain); PostQuitMessage(0); break; case DOCKING_MESSAGE: if (wParam & DOCK_IN_STATE) {

Page 347: HC700 SDK Specification

Page 347 of 680

if (lParam==DOCK_OFFICE_TYPE) MessageBox(NULL,TEXT("DOCK_IN_STATE MESSAGE -> UOD"),TEXT("DockTest"),MB_OK); if (lParam==DOCK_MOBILE_TYPE) MessageBox(NULL,TEXT("DOCK_IN_STATE MESSAGE -> Cradle"),TEXT("DockTest"),MB_OK); } if (wParam & DOCK_OUT_STATE) { MessageBox(NULL,TEXT("DOCK_OUT_STATE MESSAGE"),TEXT("DockTest"),MB_OK); } break; default: return DefWindowProc(hWnd, message, wParam, lParam); } return 0; }

Page 348: HC700 SDK Specification

Page 348 of 680

Data Types

DOCK_APIDIAGNOSE

Description This structure contains information about the Dock diagnostic data. Structure Definition typedef struct { DWORD totalNumInDock; // output DWORD totalNumOutDock; // output SYSTEMTIME lastInDockTime; // output SYSTEMTIME lastOutDockTime; // output DWORD opCode; // input } DOCK_APIDIAGNOSE , *LPDOCK_APIDIAGNOSE;

Members totalNumInDock

Number of In Dock events.

totalNumOutDock Number of Out Dock events.

lastInDockTime Last In Dock time.

lastOutDockTime Last Out Dock time.

opCode

Diagnostic type. Should be set to one of the following: DOCK_DIAG_MOBILE_RESET – Mobile dock diagnostic reset DOCK_DIAG_OFFICE_RESET – Office dock diagnostic reset DOCK_DIAG_MOBILE_LAST_INOUT – get the last Mobile dock In/Out time DOCK_DIAG_OFFICE_LAST_INOUT – get the last Office dock In/Out time DOCK_DIAG_MOBILE_NUMB_INOUT – get the number of Mobile dock In/Out events DOCK_DIAG_OFFICE_NUMB_INOUT – get the number of Office dock In/Out events DOCK_DIAG_AUX_RESET – Auxiliary diagnostic reset DOCK_DIAG_AUX_LAST_INOUT – get the last Auxiliary In/Out time DOCK_DIAG_AUX_NUMB_INOUT – get the number of Auxiliary In/Out events

Remarks

None

DOCK_VERSION_INFO

Page 349: HC700 SDK Specification

Page 349 of 680

Description This structure contains the Dock API and Dock driver versions. Structure Definition typedef struct { DWORD DOCKAPI_version; DWORD DOCKDRV_version; } DOCK_VERSION_INFO, *LPDOCK_VERSION_INFO;

Members DOCKAPI_version

Dock API version.

DOCKDRV_version Dock driver version.

Remarks

None

DOCK_STATUS

Description This structure contains the current Dock status. Structure Definition typedef struct { WORD status; WORD type; } DOCK_STATUS , *LPDOCK_STATUS;

Members status

Dock status: DOCK_IN_STATE or DOCK_OUT_STATE.

type Dock type: NO_DOCK

DOCK_MOBILE_TYPE DOCK_OFFICE_TYPE AUX_TYPE

Page 350: HC700 SDK Specification

Page 350 of 680

Remarks

This structure is obsolete. Do not use it.

Page 351: HC700 SDK Specification

Page 351 of 680

DOCK Error Codes

#define E_DOCK_SUCCESS 1 #define E_DOCK_FAILURE 0

Page 352: HC700 SDK Specification

Page 352 of 680

12. BlueTooth General Overview

Extended Systems XTNDConnect Blue SDK for Windows CE is a Bluetooth protocol stack, set of APIs and sample applications, that streamline the development of custom Windows CE solutions that utilize Bluetooth wireless communication. Once the XTNDConnect Blue SDK is installed on your system, you have access to high-level Application Programming Interfaces (APIs) allowing rapid development of custom applications that conform to the Bluetooth profiles. These high level APIs provide a development environment that isolates application development from low-level driver software and Bluetooth protocol changes. Custom applications can be developed from within Microsoft eMbedded Visual C++. The XTNDConnect Blue SDK includes a BT protocol stack that interfaces to Bluetooth radio hardware through the Host Controller Interface (HCI), as defined by the Bluetooth specification. HCI transport driver DLLs allow communication with HCI-compliant UART radio hardware.

The Bluetooth protocol stack implements the Bluetooth protocol specification Version 1.2 necessary to couple the high level APIs to the Bluetooth HCI Transport layer with subsequent coupling to the hardware driver and radio hardware itself. This stack is provided as an executable. The stack is automatically started when any application tries to use one of the Bluetooth APIs or tries to use one of

the Legacy ports. When the stack is started it will also try to start the registered Monitor Application to handle inquiries, pin requests, etc. for more details please refer to:

- SDP service class IDs : http://www.bluetooth.org/assigned-numbers/sdp.htm

- Device classes : http://www.bluetooth.org/assignednumbers/baseband.htm BlueTooth Information

• BT Stack APIs components

• Bluetooth_Monitor_API

• Bluetooth_Object_Push_API

• Bluetooth_Serial_Legacy

• XTNDConnect_Bluetooth_File_Transfer_Protocol

• Bluetooth Stack Control API

• Additional information for SW developers

Page 353: HC700 SDK Specification

Page 353 of 680

Structural Diagram This Software Development Kit is grouped into the following development components:

Bluetooth Stack for Windows CE

Serial Port Driver

Serial port

BT serial device

Monitor API (btmon.dll)

ObjectPush API (ObjPush.dll)

Legacy Serial Port 1COMX1: (BTCELegacy.dll)

Legacy Serial Port 2COMX2: (BTCELegacy.dll)

Legacy Serial Port n COMXn: (BTCELegacy.dll)

Monitor / Object Push Application

HW

SW

User Legacy Applications (DUN, LAN, FAX or Legacy Serial users)

Implement DUN, LAN access, FAX or Serial port profiles

Other BT APIs (btapi.dll)

HCI Transport Layer

Page 354: HC700 SDK Specification

Page 354 of 680

BT Stack APIs components

Monitor API The Monitor API allows development of applications that implement the Bluetooth Generic Access

Profile (GAP) and Service Discovery. The Monitor API is implemented as a DLL. Documentation is provided along with a sample application, including sample source code.

The only application, using the Monitor API is the Pocket Monitor application. The role of the Monitor Application is to configure the Bluetooth protocol stack, inquire for devices in range and aid in managing connections for other applications. It is essential that the API user implement an application that fulfils the role of Monitor.

Object Push API The Object Push APIs allows development of applications that implement the Object Push Profile.

Provided with the SDK is an Object Push APIs that is used to create and access Object Push features. Documentation is provided along with an Object Push implementation sample that is integrated into the Pocket Monitor sample application. Object Push application can perform as Object Push Client or Object Push Server. If application is registered as Object Push Server, it is registered an SDP entry indicating that other devices desiring Object Push service can connect to it.

Legacy Serial API The Legacy Serial APIs allows development of applications that implement the Bluetooth Serial, LAN

access, Dial-Up networking and FAX profiles. Legacy support is accessed through the standard Win32 APIs. The BTCELegacy DLL relies on registry entries to determine which logical port number has been

assigned (COM1, COM5, BTC2, et cetera) as well as which profile is being used (FAX, DUN, LAN, Serial). Modifying the BtProfile registry entry can change the profile. However, this profile change must be completed BEFORE the port is opened with via the CreateFile() call.

The logical COM port number is used to obtain the device handle when we are attempting to connect to another device. For this product, a sample Monitor application performs this function. The BTCELegacy DLL sends request to retrieve a device handle. The Monitor gets an event, indicating such request, and without user intervention retrieves the handle to remote device with address, that must be predefined in ConnectTo registry entry of corresponding virtual BT legacy serial port driver. Monitor application passes the handle of the device to the BTCELegacy driver via a call to ConnectLegacyDevice() function.

The BtProfile registry setting informs the dll that the port is currently being used as either a FAX, LAN, DUN, or Serial profile port. The profile determines how the SDP query is set up during the connection process. In addition, if the profile is the Serial profile, then when the COM port is opened, a serial server is initialized. An SDP entry is registered, indicating that other devices desiring serial services can connect to us. If we are unable to retrieve the profile type from the registry, then by default the port is assumed to support the serial profile.

Because the other profiles – FAX, DUN, LAN – only act as clients, they do not register SDP entries indicating, that they offer Server capabilities. Any device attempting to connect to those profiles will fail. If the BtProfile is a Dial-Up profile ( DUN ), then an associated registry entry must be present to enable CE Applications such as Remote Networking. An entry under HKEY_LOCAL_MACHINE\ExtModems must be created so that the CE Operating System will recognize the serial port as having dialup networking capabilities. The sample registry settings are included in the legacy API document.

Bluetooth Monitor API Overview This document describes the API developed for the purpose of writing device monitor applications for the Windows CE XTNDConnect Bluetooth Stack. This API implements the Bluetooth General Access Profile (GAP). API user level functions can be accessed through Btmon.dll (for linkage use bmon.lib). Include file is BTMonitorCE.h.

Page 355: HC700 SDK Specification

Page 355 of 680

Function Description BTMONITOR_RegisterCallback Registers a notification callback that will be called on

BTMonitor API events. BTMONITOR_UnRegisterCallback Unregisters a notification callback. The application will no

longer receive BTMonitor API events. GetLocalAddress Ask the Bluetooth stack to return the address of the local

Bluetooth radio. The event GetLocalAddressComplete will be called with the address when the call is complete.

SecurityMode3 Enable security mode 3. The event SecurityMode3Complete is called when the operation is complete.

Get_SecurityMode3 Get the current security settings. SaveStackSettings Saves the persistent information from the Bluetooth stack to the

registry. Bluetooth monitor applications should call this method before exiting, and any other time as needed. To retrieve the persistent information and send it to the stack, the application should later call the InitStackSettings method.

InitStackSettings Load all the persistent information stored in the registry to the Bluetooth stack. Persistent information is collected by the SaveStackSettings method.

NameDiscovery Call to remote device to retrieve the friendly name, address and class of device. When the name discovery is complete the stack will notify the application by calling the NameDiscoveryComplete event with the results.

Initialize Initializes the Bluetooth stack for use by the monitor application.

DeInitialize Unbinds the Monitor API from the Bluetooth stack and frees all allocated resources.

Get_DeviceMode Returns a mask that determines the local Bluetooth Device's Mode. Can be a combination of the next values: MODE_BIT_BAM_NOT_ACCESSIBLE : Non discoverable or connectable MODE_BIT_BAM_GENERAL_ACCESSIBLE : General discoverable and connectable MODE_BIT_BAM_LIMITED_ACCESSIBLE : Limited discoverable and connectable MODE_BIT_BAM_CONNECTABLE_ONLY : Connectable but not discoverable.

Set_DeviceMode Sets a value that determines the local Bluetooth Device's Mode.

Get_Class Returns a value that determines the local Bluetooth Device's class.

Set_Class Sets a value that determines the local Bluetooth Device's class. Get_Name Returns a value that determines the local Bluetooth Device's

Friendly Name. Set_Name Sets a value that determines the local Bluetooth Device's

Friendly Name. GetDeviceInfo Returns information about a device based on the device handle

given. DiscoverServices Returns information about a device based on the device handle

given. When the service discovery is complete the Bluetooth stack will call DiscoverServicesComplete.

CreateBond Creates a bond between the local device and the device referenced bydevice handle hDevice. CreateBond will cause PassKeyRequest event to the monitor.

SendPassKey Sends a PIN to a secure remote device whose connection can be made, called as a response to a PassKeyRequest() event. A NULL or "" szPassKey value will cancel/abort the authentication process. TheBluetooth stack will call back with a SendPassKeyComplete event when the call is complete.

Page 356: HC700 SDK Specification

Page 356 of 680

LimitedInquiry Start a device inquiry for limited access devices. When the device discovery is complete the Bluetooth stack will call the LimitedInquiryComplete event callback function with the results.

GeneralInquiry Start a device inquiry for general access devices. When the device discovery is complete the Bluetooth stack will call the GeneralInquiryComplete event callback function with the results.

ConnectLegacyDevice Associates the legacy port given by hLegacyPort with the device handle given in hDeviceHandle. Call this function in response to a EVNT_LegacyPortOpen event to allow a legacy serial connection to be made to a specific device.

GetDeviceHandle Get Bluetooth device handle for device with BD address szAddress, represented by string in format AA:BB:CC:DD:EE:FF

Callback_Events The Monitor SDK will call the callback function registered by the BTMONITOR_RegisterCallback function when an event occurs.

ReadRSSI This command will read the value for the difference between the measured Received Signal Strength Indication (RSSI) and the limits of the Golden Receive Power Range for a device handle to another Bluetooth device.

Data Types

Page 357: HC700 SDK Specification

Page 357 of 680

BTMONITOR_RegisterCallback

Description Registers a notification callback that will be called on BTMonitor API events.

Function Prototype

BOOL BTMONITOR_RegisterCallback ( BTMonitorCallback *fpCallBack)

Parameters BTMonitorCallback *fpCallBack: Pointer to a callback function

Return Values TRUE : Callback registered OK FALSE : Callback not registered. This occurs if a callback was previously registered and not unregistered.

Comments None

BTMONITOR_UnRegisterCallback

Description Unregisters a notification callback. The application will no longer receive BTMonitor API events.

Function Prototype

VOID BTMONITOR_UnRegisterCallback ()

Parameters None

Return Values None

Comments None

GetLocalAddress

Page 358: HC700 SDK Specification

Page 358 of 680

Description Ask the Bluetooth stack to return the address of the local Bluetooth radio. The event GetLocalAddressComplete will be called with the address when the call is complete.

Function Prototype

LONG GetLocalAddress ();

Parameters None

Return Values BT_STATUS_PENDING : Success BT_STATUS_FAILED : Failed. Verify that the stack has been initialized or a radio is attached to the system.

SecurityMode3

Description Enable security mode 3. The event SecurityMode3Complete is called when the operation is complete.

Function Prototype

LONG SecurityMode3 (BOOL bEnable,BOOL Encryption);

Parameters BOOL bEnable : Boolean value of True indicating security mode 3 should be enabled. False disables security mode 3. BOOL bEncryption : Boolean value of True indicates the connection requires encryption. A value of FALSE indicates no encryption will be used during the authentication.

Return Values BT_STATUS_PENDING : Success BT_STATUS_FAILED : Failed to set Security Mode 3.

Page 359: HC700 SDK Specification

Page 359 of 680

Get_SecurityMode3

Description

Function Prototype

LONG Get_SecurityMode3 (BOOL* bSec3Enabled,BOOL* bSec3EncryptionEnabled);

Parameters BOOL* bSec3Enabled: On successful return a value of True indicates that security mode 3 is enabled. False indicates that security mode 3 is disabled. BOOL *bSec3EncryptionEnabled: On Successful return a value of True indicates the connection requires encryption. A value of FALSE indicates no encryption will be used during the connection

Return Values BT_STATUS_PENDING : Success BT_STATUS_FAILED : Failed to get Security Mode 3 settings.

Page 360: HC700 SDK Specification

Page 360 of 680

SaveStackSettings

Description Saves the persistent information from the Bluetooth stack to the registry. Bluetooth monitor applications should call this method before exiting, and any other time as needed. To retrieve the persistent information and send it to the stack, the application should later call the InitStackSettings method.

Function Prototype

LONG SaveStackSettings (LPCTSTR szRegistryKeyForSettings);

Parameters LPCTSTR szRegistryKeyForSettings: String expression containing the registry key where persistent information is saved.

Return Values BT_STATUS_SUCCESS : Success Registy specific error : Failed

Comments The registry key defined by the szRegistryKeyForSettings parameter will be created under HKEY_LOCAL_MACHINE, so stack persistent information is saved on a per machine basis. If the key does not exist, it will be created. If the key does exist, all information in the key will be overwritten by the new information.

InitStackSettings

Description Load all the persistent information stored in the registry to the Bluetooth stack. Persistent information is collected by the SaveStackSettings method.

Function Prototype

LONG InitStackSettings (LPCTSTR szRegistryKeyForSettings);

Parameters LPCTSTR szRegistryKeyForSettings: String expression that contains an application specific registry key containing persistent information.

Return Values BT_STATUS_SUCCESS : Success Registy specific error : Failed

Comments Bluetooth monitor applications should call this method when started.

Page 361: HC700 SDK Specification

Page 361 of 680

NameDiscovery

Description Call to remote device to retrieve the friendly name, address and class of device. When the name discovery is complete the stack will notify the application by calling the NameDiscoveryComplete event with the results.

Function Prototype LONG NameDiscovery (LONG hDevices);

Parameters LONG hDevices :Handle to a device

Return Values BT_STATUS_SUCCESS : Success BT_STATUS_FAILED : Failed

12.1.1.1 Initialize

Description Initializes the Bluetooth stack for use by the monitor application.

Function Prototype LONG Initialize ();

Parameters None

Return Values BT_STATUS_SUCCESS : Success BT_STATUS_FAILED : Failed. Verify that no other Monitor application is running.

Comments Only one Bluetooth monitor application can be running at a time.

Page 362: HC700 SDK Specification

Page 362 of 680

DeInitialize

Description Unbinds the Monitor API from the Bluetooth stack and frees all allocated resources.

Function Prototype LONG DeInitialize ();

Parameters None

Return Values BT_STATUS_SUCCESS : Success BT_STATUS_FAILED : Failed.

Comments This function must be called before exiting an application that is using the monitor API. Failure to do so will result in memory and resource leaks..

Get_DeviceMode

Description Returns a mask that determines the local Bluetooth Device's Mode. Can be a combination of the next values: MODE_BIT_BAM_NOT_ACCESSIBLE : Non discoverable or connectable MODE_BIT_BAM_GENERAL_ACCESSIBLE : General discoverable and connectable MODE_BIT_BAM_LIMITED_ACCESSIBLE : Limited discoverable and connectable MODE_BIT_BAM_CONNECTABLE_ONLY : Connectable but not discoverable

Function Prototype LONG Get_DeviceMode ();

Parameters None

Return Values LDeviceMode : Specifies a bit mask describing the local device mode

Comments None

Set_DeviceMode

Page 363: HC700 SDK Specification

Page 363 of 680

Description Sets a value that determines the local Bluetooth Device's Mode.

Function Prototype

VOID Set_DeviceMode (LONG lNewVal);

Parameters LONG lNewVal: Specifies a bit mask describing the new device mode.

Return Values None

Comments None

Get_Class

Description Returns a value that determines the local Bluetooth Device's class.

Function Prototype LONG Get_Class ();

Parameters None

Return Values LClass : A bitmask that describes local device’s class (as defined in Bluetooth specification).

Comments None

Page 364: HC700 SDK Specification

Page 364 of 680

Set_Class

Description Sets a value that determines the local Bluetooth Device's class.

Function Prototype

VOID Set_Class (LONG lNewVal);

Parameters LONG lNewVal: Specifies a value describing the new device class.

Return Values None

Comments None

Get_Name

Description Returns a value that determines the local Bluetooth Device's Friendly Name.

Function Prototype LPCTSTR Get_Name ();

Parameters None

Return Values LPCTSTR szName : The local Bluetooth Device's Friendly Name

Comments None

Page 365: HC700 SDK Specification

Page 365 of 680

Set_Name

Description Sets a value that determines the local Bluetooth Device's Friendly Name.

Function Prototype

VOID Set_Name (LPCTSTR szNewVal);

Parameters LPCTSTR szNewVal :Specifies the new local Bluetooth Device's Friendly Name

Return Values None

Comments None

GetDeviceInfo

Description Returns information about a device based on the device handle given.

Function Prototype

LONG GetDeviceInfo (LONG hDevice,BTDEVICEINFO *pVar);

Parameters LONG hDevice : The remote device handle, obtained by calling one of the inquiry functions: GeneralInquiry or LimitedInquiry. BTDeviceInfo *pVar :Descriptive information about remote device.

Return Values BT_STATUS_SUCCESS : success BT_STATUS_FAILED : invalid handle

Comments None

Page 366: HC700 SDK Specification

Page 366 of 680

DiscoverServices

Description Returns information about a device based on the device handle given. When the service discovery is complete the Bluetooth stack will call DiscoverServicesComplete.

Function Prototype

LONG DiscoverServices (LONG hDevice);

Parameters LONG hDevice : The remote device handle, obtained by calling one of the inquiry functions: GeneralInquiry or LimitedInquiry.

Return Values BT_STATUS_SUCCESS, BT_STATUS_PENDING : success BT_STATUS_FAILED : invalid handle BT_STATUS_IN_PROGRESS : there is already a service discovery in progress

Comments None

CreateBond

Description Creates a bond between the local device and the device referenced by device handle hDevice. CreateBond will cause PassKeyRequest event to the monitor.

Function Prototype

LONG CreateBond (LONG hDevice);

Parameters LONG hDevice :The remote device handle, obtained by calling one of the inquiry functions: GeneralInquiry or LimitedInquiry.

Return Values RETURN VALUEBT_STATUS_PENDING : success BT_STATUS_BUSY : the stack is busy processing another event

Comments None

Page 367: HC700 SDK Specification

Page 367 of 680

SendPassKey

Description Sends a PIN to a secure remote device whose connection can be made, called as a response to a PassKeyRequest() event. A NULL or "" szPassKey value will cancel/abort the authentication process. TheBluetooth stack will call back with a SendPassKeyComplete event when the call is complete.

Function Prototype LONG SendPassKey (LPCTSTR szPassKey);

Parameters LPCTSTR szPassKey :The PIN to a secure remote device.

Return Values BT_STATUS_SUCCESS : success BT_STATUS_FAILED : Authentication failed

Comments None

LimitedInquiry Description Start a device inquiry for limited access devices. When the device discovery is complete the Bluetooth stack will call the LimitedInquiryComplete event callback function with the results.

Function Prototype

LONG LimitedInquiry();

Parameters None

Return Values BT_STATUS_PENDING : success BT_STATUS_BUSY : the stack is busy processing another event

Comments None

GeneralInquiry

Description Start a device inquiry for general access devices. When the device discovery is complete the Bluetooth stack will call the GeneralInquiryComplete event callback function with the results.

Page 368: HC700 SDK Specification

Page 368 of 680

Function Prototype

LONG GeneralInquiry ();

Parameters None

Return Values BT_STATUS_PENDING : success BT_STATUS_BUSY : the stack is busy processing another event

Comments None

ConnectLegacyDevice

Description Associates the legacy port given by hLegacyPort with the device handle given in hDeviceHandle. Call this function in response to a EVNT_LegacyPortOpen event to allow a legacy serial connection to be made to a specific device.

Function Prototype

LONG ConnectLegacyDevice(LONG hLegacyPort, LONG hDeviceHandle);

Parameters LONG hDeviceHandle :The device handle for the legacy port to be associated with LONG hLegacyPort:The COM port handle to associate this device with

Return Values BT_STATUS_SUCCESS : success BT_STATUS_BUSY : the stack is busy processing another event

Comments None

GetDeviceHandle

Description Get Bluetooth device handle for device with BD address szAddress, represented by string in format AA:BB:CC:DD:EE:FF

Page 369: HC700 SDK Specification

Page 369 of 680

Function Prototype

LONG GetDeviceHandle(TCHAR *szAddress, LONG *plDevHandle);

Parameters LPCTSTR szAddress : BD Address of the device LONG *plDevHandle : pointer to the variable which will receive the handle

Return Values BT_STATUS_FAILED: in case of error.

Comments None

ReadRSSI

Description This command will read the value for the difference between the measured Received Signal Strength Indication (RSSI) and the limits of the Golden Receive Power Range for a device handle to another Bluetooth device. The device handle must indicate a device with an existing ACL connection to the local device. Any positive RSSI value returned indicates how many dB the RSSI is above the upper limit, any negative value indicates how many dB the RSSI is below the lower limit. The value zero indicates that the RSSI is inside the Golden Receive Power Range. How accurate the dB values will be depends on the Bluetooth hardware.

Function Prototype LONG ReadRSSI(BtDeviceHandle DeviceHandle, LONG* rssiVal);

Parameters BtDeviceHandle DeviceHandle: Handle to the remote device whose RSSI value is to be read. LONG* rssiVal: Pointer to a caller allocated long value. On successful return this will contain the RSSI value.

Return Values BT_STATUS_SUCCESS: success. BT_STATUS_FAILED: in case of error. BT_STATUS_BUSY: there is a ReadRSSI request already in progress Bluetooth Monitor API. BT_STATUS_NO_CONNECTION: device is not connected.

Comments None

12.1.2 Callback Events The Monitor SDK will call the callback function registered by the BTMONITOR_RegisterCallback function when an event occurs. Events are returned in the wEvent parameter. Event specific parameters are received in wParam and lParam. Applications should implement a function of this type to receive notification callbacks from the BTMonitor API. Applications should call RegisterCallback to register their callback function. Applications should call UnRegisterCallback to no longer receive notification callbacks from BTMonitor API. Only one callback can be registered at a time. The events and their parameters are:

Page 370: HC700 SDK Specification

Page 370 of 680

EVNT_GeneralInquiryComplete

Description Called after the GeneralInquiry is complete.

Parameters lParam :Contains information about found devices in a pointer to a ST_INQUIRY_COMPLETE structure. wParam :Contains the status of the General Inquiry as a BtErrorCode (see sdktypes.h for values). EVNT_LimitedInquiryComplete

Description Called after the LimitedInquiry is complete.

Parameters lParam :Contains information about found devices in a pointer to a ST_INQUIRY_COMPLETE structure. wParam :Contains the status of the Limited Inquiry as a BtErrorCode (see sdktypes.h for values).

EVNT_NameDiscoveryComplete

Description Called after the NameDiscovery is complete.

Parameters lParam :a pointer to a BTDEVICEINFO structure containing information about the device. wParam :Contains the status of the Name Discovery as a BtErrorCode (see sdktypes.h for values).

EVNT_PassKeyRequest

Description A remote device must have a PIN before a connection can be made. Call the SendPassKey function in response to this event.

Parameters lParam :Contains a handle to the device requesting the PIN. wParam :Always 0.

Page 371: HC700 SDK Specification

Page 371 of 680

EVNT_DiscoverServicesComplete

Description Called after the DiscoverServices is complete.

Parameters lParam :Contains information about the services available on the device in a pointer to a ST_DISCOVERSERVICES_COMPLETE structure. wParam :Contains the status of the DiscoverServices as a BtErrorCode (see sdktypes.h for values).

EVNT_SecurityMode3Complete

Description If the SecurityMode3 function returns BT_STATUS_PENDING then the application will be called with EVNT_SecurityMode3Complete when the operation is finished. Success of the operation is based on whether authentication is set or not. If setting the authentication enable is successful but setting encryption mode fails the operation is still successful.

Parameters lParam :Always 0. wParam :Contains the status of the SecurityMode3 function as a BtErrorCode (see sdktypes.h for values). Success of the operation is based on whether authentication is set or not. If setting the authentication enable is successful but setting encryption mode fails the operation is still successful.

EVNT_SendPassKeyComplete

Description If the SendPassKey function returns BT_STATUS_PENDING then the application will be called with SendPassKeyComplete when the operation is finished.

Parameters lParam :Always 0. wParam :Contains the status of the SendPassKey function as a BtErrorCode (see sdktypes.h for values). Success of the operation is based on whether pairing was successful.

EVNT_LegacyPortOpen

Description This event is called when the user tries to open a legacy port from an application, and no device is associated with the legacy port. To associate a device with the port and allow the Bluetooth connection to finish, call the ConnectLegacyDevice function.

Parameters lParam :the handle to the legacy port opened. wParam :Contains the legacy port number

Page 372: HC700 SDK Specification

Page 372 of 680

EVNT_GetLocalAddressComplete

Description Returns the hardware address of the locally attached Bluetooth radio. Called after the GetLocalAddress is complete.

Parameters lParam : A character string representing the device address. wParam : Contains the status of the GetLocalAddress call. wParam will be BT_STATUS_SUCCESS if a local device was found and it has given us a proper hardware address. wParam will be BT_STATUS_FAILED if there is no local radio found or it is not responding.

EVNT_LinkConnectConf

Description This event is fired when an outgoing ACL connect attempt has completed.

Parameters wParam : Contains the device handle of the remote device. lParam : Contains the status of the connect attempt as a BtErrorCode (see sdktypes.h for values). On a successful connect this will be BEC_NO_ERROR. On a failed connect it will be one of the error codes.

EVNT_LinkConnectInd

Description This event is fired when an incoming ACL connect attempt has completed. Parameters wParam : Contains the device handle of the remote device. lParam : Contains the status of the connect attempt as a BtErrorCode (see sdktypes.h for values). On a successful connect this will be BEC_NO_ERROR. On a failed connect it will be one of the error codes.

EVNT_LinkDisconnect Description This event is fired when an ACL link has disconnected.

Parameters wParam : Contains the device handle of the remote device. lParam :

Page 373: HC700 SDK Specification

Page 373 of 680

Contains the reason for the disconnect as a BtErrorCode (see sdktypes.h for values).

12.1.3 Data Types

12.1.3.1 Structure BTDEVICEINFO Contains information about a remote Bluetooth device. This structure contains the following members: BtDeviceInfo strDevice : Device information returned from the Bluetooth stack. This information is not intended for general application use. Instead use the other members of this structure. char * szFriendlyName : The friendly name of the device char * szFriendlyAddress : The friendly address of the device long classOfDevice : The class ID of the device (see the Bluetooth Core Specification for information on this value.) HANDLE hDevice : The handle to this device

12.1.3.2 Structure ST_DISCOVERSERVICES_COMPLETE Contains information a completed Service Discovery. A pointer to this structure is returned in the callback events for completion of this functions. This structure contains the following members: DWORD dwNumberOfElements : Number of services found in the discovery. LONG lDeviceServices [] : Array of located service class IDs, indexed from 0 to dwNumberOfElements (as defined in Bluetooth specification).

12.1.3.3 Structure ST_INQUIRY_COMPLETE

Page 374: HC700 SDK Specification

Page 374 of 680

Contains information a completed General or Limited Inquiry. A pointer to this structure is returned in the callback events for completion of these functions. This structure contains the following members: DWORD dwNumberOfDevices : Number of devices found in the Inquiry. HANDLE hDeviceHandles[] : Array of located device handles, indexed from 0 to dwNumberOfDevices.

12.1.3.4 Type BTMonitorCallback Defines the callback function. Applications should implement a function of this type to receive notification callbacks from the BTMonitor API. Applications should call RegisterCallback to register their callback function. Applications should call UnRegisterCallback to no longer receive notification callbacks from BTMonitor API. Only one callback can be registered at a time. VOID (CALLBACK BTMonitorCallback) (WORD wEvent, WPARAM wParam, LPARAM lParam);

Page 375: HC700 SDK Specification

Page 375 of 680

Blutooth Object Push API The Client API is intended for developing applications that initiate an Object Push file transfer operation. API user level functions can be accessed through ObjPush.dll (for linkage use ObjPush.lib). Include files are ObjPushExtern.h and ObjPushCallback.h.

BTOBJPUSH_Initialize

Description It initializes the Object Push Client and Server, enabling your application to send and receive objects.

Function Prototype DWORD BTOBJPUSH_Initialize(BOOL bClientOnly);

Parameters BOOL bClientOnly: TRUE – You will only be using Client services in your application. Server services will not be available to your application. FALSE – You will be using both Client and Server services in your application.

Return Values S_OK : The application successfully initialized Object Push. E_FAIL : The application failed to initialize Object Push.

BTOBJPUSH_Deinitialize

Description Deinitialize the object push class.

Function Prototype

BOOL BTOBJPUSH_Deinitialize();

Parameters None

Return Values TRUE : The application successfully released the class. FALSE : The application failed to release the class.

Page 376: HC700 SDK Specification

Page 376 of 680

BTOBJPUSH_GetInboxPath

Description Return the path to the inbox directory where files are placed that have been received from another device.

Function Prototype

DWORD BTOBJPUSH_GetInboxPath(WCHAR *pwcVal)

Parameters WCHAR* pwcVal: Pointer to the UNICODE string containing the path to the inbox.

Return Values S_OK : The application always returns a success value.

BTOBJPUSH_SetInboxPath

Description Sets the path to the inbox directory where files are placed that have been received from another device.

Function Prototype

DWORD BTOBJPUSH_SetInboxPath(WCHAR *pwcNewVal);

Parameters WCHAR* pwcNewVal: Pointer to the UNICODE string containing the path to the inbox.

Return Values S_OK : The inbox path has been set. E_FAIL: The inbox path was not set.

Page 377: HC700 SDK Specification

Page 377 of 680

BTOBJPUSH_GetDefaultvCard

Description Returns the name of the default vCard that will be pushed or pulled during a Business exchange operation.

Function Prototype

DWORD BTOBJPUSH_GetDefaultvCard(WCHAR *pwcVal);

Parameters WCHAR* pwcVal: Pointer to the UNICODE string containing the name of the vCard.

Return Values S_OK : The application always returns a success value.

BTOBJPUSH_SetDefaultvCard

Description Sets the name of the default vCard that will be pushed or pulled during a Business exchange operation.

Function Prototype

DWORD BTOBJPUSH_SetDefaultvCard(WCHAR *pwcNewVal);

Parameters WCHAR* pwcNewVal: Pointer to the UNICODE string containing the name of the vCard.

Return Values S_OK : The vCard name has been set. E_FAIL: The vCard name was not set.

BTOBJPUSH_RetrieveObject

Description

Page 378: HC700 SDK Specification

Page 378 of 680

Instructs the ObjectPush server to retrieve the pending object. This command is called after an EVNT_ObjReceiveRequest event is received.

Function Prototype

DWORD BTOBJPUSH_RetrieveObject(BOOL GetObject);

Parameters BOOL GetObject: TRUE – retrieve the object and place it in the BTInbox. FALSE – do not retrieve the object (refuse it)

Return Values S_OK (always)

BTOBJPUSH_PutObject

Description Instructs the ObjectPush server to send the object specified by pwcObjectName.

Function Prototype

DWORD BTOBJPUSH_PutObject(HANDLE DeviceHandle,WCHAR* pwcObjectName);

Parameters HANDLE DeviceHandle: The handle to a Bluetooth device that will receive the object. Bluetooth device handles are returned from Bluetooth API Inquiry functions. WCHAR* pwcObjectName: The name of the object to send. This is the fully qualified path to the object.

Return Values S_OK : Operation Sucessful E_FAIL : Failed to Put Object

BTOBJPUSH_DovCardExchange

Description Instructs the ObjectPush server to send the vCard specified by pwcObjectName. Once the vCard has been accepted, the server is instructed to retrieve the default vCard from the remote device

Page 379: HC700 SDK Specification

Page 379 of 680

Function Prototype

DWORD BTOBJPUSH_DovCardExchange(HANDLE DeviceHandle,WCHAR* pwcObjectName);

Parameters HANDLE DeviceHandle: The handle to a Bluetooth device that will receive the object. Bluetooth device handles are returned from Bluetooth API Inquiry functions. WHCAR* pwcObjectName: The name of the object to send. This is the fully qualified path to the object.

Return Values S_OK : Operation Sucessful E_FAIL : Failed to Exchange vCards

BTOBJPUSH_AbortTransfer

Description Aborts the transfer of the object specified in the pwcObjectName parameter.

Function Prototype

DWORD BTOBJPUSH_AbortTransfer(WCHAR* pwcObjectName);

Parameters WCHAR* pwcObjectName: The name of the object currently being transferred that should be aborted.

Return Values S_OK : Abort Successful E_Invalidarg : Failed to abort due to invalid pwcObjectName

BTOBJPUSH_RegisterCallback

Description Registers a notification callback that will be called on BTObjPush API events.

Function Prototype

BOOL BTOBJPUSH_RegisterCallback(BTObjPushCallback *fpCallBack);

Parameters BTObjPushCallback* fpCallBack: Pointer to a callback function

Page 380: HC700 SDK Specification

Page 380 of 680

Return Values TRUE : Callback registered OK. FALSE : Callback not registered. This occurs if a callback was previously registered and not unregistered.

BTOBJPUSH_UnRegisterCallback

Description Deregisters the object push callback.

Function Prototype

void BTOBJPUSH_UnRegisterCallback();

Parameters None

Return Values None

12.1.4 Callback Events

12.1.4.1 EVNT_ObjReceiveRequest

Description A device has requested permission to send the object named in the ObjectName parameter. Upon receiving this event, the application should call BTOBJPUSH_RetrieveObject to either accept or refuse the object.

Parameters pwcParam contains the object name lParam = 0 lParam2 = 0

Page 381: HC700 SDK Specification

Page 381 of 680

12.1.4.2 EVNT_ObjectTransferComplete

Description A transfer has been completed. The ObjectName parameter tells the application which object has been transferred. This ObjectName is the same as was passed into the BTOBJPUSH_PutObject method or received in the EVNT_ObjReceiveRequest event.

Parameters pwcParam contains the object name lParam = 0 lParam2 = 0

12.1.4.3 EVNT_ObjectTransferProgressUpdate

Description This event is called periodically to update the application on the progress of the file transfer. The application can use the parameters to update a progress bar or similar UI.

Parameters pwcParam contains the object name lParam contains bytes currently completed lParam2 contains the total length of the object

12.1.4.4 EVNT_ObjectTransferAbort

Description This event is called to inform the application that the current operation has failed. STATUS OBP_STATUS_NO_CONNECTION: We were unable to get an OBEX Connection. OBP_STATUS_OP_ABORTED: The operation was aborted. OBP_STATUS_INTERNAL_ERROR : The operation failed due to an internal error. OBP_STATUS_INVALID_FILENAME: An invalid filename was passed into the file store. Make sure the file exists, and everything is spelled correctly.

Parameters

Page 382: HC700 SDK Specification

Page 382 of 680

pwcParam contains the object name lParam contains status of the failure lParam2 contains the error if an internal error has occurred

Page 383: HC700 SDK Specification

Page 383 of 680

Bluetooth Serial Legacy

Overview

The intent of the Bluetooth (BT) Legacy Serial profile is to allow new or existing Win32 serial COM port based communication applications to operate wirelessly over Bluetooth rather than a serial cable. Be aware that by nature Bluetooth must packetize both data and control line information to send over the airwaves. This process inherently introduces data and control line timing differences from using a real COM port and serial cable. For this reason, a legacy serial cable application must be thoroughly tested and possibly modified for desired operation over the BT legacy serial port. Another difference to consider is that, when using a wired serial port, the user is selecting the remote device connection by physically connecting the serial cable. When using the Bluetooth legacy serial port, it is necessary to view available remote BT devices with legacy serial portservice and select the desired BT device to connect to. In the WinCE operating system, the serial COM ports are defined and installed by the CE device provider to coincide with the actual communication hardware provided in the device. WinCE allows a total of up to ten ports: COM0 through COM9. Port name also may be named BTC0 - BTC9. It is impossible to define the ports COMx and BTCx with the same index ‘x’. The Bluetooth specification allows for several special function serial ports to be defined and enumerated: Legacy Serial, LAN, DUN, and FAX. This discussion only addresses the Legacy Serial profile. The same legacy serial COM port can be used to either initiate a connection to another BT device(client mode), or to respond to a request to open from another BT device (server mode). The reason for pre-designating the type of serial service is to allow the BT radio to advertise the available profile services to other radios by means of the BT Service Discovery protocol. It is possible to pre-define multiple legacy client serial ports to allow several independent applications to communicate to a remote device concurrently.

Page 384: HC700 SDK Specification

Page 384 of 680

BlueTooth WIN32 Serial Communications API

The interface to the BT legacy serial COM port is the CE Win32 Serial Comm API. Details for using these functions can be found in the Help Documentation in MSDN or the documentation included with Microsoft’s Embedded Visual Toolkit. The following standard Microsoft API calls are supported with limitations noted: CreateFile() Opens a COM port and returns a handle to the port. WriteFile() Write data to a COM port identified by the handle. ReadFile() Read data from a COM port identified by the handle. CloseHandle() Closes a COM port identified by the handle. GetCommState() Retrieves the current control settings for a specified communications device. SetCommState() Configures a communications device according to the specifications in a device-control block (DCB). The following fields of the DCB have no function: TXContinueOnXoff, fOutX, fInX, fErrorChar, fNull, fAbortOnError, XonLim, XoffLim, ErrorChar, EofChar, EvtChar. GetCommTimeouts() Retrieves the time-out parameters for all read and write operations on a specified communications device. SetCommTimeouts() Sets the time-out parameters for all read and write operations on a specified communications device. SetCommMask() Specifies a set of events to be monitored for a communications device. The following events will never be returned: EV_BREAK or EV_RXFLAG. GetCommMask() Retrieves the value of the event mask for a specified communications device. WaitCommEvent() Waits for an event to occur for a specified communications device. EscapeCommFunction() Directs a specified communications device to perform an extended function. The following subfunctions are NOT supported: SETIR, CLRIR, SETBREAK, CLRBREAK, SETXON, SETXOFF. Use of SETBREAK or CLRBREAK will NOT return an error. ClearCommError() Retrieves information about a communications error and reports the current status of a communications device. The only errors that will be returned are: CE_FRAME, CE_RXPARITY or CE_OVERRUN. All of the fields of the COMMSTAT structure return as false except the CbInQue and CbOutQue fields. GetCommProperties() Retrieves information about the communications properties for a specified communications device. GetCommModemStatus() Retrieves modem control-register values. PurgeComm() Discards all characters from the output or input buffer of a specified communications resource. The following standard Microsoft API calls may be called but do NOT perform the standard function described and will not return with an error indication: TransmitCommChar() Transmits a specified character ahead of any pending data in the output buffer of the specified communications device. SetupComm() Initializes the communications parameters for a specified communications device.

Page 385: HC700 SDK Specification

Page 385 of 680

Serial Legacy BT Device Connections

The BT legacy serial port will initiate a BT connection (client) or respond to a request to open (server) depending on how the application makes calls to the Win32 communication API and the port registry settings. A BT connection is NOT established when the initial CreateFile() function is called to open the serial port by the application (unless the "ConnectOnOpen" registry value is set) . Also, if the port has the "EnableServer" property set, the COM port will become available as a BT legacy port server. The BT Service Discovery Protocol will advertise that the legacy serial profile is available for an incoming connection. Even heaving a server option enabled, the COM port can be made to initiate a connection (be the client) by calling the WriteFile() function, EscapeCommFunction() or SetCommState() to change the DTR or RTS output control states.

12.1.5 Client Mode The COM port will initiate a connection by calling the WriteFile() (if not disabled by

registry) function, EscapeCommFunction() or SetCommState() (if not disabled by registry) to change the DTR or RTS output control states or by opening the port, that has "ConnectOnOpen" registry option.

Remote BT device to which that COM port will be connected should be specified prior to connection in port's registry value, named "ConnectTo". Actual connection will be performed in the above cases with the help of Bluetooth Monitor application, which will detect the connection event, read the address from the registry and pass it to the BT stack.

By not opening the BT connection when the CreateFile() is executed, the application can be started up and open the serial port at boot up or remain in the background without instantly requiring BT remote connection choice information from. Some legacy applications read the control line states upon start up to determine if a cable is connected. In this case, a BT connection may not be desired, but opening the port is essential. If the serial control status signals (CTS,DSR,RING,RLSD) are read with the GetCommModemStatus() function, before a remote BT connection is initiated, these signals will read as false (OFF).

Upon a successful connect, reading the serial status lines (CTS,DSR,RING,RLSD) will all read true, (ON). The CTS and DSR states can be controlled by the remote device application. The RING and RLSD status for both BT sides will be true (ON) when there is a BT connection, and false (OFF) when the BT connection is discontinued.

12.1.6 Server Mode In server mode, the application must avoid calling the WriteFile() and

EscapeCommFunction() calls until a connection is established by a remote client. A connection can be detected by monitoring the RING,RLSD modem status lines. These signal states are controlled by the BT interface, and will be set true when a connection is made. Server mode can be enabled and disabled on a particular port via a registry entry. The default setting when the registry entry is not present is disabled. When server mode is disabled, the port will not accept any incoming connections.

12.1.7 Sending and Receiving Data The data and control signal exchange is implemented with the Win32 communication calls.

The BT profile is a guaranteed transport, meaning that it is not necessary to provide modem control line handshaking to prevent data loss within the BT communication layers. These modem control lines can be used by the application for other communication purposes. Note that the sequence of data arrival and control line status changes may be different from what is experienced with a real serial cable link due to the packetization of data and control information over the radio link. In particular, it is important not to rely on pulsed signal lines, since these pulses can be combined and lost in the packetization process.

Page 386: HC700 SDK Specification

Page 386 of 680

Modem status line relationships are:

12.1.8 Closing The serial connection is closed in the legacy serial manner of using the CloseHandle() call. This call causes the BT device connection to be normally terminated.

12.1.9 Broken connection

While connected, the CE device and remote device may go out of range, or the remote device may be powered down during a connection. When the BT connection is lost, the modem status signals (RING,RLSD) will read false (OFF). These can be read by calling the GetCommModemStatus() function. It is also possible to set up an event trigger waiting for modem status line changes to watch for this condition. At each data write call the data will be sent if a connection exists and the return status will indicate success. When the connection is unknowingly lost, and a write data call is made, a new connection will be attempted as described in the connecting section above. If the connection is successful, the write call will be completed and return success, however, if a new connection cannot be made, the write call will return with an unsuccessful write error (the number of bytes written will be 0). The application should be prepared to handle this possibility with each write call.

Page 387: HC700 SDK Specification

Page 387 of 680

XTNDConnect Bluetooth File Transfer Protocol This API is used to develop applications supporting the File Transfer profile. The API is split into two separate parts; Client and Server. The API is accessed from the user level only. Types XCBFTP_EVENT_TYPE typedef U32 XCBFTP_EVENT_TYPE; Description Events are passed to the XCBFTP_EventHandler callback function in the FTP_EVENT structure. The data contained in the event structure is valid only in the context of the callback itself. Any data that needs to persist outside of the callback must be copied before the callback returns. Values Client and Server Event. XCBFTP_EVENT_CONNECTION_STATUS An event occurred on the current connection. This event is sent to indicate that a connection has been dropped or established. The data.h Connection member is valid only for the client. The status may be: BT_STATUS_SUCCESS success BT_STATUS_DEVICE_NOT_FOUND A bad BdAddr was supplied in XCBFTP_Connect() BT_STATUS_CONNECTION_FAILED unable to connect (timeout) BT_STATUS_NO_CONNECTION lost the current connection. XCBFTP_EVENT_TRANSFER_PROGRESS A file transfer is in progress. The status will be BT_STATUS_PENDING and the data member will be an XCBFTP_FILE_PROGRESS_RESULT struct indicating details of the file progress at intervals during a XCBFTP_GetFile() or XCBFTP_SendFile(). The first XCBFTP_EVENT_TRANSFER_PROGRESS event will always indicate 0 bytes complete. Subsequent intermittent progress events will continue until a XCBFTP_EVENT_TRANSFER_COMPLETE event occurs for the file. XCBFTP_EVENT_TRANSFER_COMPLETE A file transfer is complete. The data member of the event will be a XCBFTP_FILE_COMPLETE_RESULT indicating the completion of a XCBFTP_GetFile(), XCBFTP_SendFile, XCBFTP_DeleteFile() or XCBFTP_CreateFolder() operation. The status may be: BT_STATUS_SUCCESS success BT_STATUS_PENDING success, additional operations still pending BT_STATUS_ABORT transfer was aborted BT_STATUS_NOT_FOUND could not open file BT_STATUS_RESTRICTED permission denied BT_STATUS_NOT_FOUND no such file BT_STATUS_TIMEOUT operation timeout. Server Only Event. XCBFTP_EVENT_TRANSFER_REQUEST A file transfer has been requested. The data member of the event will be a XCBFTP_TRANSFER_REQUEST indicating the file name and the transfer type (Get or Send). The status will be BT_STATUS_PENDING and XCBFTP_ApproveTransfer() must be called to permit or deny the file transfer. This event will only occur on server folder shares with the XCBFTP_AUTHORIZE_PROPERTY property set. HXCBFTP_CLIENT typedef HANDLE HXCBFTP_CLIENT; Description Handle to a File Transfer Session Connection. Returned by a successful call to XCBFTP_Connect

Page 388: HC700 SDK Specification

Page 388 of 680

and used for all subsequent operations on that connection. XCBFTP_TRANSFER_TYPE typedef U32 XCBFTP_TRANSFER_TYPE; Description File Transfer types are possible dwFileTransferType values in the XCBFTP_FILE_PROGRESS_RESULT struct or the FTP_EVENT data associated with XCBFTP_EVENT_TRANSFER_PROGRESS and XCBFTP_EVENT_TRANSFER_COMPLETE events respectively. Values XCBFTP_TRANSFER_TYPE_SEND XCBFTP_TRANSFER_TYPE_GET XCBFTP_TRANSFER_TYPE_DELETE XCBFTP_TRANSFER_TYPE_SETPATH XCBFTP_TRANSFER_TYPE_GETFOLDER XCBFTP_FILE_PROGRESS_RESULT typedef struct _XCBFTP_FILE_PROGRESS_RESULT XCBFTP_FILE_PROGRESS_RESULT; Description When the FTP_EVENT dwEventType is XCBFTP_EVENT_TRANSFER_PROGRESS, the data member will be a XCBFTP_FILE_PROGRESS_RESULT struct. The buffer pointed to by pwcFileName is only valid for the duration of the event callback only. Server events will always have NULL for hConnection; Members HXCBFTP_CLIENT hClient Connection Handle. DWORD dwFileTransferType file transfer type of the event. const WCHAR *pwcFileName file (or folder) name. DWORD dwBytesComplete file transfer bytes transferred. DWORD dwObjectLength total bytes to be transferred.

XCBFTP_FILE_COMPLETE_RESULT typedef struct _XCBFTP_FILE_COMPLETE_RESULT XCBFTP_FILE_COMPLETE_RESULT; Description When the FTP_EVENT dwEventType is XCBFTP_EVENT_TRANSFER_COMPLETE, the data member will be an XCBFTP_FILE_COMPLETE_RESULT struct. The buffer pointed to by pwcFileName is only valid for the duration of the event callback only. Server events will always have NULL for hConnection; Members HXCBFTP_CLIENT hClient connection handle. const WCHAR *pwcFileName file (or folder) name. XCBFTP_TRANSFER_TYPE dwFileTransferType file transfer type of the event. XCBFTP_TRANSFER_REQUEST typedef struct _XCBFTP_TRANSFER_REQUEST XCBFTP_TRANSFER_REQUEST; Description When the FTP_EVENT dwEventType is XCBFTP_EVENT_TRANSFER_COMPLETE, the data

Page 389: HC700 SDK Specification

Page 389 of 680

member will be an XCBFTP_FILE_COMPLETE_RESULT struct. The buffer pointed to by pwcFileName is only valid for the duration of the event callback only. Server events will always have NULL for hConnection; Members XCBFTP_TRANSFER_TYPE dwFileTransferType file transfer type of the event. const WCHAR *pwcFileName

FTP_EVENT typedef struct _FTP_EVENT FTP_EVENT; Description When the FTP_EVENT dwEventType is XCBFTP_EVENT_TRANSFER_PROGRESS, the data member will be a XCBFTP_FILE_PROGRESS_RESULT struct. When dwEventType is XCBFTP_EVENT_TRANSFER_PROGRESS, the data member will be an XCBFTP_FILE_PROGRESS_RESULT struct. When dwEventType is XCBFTP_EVENT_CONNECTION_STATUS, the data member will be an HXCBFTP_CONNECTION. Members XCBFTP_EVENT_TYPE dwEventType type of the event. BtStatus status status of the event. union data Event specific data. XCBFTP_FILE_PROGRESS_RESULT stFileProgress XCBFTP_FILE_COMPLETE_RESULT stFileComplete HXCBFTP_CLIENT hClient XCBFTP_TRANSFER_REQUEST stTransRequest XCBFTP_PROPERTY typedef U32 XCBFTP_PROPERTY; Description The properties below are the supported server share file properties. Values XCBFTP_FILEREAD_PROPERTY XCBFTP_FILEWRITE_PROPERTY XCBFTP_FILEDELETE_PROPERTY XCBFTP_FOLDERREAD_PROPERTY XCBFTP_FOLDERWRITE_PROPERTY XCBFTP_FOLDERDELETE_PROPERTY XCBFTP_HIDDENREAD_PROPERTY XCBFTP_HIDDENWRITE_PROPERTY XCBFTP_HIDDENDELETE_PROPERTY XCBFTP_HIDDENSHOW_PROPERTY XCBFTP_SYSTEMREAD_PROPERTY XCBFTP_SYSTEMWRITE_PROPERTY XCBFTP_SYSTEMDELETE_PROPERTY XCBFTP_SYSTEMSHOW_PROPERTY XCBFTP_AUTHORIZE_PROPERTY XCBFTP_DEFAULT_SHARE_PROPERTY

Functions Defined by the Application XCB_FileTransferCallback typedef VOID (CALLBACK XCB_FileTransferCallback) (FTP_EVENT*);

Page 390: HC700 SDK Specification

Page 390 of 680

Description Definition for the File Transfer server and client callback function. Applications should implement a function of this type to receive notification callbacks from the XCB File Transfer API. Client applications should provide a callback pointer to the XCBFTP_Connect() function to begin receiving callback events. The client callback function will cease to be used after calling XCBFTP_Disconnect. Server applications should provide a callback pointer to XCBFTP_StartServer() to begin receiving events. The server callback function will cease to be used after a call to XCBFTP_StopServer(.) The data contained in the FTP_EVENT structure is only valid during the context of the callback. Client Types XCBFTP_FILE_INFO typedef struct _XCBFTP_FILE_INFO XCBFTP_FILE_INFO; Description This structure is returned in calls to XCBFTP_GetFirstFileInfo() and XCBFTP_GetNextFileInfo. It lists properties for a file in the current folder on the File Transfer Server. Members WCHAR wcaName[MAX_PATH] DWORD dwDate DWORD dwSize DWORD dwAttributes FTP Client Functions These user level functions can be accessed through FileTransferClient.dll (use XcbFtplient.h and FileTransferClient.lib). XCBFTP_Startup BtStatus XCBFTP_Startup(HXCBFTP_CLIENT* phClient, XCB_FileTransferCallback *fpCallBack); Description Initializes Bluetooth client. XCBFTP_Startup must be called first, and it returns an HXCBFTP_CLIENT handle to the phClient parameter. This client handle is used for all subsequent client API calls, and is valid until XCBFTP_Shutdown is called. Parameters phClient Pointer to an HXCBFTP_CLIENT that will be set to a valid client handle upon the return of BT_STATUS_SUCCESS (otherwise set NULL). fpCallBack Pointer to function that receives File Transfer client events. This value cannot be NULL. Returns BT_STATUS_SUCCESS Returned valid handle in pHandle. BT_STATUS_INVALID_PARM An invalid pointer parameter was passed in. BT_STATUS_FAILED Initialization failed. XCBFTP_Connect BtStatus XCBFTP_Connect(HXCBFTP_CLIENT hClient, BdAddr *pstDeviceAddress);

Page 391: HC700 SDK Specification

Page 391 of 680

Description Initiates a connection with the device of the given address. The XCBFTP_Connect function is an asynchronous operation. Return value of BT_STATUS_PENDING indicates that the connection is being attempted. Upon connection, the application will receive a XCBFTP_EVENT_CONNECTION_STATUS event via the fpCallback function passed into XCBFTP_Startup. Parameters hClient handle to the client. pstDeviceAddress The Bluetooth address of the device to connect to. Returns BT_STATUS_PENDING Attempting to connect. BT_STATUS_FAILED Initialization failed. BT_STATUS_NO_RESOURCES Out of memory. BT_STATUS_CONNECTION_FAILED Unable to connect.

XCBFTP_SetTransferDirectory BtStatus XCBFTP_SetTransferDirectory( hClient, WCHAR*pwcDirectoryPath); HXCBFTP_CLIENT Description Sets the client transfer directory. This directory is the local location where files that are retrieved from a FT server are placed. This path defaults to the root directory. This function is also used to set the target directory for any operation. XCBFTP_GetFile Parameters hClient handle to the client. pwcDirectoryPath Null terminated UNICODE string containing the full path to a target directory for all file being received.. Returns BT_STATUS_INVALID_PARM Bad connection handle or invalid path. XCBFTP_GetTransferDirectory BtStatus XCBFTP_GetTransferDirectory(HXCBFTP_CLIENT hClient, WCHAR *pwcDirectoryPath, DWORD *pdwSize); Description Retrieves the current client transfer directory. Parameters hClient handle to the client. pwcDirectoryPath pointer to a WCHAR buffer that receives a UNICODE null terminated string that contains the full path of the transfer directory. pdwSize Buffer indicating the size, in WCHARs, of the buffer pointed to by pwcDirectoryPath. Returns BT_STATUS_INVALID_PARM Bad connection handle.

XCBFTP_GetFirstFileInfo BtStatus XCBFTP_GetFirstFileInfo(HXCBFTP_CLIENT hClient, XCBFTP_FILE_INFO* pFileInfo); Description Initializes a XCBFTP_FILE_INFO structure. This structure must be allocated by the calling

Page 392: HC700 SDK Specification

Page 392 of 680

application. Upon a successful return, pFileInfo will contain the properties of the “first” file in the current folder on the remote device. The “first” file is simply the first file in this API’s representation of the folder listing retrieved from a remote FT server. The “next” file (initially NULL) will always be reset to the “second” file whenever XCBFTP_GetFirstFileInfo() is called. For example, to get all files, call XCBFTP_GetFirstFileInfo(), then repeatedly call XCBFTP_GetNextFileInfo() until BT_STATUS_NOT_FOUND is returned. Parameters hClient handle to the client. pFileInfo pointer to a XCBFTP_FILE_INFO to receive file information on the first file in the current folder. The dwPropertyFlags member of the XCBFTP_FILE_INFO struct supports these standard file attributes: FILE_SHARE_READ (0x00000001): Assumed for all files in all shared folders. FILE_SHARE_WRITE (0x00000002): Folders may be created. Files may be added or modified. If a file has the Read-only attribute set on the server system, it will take precedence and will not have WRITE rights (i.e. files with Read-only attribute set cannot be overwritten just because the folder is shared as read/write). FILE_SHARE_DELETE (0x00000004): File/Folder may be deleted. FILE_ATTRIBUTE_DIRECTORY (0x00000010): The file object is a directory. Returns BT_STATUS_FAILED Failure. BT_STATUS_INVALID_PARM Invalid connection handle or pointer. BT_STATUS_NOT_FOUND No items in the current directory.

XCBFTP_GetNextFileInfo BtStatus XCBFTP_GetNextFileInfo(HXCBFTP_CLIENT hClient, XCBFTP_FILE_INFO* pFileInfo); Description Initializes a XCBFTP_FILE_INFO structure. This structure must be allocated by the calling application. Upon a successful return, pFileInfo will contain the “next” file’s name and properties after having called GetFirstFileInfo() (see GetFirstFileInfo for additional details). The internal file pointer will be incremented to a new “next” file for subsequent calls. Parameters hClient handle to the client. pFileInfo pointer to a XCBFTP_FILE_INFO to receive file information on the first file in the current folder. The dwAttributes member of the XCBFTP_FILE_INFO struct supports these standard file attributes: FILE_SHARE_READ (0x00000001): Assumed for all files in all shared folders. FILE_SHARE_WRITE (0x00000002): Folders may be created. Files may be added or modified. If a file has the Read-only attribute set on the server system, it will take precedence and will not have WRITE rights (i.e. files with Read-only attribute set cannot be overwritten just because the folder is shared as read/write). FILE_SHARE_DELETE (0x00000004): File/Folder may be deleted. FILE_ATTRIBUTE_DIRECTORY (0x00000010): The file object is a directory. Returns BT_STATUS_FAILED Failure due to no connection, a bad handle, or an error in current directory. BT_STATUS_INVALID_PARM Bad connection handle or pointer. BT_STATUS_NOT_FOUND No more items are the current directory.

XCBFTP_SetCurrentFolder BtStatus XCBFTP_SetCurrentFolder(HXCBFTP_CLIENT hClient, WCHAR* pwcFolderPath);

Page 393: HC700 SDK Specification

Page 393 of 680

Description Sets the remote server’s current directory to pwcFolderPath. The path may be absolute (begins with the root) or relative to the current directory. Generally, an application that browses only one level at a time should use the relative path. The string “..” is used to set to the parent directory and “.” to refresh the current directory. A folder browse object file will automatically be transferred from the remote server after the folder is set. XCBFTP_SetCurrentFolder is asynchronous (non-blocking). Unlike some other asynchronous calls, the application must wait for the set to complete before calling SetCurrentFolder again. A return value of BT_STATUS_PENDING indicates that the request is queued, and an callback event will occur when completed. A file transfer event of type XCBFTP_EVENT_TRANSFER_COMPLETE will occur and contain a XCBFTP_FILE_COMPLETE_RESULT struct with a type of XCBFTP_TRANSFER_TYPE_GETFOLDER indicating the retrieval of a newly refreshed folder browse object (ready for reading by XCBFTP_GetFirstFileInfo, etc.). Parameters hClient handle to the client. pwcFolderPath Null terminated UNICODE string containing the name of the folder in the current folder or a full absolute path to the desired folder. Returns BT_STATUS_INVALID_PARM Invalid connection handle or the folder name was not found. BT_STATUS_RESTRICTED - Other file transfer operations are pending. All transfers from the current directory must be complete before trying to change the servers working directory.

XCBFTP_GetFile BtStatus XCBFTP_GetFile (HXCBFTP_CLIENT hClient, WCHAR* pwcFileName); Description Copies the named file or folder named filename from the server’s current directory to the local Transfer Directory. XCBFTP_GetFile is asynchronous (non-blocking). A return value of BT_STATUS_PENDING indicates that the request was successfully queued. A file transfer event of type XCBFTP_EVENT_TRANSFER_COMPLETE will occur with XCBFTP_FILE_PROGRESS_RESULT struct type XCBFTP_TRANSFER_TYPE_GET when the transfer is completed successfully or has failed. XCBFTP_GetFile may be called repeatedly to get multiple objects. The requests are queued. However, application must wait for all GetFile operations to complete before calling other types of operations (Send, Delete, etc.). A XCBFTP_EVENT_TRANSFER_COMPLETE event will occur when all each Get operation is complete. A status of BT_STATUS_PENDING indicates additional files are continuing to transfer. Events of type XCBFTP_EVENT_TRANSFER_PROGRESS will be called intermittently during the file transfer to indicate file transfer progress. Parameters hClient handle to the client pwcFileName Null terminated UNICODE string containing the name of the file to retrieve. Returns BT_STATUS_FAILED Failure. BT_STATUS_INVALID_PARM Invalid connection handle or the file name was not found. BT_STATUS_RESTRICTED Get not allowed (read only.)

XCBFTP_SendFile BtStatus XCBFTP_SendFile (HXCBFTP_CLIENT hClient, WCHAR* pwcFileName); Description

Page 394: HC700 SDK Specification

Page 394 of 680

Copies the file or folder named in pwcFileName from the local machine to the server’s current directory. If pwcFileName contains path information then it will be assumed that pwcFileName contains the full path to the object. If no path information is present then it is assumed that the object is in the current local Transfer Directory. A folder browse object file will automatically be transferred after the last file is sent so that the remote folder can be refreshed. XCBFTP_SendFile is asynchronous (non-blocking). A return value of BT_STATUS_PENDING indicates that the request was successfully queued. A file transfer event of type XCBFTP_EVENT_TRANSFER_COMPLETE will occur with XCBFTP_FILE_PROGRESS_RESULT struct type XCBFTP_TRANSFER_TYPE_SEND when the transfer has completed successfully or if it has failed. XCBFTP_SendFile may be called repeatedly to send multiple objects. The requests are queued. However, the calling application must wait for all SendFile operations to complete before calling other types of operations (Get, Delete, etc.). A XCBFTP_EVENT_TRANSFER_COMPLETE event will occur when each Send operation is complete. A status of BT_STATUS_PENDING indicates additional files are continuing to transfer, or that a folder browse object is being retrieved. After the final file send, a XCBFTP_EVENT_TRANSFER_COMPLETE event will occur with XCBFTP_FILE_COMPLETE_RESULT struct type XCBFTP_TRANSFER_TYPE_GETFOLDER to indicate that the folder browse object file is transferred. The folder contents can be refreshed through calls to XCBFTP_GetFirstFileInfo and XCBFTP_GetNextFileInfo. Events of type XCBFTP_EVENT_TRANSFER_PROGRESS will be called intermittently during the file transfer to indicate file transfer progress. Parameters hClient handle to the client pwcFileName Null terminated UNICODE string containing the name of the file to send. Returns BT_STATUS_FAILED Failure. BT_STATUS_INVALID_PARM Invalid connection handle or the file name was not found. BT_STATUS_RESTRICTED Send not allowed (read only.)

XCBFTP_AbortTransfer BtStatus XCBFTP_AbortTransfer(HXCBFTP_CLIENT hClient, BOOL bAbortAll); Description Aborts either just the current transfer or all pending GetFile or SendFile operations that have not yet completed for the given connection. Parameters hClient handle to the client bAbortAll TRUE = Abort all pending file transfers FALSE = Abort only the current file transfer. If bAbortAll is true, and a recursive GetFile or SendFile operation was in progress at the time of the abort, the current server directory should revert to the directory where the GetFile or SendFile was initiated. Returns BT_STATUS_INVALID_PARM Bad connection handle. XCBFTP_CreateFolder BtStatus XCBFTP_CreateFolder(HXCBFTP_CLIENT hClient, WCHAR* pwcFolderName); Description Creates a new folder named folderName in the server’s current directory. XCBFTP_CreateFolder is asynchronous (non-blocking). A return value of BT_STATUS_PENDING indicates that the request was successfully queued. On success, a file transfer event of type XCBFTP_EVENT_TRANSFER_COMPLETE will occur with

Page 395: HC700 SDK Specification

Page 395 of 680

XCBFTP_FILE_COMPLETE_RESULT struct type XCBFTP_TRANSFER_TYPE_GETFOLDER to indicate the success of the folder creation and the change to the newly created directory. Function will fail if the server’s current directory has the ReadOnly attribute set. Parameters hClient handle to the client pwcFolderName Null terminated UNICODE string containing the name of the folder to be created within the current folder on the server. Returns BT_STATUS_FAILED No connection. BT_STATUS_INVALID_PARM Bad connection handle or the folder name is invalid. BT_STATUS_BUSY File transfer operations are pending. All pending transfers must be completed prior to calling this function.

XCBFTP_DeleteFile BtStatus XCBFTP_DeleteFile(HXCBFTP_CLIENT hClient, WCHAR* pwcFileName); Description Removes the named file or folder in the server’s current directory. Fails if files or folders are Read-Only in the current directory. A folder browse object file will automatically be transferred after the last file is deleted so that the remote folder can be refreshed. XCBFTP_CreateFolder is asynchronous (non-blocking), and thus multiple calls to this function may be made to queue multiple file deletes. A return value of BT_STATUS_PENDING indicates that the request was successfully queued. A file transfer event of type XCBFTP_EVENT_TRANSFER_COMPLETE will occur to indicate the success or failure of the folder deletion. The status of the event will usually be BT_STATUS_PENDING. This indicates that either there are additional deletions queued, or that a folder browse object request is queued (automatically). A final client event XCBFTP_EVENT_TRANSFER_COMPLETE will contain a XCBFTP_FILE_COMPLETE_RESULT struct with a type of XCBFTP_TRANSFER_TYPE_GETFOLDER indicating the retrieval of a newly refreshed folder browse object (ready for reading by XCBFTP_GetFirstFileInfo, etc.). Parameters hClient handle to the client. pwcFileName Null terminated UNICODE string containing the name of the file or folder to be deleted. Returns BT_STATUS_FAILED No connection. BT_STATUS_INVALID_PARM Bad connection handle or the file or folder name was not found. BT_STATUS_RESTRICTED File transfer operations (other than deletes)are pending. All current other file operations must be completed before trying to delete a file.

XCBFTP_Disconnect BtStatus XCBFTP_Disconnect(HXCBFTP_CLIENT hClient); Description Disconnect from the currently connected device. Parameters hClient handle to the client.

Page 396: HC700 SDK Specification

Page 396 of 680

Returns BT_STATUS_PENDING Attempting to drop the connection. A file transfer event of type XCBFTP_EVENT_CONNECTION_STATUS will occur to indicate the success or failure of the folder disconnect. BT_STATUS_FAILED Failure due to other file transfer operations may be active. If this is the case, abort all active transfers before calling this function. XCBFTP_Shutdown BtStatus XCBFTP_Shutdown(HXCBFTP_CLIENT hClient); Description Frees all client resources. Note: Before calling this function all transfers must be completed and a connection to a remote server cannot exist. Parameters hClient handle to the client. hClient is invalid after a call to XCBFTP_Shutdown. Returns BT_STATUS_SUCCESS Shutdown successfully. BT_STATUS_INVALID_PARM Invalid handle. BT_STATUS_FAILED Unable to deinitialize the client due to a pre-existing connection. File Transfer Server The File Transfer Server implements a “virtual root directory” that is a collection of one or more directory paths to be listed as folders in the root directory. Each directory path is “shared” with a display name. At least one directory must be shared to start the server. Only one instance of the File Transfer Server may successfully be started API Server Defined Property

FILE_USE_FILE_WRITE #define FILE_USE_FILE_WRITE 0x00000008 Description Use each file’s Read-only attribute to determine whether to allow WRITE rights. This is an additional API defined property for shared folders. Server Constants XCBFTP_MAX_SHARE_NAME_LENGTH #define XCBFTP_MAX_SHARE_NAME_LENGTH 32 Description Maximum length that any shared folder name can be.

Page 397: HC700 SDK Specification

Page 397 of 680

Server Types XCBFTP_SHARE_FOLDER_INFO typedef struct _XCBFTP_SHARE_FOLDER_INFO XCBFTP_SHARE_FOLDER_INFO; Description This structure is used to encapsulate information about directories on the server that are being shared for File Transfer. Members WCHAR wcDirectoryPath[MAX_PATH] WCHAR wcDisplayName[XCBFTP_MAX_SHARE_NAME_LENGTH] DWORD dwPropertyFlags Server Functions These user level functions can be accessed through FileTransferServer.dll (use XcbFtpServer.h and FileTransferServer.lib). . XCBFTP_StartServer BtStatus XCBFTP_StartServer (XCB_FileTransferCallback *fpCallBack); Description Starts the File Transfer server and registers the event callback. Parameters fpCallBack Pointer to function that receives File Transfer server events. Returns BT_STATUS_SUCCESS - Success. BT_STATUS_FAILED - Failure - unable to register or unable to initialize the server.

XCBFTP_ShareFolder BtStatus XCBFTP_ShareFolder (WCHAR* pwcFolderPath, WCHAR* pwcDisplayName, DWORD dwPropertyFlags, DWORD* pdwShareHandle); Description Adds the folder in pwcFolderPath to the list of directories being shared. The pwcDisplayName contains the friendly name associated with the shared. The pwcDisplayName is the value sent to clients when the client requests a folder listing object. dwPropertyFlags contains the properties of folder specified in pwcFolderPath and all subfolders under pwcFolderPath. Upon a successful return, pdwShareHandle will contain a handle to the Shared Folder. Folder handles are used internally by the implementation to manage shared folders in the other XCBFTP_ShareFolder operations. Parameters pwcFolderPath Null terminated UNICODE string containing the full path to the folder to add. pwcDisplayName Null terminated UNICODE string containing the friendly name to be associated to the new share. dwPropertyFlags Bit mask containing any combination of the XCBFTP_XXXXX_PROPERTY properties stated in XcbFtp.h. This value is used to indicate read, write and delete properties for normal hidden and system files, or to set authorization if it is required. pdwShareHandle Buffer to receive the new share’s handle.

Page 398: HC700 SDK Specification

Page 398 of 680

Returns BT_STATUS_NO_RESOURCES Allocation error or maximum number of shares has been reached. BT_STATUS_INVALID_PARM pwcFolderPath is not a valid directory.

XCBFTP_RemoveSharedFolder BtStatus XCBFTP_RemoveSharedFolder (DWORD dwShareHandle); Description Remove the directory associated with dwShareHandle (obtained from XCBFTP_ShareFolder, XCBFTP_GetFirstSharedFolder or XCBFTP_GetNextSharedFolder) from the list of directories in server’s root file transfer directory. XCBFTP_RemoveSharedFolder will fail if a connection is active. Parameters dwShareHandle handle to the shared folder to be removed. Returns BT_STATUS_INVALID_PARM No share found with the given handle. BT_STATUS_FAILED Connections are active. XCBFTP_SetSharedFolderInfo BtStatus XCBFTP_SetSharedFolderInfo (DWORD dwShareHandle, WCHAR* pwcFolderPath, WCHAR* pwcDisplayName, DWORD dwropertyFlags); Description Modifies the display name, path or properties for the given shareHandle (obtained from XCBFTP_ShareFolder, XCBFTP_GetFirstSharedFolder or XCBFTP_GetNextSharedFolder). Parameters dwShareHandle handle to the shared folder to be modified. pwcFolderPath Null terminated UNICODE string containing the new absolute folder path. pwcDisplayName UNICODE null terminated string containing the new share name to be associated with the share. dwPropertyFlags Bit mask containing any combination of the XCBFTP_XXXXX_PROPERTY properties stated in XcbFtp.h. This value is used to indicate read, write and delete properties for normal hidden and system files, or to set authorization if it is required. Returns BT_STATUS_FAILED Unable to change the share’s information.

XCBFTP_GetFirstSharedFolder BtStatus XCBFTP_GetFirstSharedFolder(DWORD* pdwShareHandle); Description This function returns the handle of the “first” shared folder. The “first” shared folder is simply the first share in the implementation’s internal share list. The pointer will be set to NULL if no folders have been shared. To get handles for all shared files, call XCBFTP_GetFirstSharedFolder, then repeatedly call XCBFTP_GetNextSharedFolder with the first or previous handle until a NULL pShareHandle pointer is returned. Parameters pdwShareHandle pointer to a DWORD to receive the handle to the “first” folder. Returns

Page 399: HC700 SDK Specification

Page 399 of 680

BT_STATUS_SUCCESS - Success - pdwShareHandle points to a valid share handle. BT_STATUS_NOT_FOUND - There are no shared folders. XCBFTP_GetNextSharedFolder BtStatus XCBFTP_GetNextSharedFolder (DWORD* pdwShareHandle); Description Returns the handle of the “next” shared folder following the given pShareHandle. The incoming handle must be valid (obtained from GetFirstSharedFolder or previous call to GetNextSharedFolder). Parameters pdwShareHandle pointer to a DWORD containing the “previous” share handle (This handle can be obtained by calling GetFirstSharedFolder or GetNextSharedFolder). On return this value will contain the handle to the “next” share. Returns BT_STATUS_SUCCESS - Success - pdwShareHandle points to valid handle. BT_STATUS_NOT_FOUND - There is no “next” share or pdwShareHandle in was invalid for the “last” shared folder. XCBFTP_GetSharedFolderInfo BtStatus XCBFTP_GetSharedFolderInfo (DWORD dwShareHandle, XCBFTP_SHARE_FOLDER_INFO* pShareInfo); Description Fills in the caller allocated XCBFTP_SHARE_FOLDER_INFO struct with the shared folder’s name, path and properties for the given shareHandle. Parameters dwShareHandle shared folder handle returned by call to XCBFTP_GetFirstSharedFolder or XCBFTP_GetNextSharedFolder. pShareInfo pointer to a XCBFTP_SHARE_FOLDER_INFO that will be initialized with data for the given share handle. Returns BT_STATUS_INVALID_PARM No share found with the given handle.

XCBFTP_StopSever BtStatus XCBFTP_StopServer(); Description Aborts any current operations and closes any active connection. This call will also unregister the File Transfer SPD entry and the File Transfer event callback. Note: Before calling this function all transfers must be completed and a connection to a remote client cannot exist. Parameters none. Returns BT_STATUS_SUCCESS - Success. BT_STATUS_FAILED - Failure.

Page 400: HC700 SDK Specification

Page 400 of 680

XCBFTP_AbortTransfer BtStatus XCBFTP_AbortTransfer(); Description Aborts the currently active file transfer. Parameters none. Returns BT_STATUS_SUCCESS - Transfer aborted. BT_STATUS_PENDING - An attempt is being made to abort the transfer. The server application will receive a TRANSFER complete event when the transfer is aborted. BT_STATUS_FAILED - There is no pending transfer to abort. XCBFTP_ApproveTransfer BtStatus XCBFTP_ApproveTransfer(BOOL bApprove); Description Approves or denies a pending Get or Send request. A call to this function is required to complete a transfer when the XCBFTP_AUTHORIZE_PROPERTY property is set for a shared folder - see XCBFTP_ShareFolder() or XCBFTP_SetSharedFolderInfo(). Parameters bApprove TRUE = Allow the transfer operation. FALSE = Refuse the transfer operation. Returns BT_STATUS_SUCCESS - Success.

Bluetooth Stack Control API The stack control API is intended for advanced users and adds the possibility to control the

basic behavior of Bluetooth stack. User level functions for controlling this functionality can be accessed through XCBStackControl.dll (for linkage use XCBStackControl.lib, include file is XCBStackControl.h).

XCBSC_DisableStack

Description

12.1.9.1.1 Disables the XTNDConnect Blue protocol stack. The HCI layer of the stack is shut down and BT Btluetooth chip is powered off. Active connections and running opeartions are dropped and applications are notified of the disconnects/operation failures.

Function Prototype

BtStatus XCBSC_DisableStack()

Parameters

Page 401: HC700 SDK Specification

Page 401 of 680

None

Return Values BT_STATUS_SUCCESS: Stack disabled successfully. BT_STATUS_FAILED: Stack does not exist.

Comments While disabled, the protocol stack remains loaded in memory and responds to calls from all

APIs. If configuration functions such as setting the accessible mode or device name are called, the settings will be stored by the stack and applied to the radio when the stack is enabled. If functions that require the radio are called, such as connecting to a remote device or sending data, they will fail.

If device is powered off (stack is disabled) during active connection, remote side will notify the disconnection after Bluetooth hardware link maintenance timeout (~20 sec).

Stack disable state persists between terminal warm boots.

XCBSC_EnableStack

Description

12.1.9.1.2 Enables the XTNDConnect Blue protocol stack. The radio is powered on, the HCI layer is re-initialized and re-bound to the hardware driver. All current settings are pushed to the radio. The protocol stack is ready for operation as soon as the XCBSC_EnableStack call returns successfully. The stack startup may be a longly process (up to a number of seconds in case of successful operation and up to 60 seconds in case of some severe problems in BT HW or SW).

Function Prototype

BtStatus XCBSC_EnableStack()

Parameters None

Return Values BT_STATUS_SUCCESS: Stack enabled successfully. BT_STATUS_FAILED: Stack does not exist or failed to start.

Comments Stack enable state persists between terminal warm boots. When stack enabling is failed, next time device is warm booted, stack will try to initialize again,

i.e. logically it will remain in enabled state.

12.1.9.1.3 XCBSC_GetStackState

Description

12.1.9.1.4 Retreives the current state of Bluetooth stack.

Function Prototype

BtStatus XCBSC_GetStackState(BOOL bWait, PDWORD pdwState)

Parameters BOOL bWait: TRUE means, if stack is currently in initialization stage (while powering on it may be a longly process (up to a number of seconds in case of successful operation and up to 60 seconds in case of some severe problems in BT HW or SW), to wait until initialization finishing and then return the state, FALSE means to return the state immediately

Page 402: HC700 SDK Specification

Page 402 of 680

PDWORD pdwState: pointer to variable, which will receive the current stack state. Some possible values are:

E_BT_SUCCESS – stack is OK E_BT_DISABLED – stack is disabled E_BT_INIT – stack is initializing

For other E_BT_* codes see file FWErr.h.

Return Values BT_STATUS_SUCCESS: Stack state is read successfully. BT_STATUS_FAILED: Stack does not exist.

Comments None

12.1.9.1.5 XCBSC_SetDevicePassKey

Description

12.1.9.1.6 Sets the value for device PassKey.

Function Prototype

BtStatus XCBSC_SetDevicePassKey(TCHAR *pszPassKey)

Parameters TCHAR *pszPassKey: pointer to PassKey NULL terminated string to set. NULL means to erase device PassKey (popup dialog box will be shown with PassKey request).

Return Values BT_STATUS_SUCCESS: Pass key is set BT_STATUS_FAILED: Setting PassKey is failed

Comments PassKey length, according to Bluetooth specification, may be no more than 16 characters

(defined as constant, named BT_PASSKEY_SIZE).

12.1.9.1.7 XCBSC_GetDevicePassKey

Description

12.1.9.1.8 Retreives the current value of device PassKey.

Function Prototype

BtStatus XCBSC_GetDevicePassKey(TCHAR *pszPassKey)

Parameters TCHAR *pszPassKey: pointer to buffer for receiving the PassKey string. It should be of size BT_PASSKEY_SIZE+1 in order to be able to contain the PassKey of maximum length and NULL terminating character.

Return Values BT_STATUS_SUCCESS: Pass key is read successfully

Page 403: HC700 SDK Specification

Page 403 of 680

BT_STATUS_FAILED: Can not read Device PassKey

Comments None

12.1.9.1.9 XCBSC_SetClientPortPassKey

Description

12.1.9.1.10 Sets the value for PassKey, which will be used for connection on specific client (outgoing) Bluetooth virtual serial port.

Function Prototype

BtStatus XCBSC_SetClientPortPassKey(TCHAR *pszPortName, TCHAR *pszPassKey)

Parameters TCHAR *pszPortName: Existing Bluetooth virtual serial port port name (From the range “COM0 :” - “COM9 :” or “BTC0:” - “BTC9 :”) TCHAR *pszPassKey: pointer to NULL terminated PassKey string to set. NULL means to erase Port PassKey (Device PassKey will be used in this case).

Return Values BT_STATUS_SUCCESS: Pass key is set BT_STATUS_FAILED: Setting PassKey is failed

Comments PassKey length, according to Bluetooth specification, may be no more than 16 characters

(defined as constant, named BT_PASSKEY_SIZE).

12.1.9.1.11 XCBSC_GetClientPortPassKey

Description

12.1.9.1.12 Gets the value for PassKey, which is used for connection on specific client (outgoing) Bluetooth virtual serial port.

Function Prototype

BtStatus XCBSC_GetClientPortPassKey(TCHAR *pszPortName, TCHAR *pszPassKey)

Parameters TCHAR *pszPortName: Existing Bluetooth virtual serial port port name (From the range “COM0 :” - “COM9 :” or “BTC0:” - “BTC9 :”) TCHAR *pszPassKey: pointer to buffer for receiving the PassKey string. It should be of size BT_PASSKEY_SIZE+1 in order to be able to contain the PassKey of maximum length and NULL terminating character.

Return Values BT_STATUS_SUCCESS: Pass key is read successfully BT_STATUS_FAILED: Port PassKey does not exist

Comments None

Page 404: HC700 SDK Specification

Page 404 of 680

Additional information for SW developers

12.1.9.1.13 PassKey request response algorithm When Bluetooth Pairing is started, the PassKey is requested by the Bluetooth stack from Monitor application. The response algorithm is as follows:

Request PassKey by pop-up dialog

box

Current PassKey request is for outgoing virtual serial port

connection , which is configured with the Port

PassKey?

Device User PassKey is Configured?

Use Device User PassKey

BT Stack Proceeds with Pairing

Yes

No

No

Yes

Pairing Initiated (PassKey request by BT Stack)

Use Serial Port PassKey

Page 405: HC700 SDK Specification

Page 405 of 680

12.1.9.1.14 Bluetooth registry configuration values

12.1.9.1.15 General stack settings The registry values used for stack configuration are situated under the registry entry for BT stack driver [HKEY_LOCAL_MACHINE\Drivers\BuiltIn\XCBTStack]. The following configuration settings are applied to BT stack and are loaded on stack start:

• "DeviceClass"=<dword>> – defines the Bluetooth device class as specified in BT specifications (for definitions see http://www.bluetooth.org/assignednumbers/baseband.htm). Current implementation uses device type 0x114 –Palm Size Computer.

• “DeviceName"=<string> – defines the Bluetooth device name. If it is empty, terminal device name is used (Current implementation)

• "AccessModeNC"=<dword> - defines the Bluetooth device initial accessibility when there is no any active connection existing. It may take values:

o 0x00 – not accessible o 0x03 – general accessible & connectable o 0x13 – limited accessible & connectable o 0x02 – connectable only

Current implementation defines it as 0x03. • "AccessModeC"=<dword> - defines the Bluetooth device initial accessibility when there is at least

one active ACL connection existing. It may take the same values as previous entry. Current implementation defines it as 0x02.

• "Sec3"=<dword> - if exists and non-zero, BT security mode 3 is enabled, otherwise – disabled (In Current implementation - initially security is disabled).

• "Encrypt"=<dword> - if exists and non-zero, encryption while BT security mode 3 is enabled, otherwise – disabled (In current implementation – initially disabled).

• "MasterOnly"1=<dword> - Master only mode causes the protocol stack to request a master/slave switch on all incoming ACL links. By default, the protocol stack does not request role changes, but will accept role change requests from remote devices. When master only mode is enabled, the protocol stack will request a master/slave switch on all incoming connections. Absence of the value or value of 0 disables master only mode. Any non-zero value enables master only mode. (In current implementation – enabled).

• "EnableSniffer"=<dword> - If exists and non-zero, the sniffer (logger) of HCI protocol events, commands and data is enabled, otherwise – disabled. Sniffer dumps HCI log into the file \btprot.txt and appends data to it on each boot. WARNING: sniffer significantly slows down the Bluetooth functioning and may cause the failures in some operations because of delays. Use it with caution and only for debug purposes. (In Current implementation – initially disabled).

• "AllowRoleChange2"=<dword> - If exists and not equals to 1, the handheld terminal disables role switching for incoming connections if requested by remote devices, otherwise (flag does not exist or equals to 1) – allows this. (In Current implementation – initially enabled).

12.1.9.1.16 Virtual Serial Port settings The registry values used for legacy serial ports should be situated under the registry entry for corresponding

port driver. The values are loaded DYNAMICALLY, during the device opening/connection establishment. The following configuration settings may be used for legacy serial ports:

1 The MasterOnly value indicates if the device should request a role change when another device tries to connect. Setting this value would mean that if another device wants to connect to the local device as a master then the local device will ask the remote device to switch to a slave. 2 The AllowRoleChange value indicates how the local stack will respond to role change requests. When trying to connect to a remote device, the remote device may request that a role switch is to be performed. If AllowRoleChange == 0 then the role change request will be denied. Depending on how the remote device handles the negative reply, the Bluetooth Link may never be created.

Page 406: HC700 SDK Specification

Page 406 of 680

1. "BtProfile"=<String> – defines the Bluetooth profile, for which the port will be used. The valid values are: “SerialPort”, “LAN”, “DUN” and “FAX. It should exist before the COM port is opened.

2. "ConnectTo"=”XX.XX.XX.XX.XX.XX” – the address of remote device to which the connection will be made (should be entered prior to connection “manually” by any application or by using the new BT Monitor option – port association – a description follows). If it is absent, the connection is failed. It should exist before the actual connection to the remote device is established and is used BY MONITOR application only and not by the virtual serial port driver.

3. "PassKey"="1234" – the PassKey for automatic bonding process. It should exist before the actual connection to the remote device is established and is used BY MONITOR application only and not by the virtual serial port driver.

4. "EnableServer"=<dword> – used only for legacy port intended for simple serial communications (“SerialPort” profile). If this value exists and not equals 0, the port has server capabilities (can accept incoming connections), otherwise it can be used only to initiate connections to other devices. (In OS image COM8: has server option enabled). It should exist before the COM port is opened.

5. "ConnectOnOpen"=<dword> – used only for legacy port intended for client activity of any legacy profile. If this value exists and not equals 0, the connection to remote device will be established when application opens the port. Otherwise a connection to another device will be initiated when a legacy application calls WriteFile() or attempts to set either the DTR or RTS lines. It should exist before the COM port is opened.

6. "NotConnectOnWrite"=<dword> – used only for legacy port intended for client activity of any legacy profile. If this value exists and equals 1, the connection to remote device will NOT be initiated when a legacy application calls WriteFile(). It should exist before the COM port is opened.

7. "ConnDCB"=<dword> – used only for legacy port intended for client activity of any legacy profile. If this value exists and equals 0, the connection to remote device will NOT be established when application attempts to set either the DTR or RTS lines, while updating the DCB by SetCommState() call. Otherwise a connection to another device will be initiated. It should exist before the COM port is opened. If absent, the value is assumed to be 1 (connection on DCB change is enabled).

8. " UserModemStatus "=<dword> - If it is needed before connection to remote device to specify the initial values of CTS or DTR lines of virtual BT serial port (defaults is 0s), it can be specified in this registry value before openinig the port. It is the bitmask value, where bit #2 is DTR value, #3 is RTS value. Specify value 4 for DTR ON & RTS OFF, 8 for DTR OFF & RTS ON, 12 (0x0C) for both DTR and RTS ON and 0 for both DTR and RTS OFF.

12.1.9.1.17 Pre-defined Bluetooth virtual serial ports and their registry settings [HKEY_LOCAL_MACHINE\Drivers\BuiltIn\BTSerial1] "DevConfig"=hex:\ 10,00,00,00,05,00,00,00,10,01,00,00,00,4b,00,00,00,00,08,00,00,00,00,00,00 "Dll"="btcelegacy.dll" "Prefix"="COM" "BtProfile"="DUN" "Order"=dword:0000000f "Tsp"="Unimodem.dll" "DeviceType"=dword:00000000 "FriendlyName"="Bluetooth Modem Serial Port" "Index"=dword:0 "ConnectOnOpen"=dword:00000001 [HKEY_LOCAL_MACHINE\Drivers\BuiltIn\BTSerial2] "DevConfig"=hex:\ 10,00,00,00,05,00,00,00,10,01,00,00,00,4b,00,00,00,00,08,00,00,00,00,00,00 "Dll"="btcelegacy.dll" "Prefix"="COM" "BtProfile"="SerialPort" "Order"=dword:0000000f "Tsp"="Unimodem.dll" "DeviceType"=dword:00000000 "FriendlyName"="Bluetooth Serial Port on COM7:" "Index"=dword:00000007 "ConnectOnOpen"=dword:00000001

Page 407: HC700 SDK Specification

Page 407 of 680

[HKEY_LOCAL_MACHINE\Drivers\BuiltIn\BTSerial3] "DevConfig"=hex:\ 10,00,00,00,05,00,00,00,10,01,00,00,00,4b,00,00,00,00,08,00,00,00,00,00,00 "Dll"="btcelegacy.dll" "Prefix"="COM" "BtProfile"="SerialPort" "Order"=dword:0000000f "Tsp"="Unimodem.dll" "DeviceType"=dword:00000000 "FriendlyName"="Bluetooth Serial Port on COM8:" "Index"=dword:00000008 "EnableServer"=dword:1 [HKEY_LOCAL_MACHINE\Drivers\BuiltIn\BTC1] "DevConfig"=hex:\ 10,00,00,00,05,00,00,00,10,01,00,00,00,4b,00,00,00,00,08,00,00,00,00,00,00 "Dll"="btcelegacy.dll" "Prefix"="BTC" "BtProfile"="SerialPort" "Order"=dword:0000000f "Tsp"="Unimodem.dll" "DeviceType"=dword:00000000 "FriendlyName"="Bluetooth Serial Port on BTC1:" "Index"=dword:00000001 "ConnectOnOpen"=dword:00000001 [HKEY_LOCAL_MACHINE\Drivers\BuiltIn\BTC2] "DevConfig"=hex:\ 10,00,00,00,05,00,00,00,10,01,00,00,00,4b,00,00,00,00,08,00,00,00,00,00,00 "Dll"="btcelegacy.dll" "Prefix"="BTC" "BtProfile"="SerialPort" "Order"=dword:0000000f "Tsp"="Unimodem.dll" "DeviceType"=dword:00000000 "FriendlyName"="Bluetooth Serial Port on BTC2:" "Index"=dword:00000002 "ConnectOnOpen"=dword:00000001 [HKEY_LOCAL_MACHINE\Drivers\BuiltIn\BTC3] "DevConfig"=hex:\ 10,00,00,00,05,00,00,00,10,01,00,00,00,4b,00,00,00,00,08,00,00,00,00,00,00 "Dll"="btcelegacy.dll" "Prefix"="BTC" "BtProfile"="SerialPort" "Order"=dword:0000000f "Tsp"="Unimodem.dll" "DeviceType"=dword:00000000 "FriendlyName"="Bluetooth Serial Port on BTC3:" "Index"=dword:00000003 [HKEY_LOCAL_MACHINE\Drivers\BuiltIn\BTC6] "DevConfig"=hex:\ 10,00,00,00,05,00,00,00,10,01,00,00,00,4b,00,00,00,00,08,00,00,00,00,00,00 "Dll"="btcelegacy.dll" "Prefix"="BTC" "BtProfile"="LAN" "Order"=dword:0000000f "Tsp"="Unimodem.dll"

Page 408: HC700 SDK Specification

Page 408 of 680

"DeviceType"=dword:00000000 "FriendlyName"="Bluetooth LAN access point" "Index"=dword:00000006 "ConnectOnOpen"=dword:00000001 [HKEY_LOCAL_MACHINE\ExtModems\Bluetooth] "Port"="COM0:" "DeviceType"=dword:00000001 "FriendlyName"="Bluetooth Modem"

Page 409: HC700 SDK Specification

Page 409 of 680

13. GPRS/GSM Radio

General Overview

The G20 radio is an integrated OEM module into the handheld terminal.The user can transfer data over GPRS/GSM network using TCP/IP protocol.

The TAPI and OEM APIs are set of functions that allows the user to control the radio modem and get its currecnt status.

According to HC700 FCC grant WLAN & GPRS are not allowed to operate simultaneously - do not open both radios simultaneously in your applications. TAPI/ Extended TAPI Functions OEM API

Function Description RADIO_SetDefaultPowerState Sets in the registry the default power state of the radio ,when 0

indicates the radio is off at boot time and 1 indicates that the radio is powered on at boot time.

RADIO_GetDefaultPowerState Retrieves the radio default power state at boot time.

RADIO_SetG20PMStatus Disabled /Enabled the radio internal power management .

The G20 radio has its own internal power managemant ,the radio internal power management can be disabled /enabled by the user.

RADIO_GetG20PMStatus This function get the current radio internal power management state.

RADIO_GetGprsCoverageState Returns the Radio network coverage state, When there is a change in the coverage state of the radio , the application gets notification event(see system events), the application shall call this function to get the reason for coverage state event – In coverage or out of coverage.

RADIO_GetEquipmentInfo Returns uniqe installed radio information ,such as radio serial number(IMEI) model number, software revition ID ,etc..

RADIO_GetSignalQ This function returns the Radio Signal Strengh Indication RSSI, this provides the user the current Radio signal quality.

RADIO_GetGprsRegisterState This function returns the Radio registration status to GPRS network

RADIO_PerfomCommand This function invokes direct AT commands to the Radio serial channel, the function returns the radio response.

Example Data Types

Page 410: HC700 SDK Specification

Page 410 of 680

Page 411: HC700 SDK Specification

Page 411 of 680

Software Architecture The diagram below demonstrates the Radio software components hierarch .

Radio G20

RIL Virtual SerialPort

OEM API TAPI/Ext TAPI WinSock

Application

The application can accesses the radio services over 2 API modules, standard Telphone API (TAPI) provided by micosoft ,and OEM API provided by Motorola. TAPI A set of functions in the Win32 API that lets the Host (the handheld terminal) communicate directly with Radio systems. It provides the basic functions, structures, and messages for establishing outgoing calls and controlling modems from a Windows CE–based device.

OEM API

Provided extra Radio functionality to the user in addition to to TAPI layer

RIL The “Radio Interface Layer” (RIL) driver is the interface between the system software and the radio stack. The RIL driver services system requests for radio functionality (voice, data, etc.), and notifies the system of changes in the radio state (coverage, signal strength, incoming calls, etc.) RIL contains all of the radio specific code. It must be custom written for each radio stack. The HW interface layer between the Handheld Terminal and Radio is standard serial port communication (COM 6), and power controls

Page 412: HC700 SDK Specification

Page 412 of 680

Creating Data call There are 2 basic stages when the user want send /receive data over the GPRS network, Please refer to GPRS session diagram below, 1.Call establishment -Turn on the radio ,and verify that the Radio is registered to the network by using TAPI standad set of functions, –Create a PPP RAS connection over the supplied RAS Entry. 2.Data Transfer - Use TCP/IP Winsock to transmit/receive the data over the PPP (above virtual COM 9)established connection. - To associate the specific RAS connection to the specific socket : Extract the IP address from the RAS connection by using RasGetProjectionInfo. - BIND the socket to the retrieved IP . - Otherwise the connection manager will choose an active RAS connection according to it’s algorithm. - Several of GPRS data sessions can be active at the same time – by using different sockets for each session on the same RAS connection.

WinSock

TCP/IP

PPP

TAPI

TSP

Serial Driver

RILRadio Inerface

Layer

Radio G20

Virtual ComPort ( 9 )

Stage 1:Call Establishment

Stage 2:Data Transfer

GPRS Session

Page 413: HC700 SDK Specification

Page 413 of 680

TAPI functions Supported by the handheld terminal

Function description

lineAddProvider Install a new TSP into the telephony system.

LineCallBackFunc Is a placeholder for the callback Function application - supplied

LineClose Closes the specified open device

LineGetAddressCaps Return the telephony capabilities of on address

LineGetAddressStatus Return the current status of specified address.

LineGetDevCaps Queries a specified line device to determine its telephony capabilities

LineGetlineDevStatus Enables an application to quarry the specified open line device for its current status.

LineInitialize Initialize the use of TAPI by the application for subsequent use of the line abstraction

lineOpen Opens the line device specified by its device identifier and returns a line handle for the corresponding opened line device.

lineSetDevConfig

This function enables the application to restore the configuration of a media-stream device on a line device to a setup previously obtained using the lineGetDevConfig function.

lineClose This function closes the specified open line device

Page 414: HC700 SDK Specification

Page 414 of 680

Extended TAPI functions Supported by the handheld terminal

Function Description lineGetCurrentOperator

Retrieve the Current oprator

LineGetEquipmentState Retrieve the state of the radio transmitter and receiver

LineSetEquipmentState Set the electrical state of the device (i.e power up radio)

LineGetRadioPresence

Determine if a radio is present

LineGetRegisterStatus

Retrieve the current registration status

lineRegister

Registers the device with a particular network operator.

lineUnregister

Deregister form the current network operator

For more details regarding TAPI and Ext TAPI please refer to WinCE help.

Page 415: HC700 SDK Specification

Page 415 of 680

OEM API OEM API is additional layer to the TAPI layer , that provide the user extended radio functionalty ,which is not covered in the TAPI layer.

RADIO_SetDefaultPowerState

Description This function set in the registry the default power state of the radio ,when 0 indicates the radio is off at boot time and 1 indicates that the radio is powered on at boot time.

Function Prototype DWORD WINAPI RADIO_SetDefaultPowerState ( G20_DEFAULT_POWER_STATE eDefultPowerState )

Parameters eDefultPowerState The default Power state of the radio at boot time, 1- The radio at boot time will be turned on, 0 –The radio at boot we be set to off.

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns one of Motorola SDK errors.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 416: HC700 SDK Specification

Page 416 of 680

RADIO_GetDefaultPowerState

Description This function retrieves the radio default power state at boot time.

Function Prototype DWORD WINAPI RADIO_GetDefaultPowerState ( G20_DEFAULT_POWER_STATE * peDefultPowerState )

Parameters *eDefultPowerState Pointer to eDefultPowerState to receive the Radio default stae after boot

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns one of Motorola SDK errors.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 417: HC700 SDK Specification

Page 417 of 680

RADIO_SetG20PMStatus

Description The G20 radio has its own internal power managemant ,the radio internal power management can be disabled /enabled by the user This function disabled /enabled the radio internal power management .

Function Prototype DWORD WINAPI RADIO_SetG20PMStatus (DWORD dwG20InternalPMTimeOut)

Parameters dwG20InternalPMTimeOut- Time to sleep (in sec) up to 30sec if there is no activity in the radio, when set to 0 ,the radio internal power management is disabled and the radio is always active.

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns one of Motorola SDK errors.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 418: HC700 SDK Specification

Page 418 of 680

RADIO_GetG20PMStatus

Description The G20 radio has its own internal power managemant ,the radio internal power management can be disabled /enabled by the user. This function get the current radio internal power management state .

Function Prototype DWORD WINAPI RADIO_GetG20PMStatus (LPG20PM_STATUS lpG20PMStatus)

Parameters lpG20PMStatus A pointer to G20PM_STATUS structure to be field Structure Members: DwPmStatus- Radio power management status ,0 –disable , 1 -enable dwG20InternalPMTimeOut- time to sleep (in sec) if there is no activity in radio if DwPmStatus=0 this field will always be 0.

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns one of Motorola SDK errors.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 419: HC700 SDK Specification

Page 419 of 680

RADIO_GetGprsCoverageState

Description This function returns the Radio network coverage state , When there is a change in the coverage state of the radio , the application gets notification event(see system events), the application shall call this function to get the reason for coverage state event – In coverage or out of coverage.

Function Prototype DWORD WINAPI RADIO_GetGprsCoverageState( G20_GPRS_COVRAGE *peGprsCovragetState)

Parameters peGprsCovragetState pointer to G20_GPRS_COVRAGE enumerator values: G20_IN_GPRS_COVRAGE , G20_OUT_OF_GPRS_COVRAGE

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns one of Motorola SDK errors.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

RADIO_GetEquipmentInfo

Description This function returns uniqe installed radio information ,such as radio serial number(IMEI) model number, software revition ID ,etc..

Page 420: HC700 SDK Specification

Page 420 of 680

Function Prototype DWORD WINAPI RADIO_GetEquipmentInfo( EQUIPMENT_INFO_PARAM * peEquipmentInfo)

Parameters peEquipmentInfo pointer to EQUIPMENT_INFO_PARAM structure structure memebers: ManufacturerId- Pointer to string radio maufecture ID ModelId- Pointer to string radio model number RevisionId- Pointer to string radio firware version SerialNumber- Pointer to string radio serial number(IMEI)

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns one of Motorola SDK errors.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

RADIO_GetSignalQ

Description This function returns the Radio Signal Strengh Indication RSSI ,this provides the user the current Radio signal quality.

Page 421: HC700 SDK Specification

Page 421 of 680

Function Prototype DWORD WINAPI RADIO_GetSinalQ( DWORD *dwRssi )

Parameters dwRssi pointer to double word to be field with radio RSSI, range values 0 – 30.

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns one of Motorola SDK Radio errors.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

RADIO_GetGprsRegisterState

Description This function returns the Radio registration status to GPRS network

Page 422: HC700 SDK Specification

Page 422 of 680

Function Prototype DWORD WINAPI RADIO_GetGprsRegisterState(G20_GPRS_REG * peGprsRegState)

Parameters peGprsRegState pointer to double word to be field with radio registration status to GPRS network GPRS_REG_STATUS_UNREGISTERED – The radio is not registered to GPRS network GPRS_REG_STATUS_REGISTERED - The radio is registered to GPRS network

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns one of Motorola SDK Radio errors.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

RADIO_PerfomCommand

Description This function invokes direct AT commands to the Radio serial channel, the function returns the radio response.

Page 423: HC700 SDK Specification

Page 423 of 680

Function Prototype DWORD WINAPI RADIO_PerformCommand (TCHAR *BufferIn, DWORD InLength, TCHAR *BufferOut, DWORD *OutLength, DWORD TimeoutMs );

Parameters *BufferIn (Input) Contains the command that is sent to the radio,the string command must terminated with ‘ \r ’. InLength (Input) This parameter contains the length of the command located in buffer in wchar. BufferOut (output) Pointer to the radio response in wchar format. OutLength (In/Out) A pointer that contains the buffer size of BufferOut when the function is called , When the function returns ,this pointer contains the number of wchars that were field to the OutBuffer. TimeoutMs(input) The time the function will wait from response from the radio,if the timeout expired the function will return with E_G20_USER_TIMEOUT error.

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns one of Motorola SDK Radio errors.see return value.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

RADIO_SetAudioRoutingDevice

Description This function sets a specific audio device due to a voice call. When the device will implements a voice call, thie specific audio device will be connected to radio audio.

Function Prototype DWORD WINAPI RADIO_SetAudioRoutingDevice ( AUDIO_ROUT_DEVICE_TYPE eAudioDevice );

Parameters eAudioDevice (Input)

Page 424: HC700 SDK Specification

Page 424 of 680

Holds the audio device type will be connected in case of voice call.

Return Values If the function succeeds, the return value is E_G20_SUCCESS, otherwise the function returns E_AUD_INVALID_PARAMETER in case of invakid value or E_G20_IOCTRLFAILED in case of driver error.

Comments None

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in G20CApi.h.h. Import Library: Use G20API32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 425: HC700 SDK Specification

Page 425 of 680

DATA TYPES //Named events used by the RIL driver #define PPAD_GPRS_COVERAGE_CHANGE_EVENT TEXT("PPAD_GPRS_Coverage_Change_Event") #define PPAD_GPRS_DEREGISTRATION_EVENT TEXT("PPAD_GPRS_Deregistration_Event") #define PPAD_GPRS_REGISTRATION_EVENT TEXT("PPAD_GPRS_Registration_Event") //define broadcast msg types #define WM_PPAD_GPRS_COVERAGE_CHANGE WM_USER+0x2000 #define WM_ PPAD_GPRS_REGISTRATION _CHANGE WM_USER+0x2001 //old //define wparm status register #define PG20_AVAILABLE 0x1 #define PG20_UNAVAILABLE 0x2 #define PG20_IN_GPRS_COVERAGE 0x3 #define PG20_OUT_OF_GPRS_COVERAGE 0x4 #define PG20_REGISTERED 0x1 #define PG20_UNREGITERED 0x2 #define PG20_IN_GPRS_COVERAGE 0x3 #define PG20_OUT_OF_GPRS_COVERAGE 0x4 //-------------------------------------------------------------------- // Types //-------------------------------------------------------------------- //returns the serial routing state typedef enum G20_DEFAULT_POWER_STATE { G20_POWER_OFF = 0, G20_POWER_ON } G20_DEFAULT_POWER_STATE; typedef enum G20_GPRS_COVRAGE { G20_IN_GPRS_COVRAGE = 0, G20_OUT_OF_GPRS_COVRAGE } G20_GPRS_COVRAGE; typedef enum AUDIO_ROUT_DEVICE_TYPE { AUDIO_ROUT_NONE, // (0x00000000) No audio devices AUDIO_ROUT_HANDSET, // (0x00000001) Handset AUDIO_ROUT_SPEAKERPHONE, // (0x00000002) Speakerphone AUDIO_ROUT_HEADSET, // (0x00000003) Headset Not Supported AUDIO_ROUT_CARKIT, // (0x00000004) Carkit Not Supported AUDIO_ROUT_LAST_DEVICE } AUDIO_ROUT_DEVICE; typedef struct _EQUIPMENT_INFO_PARAM {

Page 426: HC700 SDK Specification

Page 426 of 680

TCHAR dwManufacturerId[128]; //manufacturer_id TCHAR dwModelId[128]; //model_id TCHAR dwRevisionId[128]; //Revision Id TCHAR dwSerialNumber[128]; //serial number } EQUIPMENT_INFO_PARAM; typedef struct _DEVICE_SPECIFIC_PARAM { DWORD dwCommand; //Specific Command DWORD dwInData; //Input Buffer DWORD dwOutData; //OutPut Buffer UINT cValSize; //SizeOff Buffer DWORD dwRetVal; //ret val of the function EQUIPMENT_INFO_PARAM EquipmentInfo;//store EquipmentInfo } DEVICE_SPECIFIC_PARAM; typedef struct { DWORD dwPmStatus; // G20 internal PowerManegment when 0 the G20 internal PM is disabled DWORD dwG20InternalPMTimeOut; } G20PM_STATUS , *LPG20PM_STATUS; // Version information structure typedef struct tagNOTIFY_VERSION_INFO { STRUCT_INFO StructInfo; DWORD dwCAPIVersion; // HIWORD = major ver LOWORD = minor ver. } NOTIFY_VERSION_INFO; typedef NOTIFY_VERSION_INFO FAR * LPNOTIFY_VERSION_INFO;

Page 427: HC700 SDK Specification

Page 427 of 680

Return Values #define ERROR_BIT 0x80000000 // Use bit 31 to indicate errror #define USER_BIT 0x20000000 // Bit 29 means not Win32 error #define G20_ERROR(code) (ERROR_BIT | USER_BIT | (WORD) code) // The function completed successfully. #define E_G20_SUCCESS 0 #define E_G20_NULLPOINTER G20_ERROR(0x0001) #define E_G20_CREATEMUTEX G20_ERROR(0x0002) #define E_G20_BUSYMUTEX G20_ERROR(0x0003) #define E_G20_OUTOFRANGE G20_ERROR(0x0004) #define E_G20_IOCTRLFAILED G20_ERROR(0x0005) #define E_G20_NOTSUPPORTED G20_ERROR(0x0006) #define E_AUD_STRUCTINFO G20_ERROR(0x0007) #define E_AUD_MISSINGFIELD G20_ERROR(0x0008) #define E_AUD_INVALID_PARAMETER G20_ERROR(0x0009) E_G20_ILLEGAL_COMMAND – The command is (/a perform the last command)or the command is not starting with at or finished with \r E_G20_ILLEGAL_TIMEOUT – user timeout is less than system timeout ,the system timeout is 5 sec .Any user timeout less than 5 sec will return error E_G20_USER_TIMEOUT – the user timeout has passed. E_G20_SYSTEM_TIMEOUT – The system timeout as passed E_G20_INLENGTH_ERROR – InLength is smaller then *BufferIn size E_G20_OUTBUFF_TOSMALL – RSP from the radio is larger than OUTBUFFER size. E_G20_BLOCKED_COMMAND- this command is blocked by the RIL driver. E_G20_COMMAND_WITHOUT_NULL_TERMINATED – the string in the *BufferIn is not terminated with NULL E_G20_MEM_ALLOC_FAILURE- memory allocation failed E_G20_RADIO_OFF – trying to send command to the radio while radio is off. E_G20_QUEUE_CMD_FULL – command queue is full can’t place the command into the queue E_G20_COMMAND_TOO_LONG- command lengh is above 180 chares, G20 don’t know who to handle commands above 180 chars. E_G20_SYSTEM_ERROR – when getting this error to user should call win API GetLastError() E_G20_RILGSM_ERROR- this Error is one of the RIL driver error call GetLastError()

Example Application HC700 family products support more than one radio module. We want to have compatible image for all kinds of products. So we select name WanTest, WanDataClient and WanDataServer in the sample folder in device instead of specific modem name.

Page 428: HC700 SDK Specification

Page 428 of 680

See SDK Radio GPRS sample application: G20DataClient ,G20DataServer –Demonstrates TCP/IP file transferring between 2 terminals over GPRS network ,one terminal executes G20DataServer application, the other one executes G20DataClient application that connect to the remote terminal server with multiple clients capability G20Test Demonstrates TAPI and OEM API usage.

Page 429: HC700 SDK Specification

Page 429 of 680

14. WLAN API Overview WLAN SDK provides the necessary set of procedures allowing C/C++ programmer to develop applications to control and access Wireless LAN Adapter, connect to WLAN, transfer data, set security parameters, etc.

Important notes related to WLAN API:

1. According to HC700 FCC grant WLAN & GPRS are not allowed to operate simultaneously - do not open both radios simultaneously in your applications.

2. Default WLAN radio state in HC700 terminal is OFF. It was done to decrease power consumption.Application (or user) may turn the radio on and off when needed. It is recommended to turn off WLAN radio when the application no longer uses it.

To keep WLAN connection and have data transfer more reliable, HC700 terminal will not enter its Suspend mode when WLAN is on.

3. The application that intends to use WLAN API should call to WLAN_OpenAdapter() prior to other API calls. At the end of API use, the application should call to WLAN_CloseAdapter().

4. Most APIs in this document returns valid data only when WLAN is on. In case the radio is off, an error code E_WLAN_ADAPTER_OFF will be returned. We recommend to use WLAN APIs only when WLAN radio is turned on.

5. It is recommend to application developer to consider few typical use cases explained below:

• Create new WLAN profile

• Connect to WLAN network using existing profile

• Monitor WLAN adapter’s status Create new WLAN profile Customer application uses this scenario on initialization stage, happening after terminal's boot. At the end of this scenario the new WLAN profile will be created. Note: profiles are saved after warm boot and deleted after cold boot. Application starts WLAN_OpenAdapter() // Create HANDLE to WLAN adapter // Note: use NULL as WLAN adapter name WLAN_SetRadioState(WLAN_RADIO_ON) // Turn on WLAN radio // It will take a few seconds because of Zero Config

// initialization WLAN_SetConfiguration(SSID and other profile information) //Create WLAN profile Delay (5 sec) // Zero Config inserts created profile into preferred list // Terminal is connecting to WLAN network // Use this time for other non-WLAN operations … WLAN_SetRadioState(WLAN_RADIO_OFF) // Turn off WLAN radio, if not intend to use on this

// stage WLAN_CloseAdapter() // Close HANDLE to WLAN adapter created earlier

Page 430: HC700 SDK Specification

Page 430 of 680

Page 431: HC700 SDK Specification

Page 431 of 680

Connect to WLAN network using existing profile Customer application uses this scenario when the profile is already exist. At the end of this scenario the terminal will be connected to WLAN network according to this profile. WLAN_OpenAdapter() // Create HANDLE to WLAN adapter // Note: use NULL as WLAN adapter name

// Note: Don’t call to this function if you already have // handle to WLAN adapter

WLAN_SetSSID(SSID) // Turn on WLAN radio and connect to WLAN network … WLAN_Disassociate() // Disassociate from the AP, and turn off WLAN WLAN_CloseAdapter() // Close HANDLE to WLAN adapter created earlier Monitor WLAN adapter’s status Because WLAN media is not as reliable as wired network, it can happen that WLAN connection may not be established or will be broken because of coverage or other issues. It is recommend that application will have a thread monitoring WLAN connection status. The thread may be created when the radio will be turned on. It will poll the adapter’s IP address every few seconds using WLAN_GetAdapterIPAddress( ) to verify that the terminal remains connected. Main application will kill the thread on its exit or when it turns off the radio. A few factors should be considered:

• WLAN adapter IP address is always 0.0.0.0 during connection process. • Any connection process eventually ends up by getting an IP address (ether a right IP address

in case of successful connection or Automatic Private IP address 169.254.X.X in case of connection failure). Application is responsible to recognize if the IP address is valid for its network or it is an Automatic Private IP and conclude that the connection failed.

• WLAN_GetAdapterIPAddress () and standard Microsoft IPHelper functions like IpRenewAddress ( ) and IpReleaseAddress ( ) could be used to get IP address.

Main application WLAN_OpenAdapter() // Create HANDLE to WLAN adapter // Note: use NULL as WLAN adapter name

// Note: Don’t call to this function if you already have // handle to WLAN adapter

WLAN_SetSSID(SSID) // Turn on WLAN radio and connect to WLAN network CreateThread ( MonitorThread) // Create thread for WLAN Adapter status monitoring … WLAN_Disassociate() // Disassociate from the AP, and turn off WLAN SetEvent (CloseThreadEvent) // Send event to close the Monitor thread WLAN_CloseAdapter() // Close HANDLE to WLAN adapter created earlier Monitor Thread WHILE (1) { WaitForSingleObject (CloseEvent, Timeout) // Thread is waiting for cloe event of for timeout of few seconds

Page 432: HC700 SDK Specification

Page 432 of 680

IF CloseEvent exit // end Monitor Thread ELSE // Timeout expired IpRenewAddress ( ) // Refresh WLAN Adapter IP address WLAN_GetAdapterIPAddress ( ) // Get WLAN IP address }

For better understanding of WLAN API usage, see Example.

WLAN_Example

WLAN Error Codes WLAN_Data_Types

Page 433: HC700 SDK Specification

Page 433 of 680

Basic Adapter Configuration & Management APIs: Function Description

WLAN_OpenAdapter Opens the specified WLAN adapter and creates a handle to be used for all subsequent accesses to this adapter. Call this function before calling to another WLAN APIs.

WLAN_CloseAdapter Closes the previously opened access to WLAN adapter obtained by a call to WLAN_OpenAdapter.

WLAN_GetRadioState Gets radio status (ON or OFF)

WLAN_SetRadioState Turns WLAN radio ON or OFF

WLAN_GetSSID Gets the Service Set Name (Network name) the terminal is connected to or attempts to connect to.

WLAN_SetSSID Sets the desired Service Set Name (Network name) to WLAN adapter.

WLAN_GetBSSID Gets the MAC address of the Service Set the terminal is associated with.

WLAN_GetNetworkMode Gets the current network mode of the WLAN adapter.

WLAN_SetNetworkMode Sets network mode of specific SSID.

WLAN_GetPowerMode Gets the current Power Saving mode of the WLAN adapter.

WLAN_SetPowerMode Sets Power Saving mode of WLAN adapter.

WLAN_Disassociate Disassociate the WLAN adapter from its current Service Set.

WLAN_GetDataRate Gets the current data transmission rate of the WLAN adapter.

WLAN_GetChannel Gets the current channel of the WLAN adapter.

WLAN_GetRSSI Gets the Signal Strength of the adapter.

WLAN_GetAssociationStatus Gets the association status of the adapter.

WLAN_GetAdapterIPAddress Gets current IP address of the adapter.

WLAN_GetAdapterMACAddress Gets the MAC address of the adapter.

WLAN_GetEncryptionStatus Get the current encryption status of the adapter.

WLAN_GetAuthenticationMode Get the current authentication mode of the adapter.

WLAN_GetEAPType Get the current EAP type of the adapter.

WLAN_GetConfiguration Get the current network configuration of the adapter (SSID, Network Mode, Security settings, etc.).

WLAN_SetConfiguration This function creates a new WLAN configuration and activates it. The previous configuration is saved in preferred networks list.

WLAN_GetPMConfiguration Get the current WLAN Power Management configuration of the adapter (enable suspend when WLAN is on, default WLAN power state, etc.)

Page 434: HC700 SDK Specification

Page 434 of 680

WLAN_SetPMConfiguration Sets Power Management configuration of WLAN adapter. The PM configuration consists of the following parameters:

1. WLAN power control state after WARM boot (On or Off) 2. System Suspend enabling when WLAN is On (Suspend enabled or

Disabled)

Page 435: HC700 SDK Specification

Page 435 of 680

WLAN_OpenAdapter

Description Opens the specified WLAN adapter and creates a handle to be used for all subsequent accesses to this adapter. Call this function before calling to another WLAN APIs.

Function Prototype DWORD WLANAPI WLAN_OpenAdapter(

LPCTSTR lpszAdapterName, LPHANDLE lphAdapter);

Parameters

lpszAdapterName [in] Pointer to a string containing the name of the WLAN Adapter to open. If a null pointer is specified, the function will open a first WLAN adapter available in the system.

lphAdapter [out] Pointer to a handle created for all subsequent accesses to this WLAN adapter.

Return Values

WLAN_SUCCESS indicates success. Other values indicate failure. To get extended error information, call GetLastError. Error Codes: Declared in wlanerr.h.

Comments Call to WLAN_OpenAdapter prior to calls to WLAN APIs, and on completion close the adapter by calling to WLAN_CloseAdapter.

See Also WLAN_CloseAdapter

Page 436: HC700 SDK Specification

Page 436 of 680

WLAN_CloseAdapter

Description Closes the previously opened access to WLAN adapter obtained by a call to WLAN_OpenAdapter.

Function Prototype

DWORD WLANAPI WLAN_CloseAdapter(

HANDLE hAdapter);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

Return Values

WLAN_SUCCESS indicates success. Other values indicate failure. To get extended error information, call GetLastError. Error Codes: Declared in wlanerr.h.

Comments

Call to WLAN_OpenAdapter prior to calls to WLAN APIs, and on completion close the adapter by calling to WLAN_CloseAdapter.

See Also

WLAN_OpenAdapter

Page 437: HC700 SDK Specification

Page 437 of 680

WLAN_GetRadioState

Description Gets radio status (ON or OFF)

Function Prototype

DWORD WLANAPI WLAN_GetRadioState(

HANDLE hAdapter ,

LPWLAN_RADIO_STATE pRadioState);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pRadioState [out] The pointer to WLAN_RADIO_STATE enumeration to receive the state of the radio.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns WLAN radio state (ON or OFF). Default WLAN radio state is off.

See Also

WLAN_SetRadioState , WLAN_RADIO_STATE

Page 438: HC700 SDK Specification

Page 438 of 680

WLAN_SetRadioState

Description Turns WLAN radio ON or OFF

Function Prototype

DWORD WLANAPI WLAN_SetRadioState(

HANDLE hAdapter ,

WLAN_RADIO_STATE RadioState);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

RadioState [in] Specifies the state of the radio.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function turns WLAN radio ON or OFF. Default WLAN radio state is off.

See Also

WLAN_GetRadioState, WLAN_RADIO_STATE

Page 439: HC700 SDK Specification

Page 439 of 680

WLAN_GetSSID

Description Gets the Service Set Name (Network name) the terminal is connected to or attempts to connect to.

Function Prototype

DWORD WLANAPI WLAN_GetSSID(

HANDLE hAdapter ,

LPWLAN_SSID_T pSSID);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pSSID [out] Pointer to TCHAR array to receive the SSID of the Access Point with which WLAN adapter is associated.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns the SSID with which the adapter is associated. If the adapter is not associated with SSID, it returns an empty string.

See Also

WLAN_SetSSID, WLAN_SSID_T

Page 440: HC700 SDK Specification

Page 440 of 680

WLAN_SetSSID

Description Sets the desired Service Set Name (Network name) to WLAN adapter.

Function Prototype

DWORD WLANAPI WLAN_SetSSID(

HANDLE hAdapter ,

WLAN_SSID_T SSID);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

SSID [in] TCHAR array that contains the desired SSID for WLAN adapter.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function sets the desired SSID to the adapter.

Setting an SSID results in:

• Disassociating the WLAN adapter from any SSID with which it might be associated.

• Turning on the radio if the radio is off.

• Setting the SSID with the specified value or setting it to any SSID if the SSID is not

specified.

• Attempting to associate the WLAN adapter with the new SSID. If the specific network

was already defined, WLAN_SetSSID() will connect to this SSID, otherwise the new

unsecured profile will be defined.

To disassociate and turn off the radio use WLAN_Disassociate API.

See Also

WLAN_GetSSID, WLAN_Disassociate, WLAN_SSID_T

Page 441: HC700 SDK Specification

Page 441 of 680

Page 442: HC700 SDK Specification

Page 442 of 680

WLAN_GetBSSID

Description Gets the MAC address of the Service Set the terminal is associated with.

Function Prototype

DWORD WLANAPI WLAN_GetBSSID(

HANDLE hAdapter ,

LPWLAN_MAC_ADDR_T pBSSID);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pBSSID [out] Pointer to TCHAR array to receive current BSSID.

Return Values

E_WLAN_SUCCESS indicates success. If the adapter is currently not associated, E_WLAN_NOT_CONNECTED will be returned. See WLAN Error Codes for more information.

Comments

BSSID is the MAC address of the Service Set the terminal is currently associated with.

See Also

WLAN_MAC_ADDR_T

Page 443: HC700 SDK Specification

Page 443 of 680

WLAN_GetNetworkMode

Description Gets the current network mode of the WLAN adapter.

Function Prototype

DWORD WLANAPI WLAN_GetNetworkMode(

HANDLE hAdapter ,

LPWLAN_NETWORK_MODE pNetworkMode);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pNetworkMode [out] The pointer to WLAN_NETWORK_MODE enumeration to receive the network mode of the radio.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns the network mode of the radio. Default mode is infrastructure mode.

See Also

WLAN_SetNetworkMode , WLAN_NETWORK_MODE

Page 444: HC700 SDK Specification

Page 444 of 680

WLAN_SetNetworkMode

Description Sets network mode of specific SSID.

Function Prototype

DWORD WLANAPI WLAN_SetNetworkMode(

HANDLE hAdapter ,

WLAN_SSID_T SSID ,

WLAN_NETWORK_MODE NetworkMode);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

SSID [in] TCHAR array that contains the needed SSID

NetworkMode [in] Specifies the desired network mode of the radio.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function sets the desired Network Mode of the specific SSID. Default mode is infrastructure mode.

Setting a new Network Mode results in:

• If the WLAN is off – return E_WLAN_ADAPTER_OFF error.

• If the WLAN is on - Disassociating the WLAN adapter from the SSID with which it

might be associated.

• Turning the Network Mode of the specified SSID to the desired Network Mode.

• Attempting to associate the WLAN adapter with the currently created new network

(SSID + Network Mode).

See Also

WLAN_GetNetworkMode , WLAN_SSID_T , WLAN_NETWORK_MODE

Page 445: HC700 SDK Specification

Page 445 of 680

WLAN_GetPowerMode

Description Gets the current Power Saving mode of the WLAN adapter.

Function Prototype

DWORD WLANAPI WLAN_GetPowerMode(

HANDLE hAdapter ,

LPWLAN_POWER_MODE pPowerMode);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pPowerMode [out] The pointer to WLAN_POWER_MODE enumeration to receive the power saving mode of the radio.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns the Power Save mode of the radio. Default mode is Power Saving mode.

See Also

WLAN_SetPowerMode , WLAN_POWER_MODE

Page 446: HC700 SDK Specification

Page 446 of 680

WLAN_SetPowerMode

Description Sets Power Saving mode of WLAN adapter.

Function Prototype

DWORD WLANAPI WLAN_SetPowerMode(

HANDLE hAdapter ,

WLAN_POWER_MODE PowerMode);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

PowerMode [in] Specifies the power saving mode of the radio.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function sets the desired Power Save Mode of the radio.

See Also

WLAN_GetPowerMode , WLAN_POWER_MODE

Page 447: HC700 SDK Specification

Page 447 of 680

WLAN_Disassociate

Description Disassociate the WLAN adapter from its current Service Set.

Function Prototype

DWORD WLANAPI WLAN_Disassociate(

HANDLE hAdapter );

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function disassociates the WLAN adapter from SSID that it is currently associated with. The radio also entered to its “OFF” mode. To turn the radio on and renew the association use WLAN_SetSSID API.

See Also

WLAN_SetSSID

Page 448: HC700 SDK Specification

Page 448 of 680

WLAN_GetDataRate

Description Gets the current data transmission rate of the WLAN adapter.

Function Prototype

DWORD WLANAPI WLAN_GetDataRate(

HANDLE hAdapter ,

LPWLAN_DATA_RATE pDataRate);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pDataRate [out] The pointer to WLAN_DATA_RATE enumeration to receive the data transmission rate of the WLAN radio.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns currently link speed of the radio in Mbps. The actual transmission rates depend on the RF-Modem capabilities.

See Also

WLAN_DATA_RATE

Page 449: HC700 SDK Specification

Page 449 of 680

WLAN_GetChannel

Description Gets the current channel of the WLAN adapter.

Function Prototype

DWORD WLANAPI WLAN_GetChannel(

HANDLE hAdapter ,

ULONG &ulChannel);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

ulChannel [out] ULONG value that represents current channel (1-14)

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns currently used channel of the WLAN adapter.

See Also

None.

Page 450: HC700 SDK Specification

Page 450 of 680

WLAN_GetRSSI

Description Gets the Signal Strength of the adapter.

Function Prototype

DWORD WLANAPI WLAN_GetRSSI(

HANDLE hAdapter ,

ULONG &ulRSSI);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

ulRSSI [out] ULONG normalized value that represents the Signal Strength of the WLAN adapter (0-100%)

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns the Strength of WLAN adapter Signal.

See Also

None.

Page 451: HC700 SDK Specification

Page 451 of 680

WLAN_GetAssociationStatus

Description Gets the association status of the adapter.

Function Prototype

DWORD WLANAPI WLAN_GetAssociationStatus(

HANDLE hAdapter ,

LPWLAN_ASSOCIATION_STATUS pAssociationStatus);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pAssociationStatus [out] The pointer to WLAN_ASSOCIATION_STATUS enumeration to receive the association status of the WLAN radio

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns the association status of WLAN adapter.

See Also

WLAN_ASSOCIATION_STATUS

Page 452: HC700 SDK Specification

Page 452 of 680

WLAN_GetAdapterIPAddress

Description Gets current IP address of the adapter.

Function Prototype

DWORD WLANAPI WLAN_GetAdapterIPAddress(

HANDLE hAdapter ,

LPWLAN_IP_ADDR_T pIPAddress);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pIPAddress [out] Pointer to a TCHAR array that to receive formatted string of current adapters IP address

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns the formatted string of current adapters IP address as follows: xxx.xxx.xxx.xxx

See Also

WLAN_IP_ADDR_T

Page 453: HC700 SDK Specification

Page 453 of 680

WLAN_GetAdapterMACAddress

Description Gets the MAC address of the adapter.

Function Prototype

DWORD WLANAPI WLAN_GetAdapterMACAddress(

HANDLE hAdapter ,

LPWLAN_MAC_ADDR_T pMACAddress);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pMACAddress [out] Pointer to a TCHAR array to receive a string of adapters MAC address

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns the string of adapters MAC address.

See Also

WLAN_MAC_ADDR_T

Page 454: HC700 SDK Specification

Page 454 of 680

WLAN_GetEncryptionStatus

Description Get the current encryption status of the adapter.

Function Prototype

DWORD WLANAPI WLAN_GetEncryptionStatus (

HANDLE hAdapter ,

LPWLAN_ENCRYPTION_STATUS pEncryptionStatus);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pEncryptionStatus [in] The pointer to WLAN_ENCRYPTION_STATUS enumeration to receive the encryption of the adapter.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function indicates in response which encryption modes are enabled or disabled, that the transmit key is absent, or that encryption is not supported.

When the NIC is not associated with an access point, the transmit-key status is based on the availability of a transmit key in the set of default keys.

Default encryption mode is WLAN_NDIS_ENCRYPTION_DISABLED.

See Also

WLAN_ENCRYPTION_STATUS

Page 455: HC700 SDK Specification

Page 455 of 680

WLAN_GetAuthenticationMode

Description Get the current authentication mode of the adapter.

Function Prototype

DWORD WLANAPI WLAN_GetAuthenticationMode(

HANDLE hAdapter ,

LPWLAN_AUTHENTICATION_MODE pAuthenticationMode);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pAuthenticationMode [in] The pointer to WLAN_AUTHENTICATION_MODE enumeration to receive the authentication mode of the adapter.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function gets the current authentication mode of the adapter. Default Authentication mode is WLAN_NDIS_AUTH_MODE_OPEN.

There are differences between WLAN_NDIS_AUTH_MODE_WPA_PSK and WLAN_NDIS_AUTH_MODE_WPA. The authentication suite in the WPA information element is different as described in WLAN_AUTHENTICATION_MODE enumerator - for the WLAN_NDIS_AUTH_MODE_WPA_PSK case, the NIC UI reflects that the user must enter a preshared key. Use WLAN_AddKey() to add the key.

See Also

WLAN_AUTHENTICATION_MODE

Page 456: HC700 SDK Specification

Page 456 of 680

WLAN_GetEAPType

Description Get the current EAP type of the adapter.

Function Prototype

DWORD WLANAPI WLAN_GetEAPType (

HANDLE hAdapter ,

LPWLAN_EAP_TYPE pEAPType);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pEAPType [in] The pointer to WLAN_EAP_TYPE enumeration to receive the EAP type of the adapter.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function indicates in response which EAP type is currently set to the adapter. In case 802.1X authentication is disabled, the returned EAP type is WLAN_EAP_TYPE_DISABLED – default type.

See Also

WLAN_EAP_TYPE

Page 457: HC700 SDK Specification

Page 457 of 680

WLAN_GetConfiguration

Description Get the current network configuration of the adapter (SSID, Network Mode, Security settings, etc.).

Function Prototype

DWORD WLANAPI WLAN_GetConfiguration(

HANDLE hAdapter ,

LPWLAN_CONFIGURATION_DATA pConfigData);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pConfigData [out] Pointer to WLAN_CONFIGURATION_DATA structure to receive current WLAN configuration information of WLAN adapter.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns the current network/security settings of WLAN adapter.

Note: WLAN_KEY_MATERIALS will be returned as ‘*************’ because of security matters.

See Also

WLAN_SetConfiguration, WLAN_CONFIGURATION_DATA

Page 458: HC700 SDK Specification

Page 458 of 680

WLAN_SetConfiguration

Description This function creates a new WLAN configuration and activates it. The previous configuration is saved in preferred networks list.

Function Prototype

DWORD WLANAPI WLAN_SetConfiguration (

HANDLE hAdapter ,

WLAN_CONFIGURATION_DATA configData);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

configData [in] WLAN_CONFIGURATION_DATA structure that contains the desired WLAN configuration information for WLAN adapter.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function creates a new network profile with desired configuration and tries to activate it.

Setting of a new network profile results in:

• If the WLAN is off – return E_WLAN_ADAPTER_OFF error.

• If the WLAN is on - Disassociating the WLAN adapter from the SSID with which it

might be associated.

• Creates a new network profile with desired configuration.

• Attempting to associate the WLAN adapter with the currently created new network

profile (SSID, Network Mode, security configuration).

See Also

WLAN_GetConfiguration , WLAN_CONFIGURATION_DATA

Page 459: HC700 SDK Specification

Page 459 of 680

Page 460: HC700 SDK Specification

Page 460 of 680

WLAN_GetPMConfiguration

Description Get the current WLAN Power Management configuration of the adapter (enable suspend when WLAN is on, default WLAN power state, etc.).

Function Prototype

DWORD WLANAPI WLAN_GetPMConfiguration(

HANDLE hAdapter ,

LPWLAN_PM_CONFIGURATION_DATA pPMConfigData);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

pPMConfigData [out] Pointer to WLAN_PM_CONFIGURATION_DATA structure to receive current WLAN PM configuration information of WLAN adapter.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function returns the current PM configuration settings of WLAN adapter.

See Also

WLAN_SetPMConfiguration, WLAN_PM_CONFIGURATION_DATA

Page 461: HC700 SDK Specification

Page 461 of 680

WLAN_SetPMConfiguration

Description Sets Power Management configuration of WLAN adapter. The PM configuration consists of the following parameters:

3. WLAN power control state after WARM boot (On or Off) 4. System Suspend enabling when WLAN is On (Suspend enabled or Disabled)

Function Prototype

DWORD WLANAPI WLAN_SetPMConfiguration (

HANDLE hAdapter ,

WLAN_PM_CONFIGURATION_DATA configPMData);

Parameters

hAdapter [in] Handle to previously opened WLAN adapter obtained by WLAN_OpenAdapter.

configPMData [in] WLAN_PM_CONFIGURATION_DATA structure that contains the desired WLAN PM configuration of WLAN adapter.

Return Values

E_WLAN_SUCCESS indicates success. Other values indicate failure. See WLAN Error Codes for more information.

Comments

This function sets the desired WLAN PM configuration.

See Also

WLAN_GetPMConfiguration, WLAN_PM_CONFIGURATION_DATA

Page 462: HC700 SDK Specification

Page 462 of 680

Example DWORD dwResult = WLAN_SUCCESS; HANDLE g_hAdapter = NULL; //Open Adapter dwResult = WLAN_OpenAdapter(ADAPTER_NAME, (LPHANDLE)&g_hAdapter); if((NULL == g_hAdapter) || (INVALID_HANDLE_VALUE == g_hAdapter)) ERROR… // Turn radio on dwResult = WLAN_SetRadioState((HANDLE)g_hAdapter, WLAN_RADIO_ON); WLAN_RADIO_STATE State ; WLAN_GetRadioState((HANDLE)g_hAdapter, State); if((WLAN_SUCCESS != dwResult) || (WLAN_RADIO_ON != State)) ERROR… //Connect to AP dwResult = WLAN_SetSSID((HANDLE)g_hAdapter, (WLAN_SSID_T) SSID); if(WLAN_SUCCESS != dwResult) ERROR… … // End of work with WLAN APIs: if(g_hAdapter) { // Disassociate and turn off WLAN radio

DWORD dwRetVal = WLAN_Disassociate(g_hAdapter); if( WLAN_SUCCESS != dwRetVal) ERROR… // Close adapter WLAN_CloseAdapter((HANDLE)g_hAdapter); g_hAdapter = NULL; }

Page 463: HC700 SDK Specification

Page 463 of 680

Data Types

WLAN_RADIO_STATE Description

The WLAN_RADIO_STATE enumeration is used to specify the state of WLAN radio.

Structure Definition

typedef enum

{

WLAN_RADIO_OFF ,

WLAN_RADIO_ON ,

} WLAN_RADIO_STATE, *LPWLAN_RADIO_STATE;

Members WLAN_RADIO_OFF

Use this member to turn off the radio. WLAN_RADIO_ON

Use this member to turn on the radio.

Page 464: HC700 SDK Specification

Page 464 of 680

WLAN_NETWORK_MODE

Description

The WLAN_NETWORK_MODE enumeration is used to specify the network mode of WLAN radio.

Structure Definition

typedef enum

{

WLAN_NETWORK_MODE_ADHOC ,

WLAN_NETWORK_MODE_INFRASTRUCTURE ,

WLAN_NETWORK_MODE_UNKNOWN ,

} WLAN_NETWORK_MODE, *LPWLAN_NETWORK_MODE;

Members WLAN_ NETWORK_MODE_ADHOC

Use this member to set the network mode to ad-hoc. WLAN_NETWORK_MODE_INFRASTRUCTURE

Use this member to set the network mode to infrastructure. WLAN_NETWORK_MODE_UNKNOWN

Network mode is unknown.

Page 465: HC700 SDK Specification

Page 465 of 680

WLAN_POWER_MODE

Description

The WLAN_POWER_MODE enumeration is used to specify the power saving mode of WLAN radio.

Structure Definition

typedef enum

{

WLAN_POWER_MODE_CAM ,

WLAN_POWER_MODE_PSP ,

WLAN_POWER_MODE_FAST_PSP ,

WLAN_POWER_MODE_AUTO ,

WLAN_ POWER_MODE _UNKNOWN ,

} WLAN_POWER_MODE, *LPWLAN_POWER_MODE;

Members WLAN_ POWER_MODE_CAM

Use this member to set the WLAN radio power saving mode to Continues Access Mode. WLAN_ POWER_MODE_PSP

Use this member to set the WLAN radio power saving mode to Power Saving Mode. WLAN_ POWER_MODE_FAST_PSP

Use this member to set the WLAN radio power saving mode to fast, good Power Saving Mode.

WLAN_ POWER_MODE_AUTO Use this member to set the WLAN radio power saving mode to Automatic Mode.

WLAN_ POWER_MODE_UNKNOWN Power Saving mode is unknown.

Page 466: HC700 SDK Specification

Page 466 of 680

WLAN_DATA_RATE

Description

The WLAN_DATA_RATE enumeration is used to specify the data transmission of WLAN radio.

Structure Definition

typedef enum

{

WLAN_DATA_RATE_1MBPS ,

WLAN_DATA_RATE_2MBPS ,

WLAN_DATA_RATE_5_5MBPS ,

WLAN_DATA_RATE_11MBPS ,

} WLAN_DATA_RATE, *LPWLAN_DATA_RATE;

Members WLAN_ DATA_RATE_1MBPS

WLAN radio transmission rate is 1 Mbps. WLAN_ DATA_RATE_2MBPS

WLAN radio transmission rate is 2 Mbps. WLAN_ DATA_RATE_5_5MBPS

WLAN radio transmission rate is 5.5 Mbps.

WLAN_ DATA_RATE_11MBPS WLAN radio transmission rate is 11 Mbps.

Page 467: HC700 SDK Specification

Page 467 of 680

WLAN_ASSOCIATION_STATUS

Description

The WLAN_ASSOCIATION_STATUS enumeration is used to specify the association status of WLAN radio.

Structure Definition

typedef enum

{

WLAN_ADAPTER_ASSOCIATED ,

WLAN_ADAPTER_SCANNING ,

WLAN_ADAPTER_OFF ,

} WLAN_ASSOCIATION_STATUS, *LPWLAN_ASSOCIATION_STATUS;

Members WLAN_ADAPTER_ASSOCIATED

WLAN radio associated with an Access Point. WLAN_ADAPTER_SCANNING

WLAN radio is scanning for Access Point to associate with. WLAN_ADAPTER_OFF

WLAN radio is off.

Page 468: HC700 SDK Specification

Page 468 of 680

WLAN_PM_CONFIGURATION_DATA Description

The WLAN_PM_CONFIGURATION_DATA structure incorporates the configuration of WLAN PM parameters.

Structure Definition

typedef struct _ WLAN_PM_CONFIGURATION_DATA

{

WLAN_RADIO_STATE WLANPowerStateAfterSystemBoot;

BOOL bSuspendAllowedWhenOn;

} WLAN_PM_CONFIGURATION_DATA, *LPWLAN_PM_CONFIGURATION_DATA;

Members WLANPowerStateAfterSystemBoot

Whether WLAN radio is ON after system WARM boot. Default WLAN state is OFF after COLD boot. bSuspendAllowedWhenOn

Whether Suspend is allowed when WLAN is ON. Default value is FALSE ( No Suspend when WLAN is ON).

Page 469: HC700 SDK Specification

Page 469 of 680

WLAN_ENCRYPTION_STATUS

Description

The WLAN_ENCRYPTION_STATUS enumeration is used to specify the encryption status of 802.11 NIC.

Structure Definition

typedef enum

{

WLAN_NDIS_ENCRYPTION_NOT_SUPPORTED ,

WLAN_NDIS_ENCRYPTION_DISABLED ,

WLAN_NDIS_ENCRYPTION_1_ENABLED ,

WLAN_NDIS_ENCRYPTION_1_KEY_ABSENT ,

WLAN_NDIS_ENCRYPTION_2_ENABLED ,

WLAN_NDIS_ENCRYPTION_2_KEY_ABSENT ,

WLAN_NDIS_ENCRYPTION_3_ENABLED ,

WLAN_NDIS_ENCRYPTION_3_KEY_ABSENT ,

} WLAN_ENCRYPTION_STATUS, *LPWLAN_ENCRYPTION_STATUS;

Members WLAN_NDIS_ENCRYPTION_NOT_SUPPORTED

Indicates that encryption (WEP, TKIP, and AES) is not supported. This value does not specify the availability of a transmit key.

WLAN_NDIS_ENCRYPTION_DISABLED Indicates that AES, TKIP, and WEP are disabled, and a transmit key is available.

WLAN_NDIS_ENCRYPTION_1_ENABLED Indicates that WEP is enabled; TKIP and AES are not enabled. This value does not specify the availability of a transmit key.

WLAN_NDIS_ENCRYPTION_1_KEY_ABSENT Indicates that AES, TKIP, and WEP are disabled, and a transmit key is not available.

WLAN_NDIS_ENCRYPTION_2_ENABLED Indicates that TKIP and WEP are enabled; AES is not enabled, and a transmit key is available.

WLAN_NDIS_ENCRYPTION_2_KEY_ABSENT

Indicates that there are no transmit keys available for use by TKIP or WEP, and TKIP and WEP are enabled; AES is not enabled.

WLAN_NDIS_ENCRYPTION_3_ENABLED Indicates that AES, TKIP, and WEP are enabled, and a transmit key is available.

WLAN_NDIS_ENCRYPTION_3_KEY_ABSENT

Indicates that there are no transmit keys available for use by AES, TKIP, or WEP, and AES, TKIP, and WEP are enabled.

Page 470: HC700 SDK Specification

Page 470 of 680

WLAN_AUTHENTICATION_MODE

Description

The WLAN_AUTHENTICATION_MODE enumeration is used to specify the authentication mode of 802.11 NIC.

Structure Definition

typedef enum

{

WLAN_NDIS_AUTH_MODE_OPEN ,

WLAN_NDIS_AUTH_MODE_SHARED ,

WLAN_NDIS_AUTH_MODE_AUTO_SWITCH ,

WLAN_NDIS_AUTH_MODE_WPA ,

WLAN_NDIS_AUTH_MODE_WPA_PSK ,

WLAN_NDIS_AUTH_MODE_WPA_NONE ,

WLAN_NDIS_AUTH_MODE_MAX ,

} WLAN_AUTHENTICATION_MODE, *LPWLAN_AUTHENTICATION_MODE;

Members WLAN_NDIS_AUTH_MODE_OPEN

Specifies open authentication mode. There are no checks when accepting clients (NICs) in this mode.

WLAN_NDIS_AUTH_MODE_SHARED Specifies shared authentication that uses a preshared wired equivalent privacy (WEP) key.

WLAN_NDIS_AUTH_MODE_AUTO_SWITCH Specifies auto-switch mode. When using auto-switch mode, the NIC tries 802.11 shared authentication mode first. If shared mode fails, the NIC attempts to use 802.11 open authentication mode.

WLAN_NDIS_AUTH_MODE_WPA Specifies WPA version one security. In infrastructure mode, this setting specifies the use of IEEE 802.1X for security.

WLAN_NDIS_AUTH_MODE_WPA_PSK Specifies WPA version one security. Specifies the use of a preshared key with IEEE 802.1X infrastructure mode. This mode is set when a preshared key is configured for IEEE 802.1X.

WLAN_NDIS_AUTH_MODE_WPA_NONE Specifies WPA version one security. Specifies the use of a preshared key without IEEE 802.1X in IBSS mode.

WLAN_NDIS_AUTH_MODE_MAX

Defines the upper bound.

Page 471: HC700 SDK Specification

Page 471 of 680

WLAN_EAP_TYPE

Description

The WLAN_EAP_TYPE enumeration is used to specify the EAP type.

Structure Definition

typedef enum

{

WLAN_EAP_TYPE_DISABLED ,

WLAN_EAP_TYPE_LEAP ,

WLAN_EAP_TYPE_PEAP ,

WLAN_EAP_TYPE_TLS ,

WLAN_EAP_TYPE_MD5,

WLAN_EAP_TYPE_MSCHAPv2,

} WLAN_EAP_TYPE, *LPWLAN_EAP_TYPE;

Members WLAN_EAP_TYPE_DISABLED

Specifies that 802.1X authentication is disabled.

WLAN_EAP_TYPE_LEAP Specifies LEAP as 802.1X authentication EAP type.

WLAN_EAP_TYPE_PEAP Specifies PEAP as 802.1X authentication EAP type.

WLAN_EAP_TYPE_TLS Specifies TLS as 802.1X authentication EAP type.

WLAN_EAP_TYPE_MD5 Specifies MD5 as 802.1X authentication EAP type.

WLAN_EAP_TYPE_ MSCHAPv2 Specifies MSCHAPv2 as 802.1X authentication EAP type.

Page 472: HC700 SDK Specification

Page 472 of 680

WLAN_KEY_MATERIALS Description

The WLAN_KEY_MATERIALS structure contains the network key information of WLAN profile.

Structure Definition

typedef struct _WLAN_KEY_MATERIALS

{

ULONG ulIndex;

ULONG ulKeyLength;

WLAN_KEY_T WLanKey;

} WLAN_KEY_MATERIALS, *LPWLAN_KEY_MATERIALS;

Members ulIndex

Contains Key index ulKeyLength

Contains the length of network key

WLanKey Contains the network security key

Page 473: HC700 SDK Specification

Page 473 of 680

WLAN_CONFIGURATION_DATA Description

The WLAN_CONFIGURATION_DATA structure incorporates the configuration of WLAN profile parameters.

Structure Definition

typedef struct _ WLAN_CONFIGURATION_DATA

{

WLAN_SSID_T SSID;

WLAN_NETWORK_MODE NetworkMode;

WLAN_ENCRYPTION_STATUS EncryptionStatus;

WLAN_AUTHENTICATION_MODE AuthMode;

WLAN_EAP_TYPE EAPType;

WLAN_KEY_MATERIALS KeyMaterials;

} WLAN_CONFIGURATION_DATA, *LPWLAN_CONFIGURATION_DATA;

Members SSID

Contains SSID NetworkMode

Contains the network mode (infrastructure or ad-hoc)

EncryptionStatus Contains the encryption status as described in WLAN_ENCRYPTION_STATUS

AuthMode

Contains the authentication mode as described in WLAN_AUTHENTICATION_MODE

EAPType Contains the EAP type as described in WLAN_EAP_TYPE

KeyMaterials

Contains network security key information as described in WLAN_KEY_MATERIALS

Page 474: HC700 SDK Specification

Page 474 of 680

#define SSID_STR_SIZE 32

typedef TCHAR WLAN_SSID_T [SSID_STR_SIZE];

typedef WLAN_SSID_T FAR * LPWLAN_SSID_T;

#define MAC_ADDR_STR_SIZE 6

typedef TCHAR WLAN_MAC_ADDR_T [MAC_ADDR_STR_SIZE];

typedef WLAN_MAC_ADDR_T FAR * LPWLAN_MAC_ADDR_T;

#define IP_ADDR_STR_SIZE 16

typedef TCHAR WLAN_IP_ADDR_T [IP_ADDR_STR_SIZE];

typedef WLAN_IP_ADDR_T FAR * LPWLAN_IP_ADDR_T;

#define KEY_STR_SIZE 64

#define KEY_INDEX_MIN 1

#define KEY_INDEX_MAX 4

typedef TCHAR WLAN_KEY_T [KEY_STR_SIZE];

typedef WLAN_KEY_T FAR * LPWLAN_KEY_T;

Page 475: HC700 SDK Specification

Page 475 of 680

WLAN Error Codes

#define ERROR_BIT 0x80000000 // Use bit 31 to indicate errror #define USER_BIT 0x20000000 // Bit 29 means not Win32 error #define WLAN_ERROR(code) (ERROR_BIT | USER_BIT | (WORD) code) #define E_WLAN_SUCCESS 0 #define E_WLAN_NOT_SUPPORTED WLAN_ERROR (0x0001) #define E_WLAN_INVALID_PARAMETER WLAN_ERROR (0x0002) #define E_WLAN_CONNECT_FAILED WLAN_ERROR (0x0003) #define E_WLAN_REQUEST_FAILED WLAN_ERROR (0x0004) #define E_WLAN_ADAPTER_OFF WLAN_ERROR (0x0005) #define E_WLAN_NO_MEMORY WLAN_ERROR (0x0006) #define E_WLAN_NDISUIO_ERROR WLAN_ERROR (0x0007) #define E_WLAN_CANNOTCOMMUNICATE WLAN_ERROR (0x0008) #define E_WLAN_TIMEOUT WLAN_ERROR (0x0009) #define E_WLAN_ADAPTER WLAN_ERROR (0x000A) #define E_WLAN_NOT_PRESENT WLAN_ERROR (0x000B) #define E_WLAN_INVALID_STATE WLAN_ERROR (0x00A1) #define E_WLAN_BUSY WLAN_ERROR (0x00A2) #define E_WLAN_CREATEMSGQUEUE_FAILED WLAN_ERROR (0x00A3) #define E_WLAN_WRITEMSGQUEUE_FAILED WLAN_ERROR (0x00A4) #define E_WLAN_CREATEEVENT_FAILED WLAN_ERROR (0x00A5) #define E_WLAN_CREATETHREAD_FAILED WLAN_ERROR (0x00A6) #define E_WLAN_CREATEWND_FAILED WLAN_ERROR (0x00A7) #define E_WLAN_REGWNDCLASS_FAILED WLAN_ERROR (0x00A8) #define E_WLAN_CREATEFLMAP_FAILED WLAN_ERROR (0x00AA) #define E_WLAN_MAPVIEWFL_FAILED WLAN_ERROR (0x00AB) #define E_WLAN_CREATEMUTEX_FAILED WLAN_ERROR (0x00B0) #define E_WLAN_OPENSESSION_FAILED WLAN_ERROR (0x0101) #define E_WLAN_CLOSESESSION_FAILED WLAN_ERROR (0x0102) #define E_WLAN_SUBSCRIBESESSION_FAILED WLAN_ERROR (0x0103) #define E_WLAN_UNSUBSCRIBESESSION_FAILED WLAN_ERROR (0x0103) #define E_WLAN_NOTIFICATIONS_QUE_EMPTY WLAN_ERROR (0x010A) #define E_WLAN_KEY_INDEX_ERROR WLAN_ERROR(0x010B) #define E_WLAN_KEY_LEN_ERROR WLAN_ERROR(0x010C) #define E_WLAN_KEY_DGTS_ERROR WLAN_ERROR(0x010D)

Page 476: HC700 SDK Specification

Page 476 of 680

15. Diagnostic API Library Overview The Diagnostic API Lib is a collection of test modules that perform a necessary testing of hardware. This collection of modules is comprised of various distinct components:

o Configuration Testing APIs (Serial ID)

o Memory (Checked by self-test while the unit is booting up).

o Keyboard Testing APIs

o Screen Testing APIs

o Touch Screen Testing APIs

o Battery Pack Testing APIs

o PIC Testing APIs

o Dock Testing APIs

o Media Testing APIs – (Mini SD Card, Flash File System, RAM Disk)

o Scanner Testing APIs

o Blue tooth Testing APIs

o Audio Testing APIs - (Speaker & Microphone)

o Reset (Cold\Warm Reset)

o Power Management Testing APIs

o RTC Testing APIs

o LED Testing APIs

o WLAN Radio APIs

This document describes the Diagnostic DLL for User Diagnostic Application. This document contains software definitions and description for the APIs functions. Diagnostics Modes of Operations:

Automatic Tests. A Set of tests performed in automatically manner. In this case an application returns the result of the test, PASS or FAIL. (For example, media testing.)

Manual Tests. User-Application interactive set of tests; User is asked to perform some action and the application in return checks if test passed or failed. (For example, LED testing.)

Device-to-Device Test. To perform this category of tests, user needs at least two devices. Usually it used for checking communication components. (For example: BT testing).

Page 477: HC700 SDK Specification

Page 477 of 680

Functions List Configuration • DiagConfigGetVersion Keyboard • DiagKbAutomaticTest • DiagSetKbLight • DiagGetKbLight • DiagSetKbBacklightIntenstity • DiagGetKbBacklightIntenstity Screen • DiagColorScrnPattern • DiagScrnSetBackLight • DiagScrnGetBackLight • DiagScrnSetBackLightIntensity • DiagScrnGetBackLightIntensity Touch Screen • DiagTsDrawLine • DiagTsCalibration Bluetooth • DiagBtStartEcho • DiagBtStopEcho • DiagBtTestLoopback • DiagBtInternalTest PIC • DiagPicGetVersion • DiagPicSetLED

Battery • DiagBatBridgingBatteryStatus • DiagBatGetMainBatteryStatus • DiagBatGetBkupBatteryStatus • DiagBatGetBatteryPackParams Dock • DiagDockGetStatus Scanner • DiagScanReadBarcode

Audio • DiagAudioRecord • DiagAudioPlayBack • DiagAudioGenerateTone

RTC • DiagRtcTest

Media • DiagMediaTest

PM • DiagPmGetWakeupSrc • DiagPmGetSleepType • DiagPmGetSystemInit • DiagPmTestMode

WLAN • DiagRadioWlanInternalTest • DiagRadioWlanNetworkRegisterTest • DiagRadioWlanStartEcho • DiagRadioWlanStopEcho • DiagRadioWlanTestLoopback

Page 478: HC700 SDK Specification

Page 478 of 680

15.1.1 Keyboard

Overview The Keyboard diagnostic APIs supports all available keyboard hardware testing. It includes Keyboard automatic and Backlight test. The Keyboard automatic test is responsible for testing of all keys. The user will show the keyboard picture on the screen. He will be asked to press all keys. Appropriate key will be marked on the screen. The Keyboard backlight test is responsible for testing of keyboard backlight state (turned on/off) and keyboard backlight intensity level.

Functions List • DiagKbAutomaticTest

• DiagSetKbLight

• DiagGetKbLight

• DiagSetKbBacklightIntenstity

• DiagGetKbBacklightIntenstity

Page 479: HC700 SDK Specification

Page 479 of 680

15.1.2 DiagKbAutomaticTest

15.1.2.1.1 Description The DiagKbAutomaticTest function allows performing automatic keyboard test. It will draw a keyboard picture in the “Automatic Keyboard Test” window. The user will be asked to tap all keys. On the exit this function will check if all key were pressed. If one or more keys were not pressed, it will return the list of the unpressed keys. Function Prototype DIAGAPI_API DWORD DiagKbAutomaticTest(HINSTANCE hIns,

HWND hWnd,

KEYBOARD_TEST_LIST lpUnpresedKeys

LPWORD lpNumUnpressedKeys);

Parameters [in] hIns Handle to the Instance. [in] hWnd Handle to the parent window. [out] lpUnpresedKeys The list of the unpressed keys [out] lpNumUnpressedKeys The number of the unpressed keys.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is KB_NOT_ALL_KEYS_PRESSED.

15.1.2.1.2 Comments None

15.1.2.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.2.1.4

15.1.2.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function KEYBOARD_TEST_LIST keyboard_test_list [size of KeyboardStatusStructTable];

Page 480: HC700 SDK Specification

Page 480 of 680

DWORD dwNumUnpressedKeys; HWND hWnd = AfxGetMainWnd()->m_hWnd; DiadKbAutomaticTest(hInstDLL , hWnd, keyboard_test_list, &dwNumUnpressedKeys);

15.1.3 DiagSetKbLight

15.1.3.1.1 Description The DiagSetKbLight function sets the keyboard backlight on/off.

15.1.3.1.2 Function Prototype

DIAGAPI_API DWORD DiagSetKbLight(DWORD dwBacklightState)

Parameters [in] dwBacklightState

A dwBacklightState value contains the backlight action (BACKLIGHT_ON or BACKLIGHT_OFF)

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.3.1.3 Comments None

15.1.3.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.3.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function dwResult = DiagSetKbLight (BACKLIGHT_OFF);

15.1.4 DiagGetKbLight

15.1.4.1.1 Description The DiagGetKbLight function returns the keyboard backlight state: on/off.

15.1.4.1.2 Function Prototype

DIAGAPI_API DWORD DiagGetKbLight(DWORD* pdwBacklightState)

Page 481: HC700 SDK Specification

Page 481 of 680

Parameters [in] pdwBacklightState

DWORD pointer to pdwBacklightState value that contains the retrieved backlight state (BACKLIGHT_ON or BACKLIGHT_OFF)

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.4.1.3 Comments None

15.1.4.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.4.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); // In the your function DWORD dwBackligthState; dwResult = DiagGetKbLight (&dwBackligthState);

Data Types typedef struct tagKEYBOARD_TEST_LIST { DWORD dwKeyCode; DWORD dwCheckFiled; TCHAR dwKeyText[12]; } KEYBOARD_TEST_LIST;

15.1.5 DiagSetKbBacklightIntenstity

15.1.5.1.1 Description The DiagSetKbBacklightIntenstity function sets the keyboard backlight Intensity.

15.1.5.1.2 Function Prototype

DIAGAPI_API DWORD DiagSetKbBacklightIntenstity (DWORD dwBacklightIntensity)

Parameters [in] dwBacklightIntensity

A dwBacklightIntensity value contains the backlight intensity level (1 - 32)

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

Page 482: HC700 SDK Specification

Page 482 of 680

15.1.5.1.3 Comments None

15.1.5.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.5.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function dwResult = DiagSetKbBacklightIntenstity (KBD_BACKLIGHT_INTENSITY_DEFAULT);

15.1.6 DiagGetKbBacklightIntenstity

15.1.6.1.1 Description The DiagGetKbBacklightIntenstity function retrieves the keyboard backlight current intensity and the keyboard backlight max intensity levels.

15.1.6.1.2 Function Prototype

DIAGAPI_API DWORD DiagGetKbBacklightIntenstity (DWORD dwBacklightIntesity,

DWORD dwMaxBacklightLevel) Parameters [in] dwBacklightIntesity

A dwBacklightIntesity value contains the current keyboard backlight intensity level (0-31)

[in] dwMaxBacklightLevel A dwMaxBacklightLevel value contains the max keyboard backlight intensity level the keyboard driver support of.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.6.1.3 Comments None

15.1.6.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.6.1.5 Example //Load the library HINSTANCE hInstDLL;

Page 483: HC700 SDK Specification

Page 483 of 680

hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function dwResult = DiagSetKbLight (BACKLIGHT_OFF);

Screen Overview The Screen diagnostic APIs supports all available screen hardware testing. It includes the following test procedures: drawing different patterns on the screen, screen backlight state and intensity. The Screen backlight is responsible for switching ON/OFF screen and keyboard backlight.

Functions List • DiagColorScrnPattern

• DiagScrnSetBackLight

• DiagScrnGetBackLight

• DiagScrnSetBackLightIntensity

• DiagScrnGetBackLightIntensity

Page 484: HC700 SDK Specification

Page 484 of 680

15.1.7 DiagColorScrnPattern

15.1.7.1.1 Description The DiagColorScrnPattern function allows performing the visual test of the screen. It will display a specific color (3,16 or 4096 colors) pattern to the screen.

15.1.7.1.2 Function Prototype

DIAGAPI_API DWORD DiagColorScrnPattern(COLOR_PAT_TYPE dwTestType,

HWND hWnd) Parameters

[in] hWnd Handle to the parent window.

[in] DwTestType

SCREEN_3_COLOR_PATTERN – 3-color LCD Red – Green – Blue range SCREEN_16_COLOR_PATTERN - 16-color screen SCREEN_FULL_COLOR_PATTERN - rainbow screen with all possible 4096 colors.

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.7.1.3 Comments None

15.1.7.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.7.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function HWND hWnd = AfxGetMainWnd()->m_hWnd; DiagScrnPattern (SCREEN_3_COLOR_PATTERN, hWnd)

15.1.8 DiagScrnSetBackLight

15.1.8.1.1 Description The DiagScrnSetBackLight function turns on/off the backlight state.

15.1.8.1.2 Function Prototype

DIAGAPI_API DWORD DiagScrnSetBackLight(DWORD dwBacklightState)

Page 485: HC700 SDK Specification

Page 485 of 680

Parameters [in] dwBacklightState

A dwBacklightState value contains the backlight action (BACKLIGHT_ON or BACKLIGHT_OFF)

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.8.1.3 Comments None

15.1.8.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.8.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function dwResult = DiagScrnSetBackLight (BACKLIGHT_ON);

15.1.9 DiagScrnGetBackLight

15.1.9.1.1 Description The DiagScrnGetBackLight function retrieves the screen backlight state.

15.1.9.1.2 Function Prototype

DIAGAPI_API DWORD DiagScrnGetBackLight(DWORD* pdwBacklightState)

Parameters [in] pdwBacklightState

DWORD pointer contains the backlight state (BACKLIGHT_ON or BACKLIGHT_OFF)

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.9.1.3 Comments None

15.1.9.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h.

Page 486: HC700 SDK Specification

Page 486 of 680

Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.9.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwBacklightState; dwResult = DiagScrnSetBackLight (&dwBacklightState);

Page 487: HC700 SDK Specification

Page 487 of 680

DiagScrnSetBackLightIntensity

15.1.9.1.6 Description The DiagScrnSetBackLightIntensity function sets the front light intensity level of the Handheld Terminal color display.

15.1.9.1.7 Function Prototype

DIAGAPI_API DWORD DiagScrnSetBackLight(DWORD dwBacklightIntensity)

Parameters [in] dwBacklightIntensity

A DWORD dwBackightIntensity value contains the Intensity level of the color display front light (Min Intensity Level = 0, Max Intensity Level = 31)

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.9.1.8 Comments None

15.1.9.1.9 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.9.1.10 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwBacklightIntensity = 20; dwResult = DiagScrnSetBackLightIntensity ( dwBacklightIntensity);

Page 488: HC700 SDK Specification

Page 488 of 680

DiagScrnGetBackLightIntensity

15.1.9.1.11 Description The DiagScrnGetBackLightIntensity function gets the current and maximum front light intensity levels of the Handheld Terminal color display.

15.1.9.1.12 Function Prototype

DIAGAPI_API DWORD DiagScrnGetBackLight(DWORD *pdwBacklightIntensity,

DWORD *pdwMaxBacklightIntensity ) Parameters [in] pdwBacklightIntensity

A DWORD pointer to pdwBacklightIntensity value that contains the current retrieved Intensity level of the color display front light (minimum value 0, maximum value 31)

[in] pdwBacklightIntensity

A DWORD pointer to pdwBacklightIntensity value that contains the maximum Intensity level of the color display front light

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.9.1.13 Comments None

15.1.9.1.14 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.9.1.15 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); // In the your function DWORD dwBacklightIntensity; DWORD dwMaxBacklightIntensity; dwResult = DiagScrnGetBackLightIntensity (&dwBacklightIntensity, &dwMaxBacklightIntensity );

Touch Screen Overview The Touch Screen diagnostic APIs supports all available Touch screen hardware testing. It includes two test procedures: draw line and calibration. The touch screen draw line test shows to user two points on the screen. The user will be asked to draw a line. The test checks continuation of the line and linearity.

Page 489: HC700 SDK Specification

Page 489 of 680

The second test checks the calibration of the screen. The screen will show 4 points, the user will be asked to press carefully and briefly hold stylus on the center of the X signs. At the end of test the function will check the user results coordinates with calibrated points of the system.

Functions List • DiagTsDrawLine

• DiagTsCalibration

Page 490: HC700 SDK Specification

Page 490 of 680

15.1.10 DiagTsDrawLine

15.1.10.1.1 Description The DiagTsDrawLine function will show to user two points on the screen and will ask him to draw a line. It will check continuation of the line and the bound of the strip between these points.

15.1.10.1.2 Function Prototype

DIAGAPI_API DWORD DiagTsDrawLine(HINSTANCE hIns,

HWND hWnd,

DWORD dwStripLength) Parameters

[in] hIns Handle to the Instance. [in] hWnd

Handle to the parent window. [in] dwStripLength

The strip length in pixels.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is TS_USER_DRAW_LINE_INCORRECT.

15.1.10.1.3 Comments None

15.1.10.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.10.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function HWND hWnd = AfxGetMainWnd()->m_hWnd; DWORD dwStripLength =5; DiagTsDrawLine (hInstDLL, hWnd, dwStripLength);

15.1.11 DiagTsCalibration

15.1.11.1.1 Description The DiagTsCalibration function draws five points on the screen. The user will be asked to tap these points. The function will compare the received points with the calibrated points of the system. Function Prototype DIAGAPI_API DWORD DiagTsCalibration(HINST hIns,

Page 491: HC700 SDK Specification

Page 491 of 680

HWND hWnd); Parameters

[in] hIns Handle to the Instance. [in] hWnd

Handle to the parent window.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is CALIBRATION_ERROR.

15.1.11.1.2 Comments None

15.1.11.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.11.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function HWND hWnd = AfxGetMainWnd()->m_hWnd; DWORD dwRes = DiagTsCalibration(hInstDLL, hWnd);

Page 492: HC700 SDK Specification

Page 492 of 680

Page 493: HC700 SDK Specification

Page 493 of 680

BlueTooth Overview The Bluetooth testing will use two HC700 devices. One of them will be in “Echo Bluetooth ” mode. The second will be in “Normal Bluetooth ” mode. When the second translates the messages, the first just will echo anything received message via Bluetooth radio. The Bluetooth diagnostic APIs supports all available Bluetooth hardware testing. It includes following test procedures: Start echo mode, stop echo modeand loop back test as remote tests, and internal test that retrieve the Bluetooth status.

Functions List • DiagBtStartEcho • DiagBtStopEcho • DiagBtTestLoopback 1. DiagBtInternalTest

15.1.12 DiagBtStartEcho

15.1.12.1.1 Description The DiagBtStartEcho function enters the HC700 device into Echo mode. Function Prototype

DIAGAPI_API DWORD DiagBtStartEcho ()

Parameters N/A.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is BT_ERROR_ECHO_MODE or BT_ALREADY_IN_ECHO_MODE

15.1.12.1.2 Comments None

15.1.12.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.12.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwRes = DiagBtSetEchoMode ();

Page 494: HC700 SDK Specification

Page 494 of 680

15.1.13 DiagBtStopEcho

15.1.13.1.1 Description The DiagBtStopEcho function takes off the HC700 device from Echo mode Function Prototype DIAGAPI_API DWORD DiagBtStopEcho ()

Parameters N/A.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is BT_ALREADY_STOPED_ECHO_MODE

15.1.13.1.2 Comments None

15.1.13.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.13.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwRes = DiagBtEndEcho();

Page 495: HC700 SDK Specification

Page 495 of 680

15.1.14 DiagBtTestLoopBack

15.1.14.1.1

15.1.14.1.2 Description This function is available for the HC700 device, which is in the “normal Bluetooth” mode. This device sends to the second one specific message. The second receives this message, adds ECHO prefix to the message and sends it back. The first receives the message, removes the ECHO prefix. (ECHO prefix means that the second one successfully received the message). After that it will compare received message with the original. Function Prototype DIAGAPI_API DWORD DiagBtTestLoopBack (TCHAR* tBluetoothAddres)

Parameters [in] tBluetoothAddres The Bluetooth radio address.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is BT_ERROR_LOOPBACK , BT_INVALID_ADDRESS or BT_ILLEGAL_MODE.

15.1.14.1.3 Comments None

15.1.14.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.14.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwRes = DiagBtTestLoopBack(tBluetoothAddres);

15.1.15 DiagBtInternalTest

15.1.15.1.1 Description The DiagBtInternalTest function checks the internal Bluetooth device status. Function Prototype DIAGAPI_API DWORD DiagBtInternalTest ()

Parameters N/A.

Page 496: HC700 SDK Specification

Page 496 of 680

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.15.1.2 Comments None

15.1.15.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.15.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwRes = DiagBtInternalTest ();

Page 497: HC700 SDK Specification

Page 497 of 680

Page 498: HC700 SDK Specification

Page 498 of 680

15.1.16 DiagConfigGetVersion

15.1.16.1.1

15.1.16.1.2 Description The DiagConfigGetVersion function returns the versions ID of all available components. Function Prototype DIAGAPI_API DWORD DiagConfigGetVersion

(LPDIAG_PRODUCT_PARAMETERS_INFO lpProductParamsInfo)

Parameters [out] Pointer to an DIAG_PRODUCT_PARAMETERS_INFO data structure that the function fills

with all the product parameters information

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is error value.

15.1.16.1.3 Comments None

15.1.16.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.16.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DIAGAPI_API PLATFORM_INFO PlatformInfo; DWORD dwResult; dwResult = DiagConfigGetVersion(&PlatformInfo);

Page 499: HC700 SDK Specification

Page 499 of 680

15.1.17 DiagConfigGetBlPostResult

15.1.17.1.1

15.1.17.1.2 Description The DiagConfigGetBlPostResult function returns the Boot Loader POST result. Function Prototype DIAGAPI_API DWORD DiagConfigGetBlPostResult

(DWORD* BootLoaderPostResult)

Parameters [out] Pointer to DWORD define the boot loader post result parameters.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is error value.

15.1.17.1.3 Comments None

15.1.17.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.17.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DIAGAPI_API PLATFORM_INFO PlatformInfo; DWORD dwResult; dwResult = DiagConfigGetVersion(&PlatformInfo);

Page 500: HC700 SDK Specification

Page 500 of 680

15.1.18 DiagConfigGetBootFlags

15.1.18.1.1

15.1.18.1.2 Description The DiagConfigGetBootFlags function returns the various flags - cold/warm boot, etc. Function Prototype DIAGAPI_API DWORD DiagConfigGetBootFlags(DWORD* BootFlags)

Parameters [out] Pointer to a DWORD defines the various boot flags.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is error value.

15.1.18.1.3 Comments None

15.1.18.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.18.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DIAGAPI_API PLATFORM_INFO PlatformInfo; DWORD dwResult; dwResult = DiagConfigGetVersion(&PlatformInfo);

Page 501: HC700 SDK Specification

Page 501 of 680

15.1.19 Data Types

15.1.20 typedef TCHAR DIAG_PLATFORM_SOFTWARE_VERSION_T[PLATFORM_SOFTWARE_VERSION_STR_SIZE];

15.1.21 typedef TCHAR POCKET_PC_VERSION_T [POCKET_PC_VERSION_STR_SIZE];

15.1.22 typedef TCHAR BLUETOOTH_STACK_T [BLUETOOTH_STACK_STR_SIZE];

15.1.23 typedef TCHAR BOOT_LOADER_T [BOOT_LOADER_STR_SIZE];

15.1.24 typedef struct tagDIAG_PPS_SW_VERSIONS

15.1.25 {

15.1.26 DIAG_PLATFORM_SOFTWARE_VERSION_T PlatformSwVersion;

15.1.27 PLATFORM_BUILD_TIME_STAMP_T PlatformSwBuildTimeStamp;

15.1.28 POCKET_PC_VERSION_T PocketPCVersion;

15.1.29 BLUETOOTH_STACK_T BlueToothStack;

15.1.30 BOOT_LOADER_T BootLoader;

15.1.31 PIC_FIRMWARE_VERSION_T PICfirmwareVersion;

15.1.32 XIPS_VERSION_T XIPsVersion;

15.1.33 XIPS_TIMESTAMP_T XIPsTimestamp;

15.1.34 }DIAG_PPS_SW_VERSIONS;

15.1.35 #define POCKET_PC_UUID_STR_SIZE 32

15.1.36 typedef USHORT FPGA_REVISION_T;

15.1.37 typedef USHORT PIC_REVISION_T;

15.1.38 typedef TCHAR BLUETOOTH_VERSION_T [DIAG_UNDEF];

15.1.39 typedef TCHAR SMART_BATTERY_T [DIAG_UNDEF];

15.1.40 typedef TCHAR POCKET_PC_UUID_T [POCKET_PC_UUID_STR_SIZE];

15.1.41 typedef TCHAR HARDWARE_REVISION_T [DIAG_UNDEF];

15.1.42 typedef TCHAR SCANER_FIRMWARE_T[DIAG_UNDEF];

15.1.43 typedef USHORT FPGA_FIRMWARE_VERSION_T;

Page 502: HC700 SDK Specification

Page 502 of 680

15.1.44 typedef USHORT FPGA_HARDWARE_VERSION_T;

15.1.45

15.1.46 typedef struct tagDIAG_PPS_HW_VERSIONS

15.1.47 {

15.1.48 FPGA_FIRMWARE_VERSION_T FpgaFirmwareVersion ;

15.1.49 FPGA_HARDWARE_VERSION_T FpgaHardwareVersion ;

15.1.50 PIC_REVISION_T PICRevision ;

15.1.51 BOARD_REVISION_T BoardRevision ;

15.1.52 BOARD_SERIAL_NUMBER_T BoardSerialNumber ;

15.1.53 BLUETOOTH_VERSION_T BluetoothVersion ;

15.1.54 PRODUCT_SERIAL_NUMBER_T ProductUuid;

15.1.55 CPU_REVISION_T CPURevision ;

15.1.56 SCANER_FIRMWARE_T ScanerFirmvare;

15.1.57 SMART_BATTERY_T SmartBattery;

15.1.58 POCKET_PC_UUID_T PocketPcUuid;

15.1.59 }DIAG_PPS_HW_VERSIONS;

Page 503: HC700 SDK Specification

Page 503 of 680

PIC Overview The PIC is a micro controller in the HC700 HW platform, which is responsible to wake up the HC700 from, suspend and also it controls the Tricolor LED and Smart Battery (the battery has it own API). The API enables the application to test each wake up source after suspends. It also enables Power control on Led device and BT device.

Functions List • DiagPicGetVersion • DiagPicSetLED

Page 504: HC700 SDK Specification

Page 504 of 680

15.1.60 DiagPicGetVersion

15.1.60.1.1 Description The DiagPicGetVersion function read & returns the PIC firmware version. Function Prototype DIAGAPI_API DWORD DiagPicGetVersion (LPWORD lpPicVersion)

Parameters [out] lpPicVersion -Specifies the value of the PIC Version.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is PIC_CANNOT_FIND_PIC_VESION.

15.1.60.1.2 Comments None

15.1.60.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.60.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwResult = DiagPicGetVersion(&dwPicVersion);

15.1.61

Page 505: HC700 SDK Specification

Page 505 of 680

15.1.62 DiagPicSetLED

15.1.62.1.1

15.1.62.1.2 Description The DiagPicSetLED function handles the tri-color LED. Function Prototype DIAGAPI_API DWORD DiagPicSetLED(DWORD dwStatus,

DWORD dwColor);

Parameters

[in] dwStatus Status of the led (LED_ON/ LED_OFF/ LED_BLINK)

[in] dwColor Color of the LED (LED_RED/ LED_GREEN/ LED_ORANGE)

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is PIC_LED_SET_ERROR.

15.1.62.1.3 Comments None

15.1.62.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.62.1.5 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwRes = DiagPicSetLED(LED_ON, LED_GREEN);

15.1.63

Page 506: HC700 SDK Specification

Page 506 of 680

Battery Overview The Battery diagnostic APIs obtain the Main and backup butteries necessary information: Main battery ACLineStatus

AC power status. It is one of the following values:

• AC_LINE_OFFLINE

• AC_LINE_ONLINE

• AC_LINE_BACKUP_POWER

• AC_LINE_UNKNOWN BatteryFlag

Battery charge status. It is one of the following values:

• BATTERY_FLAG_HIGH

• BATTERY_FLAG_LOW

• BATTERY_FLAG_CRITICAL

• BATTERY_FLAG_CHARGING

• BATTERY_FLAG_NO_BATTERY

• BATTERY_FLAG_UNKNOWN BatteryLifePercent

Percentage of full battery charge remaining. This member can be a value in the range 0 to 100, or 255 if the status is unknown. All other values are reserved.

BatteryVoltage

Number of millivolts (mV) of battery voltage. It can range from 0 to 65535.

BatteryCurrent Number of milliamps (mA) of instantaneous current drain. It can range from 0 to 32767 for charge and 0 to –32768 for discharge.

BatteryAverageCurrent Average number of milliamps of short term device current drain. It can range from 0 to 32767 for charge and 0 to –32768 for discharge.

BatteryTemperature

Battery temperature reported in 0.1 degree Celsius increments. It can range from –3276.8 to 3276.7.

BatteryChemistry Type of battery. It can be one of the following values:

• BATTERY_CHEMISTRY_ALKALINE

• BATTERY_CHEMISTRY_NICD

• BATTERY_CHEMISTRY_NIMH

• BATTERY_CHEMISTRY_LION

Page 507: HC700 SDK Specification

Page 507 of 680

• BATTERY_CHEMISTRY_LIPOLY

• BATTERY_CHEMISTRY_UNKNOWN BatteryLifeTime

Number of seconds of battery life remaining, or 0xFFFFFFFF if remaining seconds are unknown.

BatteryFullLifeTime Number of seconds of battery life when at full charge, or 0xFFFFFFFF if full battery lifetime is unknown.

Backup Battery BackupBatteryLifePercent

Percentage of full backup battery charge remaining. Must be in the range 0 to 100, or BATTERY_PERCENTAGE_UNKNOWN if percentage of backup battery life remaining is unknown.

BatteryVoltage Number of millivolts (mV) of battery voltage. It can range from 0 to 65535.

Functions List • DiagBatBridgingBatteryStatus • DiagBatGetMainBatteryStatus • DiagBatGetBkupBatteryStatus • DiagBatGetBatteryPackParams • Data Types

Page 508: HC700 SDK Specification

Page 508 of 680

15.1.64 DiagBatGetMainBatteryStatus

15.1.64.1.1

15.1.64.1.2 Description The DiagBatGetMainBatteryStatus function reads the status of the battery data information. Function Prototype DIAGAPI_API DWORD DiagBatGetMainBatteryStatus (LPMAIN_BATTERY_INFO

lpMainBatteryInfo)

Parameters [out] lpMainBatteryInfo Status of the main battery.

15.1.64.1.3 Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is BAT_CANNOT_GET_POWER_STATE.

15.1.64.1.4 Comments None

15.1.64.1.5 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.64.1.6 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function MAIN_BATTERY_INFO MainBatInfo; DWORD dwRes = DiagBatGetMainBatteryStatus(&MainBatInfo);

15.1.65

15.1.66

15.1.67 Data Types

15.1.68 MAIN_BATTERY_INFO //This structure consists all necessary main battery information. typedef struct tagMAIN_BATTERY_INFO {

BYTE ACLineStatus;

Page 509: HC700 SDK Specification

Page 509 of 680

BYTE BatteryFlag; BYTE BatteryLifeTime; BYTE BatteryLifePercent WORD BatteryVoltage; DWORD BatteryCurrent; DWORD BatteryAverageCurrent DWORD BatteryTemperature; BYTE BatteryChemistry;

} MAIN_BATTERY_INFO, *LPMAIN_BATTERY_INFO;

Page 510: HC700 SDK Specification

Page 510 of 680

15.1.69 DiagBatGetBkupBatteryStatus

15.1.69.1.1 Description The DiagBatGetBkupBatteryStatus function reads the voltage of the backup battery. Function Prototype DIAGAPI_API DWORD DiagBatGetBkupBatteryStatus (LPBACKUP_BATTERY_INFO

lpBkupBatInfo);

Parameters [out] lpMainBatteryInfo - Status of the main battery.

Return Value If the function succeeds, the return value is SUCCESS.

If the function fails, the return value is BAT_CANNOT_GET_POWER_STATE.

15.1.69.1.2 Comments None

15.1.69.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.69.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function BACKUP_BATTERY_INFO BkupBatInfo;DWORD dwRes = DiagBatGetBkupBatteryStatus(&BkupBatInfo);

15.1.70 Data Types

15.1.70.1.1 BACKUP_BATTERY_INFO //This structure consists all necessary main battery information. typedef struct tagBACKUP_BATTERY_INFO {

BYTE BackupBatteryLifePercent; DWORD BackupBatteryVoltage;

} BACKUP_BATTERY_INFO, *LPBACKUP_BATTERY_INFO;

Page 511: HC700 SDK Specification

Page 511 of 680

15.1.71 DiagBatGetBatteryPackParams

15.1.71.1.1

15.1.71.1.2 Description The DiagBatGetBatteryPackParams function reads the battery pack parameters. Function Prototype DIAGAPI_API DWORD DiagBatGetBatteryPackParams(LPMAIN_BATTERY_PACK_PARAMS

lpBatPackInfo)

Parameters [out] lpBatPackInfo Battery Pack Parameters

15.1.71.1.3 Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.71.1.4 Comments None

15.1.71.1.5 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.71.1.6 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function BACKUP_BATTERY_INFO BatPackInfo; DWORD dwRes = DiagBatGetBatteryPackParams(&BatPackInfo)

15.1.72

15.1.73

15.1.74 Data Types BACKUP_BATTERY_INFO //This structure consists battery pack information. typedef TCHAR DIAG_BATTERY_STRINGS_T [BATTERY_STRINGS_SIZE]; typedef struct tagMAIN_BATTERY_PACK_PARAMS

Page 512: HC700 SDK Specification

Page 512 of 680

{ WORD wRemainingCapacity; WORD wCycleCount; WORD wTimeToFull; WORD wSerialNumber; WORD wRatedCapacity; WORD wActualCapacity; WORD wManufactureDate; WORD wBatteryStatus; DIAG_BATTERY_STRINGS_T ManufactureName; DIAG_BATTERY_STRINGS_T DeviceName; DIAG_BATTERY_STRINGS_T DeviceChemistry; } MAIN_BATTERY_PACK_PARAMS, *LPMAIN_BATTERY_PACK_PARAMS;

15.1.75 DiagBatBridgingBatteryStatus

15.1.75.1.1

15.1.75.1.2 Description The DiagBatBridgingBatteryStatus function read manufacture data from the battery EPROM. Function Prototype DIAGAPI_API DWORD DiagBatBridgingBatteryStatus(LPDWORD lpBridgingBatData)

Parameters [out] lpBridgingBatData pointer to (DWORD) battery information.

15.1.75.1.3 Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

Page 513: HC700 SDK Specification

Page 513 of 680

15.1.75.1.4 Comments None

15.1.75.1.5 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.75.1.6 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD BridgingBatData; DWORD dwRes = DiagBatBridgingBatteryStatus (&BridgingBatData)

Docking Overview The Docking diagnostic API checks the IN/OUT docking event and Dock ID. The user will be asked to put HC700 into the dock; the API will return the dock type (OFFICE_DOCK / MOBILE_DOCK/AUX CONNECTOR) and status (DOCK_IN). When user pulls the HC700 from the dock, the API will return the DOCK_OUT status.

Functions List • DiagDockGetStatus

15.1.76

Page 514: HC700 SDK Specification

Page 514 of 680

15.1.77 DiagDockGetStatus

15.1.77.1.1 Description The DiagDockGetStatus function returns the dock status. If the HC700 is in the dock, this function returns dock type. Function Prototype

DIAGAPI_API DWORD DiagDockGetStatus (LPWORD lpStatus,

LPWORD lpType)

Parameters

[out] lpStatus Docking state (DOCK_IN/DOCK_OUT)

[out] lpType Docking type (OFFICE_DOCK / MOBILE_DOCK/ AUX_DOCK).

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is DOCK_CANNOT_GET_DOCK_STATUS.

15.1.77.1.2 Comments When the HC700 is out of dock the LpType parameter is NULL.

15.1.77.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.77.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwStatus, dwType; DWORD dwRes = DiagDockGetStatus(&dwStatus, & dwType);

Page 515: HC700 SDK Specification

Page 515 of 680

Scanner Overview The scanner diagnostic API tests the scanner hardware. The API will set all label types ON. When user scans the label, this API returns the barcode data.

Functions List • DiagScanReadBarcode

Page 516: HC700 SDK Specification

Page 516 of 680

15.1.78 DiagScanReadBarcode

15.1.78.1.1 Description The DiagScanReadBarcode function allows performing scanner test. It will draw a specific dialog where will present all read barcodes and scanner events. User will be able to choose a timeout. On the exit this function will return a list of scanner events. Function Prototype

DIAGAPI_API LRESULT DiagScanReadBarcode(HINSTANCE hIns, HWND hWnd,

TCHAR *pListOfScanEvents)

Parameters [in] hIns Handle to the Instance. [in] hWnd Handle to the parent window. [out] pListOfScanEvents List of scanner events.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return failed values.

15.1.78.1.2 Comments None

15.1.78.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.78.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function HWND hWnd = this->m_hWnd; extern HINSTANCE hInstDLL; DWORD dwResult = DiagScanReadBarcode (hInstDLL , hWnd, pListOfScanEvents);

Audio Overview The Audio diagnostic APIs supports all available audio hardware testing. It includes three test procedures: recording via microphone, playing the data though the speaker and tone generation. The first test checks microphone hardware. The user will be asked to choose time of recording and the .wav file in which the data will be recorded. The second test checks the speaker. The user will be asked to choose the .wav file.

Page 517: HC700 SDK Specification

Page 517 of 680

The third test also checks the speaker. Upon the given frequency, level and duration, this API will generate tone. The buzzer diagnostic API checks the buzzer hardware. It generate a beep with HIGHT or LOW volume (according to the user request).

Functions List • DiagAudioRecord • DiagAudioPlayBack • DiagAudioGenerateTone • DiagBuzzerGenerateBeep

Page 518: HC700 SDK Specification

Page 518 of 680

15.1.79 DiagAudioRecord

15.1.79.1.1 Description The DiagAudioRecord function is used for recording via microphone. Function Prototype

DIAGAPI_API DWORD DiagAudioRecord (DWORD dwTimeLength, LPCSTR lpszFile)

Parameters [in] dwTimeLength -

Time to record in seconds 0 - 10 [out] lpszFile -

Long pointer to the null-terminated string. This string can contain a complete filename with wav extension.

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is FAIL.

15.1.79.1.2 Comments None

15.1.79.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.79.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwTimeLen = 2; DWORD dwResult = DiagAudioRecord(dwTimeLen, _T(“filename.wav”));

Page 519: HC700 SDK Specification

Page 519 of 680

15.1.80 DiagAudioPlayBack

15.1.80.1.1 Description The DiagAudioPlayBack function is used for playing the .wav files though the speaker. Function Prototype

DIAGAPI_API DWORD DiagAudioPlayBack (LPCSTR lpszFile)

Parameters [in] LpszFile -

Long pointer to the null-terminated string. This string can contain a complete filename, including the extension.

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is AUDIO_ERROR_PLAYBACK.

15.1.80.1.2 Comments None

15.1.80.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.80.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwResult = DiagAudioPlayBack (_T(“filename”));

Page 520: HC700 SDK Specification

Page 520 of 680

15.1.81 DiagAudioGenerateTone

15.1.81.1.1 Description The DiagAudioGenerateTone function is used for tone generating using input parameters Function Prototype DIAGAPI_API DWORD DiagAudioGenerateTone (DWORD dwFrequency,

DWORD dwLevel,

DWORD dwDuration)

Parameters

[in] dwFrequency Frequency (500, 1000, 1500, 2000, 2500 Hz.) [in] dwLevel Level (Low, Medium, High) [in] dwDuration Duration in milliseconds (# of seconds)

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is AUDIO_ERROR_GENERATE_TONE.

15.1.81.1.2 Comments None

15.1.81.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.81.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwFrequency; DWORD dwLevel; DWORD dwDuration ; //Initialize dwFrequency, dwLevel, dwDuration. DWORD dwRes = DiagAudioGenerateTone(dwFrequency, dwLevel, dwDuration)

15.1.82 DiagBuzzerGenerateBeep

15.1.82.1.1 Description This DiagBuzzerGenerateBeep function is used for beep generation using input parameters. Function Prototype DIAGAPI_API DWORD DiagBuzzerGenerateBeep (DWORD dwLevel)

Page 521: HC700 SDK Specification

Page 521 of 680

Parameters [in] dwLevel Level (High or Low)

Return Value If the function succeeds, the return value is SUCCESS.

If the function fails, the return value is AUDIO_BUZZER_FAIL.

15.1.82.1.2 Comments None

15.1.82.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.82.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwLevel = HIGH; //Initialize dwFrequency, dwLevel, dwDuration. DWORD dwRes = DiagBuzzerGenerateBeep (dwLevel);

Page 522: HC700 SDK Specification

Page 522 of 680

RTC Overview The RTC diagnostic APIs checks RTC progress.

Functions List • DiagRtcTest

Page 523: HC700 SDK Specification

Page 523 of 680

15.1.83 DiagRtcTest

15.1.83.1.1 Description The DiagRtcTest function is used to performing an automatic test of RTC. The test checks the RTC progress and takes about two seconds. Function Prototype

DIAGAPI_API DWORD DiagRtcTest (void);

Parameters None.

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the return value is RTC_TIMER_INVALID.

15.1.83.1.2 Comments None

15.1.83.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.83.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwRes = DiagRtcTest ();

Page 524: HC700 SDK Specification

Page 524 of 680

Media Overview The Media diagnostic API is an automatic media test. According to the drive request FLASH_FILE_SYSTEM/MMC/COMPACT_FLASH/RAM_DISK, it creates a file with the specific data on the requested drive, checks the data and removes the file. Correct data in the drive means successful test result.

Functions List • DiagMediaTest

Page 525: HC700 SDK Specification

Page 525 of 680

15.1.84 DiagMediaTest

15.1.84.1.1 Description This DiagMediaTest function performs a Drive Test to a specific drive. It creates a specific file with a specific data on the given drive, reads this file and compares with the given one Function Prototype

DIAGAPI_API DWORD DiagMediaTest (DWORD dwDrive)

Parameters [in] dwDrive (FLASH_FILE_SYSTEM/

MMC/ COMPACT_FLASH/ RAM_DISK)

Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the return value is MEDIA_DRIVE_INVALID.

15.1.84.1.2 Comments None

15.1.84.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.84.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwRes = DiagMediaTest(RAM_DISK);

Page 526: HC700 SDK Specification

Page 526 of 680

15.1.85 Power Management

Overview The Power Management diagnostic APIs check the Power Management of the HC700 terminal. It enters the HC700 terminal into SUSPEND mode. The RTC will be wakeup the HC700.

Functions List • DiagPmTestMode • DiagPmGetWakeupSrc • DiagPmGetSleepType • DiagPmGetSystemInit

Page 527: HC700 SDK Specification

Page 527 of 680

15.1.86 DiagPmTestMode

15.1.86.1.1 Description This DiagPmTestMode function allows to user to put the device in Suspend operating mode. Note: Run mode will not check, because this mode is set the most time. Function Prototype

DIAGAPI_API void DiagPmTestMode (DWORD dwTimeToWakeup)

Parameters [in] dwTimeToWakeup

Time to wakeup.

Return Value None.

15.1.86.1.2 Comments None

15.1.86.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.86.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwTimeToWakeup = 2; DiagPmTestMode(dwTimeToWakeup);

15.1.87 DiagPmGetWakeupSrc

15.1.87.1.1 Description This DiagPmGetWakeupSrc Check through the kernel I/O control -IOCTL_HAL_GET_WAKE_SOURCE who is waking up the system. Function Prototype DIAGAPI_API DWORD DiagPmGetWakeupSrc (DWORD* pWakeupSrc)

Parameters [out] pWakeupSrc

The wake up source.

Return Value

Page 528: HC700 SDK Specification

Page 528 of 680

If the function succeeds, the return value is SUCCESS. Else it returns FAIL.

15.1.87.1.2 Comments None

15.1.87.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.87.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD dwWakeupCause; // Wakeup mask returned from HAL IOCTL DiagPmGetWakeupSrc(&dwWakeupCause);

Page 529: HC700 SDK Specification

Page 529 of 680

15.1.88 DiagPmGetSleepType

15.1.88.1.1 Description This DiagPmGetSleepType function Get Sleep Type via the Kernel Info. Function Prototype DIAGAPI_API DWORD DiagPmGetSleepType (DWORD* SleepType)

Parameters [out] *SleepType -

Pointer to a DWORD holding the sleep type parameter.

Return Value If the function succeeds, the return value is SUCCESS. Else it returns FAIL.

15.1.88.1.2 Comments None

15.1.88.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.88.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In the your function DWORD pdwSleepType; DiagPmGetSleepType(&dwSleepType);

15.1.89 DiagPmGetSystemInit

15.1.89.1.1 Description This DiagPmGetSystemInit function Get System Init via the Kernel Info. Function Prototype DIAGAPI_API DWORD DiagPmGetSystemInit (BOOL* bSystemInit)

Parameters [out] bSystemInit

System initialization status. #define SYSTEM_INIT_IN_PROCESS 0 #define SYSTEM_INIT_DONE 1

Page 530: HC700 SDK Specification

Page 530 of 680

Return Value

If the function succeeds, the return value is SUCCESS. Else it returns FAIL.

15.1.89.1.2 Comments None

15.1.89.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.89.1.4 Example //Load the library HINSTANCE hInstDLL; hInstDLL = LoadLibrary(_T("DiagAPI.dll")); //////////////////////////////////////////////////////////////////////////////////////////////////////////// // In your function BOOL bSysInit;

DiagPmGetSystemInit (&bSysInit);

WLAN Radio Overview The WLAN Radio testing uses two HC700 devices. One of them should be in “Echo WLAN Radio ” mode. The second should be in “Normal WLAN Radio ” mode. When the second transmits the messages, the first will just add a “ECHO_” prefix to the message and then echo the received message via the WLAN adapter. The WLAN Radio diagnostic APIs supports available WLAN Radio hardware testing. It includes the following test procedures: - INTERNAL TEST (retrieves internal WLAN adapter parameters), - Network Test (checks that radio is registered on WLAN network, checks that radio in coverage, retrieves current network operator and signal quality), - Remote Test (transmits messages between two remote HC700 devices via WLAN radio).

Functions List 2. DiagRadioWlanStartEcho 3. DiagRadioWlanStopEcho 4. DiagRadioWlanTestLoopback 5. DiagRadioWlanInternalTest 6. DiagRadioWlanNetworkRegisterTest

15.1.90 DiagRadioWlanStartEcho

Page 531: HC700 SDK Specification

Page 531 of 680

15.1.90.1.1 Description The DiagRadioWlanStartEcho function enters the HC700 device into Echo mode. This function receives the message from the client device (device in Loop back Mode), add “ECHO” prefix and send message back. Function Prototype DIAGAPI_API DWORD DiagRadioWlanStartEcho (LPTSTR lpServerName)

Parameters [out] lpServerName- pointer to string be field with server IP address.

Return Value If the function succeeds, the return value is SUCCESS.

If the function fails, the function returns one of the Radio diagnostic error codes (see Diagnostic radio error codes).

15.1.90.1.2 Comments None

15.1.90.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 532: HC700 SDK Specification

Page 532 of 680

15.1.91 DiagRadioWlanStopEcho

15.1.91.1.1 Description The DiagRadioWlanStopEcho function stops the WLAN Radio echo functionality Function Prototype DIAGAPI_API DWORD DiagRadioWlanStopEcho ()

Parameters N/A.

Return Value If the function succeeds, the return value is SUCCESS.

If the function fails, the function returns one of the Radio diagnostic error codes (see Diagnostic radio error codes).

15.1.91.1.2 Comments None

15.1.91.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 533: HC700 SDK Specification

Page 533 of 680

15.1.92 DiagRadioWlanTestLoopBack

15.1.92.1.1

15.1.92.1.2 Description This function is available for the HC700 device, which is in the “normal WLAN Radio” mode. This device sends to the second one specific message. The second receives this message, adds ECHO prefix to the message and sends it back. The first receives the message, removes the ECHO prefix. (ECHO prefix means that the second one successfully received the message). After that it will compare received message with the original. Function Prototype DIAGAPI_API DWORD DiagRadioWlanTestLoopBack (LPTSTR lpServerName)

Parameters [in] lpServerName

String pointer of remote server IP address.

Return Value If the function succeeds, the return value is SUCCESS.

If the function fails, the function returns one of the Radio diagnostic error codes (see Diagnostic radio error codes).

15.1.92.1.3 Comments None

15.1.92.1.4 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.93 DiagRadioWlanInternalTest

15.1.93.1.1 Description The DiagRadioWlanInternalTest function retrieves the internal WLAN radio parameters. Function Prototype DIAGAPI_API DWORD DiagRadioWlanInternalTest (LPWLAN_EQUIPMENT_INFO_PARAM

Page 534: HC700 SDK Specification

Page 534 of 680

lpGPRSEquipmentInfo)

Parameters [out]

LpGPRSEquipmentInfo- Pointer to structure to be field with the following fields: strSerialNumber -Radio Serial number (IMEI) strModelId -Radio Model ID strRevisionId - Radio firmware version strManufacturerId -Radio manufacture ID

Return Value If the function succeeds, the return value is SUCCESS. If the function fails, the function returns one of the Radio diagnostic error codes (see Diagnostic radio error codes).

15.1.93.1.2 Comments None

15.1.93.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

15.1.94 DiagRadioWlanNetworkRegisterTest

15.1.94.1.1 Description The DiagRadioWlanNetworkRegisterTest function checks the Radio GPRS registration status to GSM/GPRS network, checks the GPRS radio coverage status, retrieves the current operator name and signal quality. Function Prototype DIAGAPI_API DWORD DiagRadioWlanNetworkRegisterTest (LPWLAN_NETWORK_PARAM

lpNetworkParam)

Parameters [out]

lpNetworkParam - Pointer to structure to be field with the following fields: strWlanSSID - The Service Set Name (Network name) strWlanBSSID - MAC address of the Service Set the terminal is associated

with. strIpAddress - Current IP address of the adapter WlanRadioSatus – Association status of the WLAN radio.

Page 535: HC700 SDK Specification

Page 535 of 680

ulWlanRSSI - Signal Strength of the WLAN adapter Return Value

If the function succeeds, the return value is SUCCESS. If the function fails, the function returns one of the Radio diagnostic error codes (see Diagnostic radio error codes).

15.1.94.1.2 Comments None

15.1.94.1.3 QuickInfo Windows CE: Version 2.11 or later. Header: Declared in DiagAPI.h. Import Library: Use DiagAPI.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 536: HC700 SDK Specification

Page 536 of 680

Data Types Internal WLAN radio parameters: typedef enum { WLAN_ASSOCIATED , //WLAN radio associated with an Access Point.

WLAN_SCANNING , //WLAN radio is scanning for Access Point to //associate with. WLAN_OFF , //WLAN radio is off. } WLAN_RADIO_STATUS, *LPWLAN_RADIO_STATUS; // WLAN Structures typedef struct tagWLAN_EQUIPMENT_INFO_PARAM { BOOL bIsCardPresent; // Card Detection TCHAR strCardMacAdress[6]; // MAC Address TCHAR strDriverVersion[128]; // Driver version TCHAR strFirmWareVersion[128]; // manufacturer_id }WLAN_EQUIPMENT_INFO_PARAM, *LPWLAN_EQUIPMENT_INFO_PARAM; typedef struct tagWLAN_NETWORK_PARAM {

TCHAR strWlanSSID [32]; // The Service Set Name (Network name) //the terminal is connected.

TCHAR strWlanBSSID [6]; // MAC address of the Service Set //the terminal is associated with.

TCHAR strIpAddress [16]; // Current IP address of the adapter. WLAN_RADIO_STATUS WlanRadioSatus; // Association status of the

// WLAN radio. ULONG ulWlanRSSI; // Signal Strength of the WLAN adapter (0-100%) }WLAN_NETWORK_PARAM, * LPWLAN_NETWORK_PARAM;

15.1.95 ERROR Codes

Error codes

SUCCESS 0 Success FAILURE 1 Failure KB_NOT_ALL_KEYS_PRESSED 0x100 Not all keys were

pressed during keyboard automatic test

KB_CANNOT_SET_KEYBOARD_BACKLIGHT 0x101 Problem to set on/off keyboard backlight

KB_ILLEGAL _BACKLIGHT_COMMAND 0x102 Keyboard backlight illegal instruction.

DISP_ILLEGAL_PATTERN_COMMAND 0x103 Illegal screen patterns instruction.

Page 537: HC700 SDK Specification

Page 537 of 680

DISP_CANNOT_SET_SCREEN_BACKLIGHT 0x104 Problem to set on/off screen backlight

DISP_ILLEGAL_BACKLIGHT_COMMAND 0x105 Display illegal instruction

TS_USER_DRAW_LINE_INCORRECT 0x106 User draw line incorrect.

IRDA_ALREADY_IN_ECHO_MODE 0x107 IrDA already in echo mode

IRDA_ALREADY_STOPED_ECHO_MODE 0x108 IrDA already stopped echo mode

IRDA_ERROR_LOOPBACK 0x109 IrDA error in the loop back test.

IRDA_ILLEGAL_MODE 0x10A Illegal mode. RTC_TIMER_INVALID 0x10B RTC timer invalid MEDIA_DRIVE_INVALID 0x10C Media drive invalid PIC_ILLEGAL_COMPONENT 0x10D Illegal component PIC_CANNOT_FIND_PIC_VESION 0x10F Cannot find PIC

Version. PIC_NO_WAKEUP_SOURCE_DETECTED 0x110 No wakeup source

detected. PIC_LED_SET_ERROR 0x111 Error occurs on

setting LED. PIC_LED_INVALID_PARAM 0x112 Invalid parameter on

handling LED. BAT_CANNOT_GET_POWER_STATE 0x113 Couldn't get battery

state. DOCK_CANNOT_GET_DOCK_STATUS 0x114 Cannot get DOCK

status. AUDIO_ERROR_RECORD 0x115 Problem to record

via microphone. AUDIO_ERROR_PLAYBACK 0x116 Problem to play the

data though the speaker

AUDIO_ERROR_GENERATE_TONE 0x116 Problem to generate tone.

AUDIO_BUZZER_FAIL.

0x117 Buzzer Fail.

SCAN_CANNOT_OPEN 0x11B Cannot open scanner.

SCAN_CANNOT_CLOSE 0x11C Cannot close scanner.

SCAN_NO_MEMORY_ALLOCATE 0x11D Cannot allocate memory for scanner buffer.

SCAN_CANNOT_DEALLOCATE_BUFF 0x11E Cannot de-allocate scanner buffer.

SCAN_CANNOT_ENABLE 0x11F Cannot enable scanner.

SCAN_CONNOT_SET_PARAMS 0x120 Cannot set scanner parameters.

SCAN_CONNOT_READ 0x121 Cannot read scanner parameters.

CALIBRATION_ERROR 0x125 Calibration error. DIAG_PARAMS_NOT_VALID 0x126 Diag Prams error BT_ALREADY_IN_ECHO_MODE 0x127 BT already in echo

mode BT_ALREADY_STOPED_ECHO_MODE 0x128 BT already stopped

echo BT_ILLEGAL_BITRATE 0x129 BT illegal bit rate

Page 538: HC700 SDK Specification

Page 538 of 680

value. BT_CANNOT_CHANGE_BITRATE 0x12A Cannot change BT

bit rate. BT_ERROR_LOOPBACK 0x12B BT error in the loop

back test. BT_ILLEGAL_MODE 0x12C Illegal mode. BT_ERROR_ECHO_MODE 0x12D BT_ERROR_OPEN_PORT 0x12E BT_ERROR_BD_DISABLED 0x12F BT_ERROR_ENABLE_SERVER 0x130 BT_ERROR_BT_PROFILE 0x131 BT_ERROR_BD_ADDRESS 0x132 TICK_NOT_ACCURATE 0x133 NO_MMC_CARD_DETECTED 0x134 NO_CF_CARD_DETECTED 0x135 GPRS_ALREADY_IN_ECHO_MODE 0x136 GPRS_ALREADY_STOPED_ECHO_MODE 0x137 GPRS_ERROR_LOOPBACK 0x138 GPRS_ILLEGAL_MODE 0x139 GPRS_ERROR_ECHO_MODE 0x140 GPRS_NOT_SUPPORTED_PRODUCT 0x141 GPRS_TAPI_INIT_ERROR 0x142 GPRS_GET_STATE_ERROR 0x143 GPRS_SET_STATE_ERROR 0x144 GPRS_RADIO_INTERNAL_DATA_ERROR 0x145 GPRS_NEWORK_REGISTRATION_ERROR 0x146 GPRS_ESTABLISH_RAS_CONNECTION_ERROR 0x147 GPRS_CHECK_RADIO_POWER_ON_ERROR 0x148 GPRS_GET_RAS_IPADDRESS_ERROR 0x149 GPRS_ESTABLISH_SERVER_CONNECTION_ERROR 0x150 GPRS_INVALID_IP_ADDRESS 0x151 GPRS_NO_COVAREGE_ERROR 0x152 GPRS_NO_REGISTERED_GPRS_NETWORK_ERROR 0x153 GPRS_NO_REGISTERED_GSM_NETWORK_ERROR 0x154 GPRS_FAILED_TO_LOAD_G20_LIB 0x155 WLAN_ALREADY_IN_ECHO_MODE 0x156 WLAN_ALREADY_STOPED_ECHO_MODE 0x157 WLAN_ERROR_LOOPBACK 0x158 WLAN_ILLEGAL_MODE 0x159 WLAN_ERROR_ECHO_MODE 0x160 WLAN_NOT_SUPPORTED_PRODUCT 0x161 WLAN_FAILED_TO_LOAD_WLAN_LIB 0x162 WLAN_GET_STATE_ERROR 0x163 WLAN_SET_STATE_ERROR 0x164 WLAN_RADIO_INTERNAL_DATA_ERROR 0x165 WLAN_NEWORK_REGISTRATION_ERROR 0x166 WLAN_ESTABLISH_CONNECTION_ERROR 0x167 WLAN_CHECK_RADIO_POWER_ON_ERROR 0x168 WLAN_GET_RAS_IPADDRESS_ERROR 0x169 WLAN_ESTABLISH_SERVER_CONNECTION_ERROR 0x170 WLAN_INVALID_IP_ADDRESS 0x171 WLAN_NO_COVAREGE_ERROR 0x172 WLAN_NO_REGISTERED_WLAN_NETWORK_ERROR 0x173

Page 539: HC700 SDK Specification

Page 539 of 680

15.1.96

Page 540: HC700 SDK Specification

Page 540 of 680

16. OEM Power Management API

Overview The OEM PM API provides the application the ability to set and get Power Management (PM) related timeouts. These timeouts can be also changed using Control Panel Applets: “Power” and “Display”.

Functions List Function Description

PM_GetTimeout Gets the specified PM_TIMEOUT_TYPE timeout.

PM_SetTimeout Sets the specified PM_TIMEOUT_TYPE timeout.

PM_GetBootType Returns the last boot operation done in device (Warm, Cold, Watchdog).

Examples

Data Types

Page 541: HC700 SDK Specification

Page 541 of 680

PM_GetTimeout

Description This function gets the specified PM_TIMEOUT_TYPE timeout.

Function Prototype DWORD PM_GetTimeout ( PM_TIMEOUT_TYPE eTimeoutType , LPDWORD lpdwTimeout )

Parameters

eTimeoutType [in] Timeout Type. See PM_TIMEOUT_TYPE

lpdwTimeout [out] Pointer to a DWORD to receive the current timeout value in seconds.

Return Values

ERROR_SUCCESS indicates success. Other Win32 error code indicates failure.

Comments None.

See Also PM_SetTimeout

Page 542: HC700 SDK Specification

Page 542 of 680

PM_SetTimeout

Description This function sets the specified PM_TIMEOUT_TYPE timeout.

Function Prototype DWORD PM_SetTimeout ( PM_TIMEOUT_TYPE eTimeoutType , DWORD dwTimeout )

Parameters

eTimeoutType [in] Timeout type. See PM_TIMEOUT_TYPE

dwTimeout [in] New timeout value in seconds. If dwTimeout is 0, then the timeout never elapses.

Return Values

ERROR_SUCCESS indicates success. Other Win32 error code indicates failure.

Comments Minimal timeout value is 10 seconds.

See Also PM_GetTimeout

Page 543: HC700 SDK Specification

Page 543 of 680

PM_GetBootType

Description This function returns the last boot operation done in device (Warm, Cold, Watchdog).

Function Prototype DWORD PM_GetBootType(PPM_BOOT_TYPE lpeBootType)

Parameters

lpeBootType [in] PPM_BOOT_TYPE can be one of the boot reason.

Return Values

ERROR_SUCCESS indicates success. ERROR_INVALID_PARAMETER indicates on error case.

Comments

See Also #KernelIoControl

Page 544: HC700 SDK Specification

Page 544 of 680

Examples The example below demonstrates how to work with OEM PM APIs: PM_GetTimeout Example DWORD dwTimeout, dwRetVal; // Get the current AC Suspend timeout value dwRetVal = PM_GetTimeout(ACSuspendTimeout, &dwTimeout); … PM_SetTimeout Example DWORD dwTimeout, dwRetVal; // Set the AC ScreenOff timeout value to 30 sec. dwTimeout = 30; dwRetVal = PM_SetTimeout(ACScreenOffTimeout, dwTimeout); …

Page 545: HC700 SDK Specification

Page 545 of 680

Data Types typedef enum { ACScreenOffTimeout,

BattScreenOffTimeout,

ACSuspendTimeout,

BattSuspendTimeout

} PM_TIMEOUT_TYPE, *PPM_TIMEOUT_TYPE;

Members ACScreenOffTimeout

Screen OFF timeout [in seconds] when Device is powered via an External source.

BattScreenOffTimeout Screen OFF timeout [in seconds] when Device is powered via its Internal Battery.

ACSuspendTimeout Operating System entering-to-Suspend-timeout [in seconds] when Device is powered via an External source.

BattSuspendTimeout Operating System entering-to-Suspend-timeout [in seconds] when Device is powered via its Internal Battery.

typedef enum {

UnknownBoot,

ColdBoot,

WatchdogBoot,

WarmBoot = 8

} PM_BOOT_TYPE, *PPM_BOOT_TYPE;.

Page 546: HC700 SDK Specification

Page 546 of 680

17. System-Update Service

Overview The SYSTEM_UPDATE service, hereinafter UPOS, provides for the user, a means to update/upgrade the Operating System, Bootloader & PIC softwares, “in the field”. When a need for a system update occurs the user should transfer a HC700 System Package to persistent storage like IPSM or SD card (for ex. \SD\UpdateOsDir\). The package will include one or more image files (in independed XIP regions) in a form of one binary file. System package file name form can be: Pack_Rxx.xx.xx.bin. After the system package is transferred to the persistent storage, the user application on the HC700 will launch the SYSTEM_UPDATE service. The launching will be done by calling the UPOS_UpdateOS API with the system package file name (full path) as a parameter. Once launched – The SYSTEM_UPDATE service will update the HC700 system as required and then will reboot the HC700. If the system update process is initiated successfully, the user application will not gain control after invoking this API since a cold boot is performed. The results of the system update process will be kept in a specific text file on the persistent flash IPSM\SystemUpdate\UPOS_<UUID>.txt. The results of the last system update can be retreived by calling the UPOS_GetUpdateOsResult API to know if the system update process was successfully finished or failed.

Functions List Function Description

UPOS_GetVersion T/he UPOS_GetVersion function obtains information about the UPOS module version.

UPOS_UpdateOs The UPOS_UpdateOs function initiated SYSTEM_UPDATE process. Once launched – The SYSTEM_UPDATE service will update the HC700 system as required and then will reboot the HC700. If the system update process will initiated successfully, the user application will not gain control after invoking this API since a cold boot is performed. The results of the system update process will be kept in a specific text file on the persistent flash IPSM\SystemUpdate\UPOS_<UUID>.txt. The results of the last system update can be retreived by calling the UPOS_GetUpdateOsResult API to know if the system update process was successfully finished or failed.

UPOS_GetUpdateOsResult The UPOS_GetUpdateOsResult service obtains information about the last system update process result. The results of the last system update process will be kept in a specific text file on the persistent flash IPSM\SystemUpdate\UPOS_<UUID>.txt. The results of the last system update can be retreived by calling the UPOS_GetUpdateOsResult API to know if the system update process was successfully finished or failed.

• Examples

• Data Types Comments It is recommended that the user shut off all the processes running before launching this process to avoid unpredictable results. Note: The user, who calls UPOS APIs, must include uposcapi.h.

A typical usage of the UPOS_UpdateOs API includes: 1. Allocating the UPOS_UPDATEOS_INFO structure of data (See UPOS_UpdateOs Example), 2. Populating the STRUCT_INFO of the UPOS_UPDATEOS_INFO structure with valid data, 3. Populating the wFilesPathsAndNamesToFlash field of UPOS_UPDATEOS_INFO with the system package file name (full path), for ex. \Sorage Card\UpdateOsDir\Pack_R02_00_02.bin 4. Calling the function UPOS_UpdateOs to initiate the System update process,

Page 547: HC700 SDK Specification

Page 547 of 680

5. If the process successfully initiated, the System update process will start and the user application will not gain control since a cold boot is performed. 6. If any failure occurred, check the returned error code to know the exact reason of the failure. If the returned error code is E_UPOS_SYS_UPDATE_PROCESS_FAILURE, check the dwSystemUpdateProcessResultCode field of the UPOS_UPDATEOS_INFO or call the function UPOS_GetUpdateOsResult to retreive an extened description of the last error occured. 7. Releasing the pre-allocated memory. A typical usage of the UPOS_GetUpdateOsResult API includes: 1. Allocating the UPOS_UPDATEOSRESULT_INFO structure of data, 2. Populating the UPOD_STRUCT_INFO of the UPOS_UPDATEOSRESULT_INFO structure with valid data, 3. Calling the function UPOS_GetUpdateOsResult to get the last system update process result info, 4. If the function succeded, the UPOS_UPDATEOSRESULT_INFO will populated with the last OS update process results. 5. If any failure occurred, check the return error code to know the exact error code. 6. Releasing the pre-allocated memory.

Page 548: HC700 SDK Specification

Page 548 of 680

UPOS_GetVersion

Description T/he UPOS_GetVersion function obtains information about the UPOS module version.

Function Prototype

DWORD UPOS_GetVersion(

LPUPOS_VERSION_INFO lpVersionInfo);

Parameters

lpUposVersionInfo [in/out] Pointer to an UPOS_VERSION_INFO data structure that the function fills with UPOS version information.

Return Values E_UPOS_SUCCESS indicates success. Nonzero indicates failure: E_UPOS_NULLPTR E_UPOS_BADSTRUCTINFO Error Codes: Declared in uposerr.h.

Comments Before calling this function the user should allocate the UPOS_VERSION_INFO and set the STRUCT_INFO structure with valid data.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in UposCAPI.h. Import Library: Use UposAPI32.lib.

UPOS_GetVersion Example

Page 549: HC700 SDK Specification

Page 549 of 680

UPOS_UpdateOs

Description The UPOS_UpdateOs function initiated SYSTEM_UPDATE process. Once launched – The SYSTEM_UPDATE service will update the HC700 system as required and then will reboot the HC700. If the system update process will initiated successfully, the user application will not gain control after invoking this API since a cold boot is performed. The results of the system update process will be kept in a specific text file on the persistent flash IPSM\SystemUpdate\UPOS_<UUID>.txt. The results of the last system update can be retreived by calling the UPOS_GetUpdateOsResult API to know if the system update process was successfully finished or failed.

Function Prototype

DWORD UPOS_UpdateOs (

LPUPOS_UPDATEOS_INFO lpUposInfo);

Parameters

lpUposInfo [in/out] Pointer to an UPOS_UPDATEOS_INFO data structure that the user fills with the update OS information.

Return Values

Indication of success - No value will be returned in success since a cold boot will be performed. The system update process can fail at initial phases before the previous system image was removed. In this case the UPOS_UpdateOS API will return with a specific error code and the HC700 will remain with the old system image. Nonzero indicates failure of the function: E_UPOS_NULLPTR - Miss usage of the API E_UPOS_BADSTRUCTINFO - Miss usage of the API E_UPOS_EXIT_CODE_FUNC_FAILURE - The System update process failed to start E_UPOS_WAIT_FOR_SINGLE_O_FAILURE - The System update process failed to start E_UPOS_CANNOT_CREATE_PROCESS - The System update process failed to start E_UPOS_SYS_UPDATE_PROCESS_FAILURE - The System update process started but failed to Complete. In case of E_UPOS_SYS_UPDATE_PROCESS_FAILURE is returned the dwSystemUpdateProcessResultCode field in the UPOS_UPDATEOS_INFO structure should be tested to or call the UPOS_GetUpdateOsResult API to find out the exact reason of the system update process failure. In all these cases the system update process was not performed and the previous image still exists on the HC700. The possible errors are: E_UPOS_BATTERY_POWER_IS_TOO_LOW - Battery status is low E_UPOS_BATTERY_POWER_IS_UNKNOWN - Battery status unknown E_UPOS_POWER_STATUS_API_FAILURE - Battery status could not be read E_UPOS_BIN_FILE_NOT_FOUND - System file not found E_UPOS_BIN_FILE_READ_FAILURE - System file could not be read E_UPOS_INVALID_BIN_FILE - System file format is incorrect E_UPOS_BIN_FILE_CHECKSUM_ERROR - System file checksum error

Page 550: HC700 SDK Specification

Page 550 of 680

E_UPOS_ILLIGAL_STORAGE_LOCATION - System file should reside on a persistent Location (CF , MMC or IPSM) E_UPOS_RESERVED_MEM_TOO_SMALL - Not enough RAM for performing the system update Note: The above system update failures are not classified as critical errors since the system update procedure can be initated again after the error will be fixed. Error Codes: Declared in uposerr.h.

Comments Before calling this function the user should allocate the UPOS_UPDATEOS_INFO and set the STRUCT_INFO with valid data.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in UposCAPI.h. Import Library: Use UposAPI32.lib. See UPOS_UpdateOs Example

Page 551: HC700 SDK Specification

Page 551 of 680

UPOS_GetUpdateOsResult Description The UPOS_GetUpdateOsResult service obtains information about the last system update process result. The results of the last system update process will be kept in a specific text file on the persistent flash IPSM\SystemUpdate\UPOS_<UUID>.txt. The results of the last system update can be retreived by calling the UPOS_GetUpdateOsResult API to know if the system update process was successfully finished or failed.

Function Prototype

DWORD UPOS_GetUpdateOsResult (

LPUPOS_UPDATEOSRESULT_INFO lpUPOSResultInfo);

Parameters

lpUPOSResultInfo [in/out] Pointer to an UPOS_UPDATEOSRESULT_INFO data structure that the function fills with the last OS update result.

Return Values

E_UPOS_SUCCESS indicates success of the function. Nonzero indicates failure of the function: E_UPOS_NULLPTR - Miss usage of the API E_UPOS_BADSTRUCTINFO - Miss usage of the API E_UPOS_RESULT_FILE_NOT_FOUND - Result file was not found E_UPOS_RESULT_FILE_READ_FAILURE - Result file could not be read Note: In case of E_UPOS_SUCCESS is returned (i.e. success of the API) , the dwSystemUpdateProcessResultCode field in the UPOS_UPDATEOSRESULT_INFO structure should be tested to find out the result of the last system update procedure. The possible error codes in this structure are: E_UPOS_SUCCESS – The update process was comleted successfully. E_UPOS_INFO_SECTION_IS_NOT_VALID – System update internal error E_UPOS_BIN_FILE_NOT_FOUND - System file disappeared during the process E_UPOS_BIN_FILE_READ_FAILURE - System file could not be read E_UPOS_INVALID_BIN_FILE - System file incorrect format E_UPOS_BIN_FILE_CHECKSUM_ERROR - System file checksum error Note: The above system update failures are not classified as critical errors since the system update procedure can be initated again after the problem will be fixed. E_UPOS_BOOTLOADER_ERROR (Error codes: 0x001-0x100) – Indicates that the last system update procedure failed. These failure types are classified as critical errors since the system image on the HC700 is most likely to be corrupted at this stage. System update procedure mostly can not be initiated again and the terminal should be delivered to the DEPO for correcting the problem. It should be noted that this scenario is extremely rare and that in general the system update process is a very safe process. Error Codes: Declared in uposerr.h.

Page 552: HC700 SDK Specification

Page 552 of 680

Comments Before calling this function the user should allocate the UPOS_UPDATEOSRESULT_INFO and set the STRUCT_INFO with valid data.

QuickInfo Windows CE: Version 2.11 or later. Header: Declared in UposCAPI.h. Import Library: Use UposAPI32.lib. See UPOS_GetUpdateOsResult Example

Page 553: HC700 SDK Specification

Page 553 of 680

Examples The examples below demonstrate how to work with the UPOS APIs.

• UPOS_GetVersion Example

• UPOS_UpdateOs Example

• UPOS_GetUpdateOsResult Example

Page 554: HC700 SDK Specification

Page 554 of 680

UPOS_GetVersion Example // Variables definitions

DWORD dwRetVal;

WCHAR Msg[100];

UPOS_VERSION_INFO upos_ver_info;

// Initialize the Struct Info.

upos_ver_info.StructInfo.dwAllocated = sizeof(UPOS_VERSION_INFO);

upos_ver_info.StructInfo.dwUsed = sizeof(UPOS_VERSION_INFO);

// Invoke the service to get the UPOS version.

dwRetVal = UPOS_GetVersion(&upos_ver_info);

// Find out the major part of the version.

WORD MajorVer = (WORD)(upos_ver_info.dwCAPIVersion >> 16);

// Find out the minor part of the version.

WORD MinorVer = (WORD)(upos_ver_info.dwCAPIVersion & 0x0000FFFF);

// Build a message to the inform the user.

swprintf(Msg,TEXT(“%x,%x”), MajorVer, MinorVer);

// Inform the user about the UPOS version.

MessageBox(hDlg,Msg,TEXT("UPOS Version"),MB_OK);

Page 555: HC700 SDK Specification

Page 555 of 680

UPOS_UpdateOs Example // Variables definitions WCHAR Msg[500];

DWORD dwRetVal;

WCHAR SystemPackageFileName[MAX_PATH] = TEXT(“\\Storage Card\\UpdateOsDir\\Pack_R02_00_01.bin”);

POS_UPDATEOS_INFO UposInfo;

// Initialize the Struct Info. UposInfo.StructInfo.dwAllocated = sizeof(UPOS_UPDATEOS_INFO);

UposInfo.StructInfo.dwUsed = sizeof(UPOS_UPDATEOS_INFO);

// Initialize the system package file name and path. wcscpy(UposInfo.wFilesPathsAndNamesToFlash, SystemPackageFileName);

// Invoke the UPDATE_HC700_OS service. dwRetVal = UPOS_UpdateOS(&UposInfo);

// Check if the UPDATE_HC700_OS service fail. if (dwRetVal == E_UPOS_SYS_UPDATE_PROCESS_FAILURE) {

// UPDATE_HC700_OS process has started but failed so check what the exact reason. Switch ((UposInfo. dwSystemUpdateProcessResultCode) {

case E_UPOS_BIN_FILE_NOT_FOUND :

swprintf(Msg,E_UPOS_BIN_FILE_NOT_FOUND_STR);

break;

case E_UPOS_INVALID_BIN_FILE :

swprintf(Msg,E_UPOS_INVALID_BIN_FILE_STR);

break;

case E_UPOS_ILLIGAL_STORAGE_LOCATION :

swprintf(Msg,E_UPOS_ILLIGAL_STORAGE_LOCATION_STR);

break;

case E_UPOS_RESERVED_MEM_TOO_SMALL :

swprintf(Msg,E_UPOS_RESERVED_MEM_TOO_SMALL_STR);

break;

case E_UPOS_POWER_STATUS_API_FAILURE :

swprintf(Msg, E_UPOS_POWER_STATUS_API_FAILURE_STR);

break;

case E_UPOS_BATTERY_POWER_IS_TOO_LOW :

swprintf(Msg, E_UPOS_BATTERY_POWER_IS_TOO_LOW_STR);

break;

case E_UPOS_BATTERY_POWER_IS_UNKNOWN :

swprintf(Msg, E_UPOS_BATTERY_POWER_IS_UNKNOWN_STR);

break;

default :

swprintf(Msg,TEXT("Operation Failed - Error %x"),UposInfo. dwSystemUpdateProcessResultCode);

}

Page 556: HC700 SDK Specification

Page 556 of 680

// Show to the user the exact UPDATE_HC700_OS service failure. dwRetVal = MessageBox(hDlg,Msg,TEXT("Update OS"),MB_OK);

}

// UPDATE_HC700_OS process was not started so check what the exact reason. else {

switch (dwRetVal) {

case E_UPOS_BADSTRUCTINFO :

swprintf(Msg,E_UPOS_BADSTRUCTINFO_STR);

break;

case E_UPOS_NULLPTR :

swprintf(Msg,E_UPOS_NULLPTR_STR);

break;

case E_UPOS_EXIT_CODE_FUNC_FAILURE :

swprintf(Msg,E_UPOS_EXIT_CODE_FUNC_FAILURE_STR);

break;

case E_UPOS_WAIT_FOR_SINGLE_O_FAILURE :

swprintf(Msg,E_UPOS_WAIT_FOR_SINGLE_O_FAILURE_STR);

break;

case E_UPOS_CANNOT_CREATE_PROCESS :

swprintf(Msg,E_UPOS_CANNOT_CREATE_PROCESS_STR);

break;

default :

swprintf(Msg,TEXT("Operation Failed - Error %x"),dwRetVal);

}

// Inform the user about the reason why the UPDATE_HC700_OS service could not be initiated. dwRetVal = MessageBox(hDlg,Msg,TEXT("Update OS"),MB_OK);

}

Page 557: HC700 SDK Specification

Page 557 of 680

UPOS_GetUpdateOsResult Example // Variables definitions

DWORD dwRetVal;

UPOS_UPDATEOSRESULT_INFO UposResult;

// Initialize the Struct Info.

UposResult.StructInfo.dwAllocated = sizeof(UPOS_UPDATEOSRESULT_INFO);

UposResult.StructInfo.dwUsed = sizeof(UPOS_UPDATEOSRESULT_INFO);

// Invoke the service to get the last OS update result.

dwRetVal = UPOS_GetUpdateOsResult(&UposResult);

// If the service succeded to retrieve the last OS update result.

if (dwRetVal == E_UPOS_SUCCESS) {

WCHAR UposMsgStr[500];

// If the last OS update process succeded, build the following message.

if (UposResult.ResultInfo.dwSystemUpdateProcessResultCode == E_UPOS_SUCCESS) {

_stprintf(UposMsgStr,TEXT("%s\n\n%s%s\n\n%s%d\\%d\\%d %d:%d:%d"),

TEXT("System Update process\nFinished successfully"),

TEXT("File(s) Successfully Flashed: "), UposResult.ResultInfo.wSuccessfullyFlashedFiles,

TEXT("Last system update: "), UposResult.ResultInfo.stLastSystemUpdateTime.wDay,

UposResult.ResultInfo.stLastSystemUpdateTime.wMonth,

UposResult.ResultInfo.stLastSystemUpdateTime.wYear,

UposResult.ResultInfo.stLastSystemUpdateTime.wHour,

UposResult.ResultInfo.stLastSystemUpdateTime.wMinute,

UposResult.ResultInfo.stLastSystemUpdateTime.wSecond);

// Show the last OS update process result.

dwRetVal = MessageBox(hDlg, UposMsgStr, TEXT("System Update Result"), MB_OK);

}

// If the last OS update process failed, build the following message.

else {

_stprintf(UposMsgStr,TEXT("%s\n\n%s%x\n%s%s\n\n%s%s\n\n%s%d\\%d\\%d %d:%d:%d"),

TEXT("System Update process\nFailed"),

TEXT("Error Code: "), UposResult.ResultInfo.dwSystemUpdateProcessResultCode,

TEXT("Error Description: "), UposResult.ResultInfo.wSystemUpdateProcessResultDescription,

TEXT("File(s) Not Flashed: "), UposResult.ResultInfo.wNotFlashedFiles,

Page 558: HC700 SDK Specification

Page 558 of 680

TEXT("Last system update: "), UposResult.ResultInfo.stLastSystemUpdateTime.wDay,

UposResult.ResultInfo.stLastSystemUpdateTime.wMonth,

UposResult.ResultInfo.stLastSystemUpdateTime.wYear,

UposResult.ResultInfo.stLastSystemUpdateTime.wHour,

UposResult.ResultInfo.stLastSystemUpdateTime.wMinute,

UposResult.ResultInfo.stLastSystemUpdateTime.wSecond);

// Show the last OS update process result.

dwRetVal = MessageBox(hDlg, UposMsgStr,TEXT("System Update Result "),MB_OK);

}

}

// If the service failed to retrieve the last OS update result.

else {

TCHAR Msg[500];

// Find out the exact reason why the service could not retreive the result.

switch(dwRetVal) {

case E_UPOS_NULLPTR:

swprintf(Msg,E_UPOS_NULLPTR_STR);

break;

case E_UPOS_BADSTRUCTINFO:

swprintf(Msg,E_UPOS_BADSTRUCTINFO_STR);

break;

case E_UPOS_RESULT_FILE_NOT_FOUND:

swprintf(Msg,E_UPOS_RESULT_FILE_NOT_FOUND_STR);

break;

case E_UPOS_RESULT_FILE_READ_FAILURE:

swprintf(Msg,E_UPOS_RESULT_FILE_READ_FAILURE_STR);

break;

default:

swprintf(Msg,TEXT("Operation Failed - Error %x"),dwRetVal);

break;

}

// Show the reason why the service failed to rereive the last UPOS result.

dwRetVal = MessageBox(hDlg,Msg,TEXT("System Update Result"),MB_OK);

}

Page 559: HC700 SDK Specification

Page 559 of 680

Data Types • UPOS_VERSION_INFO

• UPOS_UPDATEOS_INFO

• UPOS_UPDATEOSRESULT_INFO

• STRUCT_INFO

Page 560: HC700 SDK Specification

Page 560 of 680

UPOS_VERSION_INFO // UPOS Module SW Version information structure

typedef struct tagUPOS_VERSION_INFO{

[in] STRUCT_INFO StructInfo;

[out] DWORD dwCAPIVersion;

} UPOS_VERSION_INFO, FAR * LPUPOS_VERSION_INFO;

UPOS_UPDATEOS_INFO // Update OS information structure

#define MAX_FILE_NAME_LEN (MAX_PATH-2)

#define MAX_FILES_TO_PROGRAM (4)

#define MAX_FILE_NAMES_TO_PROGRAM_LEN (MAX_PATH*MAX_FILES_TO_PROGRAM)

typedef struct tagUPOS_UPDATEOS_INFO{

[in] STRUCT_INFO StructInfo;

[in] WCHAR wFilesPathsAndNamesToFlash [MAX_FILE_NAMES_TO_PROGRAM_LEN];

[out] DWORD dwSystemUpdateProcessResultCode;

} UPOS_UPDATEOS_INFO, FAR * LPUPOS_UPDATEOS_INFO;

UPOS_UPDATEOSRESULT_INFO // UPOS result definitions

#define MAX_FILES_TO_PROGRAM 4

#define MAX_UPOS_ERROR_STR_LEN 256

#define MAX_FILE_NAME_LEN (MAX_PATH-2)

#define MAX_FILE_NAMES_TO_PROGRAM_LEN (MAX_PATH*MAX_FILES_TO_PROGRAM)

#define MAX_RESULT_DESCRIPTION_STR_LEN (MAX_UPOS_ERROR_STR_LEN+MAX_PATH+3)

// UPOS phase failed enumarator

typedef enum tagUPOS_FAILD_PHASE{

NO_PHASE_FAILED = 0,

FAILED_PHASE_1 = 1,

FAILED_PHASE_2 = 2,

FAILED_PHASE_3 = 3,

FAILED_PHASE_4 = 4,

FAILED_PHASE_5 = 5

}FAILD_PHASE;

Page 561: HC700 SDK Specification

Page 561 of 680

// UPOS result details structure

typedef struct tagUPOS_UPDATEOSRESULT_DETAIL{

[out] DWORD dwSystemUpdateProcessResultCode;

[out] WCHAR wSystemUpdateProcessResultDescription [MAX_RESULT_DESCRIPTION_STR_LEN];

[out] SYSTEMTIME stLastSystemUpdateTime;

[out] FAILD_PHASE dwFailedPhase;

[out] WCHAR wSuccessfullyFlashedFiles[MAX_FILE_NAMES_TO_PROGRAM_LEN];

[out] WCHAR wNotFlashedFiles[MAX_FILE_NAMES_TO_PROGRAM_LEN];

} UPOS_UPDATEOSRESULT, FAR * LPUPOS_UPDATEOSRESULT;

// Last System Update result information structure

typedef struct tagUPOS_UPDATEOSRESULT_INFO{

[in] STRUCT_INFO StructInfo;

[out] UPOS_UPDATEOSRESULT ResultInfo;

} UPOS_UPDATEOSRESULT_INFO, FAR * LPUPOS_UPDATEOSRESULT_INFO;

Page 562: HC700 SDK Specification

Page 562 of 680

STRUCT_INFO Description The STRUCT_INFO structure enables extensibility of API structures. A STRUCT_INFO structure is embedded in each structure of the API to describe the memory allocated and used by that structure. If the structure grows in future revisions of the API, the STRUCT_INFO information can be used to determine which fields are valid for use.

Structure Definition typedef struct tagSTRUCT_INFO { DWORD dwAllocated; DWORD dwUsed;

} STRUCT_INFO;

Members dwAllocated

Size of the allocated structure, in bytes. dwUsed

Amount of memory the structure actually uses, in bytes.

Remarks The STRUCT_INFO structure is designed to allow interoperability between components based on different revisions of an API. In order to accomplish this, all components must use the STRUCT_INFO structure in a standard way. When a structure is allocated in memory, the dwAllocated field should be set to the amount of memory allocated, and the dwUsed field should be set to zero. When filling in fields of a structure, do not add a field whose extent (offset plus size) is larger than dwAllocated and, after adding the field, update dwUsed to be equal to the extent of the field (unless it is already larger). When reading fields from a structure, the field is invalid if dwUsed is less than the extent of the field. A structure is invalid if dwAllocated is less than the size of STRUCT_INFO or dwUsed is greater than dwAllocated.

Several macros have been defined to make use of the STRUCT_INFO structure easier:

SI_FIELD_OFFSET(ptr,fld) – Returns the offset of field fld in the structure pointed to by ptr.

SI_FIELD_SIZE(ptr,fld) – Returns the size of field fld in the structure pointed to by ptr.

SI_FIELD_EXTENT(ptr,fld) – Returns the extent of field fld in the structure pointed to by ptr.

SI_FIELD_VALID(ptr,fld) – Returns flag describing validity (contains data) of field fld in the structure pointed to by ptr.

SI_FIELD_EXISTS(ptr,fld) – Returns flag describing existence (field allocated) of field fld in the structure pointed to by ptr.

SI_ALLOC_ALL(ptr) – Sets the dwAllocated field of the structure pointed to by ptr to the size of the structure.

SI_GET_POINTER(ptr,fld,type) – Returns a pointer of type type to field fld in the structure pointed to by ptr.

SI_SET_USED(ptr,fld) – Sets the dwUsed field of the structure pointed to by ptr to the extent of field fld.

SI_SET_FIELD(ptr,fld,src) – Sets the value of field fld in the structure pointed to by ptr to value src if the field exists.

SI_GET_FIELD(ptr,fld,dst) – Sets the value of dst to the value of field fld in the structure pointed to by ptr if the field is valid.

Page 563: HC700 SDK Specification

Page 563 of 680

SI_SET_IF_CHANGED(ptr,fld,src) – Sets the value of field fld in the structure pointed to by ptr to value src if the field exists and src is not equal to PARAMETER_NO_CHANGE ( = 0xFFFFFFFF ).

SI_SET_STRING(ptr,fld,src) – Sets the value of string field fld in the structure pointed to by ptr to string value src if the field exists.

SI_GET_STRING(ptr,fld,dst) – Sets the string value of dst to the value of string field fld in the structure pointed to by ptr if the field is valid.

Page 564: HC700 SDK Specification

Page 564 of 680

18. HC700 - System Update Usage Scenario

SYSTEM UPDATE – POLICY

System update refers to moving from one HC700 version of the WinCE 4.2 to another HC700 version WINCE 4.2. It does not refer to moving from a WINCE 4.2 to any another Pocket PC/WinCE OS versions/editions. System update will be needed in one of the following scenarios:

1. Microsoft has introduced some bug fixes (QFEs) or some new features.

• Bug fixes for existing products will be deployed by Microsoft to OEMs (Motorola) for release from the OEM support channel.

• The format in which bug fixes for end users will be cumulative, released in a bin file

format.

• Microsoft requires that the QFE will be delivered to the End User by Motorola.

• Motorola will first test the QFE on the HC700 and only then will distribute the QFE to Customer (using the System update process)

2. Motorola have introduced some bug fixes (QFEs) or some new features.

• Motorola will build a new system image and test it on the HC700.

• Motorola will distribute the new system to Customer (using the system update process)

Page 565: HC700 SDK Specification

Page 565 of 680

System Update – Process

Customer HOST

Cradle

Cradle

• •

Cradle n

HC700

• • •

USB 12 Mbits/Sec

HC700

HC700

Ethernet 100 Mbits/Sec

Page 566: HC700 SDK Specification

Page 566 of 680

Automatic System Update: • When a need for a system update occurs and Customer and Motorola agree to perform an HC700 system

update, Motorola will prepare a HC700 System Package. • The Package content depends on the change type. The package will include OS image and/or boot loader

and/or PIC in a form of one binary file and a release notes document that will describe the changes. • System package file name format is: Pack_Rxx.xx.xx_WithoutG20.bin • Motorola will deliver the HC700 system Package to customer

(Via the Motorola FTP site) • The automatic system update can be performed in one of two ways: Either by manually (ActiveSync) when the customer will dowload the package into HC700 device on IPSM or temproray folder (it should be enough place to copy) and double click will run the UPOS application which programms the package. Or by the built-in Motorola loader that transfers the system package to the HC700 by using a TFTP protocol and updates the system by using the built-in Update OS utility.

Page 567: HC700 SDK Specification

Page 567 of 680

18.1.1 Automatic System Update – using the Motorola Loader: • This automatic system update will take place at a DEPO or at customer station. • In the DEPO or the customer station a TFTP server is installed on a host computer. • Customer or Motorola will put the system package on the TFTP server. • On this TFTP server a configuration file will also be put (see appendix A for a demo configuration file) .The

configuration file instructs Motorola Loader to download the system package from a specific location on the TFTP server to the IPSM\UpdateOsDir directory on the HC700.

• Motorola Loader will start to run at HC700 startup waiting for the HC700 to be docked into the CRADLE. • Once the HC700 is docked into the CRADLE, Motorola Loader will download the configuration file and the

system package to the HC700 and immediately will launch the UpdateOsUtil utility which uses the UPDATE_HC700_OS service that will update the HC700 system as required and then will boot the HC700. If the system update process succeeds the UpdateOsUtil application will not gain control anymore since a cold boot is performed.

The system update process results will be kept in a specific text file on the persistent flash IPSM\SystemUpdate\UPOS_<UUID>.txt.

This file can be read by the user to verify the results and also can be transmitted to the customer HOST as an acknowledgment of the system update process completion. Each HC700 device has it’s own unique result file with a unique file name that includes the HC700 UUID, so that it can be identified on a customer HOST computer. The results of the system update process (success or failure) will be shown on the Handheld Terminal screen immediately after a boot is performed in order to verify that the System Image update process has finished successfully. Errors that can occur during the system update second phase and not considered as a critical errors – meaning that the HC700 will not need to be sent to the DEPO for re-flashing, according to the specific error – a corrective action will be taken and then the system update process can be started again for the same HC700. In the event of a critical failure to update the system image where the old system image does not exist any more and the new one was not flashed yet, the HC700 will not boot properly. In this case the HC700 should be taken to a DEPO for flashing the system image by using factory tools. It should be noted that this scenario is extremely rare and that in general the system update process is a very safe process.

18.1.2 Manual System Update:

• A manual system update process is also supported by putting the HC700 system package file on the FLASH-FS and then invoking the UpdateOsUtil application that resides on the \windows directory. You can start this utility by either going to the \Windows directory and searching for the UpdateOsUtil or by browsing the persistence FS and tapping on the system package file name.

• The System-Update Utility will open a dialog box:

Page 568: HC700 SDK Specification

Page 568 of 680

• Choose the HC700 system package file which resides on the FLASH-FS (i.e. HC700_R02.00.02.bin) .

Page 569: HC700 SDK Specification

Page 569 of 680

• Press the “Program To Flash” button in order to start the programming process of the System Image.

• A confirmation box will appear:

• Press OK to continue.

• A sand glass will appear on the screen for a couple of seconds.

• Once invoked – The UPDATE_HC700_OS service will update the HC700 system as required and then will boot the HC700. If the system update process succeeds the UpdateOsUtil application will not gain control anymore since a cold boot is performed.

• You will notice the progress of the Update System process by viewing couple of screens one after the

other on the HC700 display.

Page 570: HC700 SDK Specification

Page 570 of 680

• The results of the system update process will be kept in a specific text file on the FLASH-FS IPSM\SystemUpdate\UPOS_<UUID>.txt.

• The results of the system update process (success or failure) will be shown on the HC700 screen

immediately after a boot is performed in order to verify that the System Image update process has finished successfully.

• In addition, launch again the Update OS Utility from the \Windows directory that will display the last

System Image update results on the screen. (Detail description of result codes exists in section: Update OS Service (UPOS) API of the SDK API document)

• Press the “Viewing Programming Result” button.

• A dialog with the result information will be displayed on the screen:

Page 571: HC700 SDK Specification

Page 571 of 680

Demo configuration file for automatic System Update using the Motorola loader:

; =================================================== ; This is a sample of a HC700 configuration file : HC700_MULTI_CFG ; for system update ;=================================================== ;---------------------------------- ; Configuration file version ;------------------------------------- [VERSION] 1.0 ;--------------------------------------------------------- ; Default Configuration for all the HC700s ;-------------------------------------------------------- [CONFIGURATION] DEFAULT ;========================================================== ; Check the existence of the following files before deciding to download. ; Download is performed only if the files do not exist on the HC700 ;========================================================== [CHECK] FILE "\IPSM\UpdateOsDir\HC700_R02.00.02.bin" ;============================================================= ; HC700 directory - destination for the downloaded files ;============================================================= [DEVICE_DOWNLOAD_DIRECTORY] DIR "\IPSM\UpdateOsDir" ;===================================== ; list of files to download from Server ;===================================== [DOWNLOAD] FILE = HC700_R02.00.02.bin ;============================================================== ; list of files to open on the terminal after download is finished (used for installation) ;=============================================================== [OPEN]

Page 572: HC700 SDK Specification

Page 572 of 680

FILE windows\updateos.exe "\IPSM\UpdateOsDir\ HC700_R02.00.02.bin" ;=============================================== ; TRUE/FALSE - Is warm boot needed after opening ; (only in case of downloading) ;=============================================== [REBOOT] FALSE ;=================================================== ; list of files to RUN after the OPEN operation ;=================================================== [RUN] ;------------------------------------------ ;End of default configuration

Page 573: HC700 SDK Specification

Page 573 of 680

19. Application Loader

Overview

• Motorola Application Loader may be used to download OS Images and application updates.

• Application Loader runs automatically at terminal startup, and connects to TFTP Server upon cradle insertion.

• If 3rd party application wishes to trigger Motorola loader’s download process, then ForceApplicationDownload API should be called. It will cause the Motorola Loader to redownload the CFG file and all needed files from the TFTP Server.

Functions List Function Description

ForceApplicationDownload The ForceApplicationDownload function forces download of 3rd party Loader Application. If the terminal is not docked into CRADLE while calling this function, the download will be performed next time the device will be docked to CRADLE. If the terminal is docked into CRADLE while calling this function, it will cause immediate start of downloading procedure.

EnableLoader The EnableLoader function enables or disables Application Loader.

Page 574: HC700 SDK Specification

Page 574 of 680

Page 575: HC700 SDK Specification

Page 575 of 680

ForceApplicationDownload

Description The ForceApplicationDownload function forces download of 3rd party Loader Application. If the terminal is not docked into CRADLE while calling this function, the download will be performed next time the device will be docked to CRADLE. If the terminal is docked into CRADLE while calling this function, it will cause immediate start of downloading procedure.

Function Prototype BOOL WINAPI ForceApplicationDownload ();

Parameters None.

Return Values

If the function succeeds, the return value is TRUE.

Comments None.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in AppLoaderAPI32.h. Import Library: Use AppLoaderAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 576: HC700 SDK Specification

Page 576 of 680

EnableLoader

Description The EnableLoader function enables or disables Application Loader.

Function Prototype BOOL WINAPI EnableLoader (BOOL bEnable);

Parameters bEnable [in] Set TRUE for enabling the Loader, FALSE for disabling the Loader

Return Values

If the function succeeds, the return value is TRUE.

Comments

None.

QuickInfo

Windows CE: Version 2.11 or later. Header: Declared in AppLoaderAPI32.h. Import Library: Use AppLoaderAPI32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 577: HC700 SDK Specification

Page 577 of 680

20. Application Loader Usage Scenario

Application Update Process

Customer Host Computer

Cradle

Cradle

• •

Cradle n

HC700

• • • USB

12 Mbits/Sec

HC700

HC700

Ethernet 100 Mbits/Sec

Page 578: HC700 SDK Specification

Page 578 of 680

Overview: • This document will describe the scenarios of installing and updating the application on the

HC700.

• Three HC700 applications and two PC applications (running on the Host system) are involved:

HOST HC700

TFTP Protocol Application Protocol

TFTP Server application

Motorola Loader (TFTP client)

Customer HOST Loader application/ SMS server

HC700 Loader/SMS Client

HC700 main application

Page 579: HC700 SDK Specification

Page 579 of 680

Applications on the HC700

o The main application: Developed by the customer. Is not installed on the HC700 in the factory. Needs to be installed on the HC700 as soon as the HC700 arrives from factory. Needs to be updated occasionally. Should be launched on HC700 startup.

o Motorola Loader Application: Developed by Motorola as a TFTP client. Functionality: First time downloading, installing and launching of the Customer

Application Loader and/or the main application. While in CRADLE communicates with a TFTP server application for performing this

functionality. Is part of the HC700 system image. Is launched on HC700 startup and wait for the HC700 to be docked inside the CRADLE

to begin the potential download activities.

Page 580: HC700 SDK Specification

Page 580 of 680

Configuration File Sample • Here is a configuration file sample for downloading applications and/or OS packages from

the Host to the HC700.

• This file should be prepared by customer and put on the TFTP server (i.e. Host) on a directory specified in the TFTP Server settings.

; =================================== ; This is a sample of a HC700 configuration file ;=================================== ;---------------------------------- ; Configuration file version ;------------------------------------- [VERSION] 1.0 ;--------------------------------------------------------- ; Default Configuration for all the Terminals ;-------------------------------------------------------- [CONFIGURATION] DEFAULT ;========================================================== ; Check the existence of the following files before deciding to download. ; Download is performed only if the files do not exist on the HC700 ;========================================================== [CHECK] FILE =”IPSM\startup\ CustomerApplication.exe” ;=============================================== ; HC700 directory - destination for the downloaded files ;============================================== [DEVICE_DOWNLOAD_DIRECTORY] DIR “IPSM\startup” ;===================================== ; list of files to download from Server ;===================================== [DOWNLOAD] FILE CustomerApplication.CAB ;============================================================== ; list of files to open on the terminal after download is finished (used for installation) ;===============================================================

Page 581: HC700 SDK Specification

Page 581 of 680

[OPEN] ; First install FILE “IPSM\startup\ CustomerApplication.CAB” ; Then – run the appliocation – will run only once, after the installation FILE =”IPSM\startup\ CustomerApplication.exe” Param1 Param2 …… ;=============================================== ; TRUE/FALSE - Is warm boot needed after opening ; (only in case of downloading) ;=============================================== [REBOOT] FALSE ;============================================================== ; list of files to RUN (executed in any case – regardless of download being performed or not ;============================================================== [RUN] ;------------------------------------------ ;End of default configuration ;-------------------------------------------

Alternate Scenarios

20.1.1 Initial Downloading of the Application - Failed

20.1.1.1 Initial Downloading of the Application – Failed - Possible Causes:

• HC700 extraction from CRADLE during download:

o Motorola Loader will detect the out of dock event. o Download session will be aborted. o Not fully downloaded files will be removed from the HC700. o A notification error will be displayed on the HC700. o Next time the HC700 will be inserted in the CRADLE the application will

be re-downloaded.

• CRADLE goes into power off and power on during download as a result of

manually powering the CRADLE off and on or as a result of a temporary power lost situation:

o Motorola Loader will detect this as an out of dock event. o Download session will be aborted.

Page 582: HC700 SDK Specification

Page 582 of 680

o Not fully downloaded files will be removed from the HC700. o A notification error will be displayed on the HC700. o After the CRADLE will resume or next time the HC700 will be inserted in

the CRADLE the application will be re-downloaded.

• CRADLE reset during download:

o Motorola Loader will not detect this as an out of dock event. o Communication failure will be acknowledged by the HC700. o A couple of retries will be initiated by the HC700. o Eventually the USB connection is lost. o Download session will be aborted. o Not fully downloaded files will be removed from the HC700. o A notification error will be displayed on the HC700. o After the CRADLE will resume or next time the HC700 will be inserted in

the CRADLE the application will be re-downloaded.

Page 583: HC700 SDK Specification

Page 583 of 680

• HC700 reset during download:

o TFTP server should detect that the session was aborted. (Depends on the

behavior a the specific TFTP server) o After startup, Motorola Loader will run again and detect the situation as an

in dock event. o Motorola Loader will verify that a download session was not completed. o Not fully downloaded files will be removed from the HC700. o The application will be re-downloaded.

• Communication failure: • TFTP server failure:

o Download session will be terminated by Motorola Loader. o Not fully downloaded files will be removed from the HC700. o A notification error will be displayed on the HC700 for 1 minute. o Attempts to re-download the Application will continue as long as the

HC700 is docked inside the CRADLE.

• IPSM full (no room for downloaded files)

o Download session will be terminated by Motorola Loader. o Not fully downloaded files will be removed from the HC700. o A notification error will be displayed on the HC700. o The HC700 user will extract the HC700 from CRADLE and correct the ‘no

room’ situation on the IPSM card. o Next time the HC700 will be inserted in the CRADLE the application will

be re-downloaded.

• Configuration File Errors: (i.e. Configuration file not found on the TFTP server, Configuration file format errors, etc…)

o Download session will be terminated (or even not started) by Motorola

Loader. o A notification error will be displayed on the HC700. o The HC700 user will extract the HC700 from CRADLE and correct the

‘Configuration File Error’ situation. o Next time the HC700 will be inserted in the CRADLE the application will

be re-downloaded.

Page 584: HC700 SDK Specification

Page 584 of 680

Configuration File Format ;============================= ;HC700_MULTI_CFG file ;============================= ;=================================== ; Configuration file version ;=================================== [VERSION] 1.0 ;========================================================== ; This Configuration is for all the HC700s or for serial ; numbers only ;========================================================== [CONFIGURATION] SN = 296RRR1146 SN = 296SBYuu8 SN = 296SBY11od SN = 296SBY1145 SN = 296SBY1146 SN = 296SBY1147 [CHECK] ;========================================================== ; List of mandatory files that need to be checked on the ; HC700 before deciding to start downloading: ; Check the existence of the following files before ; deciding to download: ; If all the files listed here exist on the HC700 – download ; will not be performed. ; If at least one of the files listed here does not exist ; on the HC700 - Download will be performed . ; If no files are listed here then the download will not be ; performed. ;========================================================== FILE = “IPSM\download\App.exe” FILE = ”IPSM\download\App.dll” [DEVICE_DOWNLOAD_DIRECTORY] ;==================================================== ; Defauld directory on the HC700 for downloaded files ;=================================================== DIR “IPSM\download” [DOWNLOAD] ;======================================================== ; List of files to download from Server(should be located ; on the TFTP server default directory) ;======================================================== FILE App.CAB

Page 585: HC700 SDK Specification

Page 585 of 680

[OPEN] ;========================================================== ; list of files to open on the terminal ; used for installation purposes ; (is performed only after downloading occurred ) ;When using FILE or FILEB(File blocked) keywords - no other file from the OPEN list ; will be opened until this file will complete the OPEN operation. ; When using FILENB(File Non blocked) keyword – other filesfrom the OPEN list can ; be opened without waiting for this file to complete the Open operation. ;========================================================== FILE “IPSM\download\App.CAB” FILEB “IPSM\download\App.CAB” FILENB “IPSM\download\App.CAB” [REBOOT] ;=============================================== ; TRUE/FALSE - Is warm boot needed after opening ; (is performed only in case of downloading) ;=============================================== FALSE ;TRUE

Page 586: HC700 SDK Specification

Page 586 of 680

[RUN] ;========================================================== ; list of files to execute before exiting to Windows CE. ; is always performed regardless of downloading execution. ;When using FILE or FILENB(File Non blocked) keywords – other files from the RUN ; list can be run without waiting for this file to complete the Run operation. ; When using FILEB (File blocked) keyword – no other file from the ; RUN list will be run until this file will complete the run operation. ;========================================================== FILE windows\BarcodeScan.exe FILENB windows\BarcodeScan.exe FILEB windows\BarcodeScan.exe ;========================================================== ;End of configuration for specific Serial Numbers ;========================================================== ;========================================================== ; Default Configuration (for all the HC700s that are not ; included in the previous list of Serial Numbers) ;========================================================== [CONFIGURATION] DEFAULT [CHECK] ;========================================================== ; List of mandatory files that need to be checked on the ; HC700 before deciding to start downloading: ; Check the existence of the following files before ; deciding to download: ; If all the files listed here exist on the HC700 – download ; will not be performed. ; If at least one of the files listed here does not exist ; on the HC700 - Download will be performed . ; If no files are listed here then the download will not be ; performed. ;========================================================== FILE = “IPSM\download\App.exe” FILE = ”IPSM\download\App.dll”

Page 587: HC700 SDK Specification

Page 587 of 680

[DEVICE_DOWNLOAD_DIRECTORY] ;=============================================== ; directory on the terminal for downloaded files ;=============================================== DIR “IPSM\download” [DOWNLOAD] ;=============================================== ; list of files to download from Server ;=============================================== FILE App.CAB [OPEN] ;========================================================= ; list of files to open on the terminal ; used for installation purposes ; (is performed only after downloading occurred ) ;When using FILE or FILEB(File blocked) keywords - no other file from the OPEN list ; will be opened until this file will complete the OPEN operation. ; When using FILENB(File Non blocked) keyword – other filesfrom the OPEN list can ; be opened without waiting for this file to complete the Open operation. ;========================================================== FILE “IPSM\download\App.CAB” FILEB “IPSM\download\App.CAB” FILENB “IPSM\download\App.CAB” [REBOOT] ;=============================================== ; TRUE/FALSE - Is warm boot needed after opening ; (only in case of downloading) ;=============================================== FALSE ;TRUE

Page 588: HC700 SDK Specification

Page 588 of 680

[RUN] ;========================================================== ; list of files to execute before exiting to Windows CE. ; is always performed regardless of downloading execution. ;When using FILE or FILENB(File Non blocked) keywords – other files from the RUN ; list can be run without waiting for this file to complete the Run operation. ; When using FILEB (File blocked) keyword – no other file from the ; RUN list will be run until this file will complete the run operation. ;========================================================== FILE windows\BarcodeScan.exe FILENB windows\BarcodeScan.exe FILEB windows\BarcodeScan.exe ;========================================================== ;End of default configuration ;==========================================================

Page 589: HC700 SDK Specification

Page 589 of 680

Loader Execution Sequence

1. When the HC700 is powered ON, the registry is checked for Terminal Loader program Enable \ Disable status. If the status is: disabled – the Terminal Loader immediately exits.

2. Upon insertion of the HC700 into the CRADLE, the conditional download mechanism enables the user to start downloading the configuration file unconditionally from the TFTP server, or let the program look for an existing configuration file in the terminal.

3. If conditional download starts, the program searches for the HC700_MULTI_CFG.txt configuration file inside the terminal. If the configuration file is found, the program continues as described in the following section. Otherwise, if the configuration file is not found, the program will establish a connection with the server and download configuration file from the TFTP server.

4. The program uses the [CONFIGURATION] section, in the configuration file, to associate the suitable configuration with a specific serial number(s) of terminal(s). If the terminal number does not exist in this section, the program may process a default configuration or exit (The default configuration section is optional).

5. The Terminal Loader performs the [CHECK] section, in the configuration file, to assure the system integrity, by confirming that all files exist in the terminal, as detailed in the configuration file in the [CHECK] section.

6. If the configuration file and all components (files) are found, the program performs the [RUN] section, as detailed in the configuration file. If all or some of the file(s) listed in the [CHECK] section are missing, the program will download the files listed in the [DOWNLOAD] section from the TFTP server, then will open the files listed in the [OPEN] section and reboot the terminal (optional according to the [REBOOT] section).

The following flow-chart describes the Terminal Loader program operation:

Page 590: HC700 SDK Specification

Page 590 of 680

No Yes

[OPEN] Section Execute files in order specified in configuration file

[REBOOT] Section Should the terminal reboot?

(True/Faulse as specified in the configuration file)

Terminal Power onTerminal Loader starts

[CHECK] SectionDoes all files exist in terminal

, as detailed in this section?

[DOWNLOAD] Section download files from TFTP server

Yes

False [RUN] Section

True Exit

DOWNLOAD Establish connection and download configuration file from TFTP server

Configuration file sequence

Warm Boot

Found

Not Found Look for configuration file in the terminal

No

Check if terminal keys: Left Tab & Page-Up are pressed

Establish connection with TFTP server

Is Terminal Loader enabled

Yes

Exit

Not Pressed (Conditional download) Pressed

(Unconditional download)

No

[CONFIGURATION] Section Is terminal serial number included in

this section?

Exit

Is serial number found

in other sub configurations or in default configuration

Yes

No

Page 591: HC700 SDK Specification

Page 591 of 680

21. Cradle Interface Overview

HC700 device utilizes cradle for communicating with network infrastructure – both Ethernet and dial-up based.

The following diagram shows communication relations between HC700 and Cradle:

HC700 device communicates with cradle over USB interface. HC700 creates RAS link connection automatically upon insertion into cradle. Cradle interface component opens TCP/IP communication channel for control messages transfer between HC700 and Cradle. Cradle Interface This module is responsible for communicates with cradle and exposes higher level API/events to application about cradle/communication status. Cradle Interface creates Winsock channel over predefined TCP/IP port and provides cradle LED control and other relevant cradle notifications.Cradle Daemon is loaded as service and receives notification of RAS connect disconnect event as well as different dock in/out events.

Application registeres to Cradle Interface to receive all communication states notifications – both for intermediate RAS communication and for communication external to cradle : modem and ethernet API DLL This DLL allows high level application easy access to notification from cradle interface and cradle configuration queries. The Cradle API provides interface for communication with a cradle. The following requests are supported:

USB HOST CTRL USB Client CTRL

Cradle HC700

RAS Server RAS Client

TCP/IP TCP/IP

Winsock Winsock

Generic Server Generic Service

Page 592: HC700 SDK Specification

Page 592 of 680

Functions List

Function Description CRADLE_Register This function provides the application ability to get notifications

about the Terminal connection with the Cradle. Meaning this function registers the application window handle to receive an application-defined message when connection status is changed. The current connection status is indicated in wParam of the registered message. Notification event is sent only if actual connection status has changed , e.g. after inserting terminal into the cradle.

CRADLE_Unregister This function unregisters the application window from receiving notifications of the Terminal connection with the Cradle.

CRADLE_GetStatus This function is called to get the current status of the Terminal connection with the Cradle.

CRADLE_GetInfo This function is called to get information about the Cradle that the Terminal is inserted to.

CRADLE_SetInfo This function is called to set cradle specific information. CRADLE_GetTerminalInfo This function is called to get the Terminal information related to a

Cradle that the Terminal is inserted to. CRADLE_GetIPAddresses This function is called to get private and public IP addresses of

the Cradle and all docked Terminals. CRADLE_Dial This function is called to request the Cradle to establish a modem

dial up connection. CRADLE_Dial call operates asynchronously. CRADLE_HangUp This function is called to request the Cradle to terminate a

modem dial up connection. CRADLE_SetTimeout This function is called to set the Cradle API timeout. Meaning the

Cradle API call except CRADLE_Dial call will be blocked maximum for the specified timeout period. Default timeout value is 500 ms.

CRADLE_GetTimeout This function is called to get the Cradle API timeout. Meaning the Cradle API call except CRADLE_Dial call will be blocked maximum for the specified timeout period. Default timeout value is 500 ms.

CRADLE_UpdateFirmware This function is called to update the Cradle firmware. CRADLE_Led This function is called to test the Cradle LEDs or indicate an error

by the Cradle LEDs. CRADLE_StoreFile This function is called to store the file in the Cradle. CRADLE_GetFile This function is called to get a file, which is stored in the Cradle

and save it in the local file path name. CRADLE_SetBroadcastListenerPort This function is called to set the Communication Cradle broadcast

listener port number. CRADLE_GetLastUpdateResult This function is called to get last update cradle firmware result.

Comments All Cradle API calls except CRADLE_Dial() are blocked operations that can last maximum for the specified timeout period. Cradle timeout default value is 500 ms. It can be override by the CRADLE_SetTimeout() API. Data Types Error Codes Examples

Page 593: HC700 SDK Specification

Page 593 of 680

CRADLE_Register

Description This function provides the application ability to get notifications about the Terminal connection with the Cradle. Meaning this function registers the application window handle to receive an application-defined message when connection status is changed. The current connection status is indicated in wParam of the registered message. Notification event is sent only if actual connection status has changed , e.g. after inserting terminal into the cradle.

Function Prototype DWORD CRADLE_Register (HWND hWnd, UINT iMsg)

Parameters

hWnd [in] The handle to an application window that will receive a message (iMsg) when connection status is changed.

iMsg [in] An application defined message that should be sent when connection status is changed.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_INVALID_PARAMETER, E_CRADLE_FAILURE indicate failure. Error Codes: Declared in CradleErr.h.

Comments Type of the wParam is CRADLE_NOTIFICATION. lParam of the message depends on the wParam value.

wParam value lParam value CRADLE_NET_CONNECTED Not used

CRADLE_NET_DISCONNECTED Not used CRADLE_NET_CONNECTION_FAILED Not used

CRADLE_MODEM_PORT_OPENED Not used CRADLE_MODEM_SPEED Modem speed (DWORD)

CRADLE_MODEM_AUTHENTICATED Not used CRADLE_MODEM_UNKNOWN_ERROR Not used

CRADLE_MODEM_BUSY Not used CRADLE_MODEM_NO_DIAL_TONE Not used

CRADLE_MODEM_NO_ANSWER Not used CRADLE_MODEM_NO_CARRIER_DETECT Not used

CRADLE_MODEM_START_OF_DIAL Dial retry count (DWORD) CRADLE_MODEM_JOIN_IN Not used

CRADLE_FIRMWARE_DOWNLOAD Error Code (DOWRD) 0-Success Other - Error CRADLE_FIRMWARE_ALREADY_IN_PROCESS Not used

CRADLE_FIRMWARE_ERROR Error Code (DOWRD) CRADLE_RAS_CONNECTED Not used

CRADLE_RAS_DISCONNECTED Not used CRADLE_RAS_CONNECTION_FAILED Not used

See Also CRADLE_Unregister

Page 594: HC700 SDK Specification

Page 594 of 680

CRADLE_Unregister

Description This function unregisters the application window from receiving notifications of the Terminal connection with the Cradle.

Function Prototype DWORD CRADLE_Unregister (HWND hWnd)

Parameters

hWnd [in] The handle to an application window that is registered by CRADLE_Register API.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_INVALID_PARAMETER, E_CRADLE_FAILURE indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_Register

Page 595: HC700 SDK Specification

Page 595 of 680

CRADLE_GetStatus

Description This function is called to get the current status of the Terminal connection with the Cradle.

Function Prototype DWORD CRADLE_GetStatus (LPDWORD lpdwStatus)

Parameters

lpdwStatus [out] Current status of connection with the Cradle. This parameter can be a combination of the following:

CRADLE_STATUS_RAS_CONNECTION – there is RAS connection with a Cradle

CRADLE_STATUS_NET_CONNECTION – the Terminal is connected to a network, i.e. has a public IP address

CRADLE_STATUS_RAS_CONNECTION_FAILED – the attempt to create RAS connection with a Cradle is failed

CRADLE_STATUS_NET_CONNECTION_FAILED – the attempt to connect to a network is failed

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_Register

Page 596: HC700 SDK Specification

Page 596 of 680

CRADLE_GetInfo

Description This function is called to get information about the Cradle that the Terminal is inserted to.

Function Prototype DWORD CRADLE_GetInfo (LPCRADLE_INFO lpCradleInfo)

Parameters

lpCradleInfo [out] Pointer to a CRADLE_INFO structure to receive the Cradle parameters.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_COMM_FAILURE, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_GetTerminalInfo

Page 597: HC700 SDK Specification

Page 597 of 680

CRADLE_SetInfo

Description This function is called to set cradle specific information.

Function Prototype DWORD CRADLE_SetInfo (LPCRADLE_SET_INFO lpCradleSetInfo)

Parameters

lpCradleSetInfo [in] Pointer to a CRADLE_SET_INFO structure to set the Cradle parameters.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_COMM_FAILURE, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_GetInfo

Page 598: HC700 SDK Specification

Page 598 of 680

CRADLE_GetTerminalInfo

Description This function is called to get the Terminal information related to a Cradle that the Terminal is inserted to.

Function Prototype DWORD CRADLE_GetTerminalInfo (LPTERMINAL_INFO lpTerminalInfo)

Parameters

lpTerminalInfo [out] Pointer to a TERMINAL_INFO structure to receive the Terminal parameters.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_COMM_FAILURE, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_GetInfo

Page 599: HC700 SDK Specification

Page 599 of 680

CRADLE_GetIPAddresses

Description This function is called to get private and public IP addresses of the Cradle and all docked Terminals.

Function Prototype DWORD CRADLE_GetIPAddresses (LPIP_ADDRESSES lpIPAddresses)

Parameters

lpCradleInfo [out] Pointer to a IP_ADDRESSES structure to receive the private and public IP addresses of the Cradle and docked Terminals.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_COMM_FAILURE, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_GetInfo CRADLE_GetTerminalInfo

Page 600: HC700 SDK Specification

Page 600 of 680

CRADLE_Dial

Description This function is called to request the Cradle to establish a modem dial up connection. CRADLE_Dial call operates asynchronously.

Function Prototype DWORD CRADLE_Dial (LPDIAL_PARAMS lpDialParams)

Parameters

lpDialParams [in] Pointer to a DIAL_PARAMS structure that specifies calling parameters for the dial up connection.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_COMM_FAILURE, E_CRADLE_FAILURE, E_CRADLE_LINE_BUSY, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_GetInfo CRADLE_GetTerminalInfo CRADLE_HangUp

Page 601: HC700 SDK Specification

Page 601 of 680

CRADLE_HangUp

Description This function is called to request the Cradle to terminate a modem dial up connection.

Function Prototype DWORD CRADLE_HangUp ()

Parameters None

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_COMM_FAILURE, E_CRADLE_FAILURE, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments The Cradle will not terminate the connection unless all the Terminals, that requested CRADLE_Dial(), demand CRADLE_HangUp().

See Also CRADLE_Dial

Page 602: HC700 SDK Specification

Page 602 of 680

CRADLE_SetTimeout

Description This function is called to set the Cradle API timeout. Meaning the Cradle API call except CRADLE_Dial call will be blocked maximum for the specified timeout period. Default timeout value is 500 ms.

Function Prototype DWORD CRADLE_SetTimeout (DWORD dwTimeout)

Parameters

dwTimeout [in] Cradle API timeout value in msec. 0 indicates INFINITE timeout.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_FAILURE indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_GetTimeout

Page 603: HC700 SDK Specification

Page 603 of 680

CRADLE_GetTimeout

Description This function is called to get the Cradle API timeout. Meaning the Cradle API call except CRADLE_Dial call will be blocked maximum for the specified timeout period. Default timeout value is 500 ms.

Function Prototype DWORD CRADLE_GetTimeout (LPDWORD lpdwTimeout)

Parameters

lpdwTimeout [out] Cradle API timeout value in msec. 0 indicates INFINITE timeout.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_FAILURE indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_SetTimeout

Page 604: HC700 SDK Specification

Page 604 of 680

CRADLE_UpdateFirmware

Description This function is called to update the Cradle firmware.

Function Prototype DWORD CRADLE_UpdateFirmware (LPCTSTR lpFileName)

Parameters

lpFileName [in] Pointer to a null-terminated string that specifies the local file name of new Cradle firmware.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_FILE_NOT_FOUND, E_CRADLE_COMM_FAILURE, E_CRADLE_FAILURE, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_GetLastUpdateResult

Page 605: HC700 SDK Specification

Page 605 of 680

CRADLE_Led

Description This function is called to test the Cradle LEDs or indicate an error by the Cradle LEDs.

Function Prototype DWORD CRADLE_Led (CRADLE_LED_MODE eCradleLedMode)

Parameters

eCradleLedMode [in] Cradle LEDs mode.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_INVALID_PARAMETER, E_CRADLE_COMM_FAILURE, E_CRADLE_FAILURE, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also

Page 606: HC700 SDK Specification

Page 606 of 680

CRADLE_StoreFile

Description This function is called to store the file in the Cradle.

Function Prototype DWORD CRADLE_StoreFile (LPCTSTR lpLocalFileName , LPCTSTR lpRemoteFileName)

Parameters

lpLocalFileName [in] Pointer to a null-terminated string that specifies the local file name of the file that should be stored in the Cradle.

lpRemoteFileName [in] Pointer to a null-terminated string that specifies the remote (Cradle) file name.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_COMM_FAILURE, E_CRADLE_FILE_NOT_FOUND, E_CRADLE_FAILURE, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None.

See Also CRADLE_GetFile

Page 607: HC700 SDK Specification

Page 607 of 680

CRADLE_GetFile

Description This function is called to get a file, which is stored in the Cradle and save it in the local file path name.

Function Prototype DWORD CRADLE_GetFile (LPCTSTR lpLocalFileName , LPCTSTR lpRemoteFileName)

Parameters

lpLocalFileName [in] Pointer to a null-terminated string that specifies the local file name.

lpRemoteFileName [in] Pointer to a null-terminated string that specifies the name of the file that should be get from the Cradle.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_COMM_FAILURE, E_CRADLE_NOT_ENOUGH_MEMORY, E_CRADLE_FILE_NOT_FOUND, E_CRADLE_FAILURE, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also CRADLE_StoreFile

Page 608: HC700 SDK Specification

Page 608 of 680

CRADLE_SetBroadcastListenerPort

Description This function is called to set the Communication Cradle broadcast listener port number.

Function Prototype DWORD CRADLE_SetBroadcastListenerPort (u_short usPortNumber)

Parameters

usPortNumber [in] Port number.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_COMM_FAILURE, E_CRADLE_FAILURE, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments If CRADLE_SetBroadcastListenerPort is not called then Communication Cradle uses internal default port .

See Also

Page 609: HC700 SDK Specification

Page 609 of 680

CRADLE_GetLastUpdateResult

Description

This function is called to get last update cradle firmware result.

Function Prototype DWORD CRADLEAPI CRADLE_GetLastUpdateResult(LPUPDATE_FIRMWARE_RESULT lpUpdateResult)

Parameters

lpUpdateResult [out] Pointer to a UPDATE_FIRMWARE_RESULT structure to receive the Cradle update result.

Return Values E_CRADLE_SUCCESS indicates success. E_CRADLE_NULLPTR, E_CRADLE_FILE_NOT_FOUND, E_CRADLE_COMM_FAILURE, E_CRADLE_FAILURE, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure. Error Codes: Declared in CradleErr.h.

Comments None

See Also

CRADLE_UpdateFirmware

Page 610: HC700 SDK Specification

Page 610 of 680

Data Types

CRADLE_NOTIFICATION

CRADLE_INFO

CRADLE_SET_INFO

TERMINAL_INFO

IP_ADDRESSES

DIAL_PARAMS

CRADLE_LED_MODE

CRADLE_ CONNECTIVITY

IP_ADDR_PAIR

UPDATE_FIRMWARE_RESULT

Page 611: HC700 SDK Specification

Page 611 of 680

CRADLE_NOTIFICATION typedef enum {

CRADLE_NET_CONNECTED =1, // Terminal is connected to a network,

i.e. has a public IP addr

CRADLE_NET_DISCONNECTED, // The device disconnected from a network.

CRADLE_NET_CONNECTION_FAILED, // Attempt to connect to a network is failed

CRADLE_MODEM_PORT_OPENED, // Dial up notification

CRADLE_MODEM_SPEED, // Dial up notification

CRADLE_MODEM_AUTHENTICATED, // Dial up notification

CRADLE_MODEM_UNKNOWN_ERROR, // Dial up notification

CRADLE_MODEM_BUSY, // Dial up notification

CRADLE_MODEM_NO_DIAL_TONE, // Dial up notification

CRADLE_MODEM_NO_ANSWER, // Dial up notification

CRADLE_MODEM_NO_CARRIER_DETECT, // Dial up notification

CRADLE_MODEM_START_OF_DIAL, // Dial up notification

CRADLE_MODEM_JOIN_IN, // Dial up notification: This notification is sent when the Terminal requested to establish a dial up connection and the connection is already exists.

CRADLE_RAS_CONNECTED =0x100, // RAS connection with a Cradle

CRADLE_RAS_DISCONNECTED, // RAS disconnection from the Cradle

CRADLE_RAS_CONNECTION_FAILED // Attempt to create RAS connection with

Cradle failed

} CRADLE_NOTIFICATION, *LPCRADLE_NOTIFICATION;

Page 612: HC700 SDK Specification

Page 612 of 680

CRADLE_INFO

typedef struct tagCRADLE_INFO{

BYTE bNumOfSlots; // Number of slots

CRADLE_ CONNECTIVITY eCradleConnectvityCfg; // Cradle connectivity configuration

CRADLE_CONNECTIVITY eCurCradleConnectvity; // Current Cradle connectivity

TCHAR szCradleSerialNumer[CRADLE_SERIAL_NUMBER_SIZE]; // Cradle serial number

TCHAR szCradleFirmwareVersion[CRADLE_FIRMWARE_VERSION_SIZE]; /* Cradle firmware version */

TCHAR szFacilityID[MAX_PATH]; // Office index

TCHAR szSystemID[CRADLE_SYSTEM_ID_SIZE]; // System ID

} CRADLE_INFO, *LPCRADLE_INFO;

#define CRADLE_SERIAL_NUMBER_SIZE 26

#define CRADLE_FIRMWARE_VERSION_SIZE (sizeof("Ann.nn.nn"))

#define CRADLE_SYSTEM_ID_SIZE 9

CRADLE_SET_INFO

typedef struct tagCRADLE_SET_INFO{

TCHAR szFacilityID[MAX_PATH]; /* Office index. If this string is empty then the facility ID is not set. */

TCHAR szSystemID[CRADLE_SYSTEM_ID_SIZE]; /* System ID. If this string is empty then the system ID is not set. */

} CRADLE_SET_INFO, *LPCRADLE_SET_INFO;

#define CRADLE_SYSTEM_ID_SIZE 9

TERMINAL_INFO

typedef struct tagTERMINAL_INFO{

BYTE bSlotNum; // Slot number that the Terminal is inserted to

IP_ADDR_PAIR IPAddrPair; // Private and Public IP addresses of the Terminal

} TERMINAL_INFO, *LPTERMINAL_INFO;

Page 613: HC700 SDK Specification

Page 613 of 680

IP_ADDRESSES

typedef struct tagIP_ADDRESSES{

IP_ADDR_PAIR cradleIPAddrPair; // Cradle Private and Public IP addresses

IP_ADDR_PAIR terminalIPAddrPair[CRADLE_MAX_SLOT_NUM]; /* IP addresses of the docked Terminals. If the slot is empty then the associated IP address will be 0.0.0.0 */

} IP_ADDRESSES, *LPIP_ADDRESSES;

#define CRADLE_MAX_SLOT_NUM 8

DIAL_PARAMS

typedef struct tagDIAL_PARAMS{

DWORD dwCountryCode; // Country code

DWORD dwRetries; // Number of dial retries

DWORD dwTimeout; // Timeout between retries in msec

TCHAR szPhoneNumber[ RAS_MaxPhoneNumber + 1 ]; // Phone number

TCHAR szSpecialCommands[ RAS_MaxParamValue + 1 ]; // Special modem commands

TCHAR szAreaCode[ RAS_MaxAreaCode + 1 ]; /* Area code. If the dialing location does not have an area code, specify an empty string (""). */

TCHAR szUserName[ UNLEN + 1 ]; // User name

TCHAR szPassword[ PWLEN + 1 ]; // User’s password

TCHAR szDomain[ DNLEN + 1 ]; // Domain

} DIAL_PARAMS, *LPDIAL_PARAMS;

CRADLE_LED_MODE

typedef enum {

SelfTest,

FatalAppError,

ResetAppError

} CRADLE_LED_MODE, *LPCRADLE_LED_MODE;

CRADLE_CONNECTIVITY

typedef enum {

None,

Ethernet,

Modem

} CRADLE_CONNECTIVITY, *LPCRADLE_CONNECTIVITY;

Page 614: HC700 SDK Specification

Page 614 of 680

IP_ADDR_PAIR

typedef struct tagIP_ADDR_PAIR{

in_addr privateIPAddr; // Private IP address

in_addr publicIPAddr; // Public IP address

} IP_ADDR_PAIR, *LPIP_ADDR_PAIR;

UPDATE_FIRMWARE_RESULT typedef struct tagUPDATE_RESULT{

DWORD dwErrorCode;

DWORD dwUpdateSource;

TCHAR szDateTime[CRADLE_TIME_SIZE];

TCHAR szFirmwareName[CRADLE_UPDATE_FILE_SIZE];

TCHAR szSuccesFile1[CRADLE_UPDATE_FILE_SIZE];

TCHAR szSuccesFile2[CRADLE_UPDATE_FILE_SIZE];

TCHAR szFailedFile1[CRADLE_UPDATE_FILE_SIZE];

TCHAR szFailedFile2[CRADLE_UPDATE_FILE_SIZE];

} UPDATE_FIRMWARE_RESULT, *LPUPDATE_FIRMWARE_RESULT;

#define CRADLE_TIME_SIZE 40

#define CRADLE_UPDATE_FILE_SIZE 100

Page 615: HC700 SDK Specification

Page 615 of 680

Error codes

Error Code Description E_CRADLE_SUCCESS The operation completed successfully. E_CRADLE_NULLPTR Null pointer was passed to the function. E_CRADLE_INVALID_PARAMETER Invalid parameter was passed to the function. E_CRADLE_COMM_FAILURE Failed to communicate with the Cradle. E_CRADLE_NOT_ENOUGH_MEMORY Not enough storage is available. E_CRADLE_FILE_NOT_FOUND The specified file was not found. E_CRADLE_TIMEOUT The operation returned because the timeout

period expired. E_CRADLE_OUT_OF_CRADLE The Terminal is out of Cradle. E_CRADLE_NOT_CONNECTED There is no RAS connection with a Cradle. E_CRADLE_LINE_BUSY The dialed line is busy. E_CRADLE_FAILURE Failed to complete the operation.

Examples: #define WM_CRADLE_MSG (WM_APP + 0x100) LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) { HDC hdc; int wmId, wmEvent; PAINTSTRUCT ps; TCHAR szHello[MAX_LOADSTRING]; switch (message) { case WM_CREATE: if(CRADLE_Register(hWnd,WM_CRADLE_MSG)!=E_CRADLE_SUCCESS) { MessageBox(NULL, TEXT("Failed CRADLE_Register "), TEXT("Cradle"), MB_OK); } break; case WM_CRADLE_MSG: {

CRADLE_NOTIFICATION eNotify = (CRADLE_NOTIFICATION)wParam; switch(eNotify) { case CRADLE_RAS_CONNECTED: MessageBox(NULL, TEXT("RAS connected "), TEXT("Cradle"), MB_OK);

break; case CRADLE_RAS_DISCONNECTED: MessageBox(NULL, TEXT("RAS disconnected "), TEXT("Cradle"), MB_OK); break; case CRADLE_RAS_CONNECTION_FAILED: MessageBox(NULL, TEXT("RAS failed connect"), TEXT("Cradle"), MB_OK); break; case CRADLE_NET_CONNECTED: MessageBox(NULL, TEXT("NET connected "), TEXT("Cradle"), MB_OK); break; case CRADLE_NET_DISCONNECTED: MessageBox(NULL, TEXT("NET disconnected "), TEXT("Cradle"), MB_OK); break; case CRADLE_NET_CONNECTION_FAILED: MessageBox(NULL, TEXT("NET failed connect"), TEXT("Cradle"), MB_OK); break; case CRADLE_MODEM_PORT_OPENED: break; case CRADLE_MODEM_SPEED: { TCHAR szErrMsg[50];

Page 616: HC700 SDK Specification

Page 616 of 680

DWORD ModemSpeed = (DWORD)lParam; wsprintf (szErrMsg, TEXT("Modem Speed: %dL"), ModemSpeed); MessageBox(NULL, szErrMsg, TEXT("Cradle"), MB_OK); } break; case CRADLE_MODEM_AUTHENTICATED: break; case CRADLE_MODEM_UNKNOWN_ERROR: break; case CRADLE_MODEM_BUSY: break; case CRADLE_MODEM_NO_DIAL_TONE: break; case CRADLE_MODEM_NO_ANSWER: break; case CRADLE_MODEM_NO_CARRIER_DETECT: break; case CRADLE_MODEM_START_OF_DIAL: { TCHAR szErrMsg[50]; DWORD DialRetry = (DWORD)lParam; wsprintf (szErrMsg, TEXT("Dial Retry: %dL"), DialRetry); MessageBox(NULL, szErrMsg, TEXT("Cradle"), MB_OK); } break;

case CRADLE_MODEM_JOIN_IN: break; case CRADLE_MODEM_UNKNOWN: break; } } break; case WM_DESTROY: if(CRADLE_Unregister(hWnd)!=E_CRADLE_SUCCESS) { MessageBox(NULL, TEXT("Failed CRADLE_Unregister "), TEXT("Cradle"), MB_OK); } PostQuitMessage(0); break; case WM_PAINT: RECT rt; hdc = BeginPaint(hWnd, &ps); GetClientRect(hWnd, &rt); LoadString(hInst, IDS_HELLO, szHello, MAX_LOADSTRING); DrawText(hdc, szHello, _tcslen(szHello), &rt, DT_SINGLELINE | DT_VCENTER | DT_CENTER); EndPaint(hWnd, &ps); break; default: return DefWindowProc(hWnd, message, wParam, lParam); } return 0; } Exmples of Other Cradle APIs: void PrintCradleStatus() { DWORD dwCradleStatus = 0; if(CRADLE_GetStatus(&dwCradleStatus)!=E_CRADLE_SUCCESS) {

printf("Failed CRADLE_GetStatus\n"); } else { if(dwCradleStatus & CRADLE_STATUS_RAS_CONNECTION) printf("RAS Connection OK \n"); else if(dwCradleStatus & CRADLE_STATUS_RAS_CONNECTION_FAILED) printf("RAS Connect Failed \n");

Page 617: HC700 SDK Specification

Page 617 of 680

else printf("RAS Disconnect!\n ")); if(dwCradleStatus & CRADLE_STATUS_NET_CONNECTION) printf("Network Connection OK\n "); else if(dwCradleStatus & CRADLE_STATUS_NET_CONNECTION_FAILED) printf("Network Connection Failed\n "); else printf("Network Disconnect! \n"); } } void GetCradleInfo() {

CRADLE_INFO info;

if(CRADLE_GetInfo (&info)!=E_CRADLE_SUCCESS) { printf("Failed CRADLE_GetInfo\n); } else { // See what in "info" } } void SetLedFatal() {

if(CRADLE_Led(FatalAppError)!=E_CRADLE_SUCCESS) { MessageBox(NULL, TEXT("Failed CRADLE_Led "), TEXT("TestCradle"), MB_OK); } }

Page 618: HC700 SDK Specification

Page 618 of 680

22. Cradle interface usage scenario Cradle interface provides general HC700 to Cradle communication status and notification information. Cradle interface also provides number of APIs to configure some settings of Cradle and initiates Cradle’s modem dial-up connection. Cradle interface establishes automatic RAS connection between HC700 and Cradle upon inserting HC700 into Cradle. As a result HC700 will obtain IP from Cradle’s built-in RAS server. Application recommended Cradle Interface usage scenario: Application should register itself for messages indicating different connection stages.Registered application will receive the following notifications: • CRADLE_RAS_CONNECTED – when docked into the cradle, • CRADLE_NET_CONNECTED – when cradle is connected to Network. In LIM environment this

message will come immediately after CRADLE_RAS_CONNECTED, • CRADLE_NET_DISCONNECTED - when cradle is disconnected from Network or HC700 undocked, • CRADLE_RAS_DISCONNECTED – when undocked from cradle. Use case 1 – Network Connection/Disconnection: Application that requires network connection should do:

1. Register to cradle interface messages - CRADLE_Register (HWND hWnd, UINT iMsg); hWnd – is the application’s window handle that will receive message iMsg. Application will receive all Cradle interface notifications .To stop receiving Cradle notifications application should call CRADLE_Unregister (HWND hWnd).

2. Wait in Windows Message procedure for iMsg message with CRADLE_NET_CONNECTED wParam. This message will indicate successful network connection and valid IP is available.Any other received events are

3. Application can now connect to network resources using standard Winsock API. 4. Wait in Windows Message procedure for iMsg message with CRADLE_NET_DISCONNECTED

wParam. This message will indicate network disconnection.This may be due to cradle lost its network connection or HC700 is out of cradle.

5. Any application’s network connection will also drop at this stage.Application should close opened socket’s handles.

Use case 2 – Cradle information/settings: Application that requires cradle status or wishes to set cradle parameters should do:

1. Register to cradle interface messages - CRADLE_Register (HWND hWnd, UINT iMsg); hWnd – is the application’s window handle that will receive message iMsg. Application will receive all Cradle interface notifications .To stop receiving Cradle notifications application should call CRADLE_Unregister (HWND hWnd).

2. Wait in Windows Message procedure for iMsg message with CRADLE_RAS_CONNECTED wParam. This message will indicate connection to Cradle established.

3. Application can now use CRADLE_GetInfo, CRADLE_GetTerminalInfo , CRADLE_GetIPAddresses etc. to obtain any required cradle information . It may also use CRADLE_SetInfo to configure Cradle info or use CRADLE_Dial/ CRADLE_HangUp to initiate/drop Cradle modem communication.

To see complete usage scenario refer to example

Page 619: HC700 SDK Specification

Page 619 of 680

23. Registry API for HC700G-EPP Overview The Registry API provides the application ability to set / configure special behavior of the registry database. It include ability to set the configuration of “persistent registry”, cleaning registry – i.e. return to default registry setting, and backup/ restore procedures.

Note: These API are relevant only for HC700G-EPP devices.

Functions List Function Description

REG_GetConfiguration Gets the current persistent registry configuration.

REG_SetConfiguration Sets new persistent registry configuration.

REG_Clean Clean persistent registry and return to default registry settings

REG_StoreToFile Store a copy of the current registry database to specified file

REG_RestoreFromFile Restore registry settings from specified file

Examples Data Types

Page 620: HC700 SDK Specification

Page 620 of 680

REG_GetConfiguration

Description This function is called to get persistent registry configuration.

Function Prototype DWORD REGAPI REG_GetConfiguration (LPREG_CONF lpRegConf)

Parameters

lpRegConf [out] Pointer to a REG_CONF structure to get the persistent registry configuration.

Return Values

ERROR_SUCCESS indicates success. Other values indicate Win32 standard error code.

Comments None.

See Also REG_SetConfiguration

Page 621: HC700 SDK Specification

Page 621 of 680

REG_SetConfiguration

Description

This function is called to set persistent registry configuration.

Function Prototype DWORD REGAPI REG_SetConfiguration (LPREG_CONF lpRegConf)

Parameters

lpRegConf [in] Pointer to a REG_CONF structure to set the persistent registry configuration.

Return Values

ERROR_SUCCESS indicates success. Other values indicate Win32 standard error code.

Comments If lpRegConf->PersistentEnable is different from current setting, this command will warm boot the device. If lpRegConf->ThreadThreshold is different from current setting and lpRegConf->ThreadEnabled==TRUE, this command will warm boot the device

See Also REG_GetConfiguration

Page 622: HC700 SDK Specification

Page 622 of 680

REG_Clean

Description

This function is called to clean persistent registry and boot with image default registry settings.

Function Prototype DWORD REGAPI REG_Clean ()

Parameters

None.

Return Values

ERROR_SUCCESS indicates success. Other values indicate Win32 standard error code.

Comments This command will cold boot the device.

Page 623: HC700 SDK Specification

Page 623 of 680

REG_StoreToFile

Description

This function saves a copy of the current registry database to a specified file.

Function Prototype DWORD REGAPI REG_StoreToFile (LPCWSTR lpszFile)

Parameters

lpszFile [in] Specifies the name of the file to which the registry is saved.

Return Values

ERROR_SUCCESS indicates success. Other values indicate Win32 standard error code.

Comments None.

See Also REG_RestoreFromFile

Page 624: HC700 SDK Specification

Page 624 of 680

REG_RestoreFromFile

Description

This function replace current registry setting with registry setting in the supplied file.

Function Prototype DWORD REGAPI REG_RestoreFromFile (LPCWSTR lpszFile)

Parameters

lpszFile [in] Specifies the name of the file to which the registry should restore from.

Return Values

ERROR_SUCCESS indicates success. Other values indicate Win32 standard error code.

Comments This command will warm boot the device.

See Also REG_StoreToFile

Page 625: HC700 SDK Specification

Page 625 of 680

Examples The examples below demonstrate how to work with Registry APIs:

REG_GetConfiguration, REG_SetConfiguration Examples BOOL EnablePersistent(BOOL bEnable) { REG_CONF RegConf; if(ERROR_SUCCESS != REG_GetConfiguration(&RegConf)) {

RETAILMSG(1, (TEXT("REG_GetConfiguration Failed. Error=%X\r\n"),GetLastError()));

return FALSE; } if(bEnable!=RegConf.PersistentEnable) { RegConf.PersistentEnable = bEnable; if(ERROR_SUCCESS != REG_SetConfiguration(&RegConf)) {

RETAILMSG(1, (TEXT("REG_SetConfiguration Failed. Error=%X\r\n"),GetLastError())); return FALSE;

} } return TRUE; } REG_Clean Example void CleanRegistry() {

if(IDOK == MessageBox(NULL,TEXT("About to cold boot device!\nAre you sure?"),TEXT("Clean Registry"),MB_OKCANCEL))

{ if(!REG_Clean()) {

RETAILMSG(1, (TEXT("REG_Clean Failed. Error=%X\r\n"),GetLastError())); MessageBox(NULL,TEXT("Failed!!!"),TEXT("Clean Registry"),MB_OK);

} } } REG_StoreToFile Example BOOL SaveRegistry(LPCWSTR lpszFileName) { DWORD dwRet; SetCursor(LoadCursor(NULL, IDC_WAIT)); dwRet = REG_StoreToFile(lpszFileName); SetCursor(LoadCursor(NULL, IDC_ARROW));

Page 626: HC700 SDK Specification

Page 626 of 680

if(ERROR_SUCCESS != dwRet) {

RETAILMSG(1, (TEXT("REG_StoreToFile Failed. Error=%X\r\n"),GetLastError())); MessageBox(NULL,TEXT("Failed store registry to file!!!"),TEXT("Registry"),MB_OK|MB_ICONERROR);

return FALSE; }

MessageBox(NULL,TEXT("Success store registry to file!!!"),TEXT("Registry"),MB_OK);

return TRUE; } REG_RestoreFromFile Example BOOL RestoreRegistry(LPCWSTR lpszFileName) {

if(IDOK == MessageBox(NULL,TEXT("This action will warm boot system.\r\nAre you sure?"),TEXT("Registry"),MB_OKCANCEL))

{ if(ERROR_SUCCESS != REG_RestoreFromFile(lpszFileName)) {

RETAILMSG(1, (TEXT("REG_RestoreFromFile Failed. Error=%X\r\n"),GetLastError())); MessageBox(NULL,TEXT("Failed restore registry from file!!!"),TEXT("Registry"),MB_OK|MB_ICONERROR);

return FALSE; } } return TRUE; }

Page 627: HC700 SDK Specification

Page 627 of 680

Data Types

REG_CONF typedef struct tagREG_CONF{ BOOL PersistentEnable; //Persistent registry enable BOOL PowerDownFlushEnable; //Flush registry on power down BOOL ThreadEnable; //Flush registry thread enable DWORD ThreadPriority; //Flush registry thread priority DWORD ThreadThreshold; //Flush registry thread Threshold DWORD ThreadFlushPeriod; //Flush registry thread period timeout } REG_CONF, *LPREG_CONF;

Page 628: HC700 SDK Specification

Page 628 of 680

24. Registry API Usage Scenario

Persistent Registry:

The OS has the ability to store all registry database on persistent storage. Meaning that after any boot the OS restore the registry from a file under IPSM. This is done automatically by the OS. Application / user can enable / disable the persistent registry by using the Registry API.

By default the persistent registry is disabled.

Enabling persistent registry:

Call REG_SetConfiguration() API with REG_CONF.PersistentEnable = TRUE. In the example above: EnablePersistent(TRUE);

If system was in persistent registry disabled before, it will warm boot the device. The device will load with persistent registry enabled. The new setting (persistent enable) will be saved on system file under IPSM, and from now on (until Update OS procedure or disabling persistent registry with REG API) after any boot registry settings are persistent. If system was already in persistent registry enables, enabling it again will change nothing (no warm boot).

Disabling persistent registry:

Call REG_SetConfiguration() API with REG_CONF.PersistentEnable = FALSE. In the example above: EnablePersistent(FALSE);

If system was in persistent registry enabled before, it will delete persistent registry file from IPSM and warm boot the device. The device will load with persistent registry disabled. The new setting (persistent disable) is valid until changing it with REG API.

If system was already in persistent registry disabled, disabling it again will change nothing (no warm boot).

Changing options when persistent registry is enabled:

When registry database is saved to persistent storage?

1. Upon system enter to suspend, off, critical off and before warm boot

2. Periodically by a background thread:

The application can enable those 2 options or at least one of them. For the background thread, application can set 3 parameters:

1. Thread priority.

2. Registry activity threshold: specifies the # of reg activities before registry flush is forced.

3. Timeout period for a flush (flush occurs if there has been at least one registry change during this period of time)

Application can change those setting in one call to REG_SetConfiguration.

For example to enable persistent registry with background thread that run in IDLE priority and save registry after 128 registry activities or after 60 seconds: REG_CONF RegConf; RegConf.PersistentEnable = TRUE; RegConf.PowerDownFlushEnable = FALSE;

Page 629: HC700 SDK Specification

Page 629 of 680

RegConf.ThreadEnable = TRUE; RegConf.ThreadPriority = 255; \\ IDLE priority RegConf.ThreadThreshold = 128; RegConf.ThreadFlushPeriod = 30000; \\ 30 seconds

REG_SetConfiguration(&RegConf))

Clean registry:

Clean registry operation is a way to return the OS to default registry settings (last image defaults). This operation deletes the registry file from IPSM and cold boot the device. It doesn’t change the mode of persistent registry (if it was before enabled, it will continue to be enabled, if it was before disabled, it will continue to be disabled). There are 2 ways to perform clean registry:

1. Registry API: Application call to REG_Clean() (also available from control panel).

2. Key combination: a. Perform cold boot by pressing S+X+ON/OFF keys for 5 seconds till keyboard backlight flash

appears. b. Release ON/OFF key continue to press the S+X keys and press H key till Motorola screen

appears in order to start registry clean process. c. Motorola screen with 'Clean Registry Boot …' message will appear. d. After few seconds the device will warm boot again (if persistent is enabled). e. The image will start up with cleaned registry.

Persistent registry setting factory defaults (or after Update OS):

Persistent registry: disabled Power down flush: enabled Background thread: enabled Thread priority: 255 (IDLE) Thread threshold: 256 Thread timeout period: 60000 ms

Persistent registry setting after clean registry boot:

Persistent registry: as before clean registry Power down flush: enabled Background thread: enabled Thread priority: 255 (IDLE) Thread threshold: 256 Thread timeout period: 60000 ms

Registry Backup:

Registry database can be backup, by using the REG_StoreToFile() API. This API saves also the “persistent registry’ configuration. Note: Storing registry database to file on RAM is mush faster then storing it to file on IPSM.

Registry Restore:

Registry database can be restored, by using the REG_RestoreFromFile() API. This API restores also the “persistent registry’ configuration. The file to be restored can exist on any mounted file system that is accessible by the OS. The file to be restored must be created by REG_StoreToFile() (HC700 API) or RegCopyFile (Windows API). Note: The API will always warm boot the device.

Page 630: HC700 SDK Specification

Page 630 of 680

Registry Cloning:

The Registry backup and restore API can be used for registry cloning:

1. On master device configure all registry setting (Through control panel, user applications or manually with RegEdit).

2. On master device call to REG_StoreToFile() (also available in registry settings control panel).

3. Copy the backup file fro master device to desktop computer (with active sync…)

4. Copy the backup file to all other devices (through FTP, TFTP or any other file transfer protocol)

5. On all other device call REG_RestoreFromFile() with the backup file (also available in registry settings control panel), to apply the master device registry setting to all other devices.

Page 631: HC700 SDK Specification

Page 631 of 680

25. NTP Service The NTP service is an automated time synchronization service that is initialized at startup of the HC700. In order to run this service some modifications should be made to the default registry settings and to the network adapter parameters. Please follow the following steps: Registry related changes: 1) Locate and modify the HKEY_LOCAL_MACHINE\Services\Timesvc Key values.

a. Set “recoveryrefresh” to 300000 (5 minutes) or more b. Set “refresh” to a greater or equal value to “recoveryrefresh” c. Set “server” to the dns name of the NTP Server, please note that an explicit IP address will not do. d. “threshold” to 300000 (5 minutes) or more.

Network Adapter related changes: 2) Make sure that the DNS and WINS servers are configured correctly. Running the service 3) Warm boot the device. 4) Establish a network connection 5) NTP should update your clock (sometimes shell takes up to 1 minute to refresh the clock display).

Page 632: HC700 SDK Specification

Page 632 of 680

26. System Events

The HC700 sytem names events are defined in SystemEvents.h file described below: Global named events for Docking MOTOROLA_DOCKING_EVENT - When the HC700 is inserted to Docking or removed from Docking Global named events used for G20 activities PPAD_GPRS_COVERAGE_CHANGE_EVENT When HC700 Radio GPRS coverage is changed (in coverage ,out of coverage) PPAD_GPRS_DEREGISTRATION - When HC700 is inserted to cradle and the GPRS radio is deregistered from network PPAD_GPRS_REGISTRATION_EVENT -When HC700 is removed from cradle and GPRS Radio is registered again to the network

Page 633: HC700 SDK Specification

Page 633 of 680

27. Appendix APPENDIX_A - Scan Key Trigger Mechanism APPENDIX_B - Additional Supported API APPENDIX_C - Power management

APPENDIX_D - Resume from Critical OFF APPENDIX_E - HC700 Available and Combination Keys APPENDIX_F - Avilabe COM Ports description

Page 634: HC700 SDK Specification

APPENDIX A

Scan Key Trigger Mechanism SCAN key is part of the keyboard matrix of the HC700, When application would like to use the scan key as a trigger to scan a label, it shall register a request to keyboard driver by calling KBD_RegisterKeyStateNotification function, The application will be notified each time the Scan key is pressed and released . All the windows who called RegisterKeyStateNotification with there owned hWnd and unique massage are registered in keyboard driver hWnd handles pool, each time the scan key pressed or released ,the keyboard driver post massages to all windows who registered. In 3rd party Application using RCM_RegisterTriggerMessage & RCM_DeregisterTrigger will be transparent to the user, Motorola SDK will translate this call to RegisterKeyStateNotification .

1

Key

Window

Post Massage to All registered windows When Scan Up/Down Occurs(indicated in wParam )

KeyBoard API DLL

Board Driver

Pool of Registered Handles

W

W

Wn

l

PostMassage

Scan Key Press/Relaese

HC700 KeyBoard

in1 hWnd

in2 hWnd

in3hWnd

SCAN KEY/Up Down Recognitio

RegisterKeyStateNotification cal

Window 2

Page 634 of 680

Page 635: HC700 SDK Specification

Page 635 of 680

APPENDIX B Additional API

Overview This section describes WinCE/PocketPC APIs that are supported by HC700 The Battery Driver provides information about battery status . The API is standard WinCE/PocketPC API, therefore it’s not part of Motorola main SDK , the battery fields which are not supported in the HC700 are marked in blue. Battery_API Keyboard_Enable_Disable_API Boot Sequence and related APIs Disk API

Page 636: HC700 SDK Specification

Page 636 of 680

GetSystemPowerStatusEx2

Description The GetSystemPowerStatusEx2 function retrieves battery status information.

Function Prototype

DWORD GetVersioGetSystemPowerStatusEx2(

PSYSTEM_POWER_STATUS_EX2 pSystemPowerStatusEx2, DWORD dwLen, BOOL fUpdate );

Parameters PSystemPowerStatusEx2 [out] Pointer to an SYSTEM_POWER_STATUS_EX2 data structure to be filled with the power status information. dwLen [in] Specifies the length of the buffer pointed to by pSystemPowerStatusEx2. fUpdate [in] Specify TRUE to get the latest information from the device driver. Specify FALSE to get cached information that may be out-of-date by several seconds.

Return Values Length of the data returned in the pSystemPowerStatusEx2 buffer indicates success. Zero indicates failure.

See Also

None.

QuickInfo

Header: Declared in winbase.h.

Page 637: HC700 SDK Specification

Page 637 of 680

Data Types

SYSTEM_POWER_STATUS_EX2 This structure contains information about the power status of the system.

typedef struct _SYSTEM_POWER_STATUS_EX2{

BYTE ACLineStatus;

BYTE BatteryFlag;

BYTE BatteryLifePercent;

BYTE Reserved1;

DWORD BatteryLifeTime;

BYTE Reserved2;

BYTE BackupBatteryFlag;

BYTE BackupBatteryLifePercent;

BYTE Reserved3;

BYTE BackupBatteryLifeTime;

BYTE BackupBatteryFullLifeTime;

WORD BatteryVoltage;

DWORD BatteryCurrent;

DWORD BatteryAverageCurrent;

DWORD BatteryAverageInterval;

DWORD BatterymAHourConsumed;

DWORD BatteryTemperature;

DWORD BackupBatteryVoltage;

BYTE BatteryChemistry;

} SYSTEM_POWER_STATUS_EX2, *PSYSTEM_POWER_STATUS_EX2, *LPSYSTEM_POWER_STATUS_EX2;

ACLineStatus

AC power status. It is one of the following values:

• AC_LINE_OFFLINE

• AC_LINE_ONLINE

• AC_LINE_BACKUP_POWER

• AC_LINE_UNKNOWN

BatteryFlag Battery charge status. It is one of the following values:

• BATTERY_FLAG_HIGH

Page 638: HC700 SDK Specification

Page 638 of 680

• BATTERY_FLAG_LOW

• BATTERY_FLAG_CRITICAL

• BATTERY_FLAG_CHARGING

• BATTERY_FLAG_NO_BATTERY

• BATTERY_FLAG_UNKNOWN

Return Values BatteryLifePercent

Percentage of full battery charge remaining. Must be in the range 0 to 100, or BATTERY_PERCENTAGE_UNKNOWN if percentage of battery life remaining is unknown.

Reserved1 Must be zero.

BatteryLifeTime Number of seconds of battery life remaining, or BATTERY_LIFE_UNKNOWN if number of seconds of battery life remaining is unknown.

BatteryFullLifeTime Number of seconds of battery life when at full charge, or BATTERY_LIFE_UNKNOWN if full lifetime of battery is unknown. NOT supported in HC700.

Reserved2 Must be zero.

BackupBatteryFlag Backup battery charge status. It is one of the following values:

• BATTERY_FLAG_HIGH

• BATTERY_FLAG_LOW

• BATTERY_FLAG_CRITICAL

• BATTERY_FLAG_CHARGING

• BATTERY_FLAG_NO_BATTERY

• BATTERY_FLAG_UNKNOWN

NOT supported in HC700. BackupBatteryLifePercent

Percentage of full backup battery charge remaining. Must be in the range 0 to 100, or BATTERY_PERCENTAGE_UNKNOWN if percentage of backup battery life remaining is unknown.

Reserved3 Must be zero.

BackupBatteryLifeTime Number of seconds of backup battery life when at full charge, or BATTERY_LIFE_UNKNOWN if number of seconds of backup battery life remaining is unknown. NOT supported in HC700.

BackupBatteryFullLifeTime Number of seconds of backup battery life when at full charge, or BATTERY_LIFE_UNKNOWN if full lifetime of backup battery is unknown. NOT supported in HC700.

BatteryVoltage Number of millivolts (mV) of battery voltage. It can range from 0 to 65535.

BatteryCurrent Number of milliamps (mA) of instantaneous current drain. It can range from 0 to 32767 for charge and 0 to –32768 for discharge.

Page 639: HC700 SDK Specification

Page 639 of 680

BatteryAverageCurrent Average number of milliamps of short term device current drain. It can range from 0 to 32767 for charge and 0 to –32768 for discharge.

BatteryAverageInterval Number of milliseconds (mS) that is the time constant interval used in reporting BatteryAverageCurrent. NOT supported in HC700.

BatterymAHourConsumed Average number of milliamp hours (mAh) of long-term cumulative average discharge. It can range from 0 to –32768. This value is reset when the batteries are charged or changed. NOT supported in HC700.

BatteryTemperature Battery temperature reported in 0.1 degree Celsius increments. It can range from –3276.8 to 3276.7.

BackupBatteryVoltage Number of millivolts (mV) of backup battery voltage. It can range from 0 to 65535.

BatteryChemistry Type of battery. It can be one of the following values:

• BATTERY_CHEMISTRY_ALKALINE

• BATTERY_CHEMISTRY_NICD

• BATTERY_CHEMISTRY_NIMH

• BATTERY_CHEMISTRY_LION

• BATTERY_CHEMISTRY_LIPOLY

• BATTERY_CHEMISTRY_UNKNOWN

Page 640: HC700 SDK Specification

Page 640 of 680

EnableHardwareKeyboard

Description This function enables or disables the keyboard. The EnableHardwareKeyboard function is useful for applications in which a user can write on the touch screen. When the keyboard is disabled, a user can rest a hand on it without causing spurious keyboard input. Use the disable mode carefully. If an application hangs while the keyboard is disabled, the keyboard is not available to other applications. When EnableHardwareKeyboard changes the enabled state of the keyboard, it causes menus, tabs, buttons and static controls to repaint themselves, so they can change the way they display keyboard accelerators or other relevant information.

Function Prototype BOOL EnableHardwareKeyboard(

BOOL bEnable )

Parameters bEnable

[in] Boolean value that specifies whether to enable or disable the keyboard. Set it to TRUE to enable the keyboard or FALSE to disable it.

Return Values This function always returns TRUE.

Comments The EnableHardwareKeyboard function is useful for applications in which a user can write on the touch screen. When the keyboard is disabled, a user can rest a hand on it without causing spurious keyboard input. Use the disable mode carefully. If an application hangs while the keyboard is disabled, the keyboard is not available to other applications. When EnableHardwareKeyboard changes the enabled state of the keyboard, it causes menus, tabs, buttons and static controls to repaint themselves, so they can change the way they display keyboard accelerators or other relevant information. If the application calls one of the following non standard WinCE API : -KBD_RegisterKeyStateNotification(Moto API) or -RegisterKeyStateNotification(Symbol API) or -RCM_RegisterTrigger_message(Symbol API that registers SCAN scan key event only) The Application will continue to get the registered massages though, EnableHardwareKeyboard(FALSE) was called. To lock SCAN key enent and the other registered key event(SHIFT etc..) the application will have to call -KBD_UnRegisterKeyStateNotification or -UnregisterKeyStateNotification or -RCM_DeRegisterTrigger In respective of using the RegiterXX calls above.

QuickInfo PocketPC: WinCE 3.0 Header: Declared in Winbase.h.

Page 641: HC700 SDK Specification

Page 641 of 680

Boot Sequence and related APIs

Overview

HC700 Boot Types Key

Combination API

Cold Boot “S” + “X” + “On/Off” for 5 seconds

SetSystemPowerState

Warm Boot “A” + “F” + “ESC” for 5 seconds

SetSystemPowerState

Last boot status

N/A KernelIoControl(IOCTL_HAL_GET_BOOT_STATUS)Return a boot status: warm or cold

COLD Boot HC700 returns to initial factory setting/default. RAM contents are reset - RAM based file system and installed applications disappear. IPSM (Flash File System) preserves its contents. WARM Boot HC700 preserves all memory contents – all memory contents are preserved including RAM based file system and installed applications. All RAM based registry is preserved as well. IPSM (Flash File System) preserves its contents.

Reset API Functions List The HC700 supports the following standard Win CE APIs that enable an application to perform a warm reset.

• SetSystemPowerState

• KernelIoControl

Comments None

Examples

Page 642: HC700 SDK Specification

Page 642 of 680

SetSystemPowerState - (Warm Reset)

Description

The user application can perform a Warm Reset on the HC700 device by calling SetSystemPowerState API with the specified parameters.

This API performs a graceful warm reset, i.e. flushes files and shuts down all device peripherials prior to warm reset.

DWORD SetSystemPowerState (LPCWSTR psState, DWORD dwStateFlags, DWORD dwOptions );

Parameters psState

Set to NULL. dwStateFlags

Set to POWER_STATE_RESET. dwOptions

Set to 0.

Return Values If the system is successfully reset, this call does not return. If the reset fails, Win32 error code is returned.

QuickInfo OS Versions: Windows CE .NET 4.0 and later. Header: Declared in pm.h.

Page 643: HC700 SDK Specification

Page 643 of 680

SetSystemPowerState – (Cold Reset)

Description

The user application can perform a Cold Reset on the HC700 device by calling SetSystemPowerState API with the specified parameters.

This API performs a graceful cold reset, i.e. flushes files and shuts down all device peripherials prior to cold reset.

DWORD SetSystemPowerState (LPCWSTR psState, DWORD dwStateFlags, DWORD dwOptions );

Parameters psState

Set to NULL. dwStateFlags

Set to POWER_STATE_RESET. dwOptions

Set to POWER_COLD_RESET.

Return Values If the system is successfully reset, this call does not return. If the reset fails, Win32 error code is returned.

QuickInfo OS Versions: Windows CE .NET 4.0 and later. Header: Declared in pm.h, pmplatform.h.

Page 644: HC700 SDK Specification

Page 644 of 680

KernelIoControl - (Warm Reset)

Description

The user application can perform a Warm Reset on the HC700 device by calling KernelIoControl function with the specified parameters.

This API performs a graceful warm reset, i.e. flushes files and shuts down all device peripherials prior to warm reset.

BOOL KernelIoControl (DWORD dwIoControlCode, LPVOID lpInBuf, DWORD nInBufSize , LPVOID lpOutBuf, DWORD nOutBufSize, LPDWORD lpBytesReturned );

Parameters dwIoControlCode

IOCTL_HAL_REBOOT lpInBuf

Set to NULL. nInBufSize

Set to 0. lpOutBuf

Set to NULL. nOutBufSize

Set to 0. lpBytesReturned

Set to NULL.

Return Values If the system is successfully reset, this call does not return. If the reset fails, FALSE is returned.

QuickInfo OS Versions: Windows CE 2.12 and later. Header: Declared in Pkfuncs.h.

Page 645: HC700 SDK Specification

Page 645 of 680

Examples The example below demonstrates how to perform a warm reset on the HC700 device:

SetSystemPowerState Example DWORD dwRetVal; // Generate a graceful warm reset dwRetVal = SetSystemPowerState(NULL, POWER_STATE_RESET, 0); if (dwRetVal != ERROR_SUCCESS) {

// Failed to generate a warm reset …

} KernelIoControl Example BOOL bRetVal; // Generate a graceful warm reset bRetVal = KernelIoControl( IOCTL_HAL_REBOOT, NULL, 0, NULL, 0, 0 ); if (bRetVal == FALSE) {

// Failed to generate a warm reset …

}

Page 646: HC700 SDK Specification

Page 646 of 680

Disk API Overview

This API is intended to allow user application perform file system scanning, formatting and defragmentation of CF storage cards.

Functions list

Below functions are declared within DiskCApi.h file and exported to user application by fatutil.dll file included in system software image:

Function Prototype This function scans a volume for errors in the FAT and directories, and for lost clusters according to the options specified. BOOL ScanVolume(HANDLE hPartition, PDISK_INFO pdi, PSCAN_OPTIONS pSo, PFN_PROGRESS pfnProg, PFN_MESSAGE pfnMessage);

Parameters hPartition

Handle to partition. Call OpenPartition to get this handle. pdi

Pointer to a DISK_INFO structure. Can be obtain through a DeviceIoControl call to the appropriate drive (DSK1) with the condition code DISK_IOCTL_GETINFO.

pSo Pointer to a SCAN_OPTIONS structure. pfnProgress

Callback function indicating progress. pfnMessage

Callback function used to display a message to user.

Return Values

If the function succeeds, the return value is TRUE. If it fails, the return valid is FALSE. Typical reasons for failing would be running out of memory or error writing to disk. Function does not fail if errors were detected on the disk.

Comments None

QuickInfo

Windows CE: Version 4.0 or later. Header: Declared in DiskCAPI.h. Import Library: Use Fatutil.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

None.

Function Prototype This function scans a volume for errors in the FAT and directories, and for lost clusters according to the options specified. BOOL ScanVolumeEx(HANDLE hPartition, PSCAN_PARAMS pSp);

Page 647: HC700 SDK Specification

Page 647 of 680

Parameters hPartition

Handle to partition. Call OpenPartition to get this handle. pSp

Pointer to a SCAN_PARAMS structure.

Return Values

If the function succeeds, the return value is TRUE. If it fails, the return valid is FALSE. Typical reasons for failing would be running out of memory or error writing to disk. Function does not fail if errors were detected on the disk.

Comments None

QuickInfo

Windows CE: Version 4.0 or later. Header: Declared in DiskCAPI.h. Import Library: Use Fatutil.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example

None.

Function Prototype This function scans a volume according to the options specified. It contains a dialog box user interface that can be displayed standalone or invoked from another place such as a control panel window. BOOL ScanVolumeUI(HANDLE hPartition, HWND hWnd);

Parameters hPartition

Handle to partition. Call OpenPartition to get this handle. hWnd

Handle to parent window. Can be NULL if there is no parent.

Return Values

None.

Comments None

QuickInfo

Windows CE: Version 4.0 or later. Header: Declared in DiskCAPI.h. Import Library: Use Fatutil.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example HANDLE hStore = 0, hPartition = 0; hStore = OpenStore(TEXT("DSK1:")); if( ( hStore == INVALID_HANDLE_VALUE ) || ( hStore == NULL ) )

Page 648: HC700 SDK Specification

Page 648 of 680

{ wsprintf(szString, TEXT("OpenStore failed. Last error %dL"), GetLastError() ); MessageBox(hWnd, szString, TEXT("Failure"), MB_OK); break; } hPartition = OpenPartition(hStore, TEXT("Part00")); if( ( hPartition == INVALID_HANDLE_VALUE ) || ( hPartition == NULL ) ) { CloseHandle(hStore); wsprintf(szString, TEXT("OpenPartition failed. Last error %dL"), GetLastError() ); MessageBox(hWnd, szString, TEXT("Failure"), MB_OK); break; } // We must to dismount partition before scanning DismountPartition(hPartition); ScanVolumeUI(hPartition, hWnd); // Mount partition soon MountPartition(hPartition); CloseHandle(hPartition); CloseHandle(hStore);

Function Prototype This function formats a volume according to the options specified. BOOL FormatVolume(HANDLE hPartition, PDISK_INFO pdi, PFORMAT_OPTIONS pFo, PFN_PROGRESS pfnProg, PFN_MESSAGE pfnMessage);

Parameters hPartition

Handle to partition. Call OpenPartition to get this handle. pdi

Pointer to a DISK_INFO structure. Can be obtain through a DeviceIoControl call to the appropriate drive (DSK1) with the condition code DISK_IOCTL_GETINFO.

pFo Pointer to a FORMAT_OPTIONS structure. pfnProgress

Callback function indicating progress. pfnMessage

Callback function used to display a message to user.

Return Values

If the function succeeds, the return value is TRUE. If it fails, the return valid is FALSE. Typical reasons for failing would be running out of memory or error writing to disk. Function does not fail if errors were detected on the disk.

Comments None

QuickInfo

Windows CE: Version 4.0 or later. Header: Declared in DiskCAPI.h. Import Library: Use Fatutil.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Page 649: HC700 SDK Specification

Page 649 of 680

Example None

Function Prototype This function formats a volume according to the options specified. BOOL FormatVolumeEx(HANDLE hPartition, PFORMAT_PARAMS pSp);

Parameters hPartition

Handle to partition. Call OpenPartition to get this handle. pFp

Pointer to a FORMAT_PARAMS structure.

Return Values

If the function succeeds, the return value is TRUE. If it fails, the return valid is FALSE. Typical reasons for failing would be running out of memory or error writing to disk. Function does not fail if errors were detected on the disk.

Comments None

QuickInfo

Windows CE: Version 4.0 or later. Header: Declared in DiskCAPI.h. Import Library: Use Fatutil.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example None

Function Prototype This function formats a volume according to the options specified. It contains a dialog box user interface that can be displayed standalone or invoked from another place such as a control panel window. BOOL FormatVolumeUI(HANDLE hPartition, HWND hWnd);

Parameters hPartition

Handle to partition. Call OpenPartition to get this handle. hWnd

Handle to parent window. Can be NULL if there is no parent.

Return Values

None.

Comments None

Page 650: HC700 SDK Specification

Page 650 of 680

QuickInfo

Windows CE: Version 4.0 or later. Header: Declared in DiskCAPI.h. Import Library: Use Fatutil.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example HANDLE hStore = 0, hPartition = 0; hStore = OpenStore(TEXT("DSK1:")); if( ( hStore == INVALID_HANDLE_VALUE ) || ( hStore == NULL ) ) { wsprintf(szString, TEXT("OpenStore failed. Last error %dL"), GetLastError() ); MessageBox(hWnd, szString, TEXT("Failure"), MB_OK); break; } hPartition = OpenPartition(hStore, TEXT("Part00")); if( ( hPartition == INVALID_HANDLE_VALUE ) || ( hPartition == NULL ) ) { CloseHandle(hStore); wsprintf(szString, TEXT("OpenPartition failed. Last error %dL"), GetLastError() ); MessageBox(hWnd, szString, TEXT("Failure"), MB_OK); break; } // We must to dismount partition before formating DismountPartition(hPartition); FormatVolumeUI(hPartition, hWnd); // Mount partition soon MountPartition(hPartition); CloseHandle(hPartition); CloseHandle(hStore);

Function Prototype This function defragments files on a volume and removes any free space in fragmentation. It calls scan disk first to verify volume is free from errors. BOOL DefragVolume(HANDLE hPartition, PDISK_INFO pdi, PDEFRAG_OPTIONS pDo, PFN_PROGRESS pfnProg, PFN_MESSAGE pfnMessage);

Parameters hPartition

Handle to partition. Call OpenPartition to get this handle. pdi

Pointer to a DISK_INFO structure. Can be obtain through a DeviceIoControl call to the appropriate drive (DSK1) with the condition code DISK_IOCTL_GETINFO.

pDo Pointer to a DEFRAG_OPTIONS structure. pfnProgress

Callback function indicating progress. pfnMessage

Callback function used to display a message to user.

Page 651: HC700 SDK Specification

Page 651 of 680

Return Values

If the function succeeds, the return value is TRUE. If it fails, the return valid is FALSE. Typical reasons for failing would be running out of memory or error writing to disk. Function does not fail if errors were detected on the disk.

Comments None

QuickInfo

Windows CE: Version 4.0 or later. Header: Declared in DiskCAPI.h. Import Library: Use Fatutil.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example None

Function Prototype This function defragments files on a volume and removes any free space in fragmentation. It calls scan disk first to verify volume is free from errors. BOOL FormatVolumeEx(HANDLE hPartition, PDEFRAG_PARAMS pSp);

Parameters hPartition

Handle to partition. Call OpenPartition to get this handle. pDp

Pointer to a DEFRAG_PARAMS structure.

Return Values

If the function succeeds, the return value is TRUE. If it fails, the return valid is FALSE. Typical reasons for failing would be running out of memory or error writing to disk. Function does not fail if errors were detected on the disk.

Comments None

QuickInfo

Windows CE: Version 4.0 or later. Header: Declared in DiskCAPI.h. Import Library: Use Fatutil.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example None

Page 652: HC700 SDK Specification

Page 652 of 680

Function Prototype This function defragments a volume according to the options specified. It contains a dialog box user interface that can be displayed standalone or invoked from another place such as a control panel window. BOOL DefragVolumeUI(HANDLE hPartition, HWND hWnd);

Parameters hPartition

Handle to partition. Call OpenPartition to get this handle. hWnd

Handle to parent window. Can be NULL if there is no parent.

Return Values

None.

Comments None

QuickInfo

Windows CE: Version 4.0 or later. Header: Declared in DiskCAPI.h. Import Library: Use Fatutil.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.

Example HANDLE hStore = 0, hPartition = 0; hStore = OpenStore(TEXT("DSK1:")); if( ( hStore == INVALID_HANDLE_VALUE ) || ( hStore == NULL ) ) { wsprintf(szString, TEXT("OpenStore failed. Last error %dL"), GetLastError() ); MessageBox(hWnd, szString, TEXT("Failure"), MB_OK); break; } hPartition = OpenPartition(hStore, TEXT("Part00")); if( ( hPartition == INVALID_HANDLE_VALUE ) || ( hPartition == NULL ) ) { CloseHandle(hStore); wsprintf(szString, TEXT("OpenPartition failed. Last error %dL"), GetLastError() ); MessageBox(hWnd, szString, TEXT("Failure"), MB_OK); break; } // We must to dismount partition before formating DismountPartition(hPartition); DefragVolumeUI(hPartition, hWnd); // Mount partition soon MountPartition(hPartition); CloseHandle(hPartition); CloseHandle(hStore);

Page 653: HC700 SDK Specification

Page 653 of 680

APPENDIX C

Power Management Mechanism

Introduction

The goal of the Power Management (PM) is to reduce the power consumption of a target device. As a result the device will be able to provide service for longer periods of time when the battery is used wisely.

HC700 - Power States HC700 supports the following system power states: No Power

• In this state, the CPU is off and no power is supplied to the RAM. • All platform devices are off.

On

• This is the standard running mode. • The CPU is running, and it schedules threads. • If there are no threads to run, the CPU enters idle mode. • The RAM and most of the platform devices are powered. • There is automatic backlight off by backlight timeout. For more details see section 2.2.

Screen Off

• The CPU is running, and it schedules threads. • If there are no threads to run, the CPU enters idle mode. • The display and backlight are off. • This power state is entered during a user inactivity timeout. For more details see section

2.3.

Suspend

• In this state, no threads are running. • The CPU is in a suspended mode, and the timer interrupt is stopped. • RAM is in a self-refresh state and maintains all its values. • Most of the platform devices are off. • This power state is entered during an inactivity timeout or user request—for example, by

pressing the ON/OFF button.

Page 654: HC700 SDK Specification

Page 654 of 680

Unattended

• The CPU is running, and it schedules threads. • If there are no threads to run, the CPU enters idle mode. • The display, backlight and audio are off. • This state is intended for use when the user is not directly using the device but system

processes on it are active. For example, if the device wakes up to server sync, the display, backlight, and audio don’t need to/won’t be turned on.

Critical off

• In this state, the CPU is suspended. • RAM is in a self-refresh state and maintains all its values. • All platform devices are off. • This power state is entered during a critical battery state or battery removal.

Off

• In this state, the CPU is suspended. • RAM is in a self-refresh state and maintains all its values. • All platform devices are off. • This power state is entered during a user request by two sec. ON/OFF button pressing.

Page 655: HC700 SDK Specification

Page 655 of 680

HC700 - Transition between states The following illustration shows the power states and transitions. The target power states are shown as blocks and transitional states are represented by arrows.

Critical Off

User activity

Suspend timeout expiration (includes Screen Off timeout)

Screen OffUnattendedUser activity

1. ON/OFF button momentary pressing (on battery power only).2. Suspend timeout expiration if Screen Off timeout is disabled.

Warm boot

Off

1. ON/OFF button momentary pressing (the battery is OK)

2.External power supply presence

2 sec. ON/OFF button pressing (on battery power only).

SW request initiated by user

On

Suspend

RebootWakeup: User activity, RTC alarm

Wakeup: SystemComm.

Suspend timeoutexpiration

No external power:1. Battery removal2. Critical battery state

No external power:1. Battery removal2. Critical battery state

Screen Off timeout expiration

Page 656: HC700 SDK Specification

Page 656 of 680

27.1.1 On to Suspend: If HC700 is not working from external power and not in the CRADLE, the following activities will cause an “On to Suspend” transition:

• Automatically: Suspend timeout expiration. (Default: 1 min, can be changed via control pannel: Settings/Control Panel/Power – see below)

•Manually: ON/OFF button momentary pressing (less than 2 seconds)

Page 657: HC700 SDK Specification

Page 657 of 680

Notes:

• While in suspend, HC700 system Led is blinking slowly in green.

• HC700 does not enter automatically to suspend mode while in CRADLE. (In addition On/OFF key pressing is disabled while in CRADLE)

• Any communication activity (on USB, Bluetooth, WLAN, and Serial) will prevent entering

automatically to suspend mode.

• Manually entering to suspend mode (i.e. short On/Off key pressing) is disabled during Bluetooth or WLAN active communication.

27.1.2 Suspend to On:

The following user activities will cause a “Suspend to On” transition: (i.e. wake-up events)

• ON/OFF button momentary pressing.

• HC700 insertion to CRADLE.

• Pressing SCAN key.

• USB cable insertion/removal to/from external connector.

• Connect power to external connector.

• RTC alarm. Notes:

• Tapping on the touch screen - does not wake the HC700.

• Pressing any key - does not wake the HC700.

27.1.3 Suspend to Unattended:

The following system activities will cause a “Suspend to Unattended” transition: (i.e. wake-up events)

• Receive data on the BT radio.

Notes:

• While in Unattended, HC700 system Led is blinking in green according to the following pattern: 3 fast blinks with pause.

• Data on USB, and Data on External serial – do not wake the HC700.

Page 658: HC700 SDK Specification

Page 658 of 680

27.1.4 Unattended to Suspend:

The following activities will cause an “Unattended to Suspend” transition:

• Suspend timeout expiration. Notes:

• Any communication activity (on USB, Bluetooth, and Serial) will prevent entering automatically to suspend mode.

27.1.5 Unattended to On: User activity will cause “Unattended to On” transition. User activity is defined as:

• Any key pressing • ON/OFF button pressing • Touch panel activation • Insertion to CRADLE • USB cable insertion/removal to/from external connector

27.1.6 On to Critical Off: If HC700 is not working from external power and is not in the CRADLE, the following activities will cause “On to Critical Off” transition:

• Battery removal

• Critical Off condition (The main battery had reached a remaining capacity equivalent to 72 sleep hours)

Notes:

• HC700 does not enter Critical Off while in CRADLE or connected to external power.

27.1.7 On to Off: If HC700 is not working from external power and is not in the CRADLE, the following activities will cause “On to Off” transition:

• ON/OFF button continuous pressing (more than 2 seconds) Notes:

• ON/OFF button is disabled while in CRADLE or connected to external power.

Page 659: HC700 SDK Specification

Page 659 of 680

27.1.8 Critical Off to On: The following activities will cause “Critical off to On” transition:

• New battery installed and ON/OFF button momentary pressing (if battery is OK). • Insert the HC700 to CRADLE. • Connect power to external connector.

Notes:

o If the HC700 was left without a main battery for less than 5 minutes then when resuming from Critical-Off the HC700 will return to the same place where it was when entering the Critical-Off state.

o If the HC700 entered Critical Off (Battery taken out or critical voltage detected) while

the previous resume process was not completed then when resuming from Critical Off, a warm boot will be performed and a special sound will be played.

o If the HC700 was left without a main battery for more than 5 minutes then when

resuming from Critical-Off a cold boot will be performed. (This is because the backup battery lasts only for 5 minutes)

o While the resume from critical-off process is on going (~6 seconds) and the HC700 is

working from battery (not in CRADLE and not working from external power) the Red system Led will be ON – for informing the user that during that time he is not allowed to take out the battery. After the resume process has finished successfully, the Red Led will be shut off.

27.1.9 Off to On: The following activities will cause “Off to On” transition:

• ON/OFF button momentary pressing (if battery is OK). • Insert the HC700 to CRADLE. • Connect power to external connector.

Notes:

o While the resume from Off process is on going (~6 seconds) and the HC700 is working from battery (not in CRADLE and not working from external power) the Red system Led will be ON – for informing the user that during that time he is not allowed to take out the battery. After the resume process has finished successfully, the Red Led will be shut off.

27.1.10 Suspend to Critical Off: If HC700 is not working from external power the following activities will cause “Suspend to Critical Off” transition:

• Battery removal

• Critical Off condition (The main battery had reached a remaining capacity equivalent to 72 sleep hours)

Page 660: HC700 SDK Specification

Page 660 of 680

Notes:

• HC700 does not enter Critical Off while in CRADLE or connected to external power.

27.1.11 On to Screen Off: Screen Off timeout expiration will cause “On to Screen Off” transition. User inactivity means:

• No key pressing • No touch panel activation • No insertion or extraction from CRADLE. • No USB cable insertion/removal to external connector

Default Screen Off timeout is 1 minute. This value can be changed via control panel: Settings/Control Panel/Display – see below.

27.1.12 Screen Off to On: User activity will cause “Screen Off to On” transition. User activity is defined as:

• Any key pressing • ON/OFF button pressing • Touch panel activation • Extraction from CRADLE • USB cable insertion/removal to/from external connector

Backlight (Display, Keyboard)

Page 661: HC700 SDK Specification

Page 661 of 680

On HC700 the keyboard & display backlights are separated since the Display BL (actually brightness) needs to be used also during the day.

On HC700 startup: Display backlight is on and Keyboard backlight is off.

27.1.13 Display Backlight – ON, OFF, Levels

• The Display backlight can be turned ON or turned OFF by:

• Pressing the Shift key for 2 seconds.

• Using the Display_SetBacklightState API.

• Using the Intensity tab from the Backlight control panel. (Settings/Control Panel/Backlight) • The Display backlight level (up to 32) can be changed by:

• Pressing the Shift and up arrow key simultaneously – to increase the backlight level and

also to turn the backlight ON.

• Pressing the Shift and down arrow key simultaneously – to decrease the backlight level.

• Using the Display_SetBacklightIntensity API.

• Using the Intensity tab from the Backlight control pannel. (Settings/Control Panel/Backlight)

27.1.14 Keyboard Backlight – ON, OFF, Levels

• The Keyboard backlight can be turned ON by:

Page 662: HC700 SDK Specification

Page 662 of 680

• Pressing the Shift key for 4 seconds. (Then both Display BL and Keyboard BL will be ON)

• Note: Pressing again the Shift key for 2 seconds will turn off both the Display BL and Keyboard BL.

• Using the KBD_SetBacklightState API.

• Using the Intensity tab from the Backlight control panel. (Settings/Control Panel/Backlight)

• The Keyboard backlight level (up to 15) can be changed by:

• Pressing the Shift and Right Arrow key simultaneously – to increase the backlight level and also to

turn the backlight ON. • Pressing the Shift and Left Arrow key simultaneously – to decrease the backlight level. • Using the KBD_SetBacklightIntensity API. • Using the Intensity tab from the Backlight control panel. (Settings/Control Panel/Properties)

27.1.15 Display & Keyboard Backlights – Automatic OFF by inactivity

• HC700 turns off the Display & Key board backlights after inactivity timeouts.

• There are separate backlight inactivity timeouts for the Display and for the Keyboard.

• There are separate backlight inactivity timeouts for working on battery and for working on external power.

• The default inactivity timeout for turning OFF the Display when working from battery is 10

seconds.

Page 663: HC700 SDK Specification

Page 663 of 680

• The default inactivity timeout for turning OFF the Display when working from external power is:

1 minute.

• These timeouts may be changed by • API: DISPLAY_SetBacklightTimeout • Control panel: ‘Battery Power’ and ‘External Power’ tabs in the Backlight applet in the

control panel (Settings/Control Panel/Backlight).

• The default inactivity timeout for turning OFF the Keyboard when working from battery is 15 seconds.

• The default inactivity timeout for turning OFF the Keyboard when working from external power

is: 15 seconds.

• These timeouts may be changed by • API: KBD_SetBacklightTimeout • Control panel: ‘Battery Power’ and ‘External Power’ tabs in the Backlight applet in the

control panel (Settings/Control Panel/Backlight).

Page 664: HC700 SDK Specification

Page 664 of 680

When HC700 is docked in CRADLE:

• Upon docking in the cradle the Keyboard backlight and the Display backlight will be turn ON with the maximum intensity level for 10 seconds.

LCD

• HC700 automatically turns off the LCD after user inactivity timeout while in CRADLE or connected to external power. Meaning the system power state is changed to “Screen Off”.

• HC700 turns the LCD on in case of user activity. Meaning the system power state is changed

to “On”. User activity is defined as: • Any key pressing • ON/OFF button pressing • Touch panel activation • Extraction from CRADLE • USB cable insertion/removal to/from external connector

• There is separate user inactivity timeouts for working on battery and for working on AC power.

• The default user inactivity timeout for working from battery is disabled.

• The default user inactivity timeout for working from external power is 1 minute.

• These timeouts may be changed by

• API: PM_SetTimeout • Control Panel: ‘Display Off’ tab in the Display applet in the control panel

(Settings/Control Panel/Display).

Page 665: HC700 SDK Specification

Page 665 of 680

Battery States and notifications The main battery and backup battery status can be viewed via the Power applet in the control pannel. (Settings/Control Panel/Power)

Applications can use the standard API GetSystemPowerStatusEx2 for receiving more detailed information. (Refer to the API doc).

When the main battery reaches low capacity, an icon representing a not-full battery will appear on the task bar.

Page 666: HC700 SDK Specification

Page 666 of 680

When the main battery reaches very low capacity, an icon representing an empty battery will appear on the task bar and a “Main Battery Very Low” warning dialog box will be displayed. The user should immediately replace the main battery with another one or insert the HC700 into the CRADLE for recharging.

Page 667: HC700 SDK Specification

Page 667 of 680

In order to verify the battery status: Tap the digital clock on the right hand corner of the screen. A notification bubble will appear on the screen containing the battery status icon: Battery in charging, battery full, battery half or battery low charged. When the main battery is in charging representing charging will appear on the task bar. Battery in charging battery full

Bluetooth Power Management On HC700 startup the Bluetooth radio is automatically turned ON and put into sleep mode. The Bluetooth radio is in sleep mode while there is no BlueTooth activity. When the HC700 initiates a BlueTooth write, the BlueTooth radio wakes up, performs the writing and goes back to sleep after the activity finishes. If the HC700 receives data or other requests from another BlueTooth device, the BlueTooth radio inside the HC700 wakes up and if the HC700 is in suspend mode wakes also the HC700 up.

WLAN Power Management By default - on HC700 startup the WLAN radio is OFF. The WLAN radio can be turned ON or turned OFF in one of the following ways:

• By using the WLAN API: WLAN_SetRadioState • By using the WLAN control panel (Settings/Control Panel/Wireless LAN Power):

Page 668: HC700 SDK Specification

Page 668 of 680

While the WLAN radio is ON – the HC700 will not enter suspend either automatically or intentionally by pressing the On/Off button.

Power Management while in CRADLE

• When HC700 is docked in CRADLE the display backlight and the keyboard backlight is turned ON with the maximum level for 10 seconds.

• HC700 system Led will display battery charging status as described below:

State System LED Charging Error / Defective Battery Blinking Red / Green Waiting to charge Blinking Yellow Normal Charging Steady Red Fully Charged Steady Green

Page 669: HC700 SDK Specification

Page 669 of 680

APPENDIX D

Resume from Critical OFF

Critical Off – Overview

On to Critical Off: If HC700 is not working from external power the following activities will cause “On to Critical Off” transition:

• Battery removal

• Critical Off condition (The main battery had reached a remaining capacity equivalent to 72 sleep hours)

Notes:

1. HC700 does not enter Critical Off while in Communication Cradle. 2. HC700 does not enter Critical Off while connected to external power. (ON/OFF pressing is

disabled)

Critical Off to On: The following activities will cause “Critical Off to On” transition:

• New battery installed and ON/OFF button momentary pressing (if battery is OK). • Insert the HC700 to Cradle. • Connect power to external connector.

Notes:

o If the HC700 was left without a main battery for less than 5 minutes then when resuming from Critical-Off the HC700 will return to the same place where it was when entering the Critical-Off state.

o If the HC700 entered Critical Off (Battery taken out or critical voltage detected) while

the previous resume process was not completed then a warm boot will be performed and a special sound will be played.

o If the HC700 was left without a main battery for more than 5 minutes then when

resuming from Critical-Off a cold boot will be performed. (This is because the backup battery lasts only for 5 minutes)

o While the resume from critical-off process is on going (~6 seconds) and the HC700 is

working from battery (not in Cradle and no power is connected to external connector) the Red Led will be ON – for informing the user that during that time he is not allowed to take out the battery. After the resume process has finished successfully the Red Led will be shut off.

Suspend to Critical Off:

Page 670: HC700 SDK Specification

Page 670 of 680

If HC700 is not working from external power the following activities will cause “Suspend to Critical Off” transition:

• Battery removal

• Critical Off condition (The main battery had reached a remaining capacity equivalent to 72 sleep hours)

Notes:

• HC700 does not enter Critical Off while in Cradle or connected to external power.

Entering and Resuming from Critical Off – Use Cases All the use cases are for HC700s working on batteries without external power and out of the Cradle.

No communication/No Scanning Regular (no communication/no scanning) activity is ongoing while entering Critical Off. (I.e. – the focus is on an application that does not do communication of any type – in the background other “no communication” apps are running) When resuming from critical off:

• All the applications will return exactly to the same place where they were before. • The focus application will be the same one as before with the same GUI on the screen.

System Startup

27.1.16System Startup – Scenario 1 (After System startup completed) Entering Critical-Off state occurs after the system startup completed. (See No communication/No scanning scenario).

When resuming from critical off: • The application will return exactly to the same place where it was.

27.1.17System Startup – Scenario 2 (Before System startup completed) Entering Critical-Off state occurs during the system startup – before startup completion. (No application was launched yet) When resuming from critical off: Sometimes (when startup procedure was interrupted after boot loader launching and before the OS started to launch)

• A warm boot will automatically take place. • No application is being affected – since none was running.

Sometimes (when startup procedure was interrupted after all the drivers finished launching)

• A normal resume from Critical Off will take place.

Page 671: HC700 SDK Specification

Page 671 of 680

• No application is being affected – since none was running.

Sometimes (when startup procedure was interrupted after some of the OS drivers had already launched but some were not)

• A warm boot will automatically take place. • No application is being affected – since none was running.

During previous Resume from Critical-Off

27.1.18During Previous Resume from Critical-Off (Before the resume process completed)

Trying to enter Critical-Off state during the previous resume from critical-off (before the resume/startup process has completed) Notes:

1. Entering Critical-Off during previous resume (The Red Led is ON)- by removing the battery or reaching a very low capacity – will immediately shut down and will not finish the previous resume.

2. When resuming from critical off:

If the previous resume from critical-off finished successfully then • The application will return exactly to the same place where it was.

Else (The previous resume has not finished)

• A warm boot will take place. • A special sound will be played boot.

During previous Resume from Suspend

27.1.19During Previous Resume from Suspend (Before the resume process completed)

Trying to enter Critical-Off state during the previous resume from Suspend (before the resume/startup process has completed)

Notes:

1. Entering Critical-Off during previous resume (The Red Led is NOT ON)- by removing the battery or by reaching a very low capacity - will immediately shut down and will not finish the previous resume

2. When resuming from critical off:

If the previous resume from suspend finished successfully then • The application will return exactly to the same place where it was.

Else (The previous resume has not finished)

• A warm boot will take place. • A special sound will be played.

Page 672: HC700 SDK Specification

Page 672 of 680

Scanner Scanning activity is ongoing while entering Critical Off. When resuming from critical off:

• The scanning application will return exactly to the same place where it was before. • If the Critical Off state actually interrupted a communication process with the scanner

then this operation is aborted. • The user can repeat the last operation with the scanner and continue to scan as

before.

BlueTooth Bluetooth activity is ongoing while entering Critical Off. Generally speaking the scenario of entering a critical-off situation and resuming from it – is observed and treated in the application as a Bluetooth disconnection (like an out of range situation) for the period of time that the Critical-Off situation lasted + the time it takes for re-initiating the Bluetooth module (1-5 seconds): While connected, the HC700 device and the remote device may go Out of range, or the remote device may be powered down during a connection. In those cases the BT connection on the HC700 is lost and the modem status signals (RING, RLSD) indicate a false status (OFF). These status signals can be read from the application by Calling the GetCommModemStatus () function. It is also possible to set up an event trigger waiting for modem status line changes to watch for this condition. At each data write call, the data will be sent if a connection exists and the return status will indicate success. When the connection is unknowingly lost, and a write data call is made, a new connection will be attempted. If the connection is successful, the write call will be completed and return success, however, if a new connection cannot be made, the write call will return with an unsuccessful write error (The number of bytes written will be 0). The application should be prepared to handle this possibility with each write call by performing retries on the write operation with delays between the retries attempts. At each data read call, if the connection does not exist then the read will return with 0 bytes read. The application should be prepared to handle this possibility with each read call.

If the application follows the above guidelines that are needed for a regular disconnection then this covers the Critical-Off situation as well.

27.1.20Bluetooth – Scenario 1 (Discoverable) Before entering Critical-Off state, no BlueTooth connection is already opened. The Bluetooth module is in sleep-listen mode (Discoverable) When resuming from critical off:

• The Bluetooth application will return exactly to the same place where it was. • If immediately after resuming, a Bluetooth operation is initiated then it will be delayed

for 1-5 seconds (the amount of time that takes to re-initiate the Bluetooth module) and eventually will be performed – no impact on the way the application is written.

27.1.21Bluetooth – Scenario 2 (Connected) When entering Critical-Off state, a BlueTooth connection is already opened but no data is currently being transferred. When resuming from critical off:

• The BlueTooth application will return exactly to the same place where it was. • The BlueTooth connection will be disconnected. • The Bluetooth module will be re-initiated (1-5 seconds)

Page 673: HC700 SDK Specification

Page 673 of 680

• If the next operation is a transmit operation (write) it will wait for the Bluetooth initialization to complete and will automatically establish a new connection.

• If the next operation is a receive operation (read) it will wait for the Bluetooth initialization to complete and then will fail because the connection is lost. (Number of read bytes will be 0). It’s up to the application protocol what to do in this case (i.e. send a NAK, do nothing and wait until a new connection is established by the other party, etc…).

27.1.22Bluetooth – Scenario 3 (In Transmit) When entering Critical-Off state, a BlueTooth session is already opened and data is currently being transferred. (Transmit mode) When resuming from critical off –

• The BlueTooth application will return exactly to the same place where it was. • The last transmitted packet of data was lost - did not completely reach the other side. • The transmit function will return with an error (number of transmitted bytes will be 0) • The BlueTooth session will no longer be valid. • If the application will retry to transmit the same packet then the transmission will wait

for the Bluetooth initialization to complete and will automatically establish a new connection.

27.1.23Bluetooth – Scenario 4 (In Receive) When entering Critical-Off state, a BlueTooth session is already opened and data is currently being transferred. (Receive mode) When resuming from critical off –

• The BlueTooth application will return exactly to the same place where it was. • The last transmitted packet of data was lost - did not completely reach the HC700. • The receive function will return with an error (number of received bytes will be 0) • The BlueTooth session will no longer be valid. • It’s up to the application protocol what to do in this case (i.e. send a NAK, do nothing

and wait until a new connection is established by the other party, etc…).

27.1.24Bluetooth – Scenario 5 (Connecting) When entering Critical-Off state, a BlueTooth session is in the initiation process. When resuming from critical off:

• The BlueTooth application will return exactly to the same place where it was. • The BlueTooth session initiation function will return with an error indicating a fail to

connect.

USB USB activity is ongoing while entering Critical Off.

Page 674: HC700 SDK Specification

Page 674 of 680

27.1.25USB – Scenario 1 When entering Critical-Off state, an ActiveSync over USB connection is already opened but no data is currently being transferred. The PC detects a disconnection and disconnects on its side. When resuming from critical off:

• The application on the HC700 will return exactly to the same place where it was. • The USB connection is automatically re-established. • Data can be transferred as before.

27.1.26USB – Scenario 2 (File Transfer) When entering Critical-Off state, an ActiveSync over USB connection is already opened and data (i.e. a file) is currently being transferred. The PC detects a disconnection and disconnects on its side. When resuming from critical off:

• The application on the HC700 will return exactly to the same place where it was. • The file was not transferred. • The USB connection is automatically re-established. • The file transfer may be re-initiated by the user.

27.1.27USB – Scenario 3 (Remote Tools) When entering Critical-Off state, a Remote Tools (i.e. Remote Registry) over USB connection is already opened and data (i.e. the registry) is currently being transferred from the HC700 to the PC. The PC detects a disconnection and disconnects on its side. When resuming from critical off:

• The application on the HC700 will return exactly to the same place where it was. • The registry was not transferred. • The USB connection is automatically re-established. • The Remote tool needs to be run again on the PC by the user.

27.1.28USB – Scenario 4 (Debugging) When entering Critical-Off state, an application debugging session over USB is already opened. The application for debugging is already running on the HC700 . The PC detects a disconnection and disconnects on its side. When resuming from critical off:

• The application on the HC700 will return exactly to the same place where it was. • The USB connection is automatically re-established. • The debugging session is aborted and need to be initiated again by closing the

application on the HC700 and rerunning it and launching again the debugger on the PC.

• NOTE – It is extremely unlikely to debug without external power – so this scenario will probably never happen.

Page 675: HC700 SDK Specification

Page 675 of 680

Mini SD File system activity is ongoing while entering Critical Off.

27.1.29MINI SD – Scenario 1 (File copy) When entering Critical-Off state, a file copy operation from/to the MINI SD card is in process. The operation is stopped in the middle. When resuming from critical off:

• The application will return exactly to the same place where it was. • The file copy operation is aborted after a timeout of a few seconds. The file was not

copied. • The file copy operation needs to be re-initiated.

Audio Audio activity is ongoing while entering Critical Off.

27.1.30Audio – Scenario 1 (Recording) When entering Critical-Off state, a recording operation is in process. The operation is stopped in the middle. When resuming from critical off:

• The application will return exactly to the same place where it was. • The recording will continue.

27.1.31Audio – Scenario 2 (Playing a wave file) When entering Critical-Off state, playing a wave file is in process. The operation is stopped in the middle. When resuming from critical off:

• The application will return exactly to the same place where it was. • The Playing is stopped. • The play operation needs to be re-initiated by the user.

Page 676: HC700 SDK Specification

Page 676 of 680

APPENDIX E HC700 Available and Combination Keys

AVAILABLE KEYS

Key Action Symbolic

constant HC700I/ HC700G

HC700L

26-characters alphabet a-z

Press key to generate a-z character

a – z

√ √

SHIFT Press SHIFT to toggle between alpha and numeric modes. In

numeric mode, pressing a key produces the yellow

number/symbol. Pressing SHIFT key

more than 2 seconds turn on the display backlight. Pressing SHIFT in alpha

mode will print the capital characters.

0 – 9 ? / : ” ! @ # $ %

^ & * + - . ,

√ √

FUNC Function key assigns the F1-F12.

Function key is once use key. The keys return to

previous state after pressing F1-F12 key.

VK_F1-VK_F12 √ √

P1,P2 Operate the application according to customer selection in registry.

√ √

ESC Go to previous VK-ESCAPE √ √ TAB Tab VK-TAB √ √ SP Press SP in alpha mode

produce a blank space. VK-SPACE √ √

BKSP Press BK-SP to erase the previews character in the

display.

VK-BACK √ √

OK Enter VK-RETURN √ √ Send Run the Phone

application. When phone application runs this key starts a call.

VK_F3 √ —

End Hang-Up the call VK-END √ — Previous Field VK_RIGHT √ √ Next Field VK_LEFT √ √

Up arrow key VK-UP √ √

Down arrow key VK-DOWN √ √

SCAN Press SCAN to scan bar codes

VK_SCAN √ √

PTT HC700I only

Page 677: HC700 SDK Specification

Page 677 of 680

Available Combination key

Key combination

Action Symbolic constant

HC700I/ HC700G

HC700L

ON-OFF

Press ON-OFF key to toggle the HC700 between

on and suspend. Pressing ON-OFF key more

than 4 seconds turns the HC700 off

√ √

SHIFT Press SHIFT for 3 Seconds to turn off the display

backlight

√ √

SHIFT + alphabet key

Press SHIFT + an Alphabet key to generate an uppercase letter. (Default is

lowercase letters)

A – Z √ √

SHIFT + Right key

Press SHIFT + Right Key to increase the keyboard

backlight intensity

√ √

SHIFT + Left key

Press SHIFT + Right Key to decrease the keyboard

backlight intensity

√ √

SHIFT + Up key

Press SHIFT + Up Key to increase the Display backlight intensity

√ √

SHIFT + Down key

Press SHIFT + Down Key to decrease the Display

backlight intensity.

√ √

SPACE + E key

Press SPACE + “E” Key to route call audio to Earpiece.

SPACE + S key

Press SPACE + “S” Key to route call audio to Speaker.

Pressing SHIFT + SP toggle cause the function

mode. In this function mode: Pressing “I” key will launch

the Platform Information Control Panel.

Pressing “C” key will launch the calibration

application. Pressing “Down” key will

decrease volume down. Pressing “Up” key will

increase volume up.

SHIFT + SP

Pressing “Scan” key will launch the virtual keyboard.

√ √

S + X + Press S+ X+ ON/OFF to produce Cold Reset

√ √

S + X + H Press S+ X+ H after S+ X+

ON/OFF to Clean persistent registry

A + F + P2 Press A+ F+ P2 to √

Page 678: HC700 SDK Specification

Page 678 of 680

produce Warm Reset A + F + ESC Press A+ F+ ESC to

produce Warm Reset √

All key combination functionality can be disabled by writing 0 to “Enabled” value in registry. The “Enable” value default is 1. The key located at: [HKEY_LOCAL_MACHINE\Software\Motorola\AppButtons] registry key.

Anyway, you can also disable the P1, P2 application keys by control panel: Settings->Personal->Buttons and put the all application in <None> value. Another way to disable these keys is to update the registry according to following fields: P1: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Shell\Keys\40C1] when the value Default should be empty. P2: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Shell\Keys\40C2] when the value Default should be empty.

Page 679: HC700 SDK Specification

Page 679 of 680

Page 680: HC700 SDK Specification

Page 680 of 680

APPENDIX F

HC700 - COM PORTS

1301 E. Algonquin Road, Schaumburg, IL 60196. MOTOROLA and the Stylized M Logo are registered in the U.S. Patent and Trademark Office. All other product or service names are the property of their respective owners. © Motorola, Inc. 2006.

COM # Name Purpose

COM0 Blue Tooth virtual port DUN profile

27.1.32 COM1

FFUART General (debug prints

COM2 BTUART Bluetooth physical port

COM3 STDUART IRDA communication

COM4 Dual Uart 1 WAN (G20/iO200) communication port

COM5 Dual Uart 2 Optional Debug Port

COM6 GPS COM Virtual or physical COM for GPS

COM7 Blue Tooth virtual port Serial profile – SPP client

COM8 Blue Tooth virtual port Serial profile – SPP server

COM9 Virtual port Communications via GPRS

MUX0 MUX Port on COM 4 RIL COM Port

MUX1 MUX Port on COM 4 Packet Data COM Port

USB0 Virtual COM for ActiveSync ActiveSync via USB

BTC1 Blue Tooth virtual port. Free for Customer future use

BTC2 Blue Tooth virtual port. Free for Customer future use

BTC3 Blue Tooth virtual port. Free for Customer future use

BTC4 Blue Tooth virtual port. Free for Customer future use

BTC5 Blue Tooth virtual port. Free for Customer future use

BTC6 Blue Tooth virtual port. LAN Access Profile

BTC9 Blue Tooth virtual port. Reserved for MCIL. Optionally for ActiveSync over Bluetooth in future.