HC700 SDK Specification

Data Design Center
Network & Enterprise Sector (NE)
HC700
Family of Handheld Computers
SOFTWARE DEVELOPMENT KIT

SPECIFICATION
VER 01.16
Page 1 of 680
Page 2 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
Wireless Imager section: add SCAN_AUTOEXPOSURE data type
01.07 23.05.2006 Motorola and provide more descriptions for SCAN_IMAGE_ACQUISITION
data type.
Wireless Imager section example: fix SCAN_SYM_MASC_FLAGS
01.08 06.07.2006 Motorola
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
Specify ocr direction as unsupported parameter in Wireless Imager
01.14 03.8.2006 Motorola
Scanning API
According to HC700 FCC grant WLAN & GPRS are not allowed to
01.15 07.8.2006 Motorola
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 3 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 4 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 5 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 6 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 7 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 8 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 9 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 fails, the return value is E_SCN_INVALIDHANDLE
QuickInfo
Example
Page 10 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
Example
Page 11 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
E_SCN_NULLPTR, E_SCN_INVALIDHANDLE, E_SCN_NOMOREITEMS.
Comments
None
QuickInfo
Example
Page 12 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 fails, the return value is E_SCN_INVALIDHANDLE.
Comments
None
QuickInfo
Example
Page 13 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
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
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
Page 14 of 680
Return Values
Comments
None
QuickInfo
Example
Page 15 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
Example
// Allocate a new scan buffer
lpScanBuffer = SCAN_AllocateBuffer(TRUE,dwSize);
Page 16 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 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
Example
// Deallocate the scan buffer
SCAN_DeallocateBuffer(lpScanBuffer);
Page 17 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
Return Values
If the function fails, the return value is E_SCN_INVALIDHANDLE or E_SCN_NOTENABLED.
Comments
None
QuickInfo
Example
// Disable the scanner
dwResult = SCAN_Disable(hScanner);
Page 18 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
Return Values
E_SCN_INVALIDHANDLE, E_SCN_ALREADYENABLED, E_SCN_CANTSTARTDEVICE,
E_SCN_CANTGETDEFAULTS, E_SCN_CREATEEVENT, E_SCN_CREATETHREAD.
Comments
None
QuickInfo
Example
// Enable the scanner
dwResult = SCAN_Enable(hScanner);
// If the enable failed
// Terminate scanning
ScanTerm();
// Report an error
ReportError(TEXT("ScanInit Enable"),dwResult);
Page 19 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
E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEIN,
E_SCN_INVALIDPARAM, E_SCN_READNOTPENDING.
Comments
None
QuickInfo
Example
// Cancel the read
SCAN_CancelRead(hScanner,1));
Page 20 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
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
E_SCN_INVALIDHANDLE, E_SCN_NOTENABLED, E_SCN_NULLPTR, E_SCN_BUFFERSIZEOUT,
E_SCN_STRUCTSIZE, E_SCN_INVALIDPARAM.
Comments
None
QuickInfo
Example
// Get current decoder parameters
dwResult = SCAN_GetDecoderParams(hScanner,lpDecoder,&decoder_params);
Page 21 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
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
Comments
This API is implemented for the restricted number of decoders (see Data Types section).
QuickInfo
See Also
SCAN_Open, SCAN_GetDecoderParams, DECODER_PARAMS, DECODER
Example
Page 22 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
lpDeviceInfo
Pointer to a DEVICE_INFO structure to be filled in with the device information.
Return Values
E_SCN_STRUCTSIZE.
Comments
None
QuickInfo
See Also
SCAN_Open, DEVICE_INFO
Example
Page 23 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
lpDecoderList
Pointer to a DECODER_LIST structure to be filled in with the enabled decoders.
Return Values
If the function fails, the return value is one of the following:
E_SCN_STRUCTSIZE, E_SCN_MISSINGFIELD
Comments
None
QuickInfo
See Also
SCAN_Open, SCAN_SetEnabledDecoders, DECODER_LIST
Example
// Get enabled decoder list
dwResult = SCAN_GetEnabledDecoders(hScanner,&DecoderList);
Page 24 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,
);
Parameters
hScanner
lpDecoderList
Pointer to a DECODER_LIST structure holding the new enabled decoders.
Return Values
E_SCN_STRUCTSIZE, E_SCN_MISSINGFIELD, E_SCN_INVALIDPARAM.
Comments
None
QuickInfo
See Also
SCAN_Open, SCAN_GetEnabledDecoders, DECODER_LIST
Example
dwResult = SCAN_SetEnabledDecoders(hScanner,&DecoderList);
Page 25 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
lpScanParams
Pointer to a SCAN_PARAMS structure to be filled in with the scan parameters.
Return Values
E_SCN_STRUCTSIZE.
Comments
None
QuickInfo
See Also
SCAN_Open, SCAN_SetScanParameters, SCAN_PARAMS
Example
// Get current scan parameters
dwResult = SCAN_GetScanParameters(hScanner,&scan_params);
Page 26 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
lpScanParams
Pointer to a SCAN_PARAMS structure holding the new scan parameters.
Return Values
Comments
None
QuickInfo
See Also
SCAN_Open, SCAN_GetScanParameters, SCAN_PARAMS
Example
SCAN_SetScanParameters(hScanner,&scan_params);
Page 27 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
lpReaderParams
Pointer to a READER_PARAMS structure to be filled in with the reader parameters.
Return Values
E_SCN_STRUCTSIZE.
Comments
None
QuickInfo
See Also
SCAN_Open, SCAN_SetReaderParameters, READER_PARAMS
Example
dwResult = SCAN_GetReaderParams(hScanner,&reader_params);
Page 28 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
lpReaderParams
Pointer to a READER_PARAMS structure to be set.
Return Values
E_SCN_STRUCTSIZE.
Comments
None
QuickInfo
See Also
SCAN_Open, SCAN_GetReaderParameters, READER_PARAMS
Example
dwResult = SCAN_SetReaderParams(hScanner,&reader_params);
Page 29 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
Return Values
If the function fails, the return value is E_SCN_INVALIDHANDLE or E_SCN_NOTENABLED
Comments
None
QuickInfo
Example
// Flush pending read
dwResult = SCAN_Flush(hScanner);
Page 30 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
lpScanStatus
Pointer to a SCAN_STATUS structure to be filled in with the scan status.
Return Values
E_SCN_STRUCTSIZE.
Comments
None
QuickInfo
Example
Page 31 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,
);
Parameters
hScanner
lpDecoderList
Pointer to a DECODER_LIST structure to be filled in with the supported decoders.
Return Values
If the function fails, the return value is one of the following:
E_SCN_STRUCTSIZE, E_SCN_MISSINGFIELD
Comments
None
QuickInfo
See Also
SCAN_Open, DECODER_LIST
Example
// Get enabled decoder list
dwResult = SCAN_GetSupportedDecoders(hScanner,&DecoderList);
Page 32 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
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.
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
Example
Page 33 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
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
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
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
Example
Page 34 of 680
// Submit the read
dwResult = SCAN_ReadLabelMsg(hScanner,lpScanBuffer,hwnd,uMsg,dwTimeout,NULL);
Page 35 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
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
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
QuickInfo
Example
Page 36 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
E_SCN_STRUCTSIZE.
Comments
None
QuickInfo
Example
Page 37 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
In case of error this function will return with one of exists error codes.
QuickInfo
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 38 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 39 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]
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.
lpImgBuffer [Out]
that receives the image data. Maybe NULL if bWait is equal to FALSE.
lpReserved
Return Values
QuickInfo
Example

dwResult = SCAN_GetLastImage(hScanner, TRUE, (LPSCAN_IMAGE_DATA)bImageBuffer, &dwBufferSize, &g_GetImageParams,
NULL);
{
wsprintf(szString, TEXT("Unable to take the picture. Error 0x%x"), dwResult);
Page 40 of 680
return;
}

DWORD dwImageDataSize = lpImageBuffer->dwImageDataSize;
Page 41 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]
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
lpimgParams [In]
This parameter contains the pointer to the structure defines the desired intelligent image relatively to barcode.
lpImgBuffer [Out]
that receives intelligent image data.
lpReserved
Return Values
QuickInfo
Example
SCAN_IQ_IMG_PARAMS ImgSigParams;
ImgSigParams.dwAspectRatio = 18;
ImgSigParams.nCenterXoffset = 2;
ImgSigParams.nCenterYoffset = -43;
ImgSigParams.dwImageWidth = 190;
Page 42 of 680
ImgSigParams.dwImageHeight = 50;
ImgSigParams.dwResolution = 3;
ImgSigParams.SignatureFormat= SCAN_FORMAT_RAW_BINARY;
ImgSigParams.dwReserved1 = 0;
ImgSigParams.dwReserved2 = 0;

dwResult = SCAN_GetIntelligentImage(hScanner, TRUE, ImgSigParams, (LPSCAN_IMAGE_DATA)bImageBuffer, &dwBufferSize,
NULL);
Page 43 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]
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
lpimgParams [In]
This parameter contains the pointer to the structure defines the desired intelligent image relatively to barcode.
lpImgBuffer [Out]
that receives intelligent image data.
lpReserved
Return Values
QuickInfo
Example
SCAN_IMG_ROI_PARAMS ImgRoiParams;
ImgRoiParams. dwXdimension = 15000;
Page 44 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;

dwResult = SCAN_GetIntelligentImage(hScanner, TRUE, ImgRoiParams, (LPSCAN_IMAGE_DATA)bImageBuffer, &dwBufferSize,
NULL);
Page 45 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]
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
Return Values
QuickInfo
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 46 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]
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
Return Values
QuickInfo
Example
dwResult = SCAN_FormatImageDatae(hScanner, SCAN_IMAGE_FORMAT_RAW_GRAY,
SCAN_IMAGE_FORMAT_TIFF_COMPRESSED, ImageFile, &dwImageSize , ImageBuffer.dwImageWidth,
Page 47 of 680
ImageBuffer.dwImageHeight, 0, NULL );
{
// Report an error
return;
}
Page 48 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]
lpParamData
Reserved. Set to NULL
lpParamSize
Reserved. Set to NULL
Return Values
QuickInfo
Example
dwResult = SCAN_SetDefaultParams(hScanner, NULL, NULL);
{
wsprintf(szString, TEXT("Unable to set the default params to imager. Error 0x%x"), dwResult);
return;
}
Page 49 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]
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
QuickInfo
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);
{
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 50 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]
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.
Return Values
QuickInfo
Example
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);
{
wsprintf(szString, TEXT("Unable to set decode mode param. Error 0x%x"), dwResult);
EndDialog(hDlg, 1);
return TRUE;
}
Page 51 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]
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.
lpImgStreamParams
This parameter defines the characteristics of the picture to be acquired from imager in stream mode.
lpReserved
Return Values
QuickInfo
Page 52 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]
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
Return Values
QuickInfo
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 = dwMinBlackness; // 300 - 30% blackness, 75 - 7.5% blackness
IsImgPresentParams.lpImgData = lpImageData;
DWORD dwResult = SCAN_IsImagePresent(hScanner, &IsImgPresent, &IsImgPresentParams, NULL);

{
wsprintf(szString, TEXT("Unable to check this image for blackness. Error 0x%x"), dwResult);
}
Page 53 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 54 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 55 of 680
Specifies last time took for decode operation. See SCAN_INTERNAL_GET_DECODE_TYPE for
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
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.
typedef enum
SCAN_IMAGER_INTERNAL_HHP = 0
} SCAN_IMAGER;
Members
Page 56 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.
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.
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 57 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.
// 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 58 of 680
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.
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)
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 59 of 680
SCAN_INTERNAL_DECODE_LIMIT_TIME
Description
Specifies the times limites for decoding barcodes.
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.
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 60 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.
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.
typedef enum
{
SCAN_INTERNAL_ENGINE_ID_NONE = 0 ,
SCAN_INTERNAL_ENGINE_ID_IT4200 = 1 ,
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 61 of 680
IT4000 imager type
IT4100 imager type
IT4300 imager type
SCAN_INTERNAL_ROTATION
Description
Specifies the imager rotation types.
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.
typedef struct
{
DWORD dwSize;
DWORD dwEngineID;
Page 62 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.
#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 63 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.
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 64 of 680
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 65 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 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
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 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 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
and define the specular settings
FixedExposure
It specifies the fixed exposure time for barcode and image aquciton.
FixedGain
It specifies the fixed gain value for barcode and image aquciton.
FixedFrameRate
It specifies the fixed frame rate value for barcode and image aquciton.
SCAN_INTERNAL_EXPOSURE_PARAMS
Description
Specifies the parameters for imager’s operation.
Page 66 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.
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.
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 67 of 680
Description
Specifies different imager engine parameters.
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
dwEngineId
dwFirmwareChecksum
Read only parameter. Defines the internal imager firmware version.
SCAN_INTERNAL_AZTEC_PARAMS
Description
Specifies the parameters for Aztec symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_AZTEC_PARAMS, *LPSCAN_INTERNAL_AZTEC_PARAMS;
Page 68 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
SCAN_INTERNAL_CODABAR_PARAMS
Description
Specifies the parameters for Codabar symbology type.
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
dwMaxLength
Page 69 of 680
SCAN_INTERNAL_CODE39_PARAMS
Description
Specifies the parameters for Code39 symbology type.
typedef struct
{
BOOL bSSXmit;
BOOL bCheckCharOn;
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
bXmitCheckChar
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 70 of 680
smaller than this minimum length are not reported by the engine. The minimum allowable value is 0.
The default is 1.
dwMaxLength
SCAN_INTERNAL_EAN13_PARAMS
Description
Specifies the parameters for Ean13 symbology type.
typedef struct
{
BOOL bAddenda2Digit;
BOOL bAddendaReq;
BOOL bAddendaSeparator;
} SCAN_INTERNAL_EAN13_PARAMS, *LPSCAN_INTERNAL_EAN13_PARAMS;
Members
bXmitCheckChar
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
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 71 of 680
SCAN_INTERNAL_EAN8_PARAMS
Description
Specifies the parameters for Ean8 symbology type.
typedef struct
{
BOOL bAddendaReq;
} SCAN_INTERNAL_EAN8_PARAMS, *LPSCAN_INTERNAL_EAN8_PARAMS;
Members
bXmitCheckChar
bAddenda2Digit
bAddenda5Digit
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
bAddendaSeparator
TRUE.
SCAN_INTERNAL_UPCA_PARAMS
Description
Specifies the parameters for Upca symbology type.
Page 72 of 680
typedef struct
{
BOOL bXmitNumSys;
BOOL bAddendaReq;
} SCAN_INTERNAL_UPCA_PARAMS, *LPSCAN_INTERNAL_UPCA_PARAMS;
Members
bXmitCheckChar
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
bAddenda5Digit
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
bAddendaSeparator
TRUE.
SCAN_INTERNAL_UPCE_PARAMS
Description
Specifies the parameters for Upce symbology type.
typedef struct
{
Page 73 of 680
BOOL bXmitNumSys;
BOOL bExpandVersionE;
BOOL bAddendaReq;
} SCAN_INTERNAL_UPCE_PARAMS, *LPSCAN_INTERNAL_UPCE_PARAMS;
Members
bXmitCheckChar
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
bAddenda5Digit
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
bAddendaSeparator
TRUE.
SCAN_INTERNAL_CODABLOCK_PARAMS
Description
Specifies the parameters for Codablock symbology type.
Page 74 of 680
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_CODABLOCK_PARAMS, *LPSCAN_INTERNAL_CODABLOCK_PARAMS;
Members
dwMinLength
dwMaxLength
SCAN_INTERNAL_IATA25_PARAMS
Description
Specifies the parameters for Iata25 symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_IATA25_PARAMS, *LPSCAN_INTERNAL_IATA25_PARAMS;
Members
dwMinLength
dwMaxLength
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 75 of 680
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_MATRIX25_PARAMS, *LPSCAN_INTERNAL_MATRIX25_PARAMS;
Members
dwMinLength
dwMaxLength
the default) is 80.
SCAN_INTERNAL_STRT25_PARAMS
Description
Specifies the parameters for Strt25 symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_STRT25_PARAMS, *LPSCAN_INTERNAL_STRT25_PARAMS;
Members
dwMinLength
dwMaxLength
the default) is 48.
SCAN_INTERNAL_PLESSEY_PARAMS
Description
Page 76 of 680
Specifies the parameters for Plessey symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_PLESSEY_PARAMS, *LPSCAN_INTERNAL_PLESSEY_PARAMS;
Members
dwMinLength
dwMaxLength
the default) is 48.
SCAN_INTERNAL_CODE16K_PARAMS
Description
Specifies the parameters for Code16k symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_CODE16K_PARAMS, *LPSCAN_INTERNAL_CODE16K_PARAMS;
Members
dwMinLength
dwMaxLength
the default) is 160.
SCAN_INTERNAL_TELEPEN_PARAMS
Description
Page 77 of 680
Specifies the parameters for Telepen symbology type.
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
dwMaxLength
the default) is 60.
SCAN_INTERNAL_POSICODE_PARAMS
Description
Specifies the parameters for Posicode symbology type.
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 78 of 680
dwMaxLength
the default) is 48.
SCAN_INTERNAL_KOREAPOST_PARAMS
Description
Specifies the parameters for KoreaPost symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_KOREAPOST_PARAMS, *LPSCAN_INTERNAL_KOREAPOST_PARAMS;
Members
dwMinLength
dwMaxLength
the default) is 48.
SCAN_INTERNAL_CHINAPOST_PARAMS
Description
Specifies the parameters for ChinaPost symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_CHINAPOST_PARAMS, *LPSCAN_INTERNAL_CHINAPOST_PARAMS;
Members
Page 79 of 680
dwMinLength
dwMaxLength
the default) is 80.
SCAN_INTERNAL_INT25_PARAMS
Description
Specifies the parameters for Int25 symbology type.
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
bXmitCheckDigit
dwMinLength
The default is 6.
dwMaxLength
the default) is 80.
SCAN_INTERNAL_MAXICODE_PARAMS
Page 80 of 680
Description
Specifies the parameters for Maxicode symbology type.
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
dwMaxLength
SCAN_INTERNAL_MSI_PARAMS
Description
Specifies the parameters for Msi symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_MSI_PARAMS, *LPSCAN_INTERNAL_MSI_PARAMS;
Members
bXmitCheckChar
Page 81 of 680
dwMinLength
The default is 4.
dwMaxLength
the default) is 48.
SCAN_INTERNAL_MESA_PARAMS
Description
Specifies the parameters for Mesa symbology type.
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
bIMSEnabled
BOOL variable that contains the enabled state of Interleaved 2 of 5 Mesa. TRUE = Enabled, FALSE =
Disabled.
b9MSEnabled
Page 82 of 680
Description
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
Members
dwMinLength
dwMaxLength
the default) is 81.
SCAN_INTERNAL_MICROPDF_PARAMS
Description
Specifies the parameters for Micropdf symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_MICROPDF_PARAMS, *LPSCAN_INTERNAL_MICROPDF_PARAMS;
Members
dwMinLength
dwMaxLength
Page 83 of 680
SCAN_INTERNAL_PDF417_PARAMS
Description
Specifies the parameters for Pdf417 symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_PDF417_PARAMS, *LPSCAN_INTERNAL_PDF417_PARAMS;
Members
dwMinLength
dwMaxLength
Description
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
Members
dwMinLength
Page 84 of 680
dwMaxLength
the default) is 80.
SCAN_INTERNAL_COMPOSITE_EX_PARAMS
Description
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
dwMaxLength
SCAN_INTERNAL_DATAMATRIX_PARAMS
Description
Specifies the parameters for Datamatrix symbology type.
typedef struct
{
WORD dwMinLength;
Page 85 of 680
WORD dwMaxLength;
} SCAN_INTERNAL_DATAMATRIX_PARAMS, *LPSCAN_INTERNAL_DATAMATRIX_PARAMS;
Members
dwMinLength
dwMaxLength
SCAN_INTERNAL_QR_PARAMS
Description
Specifies the parameters for Qr symbology type.
typedef struct
{
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_QR_PARAMS, *LPSCAN_INTERNAL_QR_PARAMS;
Members
dwMinLength
dwMaxLength
SCAN_INTERNAL_RSS_PARAMS
Description
Specifies the parameters for Rss symbology type.
typedef struct
{
Page 86 of 680
WORD dwMinLength;
WORD dwMaxLength;
} SCAN_INTERNAL_RSS_PARAMS, *LPSCAN_INTERNAL_RSS_PARAMS;
Members
dwMinLength
dwMaxLength
the default) is 80.
Description
typedef struct
{
BOOL bTwoCheckDigits;
WORD dwMinLength;
WORD dwMaxLength;
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
dwMaxLength
the default) is 80.
Page 87 of 680
SCAN_INTERNAL_PLANET_PARAMS
Description
Specifies the parameters for Planet symbology type.
typedef struct
{
} 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.
typedef struct
{
} 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
typedef union
{
SCAN_INTERNAL_AZTEC_PARAMS AztecParams;
Page 88 of 680
SCAN_INTERNAL_CODABAR_PARAMS CodabarParams;
SCAN_INTERNAL_CODE39_PARAMS Code39Params;
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_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 89 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
Code49Params
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 90 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
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 91 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
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 92 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.
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 93 of 680
typedef struct tagSCAN_FINDINFO
TCHAR szDeviceName[MAX_DEVICE_NAME];
TCHAR szPortName[MAX_DEVICE_NAME];
TCHAR szFriendlyName[MAX_PATH];
TCHAR szRegistryBasePath[MAX_PATH];
} SCAN_FINDINFO;
Members
StructInfo
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 94 of 680
typedef struct tagSCAN_BUFFER
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
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 95 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

SCNBUF_GETOFFSET(ptr) – Returns the offset to the data buffer following the

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.
typedef struct tagSCAN_STATUS
Page 96 of 680
{
BOOL bEnabled;
DWORD dwStatus;
DWORD dwKlasseEinsTimeUsed;
DWORD dwKlasseEinsTimeLeft;
} SCAN_STATUS;
Members
StructInfo
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 97 of 680
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_UNKNOWN 0xFF
#define LABELTYPE_AZTEC 0x60
#define LABELTYPE_MESA 0x61
#define LABELTYPE_COMPOSITE 0x63
#define LABELTYPE_DATAMATRIX 0x64
#define LABELTYPE_MAXICODE 0x65

Page 98 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.
enum tagSCAN_EVENT_CODE
{
Page 99 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 100 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
read.
Not supported.
SCAN_EVENT_SEQUENCE_ERROR
The MDD has encountered a non-fatal concatenation error. This event is only sent to the open
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.
typedef struct tagDECODER_PARAMS
DECODER cDecoder;
DWORD dwMinLength;
DWORD dwMaxLength;
DECODER_SPECIFIC dec_specific;
Page 101 of 680

} DECODER_PARAMS
Members
StructInfo
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 102 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;
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.
typedef struct tagCODABAR_PARAMS
BOOL bRedundancy;
BOOL bClsiEditing;
BOOL bNotisEditing;
Page 103 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.
typedef struct tagCODE39_PARAMS
BOOL bVerifyCheckDigit;
BOOL bReportCheckDigit;
BOOL bConcatenation;
BOOL bFullAscii;
BOOL bRedundancy;
Page 104 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
accepted.

= 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.
typedef struct tagI2OF5_PARAMS
Page 105 of 680

BOOL bRedundancy;
DWORD dwVerifyCheckDigit;
BOOL bReportCheckDigit;
BOOL bConvertToEAN13;
} I2OF5_PARAMS;
Members
bRedundancy
accepted.

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
BOOL bRedundancy;
Page 106 of 680

} CODE93_PARAMS;
Members
bRedundancy
accepted.
Note: This flag is only considered if LASER_SPECIFIC.dwLinearSecurityLevel =

SECURITY_REDUNDANCY_AND_LENGTH ( = 0 ).
Not supported .
CODE128_PARAMS
Description
{
BOOL bRedundancy;
BOOL bEAN128;
BOOL bISBT128;
BOOL bOther128;
} CODE128_PARAMS;
Members
bRedundancy
accepted.

Not supported .
Page 107 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.
typedef struct tagDEVICE_INFO
{
DECODERS Decoders;
BOOL bBeamWidth;
BOOL bAimMode;
BOOL bDirection;
BOOL bFeedback;
} DEVICE_INFO;
Members
StructInfo
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 108 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.
typedef struct tagDECODER_LIST
DECODERS Decoders;
}DECODER_LIST;
Members
StructInfo
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 109 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.
typedef struct tagSCAN_PARAMS
{
DWORD dwCodeIdType;
DWORD dwScanType;
BOOL bLocalFeedback;
DWORD dwDecodeBeepTime;
DWORD dwDecodeBeepFrequency;
Page 110 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
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 111 of 680
This parameters is not supported
bLocalFeedback
Flag to enable local feedback. If reset, feedback is only done on the scanner device.
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.
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.
typedef struct
{
WORD wImageTop;
WORD wImageLeft;
WORD wImageRight;
Page 112 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 113 of 680

SCAN_IMAGE_FORMAT
Description
The SCAN_IMAGE_FORMAT enumerator defines the list of supported image formats.
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.
typedef enum
Page 114 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.
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.
Page 115 of 680
typedef struct
DWORD dwStructSize;
DWORD dwImageHeight;
DWORD dwImageWidth;
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.
typedef struct
DWORD dwAspectRatio;
int nCenterXoffset;
int nCenterYoffset;
DWORD dwImageWidth;
DWORD dwResolution;
DWORD dwReserved1;
DWORD dwReserved2;
SCAN_IMAGE_FORMAT SignatureFormat;
Page 116 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.
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 117 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 118 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.
An error occurred opening the registry key containing the
E_SCN_OPENINGPARAMKEY 0xA0000003
driver's settings.
An error occurred reading the registry key containing the
E_SCN_READINGPARAMKEY 0xA0000004
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.
The physical device driver (PDD) DLL did not contain the
E_SCN_INVALIDDEVICE 0xA000000A
required entry points.
Required device is not present, already in use or not
E_SCN_DEVICEFAILURE 0xA000000B
functioning properly.
E_SCN_CANTSTARTDEVICE 0xA000000C The device could not be started.
The default parameters could not be obtained from the
E_SCN_CANTGETDEFAULTS 0xA000000D
physical device driver (PDD).
An attempt was made to use or stop the scanner device
E_SCN_NOTSTARTED 0xA000000E
and it was not started.
An attempt was made to start the device when the device
E_SCN_ALREADYSTARTED 0xA000000F
was already started.
An attempt was made to access the scanner device and it
E_SCN_NOTENABLED 0xA0000010
was not enabled.
An attempt was made to enable scanning when scanning
E_SCN_ALREADYENABLED 0xA0000011
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.
The size of the buffer passed as an input to
E_SCN_BUFFERSIZEIN 0xA0000015 DeviceIoControl is less than sizeof(STRUCT_INFO) or is
less than the size specified in StructInfo.dwUsed.
The size of the buffer passed as an output to
E_SCN_BUFFERSIZEOUT 0xA0000016 DeviceIoControl is less than sizeof(STRUCT_INFO) or is
less than the size specified in StructInfo.dwAllocated.
A STRUCT_INFO structure field is invalid. Either
E_SCN_STRUCTSIZE 0xA0000017 dwAllocated or dwUsed is less than the size of
STRUCT_INFO or dwUsed is greater than dwAllocated.
The size of a structure specified in a StructInfo is too small
E_SCN_MISSINGFIELD 0xA0000018
to contain a required field.
Page 119 of 680

E_SCN_INVALIDHANDLE 0xA0000019 An invalid handle was passed to a function.
The value of a parameter either passed as an argument to
E_SCN_INVALIDPARAM 0xA000001A 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.
Attempt to submit a read that is incompatible with reads
E_SCN_READINCOMPATIBLE 0xA0000023
already queued.
Attempt to perform physical device driver (PDD) feedback
E_SCN_NOFEEDBACK 0xA0000024
with no feedback capabilities.
Version of function not supported (e.g. ANSI vs.
E_SCN_NOTSUPPORTED 0xA0000026
UNICODE).
The requested operation is inconsistent with the current
E_SCN_WRONGSTATE 0xA0000027
state of the device.
No more items are available to be returned from
E_SCN_NOMOREITEMS 0xA0000028
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.
An exception occurred while trying to call the scanner
E_SCN_EXCEPTION 0xA000002B
driver.
A scanner API function failed with a non-scanner API error
E_SCN_WIN32ERROR 0xA000002C
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.
Internal error in signature capture function: code id of
E_SCN_BADSMARTIMAGE 0xA0000040 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
The resulting image was zoomed more than required by
E_SCN_TOO_MUCH_INTERPOLATION 0xA0000042
ZoomLimit parameter.
Page 120 of 680

E_SCN_PDD_EXCEPTION 0xA0000043 An exception occurred in underlaying imager driver
Page 121 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 122 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 123 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
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 124 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 125 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 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
Example
HANDLE hScanner;
DWORD dwResult;
// Open scanner
dwResult = SCAN_Open(TEXT("BT_Server"), &hScanner);
{
// Report an error
return;
Page 126 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]
Return Values
If the function fails, the return value is E_SCN_INVALIDHANDLE
Comments
None
QuickInfo
Example
DWORD dwResult;
dwResult = SCAN_Close( hScanner );
{
// Report an error
return;
}
Page 127 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]
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 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
Example
DWORD dwResult;
HANDLE hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
dwResult = SCAN_RegisteNotificationsr(hScanner, hEvent, NULL, NULL );
{
// Report an error
return;
}
Page 128 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]
Return Values
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
Example
DWORD dwResult;
dwResult = SCAN_DeRegisteNotificationsr(hScanner );
{
// Report an error
return;
}
Page 129 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]
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
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
Example
DWORD dwResult;
SCAN_NOTIFICATION_TYPE notifyType;
DWORD dwBufferSize = 4096;
LPBYTE pBuffer = malloc(4096);
dwResult = SCAN_GetNotificationResult(hScanner, &notifyType, pBuffer, &dwBufferSize);
{
// Report an error
return;
}
Page 130 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]
AckResponse [In]
The acknowledge that will be sent back to remote imager device.
Return Values
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
Example
DWORD dwResult;
SCAN_ACKNOWLEDGE Ack;
dwResult = SCAN_AcknowledgeResponse(hScanner, Ack);
{
// Report an error
return;
}
Page 131 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]
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
Comments
The user must call SCAN_RegisterNotifications function before this function to be ready to receive the scanning
notification results.
QuickInfo
Example
DWORD dwResult;
SCAN_SOFT_TRIGGER softTrigger = SCAN_TRIGGER_SINGLE;
dwResult = SCAN_SetSoftTrigger(hScanner, softTrigger);
{
// Report an error
return;
}
Page 132 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]
remoteParams [In]
Specifies the previously known parameters of remote scanner to connect to.
Return Values
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
Example
DWORD dwResult;
SCAN_REMOTE_PARAMS remoteScanner;;
wsccpy( remoteScanner.BdAdress, TEXT(33:33:33:33:33:33“”));
dwResult = SCAN_RemoteConfig(hScanner, remoteScanner);
{
// Report an error
return;
}
Page 133 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]
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
Comments
This function returns the current set of enabled symbologies by remote imagers.
Only enabled symbologies will be readable by remote scanner.
QuickInfo
Example
DWORD dwResult;
BOOL symbologyStatus[SCAN_MAX_SYMBOLOGIES];
dwResult = SCAN_GetEnabledSymbologies(hScanner, symbologyStatus);
{
// Report an error
return;
}
if( symbologyStatus[SYM_CODE39] )
MessageBox( “Code 39 enabled” );
Page 134 of 680

SCAN_SetEnabledSymbologies
Description
The SCAN_SetEnabledSymbologies function used to set the desired list of currently enabled symbologies on
Function Prototype
DWORD SCAN_SetEnabledSymbologies(HANDLE hScanner, LPBOOL lpbSymStatus)
Parameters
hScanner [In]
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
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
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);
{
// Report an error
return;
}
Page 135 of 680

SCAN_GetImagerParams
Description
The SCAN_GetImagerParams function used to get current parameters set of specified configuration item from
Function Prototype
DWORD SCAN_GetImagerParams(HANDLE hScanner, SCAN_PARAM_TYPE ParamType,
LPVOID lpParamData, LPDWORD lpdwParamSize)
Parameters
hScanner [In]
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.
Return Values
Comments
This function returns the current configuration and parameters of remote imagers.
QuickInfo
Example

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 );
{
// Report an error
return;
}
if( SymbologyParams.code39.dwFlags & SCAN_SYMBOLOGY_ENABLE )

{
// Symbology enabled
}
Page 136 of 680
else
{
// Symbology disabled
}
Page 137 of 680

SCAN_SetImagerParams
Description
The SCAN_SetImagerParams function used to set desired parameters set of specified configuration item to
Function Prototype
DWORD SCAN_SetImagerParams(HANDLE hScanner, SCAN_PARAM_TYPE ParamType,
LPVOID lpParamData, LPDWORD lpdwParamSize)
Parameters
hScanner [In]
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
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
Example

SCAN_PARAM_TYPE paramType = SCAN_PARAM_TYPE_SYMBOLOGY;
// Must to clear the structure before calling SCAN_SetImagerParams

SymbologyParams. code39. dwMask = SCAN_SYM_MASK_FLAGS;

SymbologyParams. code39. dwFlagsk &= ~SCAN_SYMBOLOGY_ENABLE;
dwResult = SCAN_SetImagerParams(hScanner, paramType, &SymbologyParams, &dwParamSize );
{
// Report an error
return;
}
Page 138 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]
Return Values
Comments
When remote imager device disconnects from terminal, the last one will receive the notification about the
disconnection.
QuickInfo
Example
dwResult = SCAN_RemoteDisconnect(hScanner)
{
// Report an error
return;
}
Page 139 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]
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
Comments
If the size specified by szRemoteBDAddress parameter is not sufficient, the function will fail and
lpdwRemoteBDAddressSize will return the required size.
QuickInfo
Example
TCHAR szRemoteBDAdress[20];
DWORD dwSize = sizeof(szRemoteBDAdress);
dwResult = SCAN_GetRemoteCDAddress(hScanner, szRemoteBDAdress, &dwSize)
{
// Report an error
return;
}
Page 140 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]
Return Values
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
Example
dwResult = SCAN_Enable(hScanrre)
{
// Report an error
return;
}
Page 141 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]
Return Values
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
Example
dwResult = SCAN_Disable(hScanrre)
{
// Report an error
return;
}
Page 142 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]
szFirmwareFilename [In]
The absolute file name of the new firmware to upgrade.
Return Values
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
Example
dwResult = SCAN_UpgradeFirmware(hScanrre, TEXT(“c:\Application.bin”))
{
// Report an error
return;
}
Page 143 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]
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
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
Example
LPSCAN_FIRMWARE_UPGRADE_STATUS IsUpgradeRequired;
dwResult = SCAN_IsRemoteUpgradeFirmware (hScanrre, TEXT(“c:\Firmware.bin”), &IsUpgradeRequired)
{
// Report an error
return;
}
Page 144 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]
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
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
Page 145 of 680

Example
wcscpy(szCmd, TEXT(“RF1000D200V3PF2000D100V1PF3000D300V4PLRI250C10”));
dwResult = SCAN_BeepLed(hScanrre,szCmd, 0);
{
// Report an error
return;
}
Page 146 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]
bWait [In]
Only FALSE is supported. This value will define the notification mechanism for getting resulting image.
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
Return Values
QuickInfo
Example
// read image with current image parameters
dwResult = SCAN_GetRemoteImage(g_hRemoteScanner, FALSE, NULL, NULL, NULL);

{
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 147 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]
bWait [In]
lpImageTransferParams [In]
This parameter defines the parameters the image will be transferred with.
lpReserved
Return Values
QuickInfo
Example
// read image with current image parameters
dwResult = SCAN_GetRemoteLastImage(g_hRemoteScanner, FALSE, NULL, NULL);

{

return 0;
}
Page 148 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]
bWait [In]
SignatureParams [In]
This parameter configures the taking of signature capting image.
lpReserved
Return Values
QuickInfo
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);

{

return 0;
}
Page 149 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.
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 150 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.
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 151 of 680

SCAN_ACKNOWLEDGE
Description
The SCAN_ACKNOWLEDGE enumeration is used to specify the kind of acknowledge response to be

sent to remote imager.
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.
#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.
#define SCAN_MAX_MESSAGE_LEN 5000
typedef struct
Page 152 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.
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 153 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.
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.
typedef struct
DWORD dwStructSize;
TCHAR pchMessage[MAX_MESSAGE_LEN];
Scan_Symbology SymbologyType;
DWORD dwLength;
} Scan_Decode_Msg;
Members
Page 154 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.
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 155 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
SCAN_SYMBOLOGY
Description
The SCAN_SYMBOLOGY enumeration is used for identification of different symbologies used for
scanning be remote imager.
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 156 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.
typedef struct
DWORD dwConnectTimeout;
DWORD dwNoBarcodeTimeout;
DWORD dwSuspendTimeout;
DWORD dwNoAckTimeout;
DWORD dwReserved1;
Page 157 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
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.
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 158 of 680

dwReserved1
dwReserved2
SCAN_REMOTE_DECODE_MODE
Description
The SCAN_REMOTE_DECODE_MODE structure is used to configure a decoding mode (algorithm) by

remote imager.
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.
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 159 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.
#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
TCHAR szRemoteBluetoothVersion
TCHAR szRemoteApplicationDecoderVersion
TCHAR szRemoteApplicationScanDriverVersion
TCHAR szRemoteApplicationTimeStamp
[SCAN_MAX_APPLICATION_TIME_STAMP_LENGTH];
Page 160 of 680

TCHAR szRemoteProductManufactureDate
[SCAN_MAX_FACTORY_FILE_MESSAGE_LENGTH];
TCHAR szRemoteProductSerialNumber
TCHAR szRemoteProductType
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 161 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.
// 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.
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 162 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.
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.
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 163 of 680
SCAN_AUTOEXPOSURE
Description
Specifies possible capture mode for acquiring images by remote imager.
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.
// 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 164 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

#define CAPTURE_MASK_ALL 0x007ff

typedef struct
{
DWORD dwStructSize;
DWORD dwMask;
DWORD dwWhiteValue;
DWORD dwWhiteWindow;
DWORD dwMaxNumExposures;
SCAN_DUTY_CYCLE illuminatCycle;
Page 165 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.
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.
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 166 of 680

fixedExposure
Specifies the fixed explosure value for image acquisition.
frameRate
This parameter defines the starting frame rate to be used by the auto exposure logic during image
acquisition.
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.
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.
typedef union
Page 167 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.
typedef union
SCAN_1_FRAMES_PER_SEC = 1 ,
SCAN_2_FRAMES_PER_SEC ,
SCAN_10_FRAMES_PER_SEC = 10,
} SCAN_FRAME_RATE;
Members
SCAN_X_FRAMES_PER_SEC
Specifies X frames per seconds.
SCAN_AUTOEXPLOSURE
Page 168 of 680
Description
The SCAN_AUTOEXPLOSURE union represents.
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 169 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.
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 170 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.
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 171 of 680
The SCAN_REMOTE_DECODE_LIMIT_TIME structure is used to configure barcode decoder
searching times by remote imager.
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.
typedef struct
{
DWORD dwStructSize;
DWORD dwImageWidth;
DWORD dwCapturedFrames;
DWORD dwGain;
DWORD dwExposureTime;
DWORD dwUnderexposedPixels;
DWORD dwOverexposedPixels;
DWORD dwImageDataOffset;
DWORD dwImageDataSize;
} SCAN_REMOTE_IMAGE_DATA;
Members
Page 172 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.
typedef struct
{
DWORD dwAspectRatio;
int nCenterXOffset;
int nCenterYOffset;
DWORD dwImageWidth;
Page 173 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.
typedef struct
{
SCAN_FIRMWARE_TYPE ProgrammingFirmwareType;
DWORD dwTransferProgress;
SCAN_TRANSFER_STATUS dwTransferStatus;
DWORD dwProgrammingProgress;
SCAN_PROGRAMM_STATUS dwProgrammingStatus;
} SCAN_PROGRESS;
Members
Page 174 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.
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 175 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.
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 176 of 680
BlueTooth passkey error.
SCAN_SYM_CONFIG
Description
The SCAN_SYM_CONFIG structure is used to keep symbologie’s parameters.
typedef struct
DWORD dwStructSize;
SCAN_CODABAR_CFG codabar;
SCAN_CODE11_CFG code11;
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 177 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
Code39
Code49
Code93
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 178 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 179 of 680
The ScanSymFlagsOnly structure is used to contains symbology parameters without supported
symbologies lengths.
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.
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 180 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.
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 181 of 680

The ScanOCRMode_t specifies which OCR fonts (if any) are selected for decoding.
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.
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 182 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_TRIOPTIC39_CFG ScanSymFlagsOnly
#define SCAN_COUPONCODE_CFG ScanSymFlagsOnly
#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 183 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_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 184 of 680

Example
#include <ScanCApi.h>
...
#define BUFFER_SIZE (24*1024)
...
HANDLE hScanner;
DWORD dwResult;
dwResult = SCAN_Open(TEXT("BT_Server"), &hScanner);

{
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 185 of 680
ReportError("Out of memory");
return 0;
}
// Register for waiting notifications on event

dwRes = SCAN_RegisterNotifications(hScanner, hEvent, NULL, NULL);
if( dwRes != E_SCN_SUCCESS )
{
ReportError("SCAN_RegisterNotifications", dwRes);
free(pBuffer);
return 0;
}
// Enable barcode scaning

dwRes = SCAN_Enable(hScanner);
{
ReportError("SCAN_Enable", dwRes);
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);
{
ReportError("SCAN_GetNotificationResult failed", dwRes);
continue;
}
// Recognize notification type

switch( notifyType )
Page 186 of 680
{
case SCAN_NOTIFY_REMOTE_CONNECT:
...
ShowMessage("Remote imager connected");
...
// Send set of desired parameters
SCAN_PARAM_TYPE paramType =
SCAN_PARAM_TYPE_SYMBOLOGY;
// 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 187 of 680
lpScnPicture = (LPSCAN_IMAGE_DATA)pBuffer;
...
ShowPicture(lpScnPicture+lpScnPicture. DwImageDataOffset,
lpScnPicture. DwImageDataSize);
...
break;
}
}
SCAN_DeRegisterNotifications(hScanner);
free(pBuffer);
}
Page 188 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.
The physical device driver (PDD) DLL did not contain the
E_SCN_INVALIDDEVICE 0xA000000A
required entry points.
Required device is not present, already in use or not
E_SCN_DEVICEFAILURE 0xA000000B
functioning properly.
An attempt was made to access the scanner device and it
E_SCN_NOTENABLED 0xA0000010
was not enabled.
E_SCN_NULLPTR 0xA0000013 A NULL pointer was passed for a required argument.
A STRUCT_INFO structure field is invalid. Either
E_SCN_STRUCTSIZE 0xA0000017 dwAllocated or dwUsed is less than the size of
E_SCN_INVALIDHANDLE 0xA0000019 An invalid handle was passed to a function.
The value of a parameter either passed as an argument to
E_SCN_INVALIDPARAM 0xA000001A 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.
Version of function not supported (e.g. ANSI vs.
E_SCN_NOTSUPPORTED 0xA0000026
UNICODE).
No more items are available to be returned from
E_SCN_NOMOREITEMS 0xA0000028
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.
An exception occurred while trying to call the scanner
E_SCN_EXCEPTION 0xA000002B
driver.
A scanner API function failed with a non-scanner API error
E_SCN_WIN32ERROR 0xA000002C
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 189 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 190 of 680

4. Wireless Imager Usage Scenario
Signature Capturing Scenarios

• For internal imager:
Start signature capture screen.
bSignatureCapture = TRUE;
Call SCAN_ReadLabelEvent(hEvent) to read

a barcode.
Wait for barcode on event provided by

SCAN_ReadLabelEvent
Yes
No
bSignatureCapture == TRUE
Call Process Barcode label

SCAN_GetIntelligentImage(TRUE) received.
Process Signature Capture received
Page 191 of 680

• For wireless imager:
Start signature capture screen.

bSignatureCapture = TRUE;
Call SCAN_RegisterNotifications(hEvent) to
register to receive all notifications from
imager.
Call SCAN_SetSoftTrigger to scan the

barcode label
Wait for barcode notification on event

provided by SCAN_RegisterNotifications
No
bSignatureCapture == TRUE
Yes
Call Process Barcode label

SCAN_GetIntelligentImage(FALSE) received.
Wait for image notification on event

provided by SCAN_RegisterNotifications
Process signature capture received.
Page 192 of 680

5. Wireless imager specifications
Wireless Imager States
B.T Security Mode 3
Connection Scenarios
Scanning Scenarios
Wireless Imager Led/Beep
Page 193 of 680

Wireless Imager States
Startup
IDLE
Trigger + PassKey
For changing Passkey only
Fatal Trigger + BD_ADDR
BT Fail
Connecting…
BT Remote Connection
BT Connection
Temporary
BT Fail
Scanning/
commands…
BT Disconnect from Terminal
Cleanup
Page 194 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 195 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 196 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 197 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.
HC700 Wireless Imager
Set Soft Trigger()
Start Scan
“47644”
SCAN_Get Notification Result
SCAN_Acknowledge Response
ACK1/ACK2…
Good/Bad Read indication
ACK Timeout indication

No Barcode
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
Page 198 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 199 of 680

Option 2: Continues Mode/Software Trigger from the HC700
In this mode the HC700 application initiate continues scanning.
Set Soft Trigger()
Start Scan
“47644”

ACK1/ACK2…

No Barcode
Page 200 of 680

Following are steps for Continues mode/Software trigger:
1. HC700 Application start a label read by calling SCAN_SetSoftTrigger(“Continues Scan”)
4. HC700 Application get the event notification SCAN_NOTIFY_REMOTE_BARCODE
9. Wireless imager start scanning the next label.

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
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 201 of 680

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.
Function Key
“47644”
ACK1/ACK2…

No Barcode
Page 202 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.
4. HC700 Application get the event notification SCAN_NOTIFY_REMOTE_BARCODE.

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
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 203 of 680

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.
Function Key
“47644”
ACK1/ACK2…
No Barcode
Page 204 of 680

Following are steps for Continues mode/Hardware trigger:
1. The user double click on the function key on the wireless imager.
4. HC700 Application get the event notification
9. Wireless imager start scanning the next label.

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
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 205 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 blink Green once Beep4
Host indication (80ms,3250Hz)
Scan Timeout expired Beep5

(200ms,300Hz)
Unsuccessful scan based on blink Red once Beep6

Host indication (80ms,2000Hz)
No host acknowledge after Red 2 times Beep7
timeout (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 206 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
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 207 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 208 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.
Header: Declared in RcmCAPI.h.
Import Library: Use RcmAPI32.lib.
Example
RCM_RegisterTriggerEvent Example
Page 209 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
Quick Info
Page 210 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
Quick Info
Example
RCM_DeregisterTrigger Example
Page 211 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
Quick Info
Page 212 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
Quick Info
Page 213 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
Quick Info
Page 214 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
Quick Info
See Also
RCM_VERSION:
// Version information structure
typedef struct tagRCM_VERSION_INFO
{
STRUCT_INFO StructInfo; // Information about
structure extents
// HIWORD = major, LOWORD = minor

DWORD dwResCoordVersion;
DWORD dwUUIDVersion;
DWORD dwTemperatureVersion;
} RCM_VERSION_INFO;
Page 215 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 216 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.
#define TRIGGER_STAGE1_MASK 0x000000ff
#define TRIG1_STAGE1 0x00000001
Members
None
See Also
RCM_GetTriggerRegistration, RCM_GetTriggerStatus, RCM_RegisterTriggerMessage
Page 217 of 680

UNITID
Description
The UNITID structure holds an 8-byte unique unit identification number.
typedef BYTE UNITID[8];
typedef UNITID FAR * LPUNITID;
Members
None
RCM_VERSION_INFO
typedef struct tagRCM_VERSION_INFO

{
STRUCT_INFO StructInfo; // Information about structure extents
DWORD dwResCoordVersion;
DWORD dwUUIDVersion;
DWORD dwTemperatureVersion;
}
RCM_VERSION_INFO;
typedef RCM_VERSION_INFO FAR * LPRCM_VERSION_INFO;
Page 218 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 219 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
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 220 of 680

Page 221 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
Header: Declared in DispCAPI.h.
Import Library: Use DispAPI32.lib.
Example
dwResult = DISPLAY_GetBacklightState(&dwState);
Page 222 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
Comments
None
QuickInfo
Example
dwResult = DISPLAY_SetBacklightState(dwState);
Page 223 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 fails, the return value is E_DSP_NULLPTR, E_DSP_STRUCTINFO, or
E_DSP_MISSINGFIELD.
Comments
None
QuickInfo
Unicode: Implemented as Unicode and ANSI versions on Windows NT.Example
Page 224 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);
Page 225 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 fails, the return value is E_DSP_ERROR.
Comments
The function will always return 1 level.
QuickInfo
Example
dwResult = DISPLAY_ GetBacklightIntensityLevels (&dwLevels);
Page 226 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
Comments
QuickInfo
Example
dwResult = DISPLAY_GetBacklightIntensity (&dwBacklightIntensity);
Page 227 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 fails, the return value is E_DSP_ERROR.
Comments
None
QuickInfo
Example
dwResult = DISPLAY_SetBacklightState (dwBacklightState);
Page 228 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 229 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
Comments
None.
See Also
DISPLAY_GetBacklightTimeout
Page 230 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
Comments
The Touch Panel can be either disabled or enabled (Toggle) via the Device Keyboard by pressing the
TBD key combination.
See Also
Page 231 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 232 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.
typedef struct tagDISPLAY_VERSION_INFO
{
} 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.
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 233 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
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 234 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.
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 235 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 236 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
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 237 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 238 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 239 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.
Comments
None.
See Also
KBD_RegisterEvent
Page 240 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
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 241 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
Comments
None.
See Also
KBD_RegisterKeyStateNotification
Page 242 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
Comments
Upon notification the Windows Message associated wParam contains the current keyboard state
(e.g. ALPHA, NUM, FUNC)
See Also
KBD_UnregisterKeyboardNotification
Page 243 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
Comments
None.
See Also
KBD_RegisterKeyboardNotification
Page 244 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
Header: Declared in KbdApi.h.
Import Library: Use KbdApi32.lib.
Page 245 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
Header: Declared in KbdApi.h.
Import Library: Use KbdApi32.lib.
Page 246 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
Comments
None.
See Also
KBD_VERSION:
typedef struct tagKBD_VERSION
{
DWORD dwCAPIVer;
DWORD dwKbdVer;
} KBD_VERSION, *LPKBD_VERSION;
Page 247 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
Comments
None.
See Also
KBD_SetBacklightIntensity
KBD_GetBacklightIntensityLevels
Page 248 of 680

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
Comments
None.
See Also
Page 249 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
Comments
None.
See Also
KBD_SetBacklightState
Page 250 of 680

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
Comments
None.
See Also
Page 251 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
Comments
None.
See Also
KBD_GetBacklightState
Page 252 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
Comments
None.
See Also
KBD_SetBacklightTimeout
Page 253 of 680

KBD_SetBacklightTimeout
Description
This function sets the keyboard backlight timeout.
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
Comments
None.
See Also
KBD_GetBacklightTimeout
Page 254 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
Function Prototype
DWORD KBD_EnableKeyCombination( )
Parameters
None.
Return Values
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
Function Prototype
DWORD KBD_DisableKeyCombination( )
Parameters
None.
Return Values
Comments
None.
See Also
KBD_EnableKeyCombination
Page 255 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
Comments
None.
See Also
KBD_SetLayoutKey
Page 256 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
Comments
None.
See Also
KBD_GetLayoutKey
Page 257 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
Comments
None.
See Also
KBD_GetKeyState
Page 258 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
Keys = {0x37,0x38,0x39}
UpDownEvent = KEY_DOWN
Page 259 of 680

3) Key Combination with duration event
===================================
KbdEventType = KEY_COMB_WITH_DURATION
Keys = {0x37,0x38,0x39}
MinDuration = 2 // Duration of 2 sec.
DurationWithRepetition = 1; // Repetition event, every 2 sec,
// if the key combination is stay
//press, a notification will be generate.
4) Any Key press event

===================
KbdEventType = ANY_KEY_PERESS
NumOfKeys = 0
Keys = {}
AppEventHandle = 0x0c15ce7d // Application Event Handle
5) Register on registry event

==========================
KbdEventType = KEY_COMB_WITH_DURATION
KbdRegistryEvent = REG_KEYBOARD_BL_INTENSITY_UP
NumOfKeys = 0
Keys = {}
AppEventHandle = 0x0c15ce7d // Application Event Handle
*/
Page 260 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 261 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 262 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 263 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.
timeout.
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.
typedef struct tagKEYPAD_SERVICES_INFO

{
KEYBOARD_EVENT_TYPE KbdEventType;
KEYBOARD_REG_EVENT KbdRegistryEvent;
Page 264 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 265 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 266 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 267 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)

#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 268 of 680

9. Notification API
The Notification API provides the ability for applications to control the notification device - LED
Functions List
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 269 of 680

Page 270 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
Header: Declared in NtfyCAPI.h.
Import Library: Use NtfyAPI32.lib.
Example
NOTIFY_FindClose Example
Page 271 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.
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
Example
NOTIFY_FindFirst Example
Page 272 of 680

Page 273 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.
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
Example
NOTIFY_FindNext Example
Page 274 of 680

Page 275 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.
Comments
Before calling this function the user should allocate the CYCLE_INFO and initialize the StructInfo
field.
See Also
NOTIFY_SetCycleInfo, CYCLE_INFO.
QuickInfo
Example
NOTIFY_GetCycleInfo Example
Page 276 of 680

Page 277 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
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
Comments
Before calling this function the user should allocate the lpdwState.
See Also
NOTIFY_SetState.
QuickInfo
Example
NOTIFY_GetState Example
Page 278 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.
Comments
Before calling this function the user should allocate the NOTIFY_VERSION_INFO and initialize the
StructInfo field.
See Also
NOTIFY_VERSION_INFO.
QuickInfo
Example
NOTIFY_GetVersion Example
Page 279 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
lpCycleInfo
[in] Pointer to the CYCLE_INFO structure.
Return Values
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
Example
NOTIFY_SetCycleInfo Example
Page 280 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
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
Comments
None.
See Also
NOTIFY_GetState.
QuickInfo
Example
NOTIFY_SetState Example
Page 281 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
Comments
None.
See Also
NOTIFY_SetBuzzerEx, NOTIFY_GetLedExInfo
QuickInfo
Example
NOTIFY_SetLedEx Example
Page 282 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
Comments
None.
See Also
NOTIFY_GetBuzzerExInfo, NOTIFY_SetLedEx
QuickInfo
Example
NOTIFY_GetLedExInfo Example
Page 283 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_SetCycleInfo Example
NOTIFY_SetState Example
Complete Example
Page 284 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 285 of 680

}
NOTIFY_FindClose(hFindHandle);
return TRUE;
return FALSE;
Complete Example
Page 286 of 680

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);
return FALSE;
Complete Example
Page 287 of 680

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);
return FALSE;
_stprintf(szVersion, TEXT("%02X.%02X"), HIWORD(version.dwCAPIVersion),
LOWORD(version.dwCAPIVersion));
return TRUE;
Complete Example
Page 288 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++)
break;
SI_INIT (&NotifyObject);
if ( nNotifyCount == 0 )
dwResult = NOTIFY_FindFirst(&NotifyObject, &hFindHandle);
else
dwResult = NOTIFY_FindNext(&NotifyObject, hFindHandle);
Page 289 of 680

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);
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.
**********************************************************************/
BOOL Beep(DWORD dwFrequency, DWORD dwVolume, DWORD dwDuration)
DWORD dwResult;
CYCLE_INFO CycleInfo;
SI_INIT (&CycleInfo);
Page 290 of 680
// Get current beeper settings
dwResult = NOTIFY_GetCycleInfo(g_dwBeeperIndex, &CycleInfo);
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);
return FALSE;
// Beep for the specified duration (dwDuration).
dwResult = NOTIFY_SetState(g_dwBeeperIndex, NOTIFY_STATE_CYCLE);
return FALSE;
return TRUE;
/********************************************************************
* FUNCTION: LEDOn
* PARAMETERS: dwColor – LED color
* DESCRIPTION: Turns on LED with the specified color.
**********************************************************************/
BOOL LEDOn(DWORD dwColor)
DWORD dwResult;
Page 291 of 680

// Get current LED settings
dwResult = NOTIFY_GetCycleInfo(g_dwLEDIndex, &CycleInfo);
return FALSE;
CycleInfo.ObjectTypeSpecific.TricolorLedSpecific.dwColor = dwColor;
// Set the required LED color
dwResult = NOTIFY_SetCycleInfo(g_dwLEDIndex, &CycleInfo);
return FALSE;
// Turn on the LED
dwResult = NOTIFY_SetState(g_dwLEDIndex, NOTIFY_STATE_ON);
return FALSE;
return TRUE;
/********************************************************************
* FUNCTION: LEDOff
* PARAMETERS: None
* DESCRIPTION: Turns off LED.
**********************************************************************/
BOOL LEDOff()
DWORD dwResult;
// Turn off the LED
dwResult = NOTIFY_SetState(g_dwLEDIndex, NOTIFY_STATE_OFF);
Page 292 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.
**********************************************************************/
BOOL LEDBlink(DWORD dwColor, DWORD dwOn, DWORD dwOff, DWORD dwCycles)
DWORD dwResult;
// Get current LED settings
dwResult = NOTIFY_GetCycleInfo(g_dwLEDIndex, &CycleInfo);
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);
return FALSE;
Page 293 of 680
// Blink the LED
dwResult = NOTIFY_SetState(g_dwLEDIndex, NOTIFY_STATE_CYCLE);
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 294 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))
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 295 of 680

if (!LEDBlink(dwColor, dwOn, dwOff, dwCycles))
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 296 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 297 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 298 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{
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 299 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 300 of 680

NOTIFY_VERSION_INFO
typedef struct tagNOTIFY_VERSION_INFO{
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 301 of 680

Page 302 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
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 303 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 304 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.
Example
See PPS_GetVersion Example
Page 305 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
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
Example
See PPS_GetPlatformHwInfo Example
Page 306 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
Comments
Before calling this function the user should allocate the PPS_PLATFORM_SW_INFO and set the
See Also
None.
QuickInfo
Example
See PPS_GetPlatformSwInfo Example
Page 307 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
Comments
Before calling this function the user should allocate the PPS_PRODUCT_UUID_INFO and set the
See Also
None.
QuickInfo
Example
See PPS_GetProductUuidInfo Example
Page 308 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
Comments
Before calling this function the user should allocate the PPS_PHYSICAL_MEMORY_INFO and set the
See Also
None.
QuickInfo
Example
See PPS_GetPhysicalMemoryInfo Example
Page 309 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
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
Example
See PPS_GetBlueToothInfo Example
Page 310 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
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
Example
See PPS_GetImagerInfo Example
Page 311 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
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
Example
See PPS_GetWlanInfo Example
Page 312 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
Comments
Before calling this function the user should allocate the PPS_PRODUCT_PARAMETERS_INFO and set the
See Also
None.
QuickInfo
Example
See PPS_GetProductParametersInfo Example
Page 313 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
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
See Also
PPS_ReadFactoryFile
QuickInfo
Example
See PPS_GetFactoryFileInfo Example
Page 314 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
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
Example
See PPS_ ReadFactoryFile Example
Page 315 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 316 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 {
swprintf(Msg,TEXT(“ERROR:%x”), dwError);
// Inform the user.
MessageBox(hDlg,Msg,TEXT("PPS Version"),MB_OK);
Page 317 of 680

PPS_GetPlatformHwInfo Example
DWORD dwError;
WCHAR Msg[100];
PPS_PLATFORM_HW_INFO pps_plat_hw_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))) {
swprintf(Msg,TEXT(“%d”), pps_plat_hw_info. BoardRevision);
// Inform the user.
MessageBox(hDlg,Msg,TEXT("Board Revision "),MB_OK);
else {
swprintf(Msg,TEXT(“ERROR:%d”), dwError);
// Inform the user.
MessageBox(hDlg,Msg,TEXT("Board Revision "),MB_OK);
Page 318 of 680

PPS_GetPlatformSwInfo Example
DWORD dwError;
WCHAR Msg[100];
PPS_PLATFORM_SW_INFO pps_plat_sw_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);
((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);
else {
// Inform the user.
MessageBox(hDlg,Msg,TEXT("OS SoftwareVersion "),MB_OK);
Page 319 of 680

PPS_GetProductUuidInfo Example
DWORD dwError;
WCHAR Msg[100];
PPS_PRODUCT_UUID_INFO pps_uuid_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 {
// Inform the user.
MessageBox(hDlg,Msg,TEXT("Product S/N"),MB_OK);
Page 320 of 680

PPS_GetPhysicalMemoryInfo Example
DWORD dwError;
WCHAR Msg[100];
PPS_PHYSICAL_MEMORY_INFO pps_mem_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);
((dwError == E_PPS_PARTIAL_SUCCESS) && (pps_mem_info.Linear_FlashSize != -1 )) ) {
swprintf(Msg,TEXT(“%x”), pps_mem_info.Linear_FlashSize);
// Inform the user.
MessageBox(hDlg, Msg, TEXT("Linear Flash Size"),MB_OK);
else {
// Inform the user.
MessageBox(hDlg, Msg, TEXT("Linear Flash Size"),MB_OK);
Page 321 of 680

PPS_GetBlueToothInfo Example
DWORD dwError;
WCHAR Msg[100];
PPS_BLUETOOTH_INFO bt_info;
bt_info.StructInfo.dwAllocated = sizeof(PPS_BLUETOOTH_INFO);
bt_info.StructInfo.dwUsed = sizeof(PPS_BLUETOOTH_INFO);
dwError = PPS_GetBlueToothInfo (&bt_info);
((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 {
// Inform the user.
MessageBox(hDlg, Msg, TEXT("BD Address "),MB_OK);
Page 322 of 680

PPS_GetImagerInfo Example
DWORD dwError;
TCHAR Msg[100];
PPS_IMAGER_INFO imager_info;
imager_info.StructInfo.dwAllocated = sizeof(PPS_IMAGER_INFO);
imager_info.StructInfo.dwUsed = sizeof(PPS_IMAGER_INFO);
dwError = PPS_GetImagerInfo (&imager_info);
((dwError == E_PPS_PARTIAL_SUCCESS) && (imager_info. ImagerHardwareType != 0 )) ) {
// Inform the user.
MessageBox(hDlg, imager_info. ImagerHardwareType, TEXT("ImagerHardwareType"),MB_OK);
else {
// Inform the user.
MessageBox(hDlg, Msg, TEXT("ImagerHardwareType"),MB_OK);
Page 323 of 680

PPS_GetWlanInfo Example
DWORD dwError;
TCHAR Msg[100];
PPS_WLAN_INFO wlan_info;
wlan_info.StructInfo.dwAllocated = sizeof(PPS_WLAN_INFO);
wlan_info.StructInfo.dwUsed = sizeof(PPS_WLAN_INFO);
dwError = PPS_GetWlanInfo (&wlan_info);
((dwError == E_PPS_PARTIAL_SUCCESS) && (wlan_info.WlanDriverVersion != 0 )) ) {
// Inform the user.
MessageBox(hDlg, wlan_info. WlanDriverVersion, TEXT("WlanDriverVersion "),MB_OK);
else {
// Inform the user.
MessageBox(hDlg, Msg, TEXT("WlanDriverVersion"),MB_OK);
Page 324 of 680

PPS_GetProductParametersInfo Example
DWORD dwError;
WCHAR Msg[100];
PPS_PRODUCT_PARAMETERS_INFO pps_params_info;
pps_params_info.StructInfo.dwAllocated = sizeof(PPS_PRODUCT_PARAMETERS_INFO);
pps_params_info.StructInfo.dwUsed = sizeof(PPS_PRODUCT_PARAMETERS_INFO);
dwError = PPS_GetProductParametersInfo (&pps_params_info);
((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 {
// Inform the user.
MessageBox(hDlg, Msg, TEXT("OS Software Version"),MB_OK);
Page 325 of 680

PPS_GetFactoryFileInfo Example
DWORD dwError;
WCHAR Msg[100];
PPS_FACTORY_FILE_INFO pps_factory_info;
pps_factory_info.StructInfo.dwAllocated = sizeof(PPS_FACTORY_FILE_INFO);
pps_factory_info.StructInfo.dwUsed = sizeof(PPS_FACTORY_FILE_INFO);
dwError = PPS_GetFactoryFileInfo(&pps_factory_info);
((dwError == E_PPS_PARTIAL_SUCCESS) && (pps_factory_info.FactoryFileActualSize != -1 )) ) {
swprintf(Msg,TEXT(“%x”), pps_factory_info.FactoryFileActualSize);
// Inform the user.
MessageBox(hDlg, Msg, TEXT("Factory File Actual Size"),MB_OK);
else {
// Inform the user.
MessageBox(hDlg, Msg, TEXT("Factory File Actual Size"),MB_OK);
Page 326 of 680

PPS_ReadFactoryFile Example
DWORD dwError;
DWORD NumberOfBytesRead;
PPS_FACTORY_FILE_INFO PPS_factory_info;
PPS_factory_info.StructInfo.dwAllocated = sizeof(PPS_FACTORY_FILE_INFO);
PPS_factory_info.StructInfo.dwUsed = sizeof(PPS_FACTORY_FILE_INFO);
dwError = PPS_GetFactoryFileInfo(&PPS_factory_info);
((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 {
// Inform the user.
MessageBox(hDlg, Msg, TEXT("Read Factory File Content"),MB_OK);
Page 327 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 328 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{
[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 329 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{
[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 330 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{
[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{
[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 331 of 680

[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

{
[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{
[out] WLAN_VERSION_T WlanDriverVersion;

Page 332 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
typedef struct tagPPS_PRODUCT_PARAMETERS_INFO{
[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
typedef struct tagPPS_FACTORY_FILE_INFO{
[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 333 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
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 334 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 335 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.
Comments
None.
See Also
DOCK_UnRegister
Page 336 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
Comments
None.
See Also
DOCK_RegisterEx
Page 337 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
Comments
Warm Boot or Cold Boot resets the diagnostic data.
See Also
DOCK_GetStatusEx, DOCK_RegisterEx
Page 338 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
Comments
None.
See Also
DOCK_GetStatusEx, DOCK_RegisterEx
Page 339 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
Comments
This function is obsolete. DOCK_GetStatusEx should be called instead.
See Also
DOCK_GetStatusEx
Page 340 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
Comments
This function is obsolete. Applications should call DOCK_RegisterEx instead.
See Also
DOCK_RegisterEx
Page 341 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 342 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

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 */
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 */
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 */
break;
case ID_FILE_UNREGISTER:
// Unregister all hWnd registrations
Page 343 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 344 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 345 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;
}
//--------------------------------------------------------------------

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 346 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 0;
}
Page 347 of 680

Data Types
DOCK_APIDIAGNOSE
Description
This structure contains information about the Dock diagnostic data.
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 348 of 680
Description
This structure contains the Dock API and Dock driver versions.
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.
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 349 of 680
Remarks
This structure is obsolete. Do not use it.
Page 350 of 680

DOCK Error Codes
#define E_DOCK_SUCCESS 1
#define E_DOCK_FAILURE 0
Page 351 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 352 of 680

Structural Diagram
This Software Development Kit is grouped into the following development components:
SW
Monitor / Object Push Application User Legacy Applications

(DUN, LAN, FAX or Legacy Serial users)
Monitor API ObjectPush API Legacy Serial Port 1 Legacy Serial Port 2 Legacy Serial Port n Other BT APIs
(btmon.dll) (ObjPush.dll) COMX1: COMX2: COMXn: (btapi.dll)
(BTCELegacy.dll) (BTCELegacy.dll) (BTCELegacy.dll)
Implement DUN, LAN access, FAX or Serial port profiles
Bluetooth Stack for Windows CE
HCI Transport Layer
Serial Port Driver
Serial port HW
BT serial device
Page 353 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 354 of 680
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 355 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 356 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 357 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_FAILED : Failed to set Security Mode 3.
Page 358 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_FAILED : Failed to get Security Mode 3 settings.
Page 359 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
Registy specific error : Failed
Comments
Bluetooth monitor applications should call this method when started.
Page 360 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_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_FAILED : Failed. Verify that no other Monitor application is running.
Comments
Only one Bluetooth monitor application can be running at a time.
Page 361 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_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 362 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 363 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 364 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 365 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 366 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_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
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 367 of 680
Function Prototype
LONG GeneralInquiry ();
Parameters
None
Return Values
BT_STATUS_PENDING : success
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
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 368 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 369 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 370 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 371 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 :
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 :
lParam :
Page 372 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 373 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 374 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 375 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 376 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 377 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 378 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 379 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 380 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
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
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 381 of 680
lParam contains status of the failure
lParam2 contains the error if an internal error has occurred
Page 382 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 383 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
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

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 384 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 385 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 386 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 387 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
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 388 of 680
member will be an XCBFTP_FILE_COMPLETE_RESULT struct. The buffer pointed to by
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 389 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 390 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
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
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 391 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
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
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 392 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 393 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
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
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 394 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
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
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
Page 395 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 396 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 397 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 398 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_FAILED - Failure.
Page 399 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
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 400 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 401 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 402 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 403 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:
Pairing Initiated
(PassKey request by BT Stack)
Current PassKey request is for

outgoing virtual serial port Yes
connection , which is
configured with the Port
PassKey?
No
Yes
Device User PassKey is
Configured?
No
Request PassKey Use Device User Use Serial Port

by pop-up dialog PassKey PassKey
box
BT Stack Proceeds with Pairing
Page 404 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 405 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
"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
"Prefix"="COM"
"BtProfile"="SerialPort"
"FriendlyName"="Bluetooth Serial Port on COM7:"
"Index"=dword:00000007
Page 406 of 680
"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
"Prefix"="COM"
"FriendlyName"="Bluetooth Serial Port on COM8:"
"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
"Prefix"="BTC"
"FriendlyName"="Bluetooth Serial Port on 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
"Prefix"="BTC"
"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
"Prefix"="BTC"
"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
"Prefix"="BTC"
"BtProfile"="LAN"
Page 407 of 680

"FriendlyName"="Bluetooth LAN access point"
[HKEY_LOCAL_MACHINE\ExtModems\Bluetooth]
"Port"="COM0:"
"FriendlyName"="Bluetooth Modem"
Page 408 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
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 409 of 680

Page 410 of 680
Software Architecture
The diagram below demonstrates the Radio software components hierarch .
Application
OEM API TAPI/Ext TAPI WinSock
Virtual Serial
RIL
Port
Radio G20
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 411 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
Stage 1: Stage 2:
Call Establishment Data Transfer
TAPI
TSP
RIL Virtual Com

Radio Inerface Port ( 9 )
Layer
Serial Driver
Radio G20
GPRS Session
Page 412 of 680

TAPI functions Supported by the handheld terminal
Function description
Install a new TSP into the telephony
lineAddProvider
system.
Is a placeholder for the callback Function
LineCallBackFunc
application - supplied
LineClose Closes the specified open device
Return the telephony capabilities of on
LineGetAddressCaps
address
Return the current status of specified
LineGetAddressStatus
address.
Queries a specified line device to
LineGetDevCaps
determine its telephony capabilities
Enables an application to quarry the
LineGetlineDevStatus specified open line device for its current
status.
Initialize the use of TAPI by the
LineInitialize application for subsequent use of the line
abstraction
Opens the line device specified by its
lineOpen device identifier and returns a line handle
for the corresponding opened line device.
This function enables the application to
restore the configuration of a media-
lineSetDevConfig stream device on a line device to a setup
previously obtained using the
lineGetDevConfig function.
This function closes the specified open
lineClose
line device
Page 413 of 680

Extended TAPI functions Supported by the handheld
terminal
lineGetCurrentOperator Retrieve the Current oprator
Retrieve the state of the radio transmitter and

LineGetEquipmentState
receiver
Set the electrical state of the device (i.e power
LineSetEquipmentState
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 414 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
Header: Declared in G20CApi.h.h.
Import Library: Use G20API32.lib.
Page 415 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
SDK errors.
Comments
None
QuickInfo
Page 416 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
SDK errors.
Comments
None
QuickInfo
Page 417 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
SDK errors.
Comments
None
QuickInfo
Page 418 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
SDK errors.
Comments
None
QuickInfo
RADIO_GetEquipmentInfo
Description
This function returns uniqe installed radio information ,such as radio serial number(IMEI)
model number, software revition ID ,etc..
Page 419 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
SDK errors.
Comments
None
QuickInfo
RADIO_GetSignalQ
Description
This function returns the Radio Signal Strengh Indication RSSI ,this provides the user the current Radio
signal quality.
Page 420 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
SDK Radio errors.
Comments
None
QuickInfo
RADIO_GetGprsRegisterState
Description
This function returns the Radio registration status to GPRS network
Page 421 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
SDK Radio errors.
Comments
None
QuickInfo
RADIO_PerfomCommand
Description
This function invokes direct AT commands to the Radio serial channel, the function returns the radio
response.
Page 422 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
SDK Radio errors.see return value.
Comments
None
QuickInfo
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 423 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
Page 424 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 425 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;

typedef struct tagNOTIFY_VERSION_INFO
{
DWORD dwCAPIVersion; // HIWORD = major ver LOWORD = minor ver.
} NOTIFY_VERSION_INFO;
typedef NOTIFY_VERSION_INFO FAR * LPNOTIFY_VERSION_INFO;
Page 426 of 680

Return Values

#define G20_ERROR(code) (ERROR_BIT | USER_BIT | (WORD) code)
#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 427 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 428 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 429 of 680

Page 430 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.

// 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

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

// 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
Monitor Thread
WHILE (1)
{
WaitForSingleObject (CloseEvent, Timeout) // Thread is waiting for cloe event of for timeout of few
seconds
Page 431 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 432 of 680

Basic Adapter Configuration & Management APIs:
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.
Gets the current network mode of the WLAN adapter.
WLAN_GetNetworkMode
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.

Gets the Signal Strength of the adapter.
WLAN_GetRSSI
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.

Get the current encryption status of the adapter.
WLAN_GetEncryptionStatus
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.
Get the current WLAN Power Management configuration of the
WLAN_GetPMConfiguration adapter (enable suspend when WLAN is on, default WLAN power
state, etc.)
Page 433 of 680
Sets Power Management configuration of WLAN adapter. The PM
WLAN_SetPMConfiguration
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 434 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 435 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 436 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
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 437 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
RadioState
[in] Specifies the state of the radio.
Return Values
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 438 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
pSSID
[out] Pointer to TCHAR array to receive the SSID of the Access Point with which WLAN
adapter is associated.
Return Values
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 439 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
SSID
[in] TCHAR array that contains the desired SSID for WLAN adapter.
Return Values
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 440 of 680

Page 441 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
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 442 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
pNetworkMode
[out] The pointer to WLAN_NETWORK_MODE enumeration to receive the network mode of
the radio.
Return Values
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 443 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
SSID
[in] TCHAR array that contains the needed SSID
NetworkMode
[in] Specifies the desired network mode of the radio.
Return Values
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 444 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
pPowerMode
[out] The pointer to WLAN_POWER_MODE enumeration to receive the power saving mode
of the radio.
Return Values
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 445 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
PowerMode
[in] Specifies the power saving mode of the radio.
Return Values
more information.
Comments
This function sets the desired Power Save Mode of the radio.
See Also
WLAN_GetPowerMode , WLAN_POWER_MODE
Page 446 of 680

WLAN_Disassociate
Description
Disassociate the WLAN adapter from its current Service Set.
Function Prototype
DWORD WLANAPI WLAN_Disassociate(
HANDLE hAdapter );
Parameters
hAdapter
Return Values
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 447 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
pDataRate
[out] The pointer to WLAN_DATA_RATE enumeration to receive the data transmission rate
of the WLAN radio.
Return Values
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 448 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
ulChannel
[out] ULONG value that represents current channel (1-14)
Return Values
more information.
Comments
This function returns currently used channel of the WLAN adapter.
See Also
None.
Page 449 of 680

WLAN_GetRSSI
Description
Gets the Signal Strength of the adapter.
Function Prototype
DWORD WLANAPI WLAN_GetRSSI(
HANDLE hAdapter ,
ULONG &ulRSSI);
Parameters
hAdapter
ulRSSI
[out] ULONG normalized value that represents the Signal Strength of the WLAN adapter (0-
100%)
Return Values
more information.
Comments
This function returns the Strength of WLAN adapter Signal.
See Also
None.
Page 450 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
pAssociationStatus
[out] The pointer to WLAN_ASSOCIATION_STATUS enumeration to receive the
association status of the WLAN radio
Return Values
more information.
Comments
This function returns the association status of WLAN adapter.
See Also
WLAN_ASSOCIATION_STATUS
Page 451 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
pIPAddress
[out] Pointer to a TCHAR array that to receive formatted string of current adapters IP
address
Return Values
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 452 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
pMACAddress
[out] Pointer to a TCHAR array to receive a string of adapters MAC address
Return Values
more information.
Comments
This function returns the string of adapters MAC address.
See Also
WLAN_MAC_ADDR_T
Page 453 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
pEncryptionStatus
[in] The pointer to WLAN_ENCRYPTION_STATUS enumeration to receive the encryption
of the adapter.
Return Values
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 454 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
pAuthenticationMode
[in] The pointer to WLAN_AUTHENTICATION_MODE enumeration to receive the
authentication mode of the adapter.
Return Values
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 455 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
pEAPType
[in] The pointer to WLAN_EAP_TYPE enumeration to receive the EAP type of the adapter.
Return Values
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 456 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
pConfigData
[out] Pointer to WLAN_CONFIGURATION_DATA structure to receive current WLAN
configuration information of WLAN adapter.
Return Values
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 457 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
configData
[in] WLAN_CONFIGURATION_DATA structure that contains the desired WLAN
configuration information for WLAN adapter.
Return Values
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 458 of 680

Page 459 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
pPMConfigData
[out] Pointer to WLAN_PM_CONFIGURATION_DATA structure to receive current WLAN
PM configuration information of WLAN adapter.
Return Values
more information.
Comments
This function returns the current PM configuration settings of WLAN adapter.
See Also
WLAN_SetPMConfiguration, WLAN_PM_CONFIGURATION_DATA
Page 460 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
configPMData
[in] WLAN_PM_CONFIGURATION_DATA structure that contains the desired WLAN PM
configuration of WLAN adapter.
Return Values
more information.
Comments
This function sets the desired WLAN PM configuration.
See Also
WLAN_GetPMConfiguration, WLAN_PM_CONFIGURATION_DATA
Page 461 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 462 of 680

Data Types
WLAN_RADIO_STATE
Description
The WLAN_RADIO_STATE enumeration is used to specify the state of WLAN radio.
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 463 of 680

WLAN_NETWORK_MODE
Description
The WLAN_NETWORK_MODE enumeration is used to specify the network mode of WLAN radio.
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 464 of 680

WLAN_POWER_MODE
Description
The WLAN_POWER_MODE enumeration is used to specify the power saving mode of WLAN radio.
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 465 of 680

WLAN_DATA_RATE
Description
The WLAN_DATA_RATE enumeration is used to specify the data transmission of WLAN radio.
typedef enum
WLAN_DATA_RATE_1MBPS ,
WLAN_DATA_RATE_5_5MBPS ,
} WLAN_DATA_RATE, *LPWLAN_DATA_RATE;
Members
WLAN_ DATA_RATE_1MBPS
WLAN radio transmission rate is 1 Mbps.
WLAN_ DATA_RATE_5_5MBPS
WLAN radio transmission rate is 5.5 Mbps.
Page 466 of 680

WLAN_ASSOCIATION_STATUS
Description
The WLAN_ASSOCIATION_STATUS enumeration is used to specify the association status of WLAN

radio.
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 467 of 680

WLAN_PM_CONFIGURATION_DATA
Description
The WLAN_PM_CONFIGURATION_DATA structure incorporates the configuration of WLAN PM

parameters.
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 468 of 680

WLAN_ENCRYPTION_STATUS
Description
The WLAN_ENCRYPTION_STATUS enumeration is used to specify the encryption status of 802.11

NIC.
typedef enum
WLAN_NDIS_ENCRYPTION_NOT_SUPPORTED ,
WLAN_NDIS_ENCRYPTION_DISABLED ,
WLAN_NDIS_ENCRYPTION_1_ENABLED ,
WLAN_NDIS_ENCRYPTION_1_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.
Indicates that TKIP and WEP are enabled; AES is not enabled, and a transmit key is available.
Indicates that there are no transmit keys available for use by TKIP or WEP, and TKIP and WEP are
enabled; AES is not enabled.
Indicates that AES, TKIP, and WEP are enabled, and a transmit key is available.
Indicates that there are no transmit keys available for use by AES, TKIP, or WEP, and AES, TKIP, and
WEP are enabled.
Page 469 of 680

WLAN_AUTHENTICATION_MODE
Description
The WLAN_AUTHENTICATION_MODE enumeration is used to specify the authentication mode of

802.11 NIC.
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 470 of 680

WLAN_EAP_TYPE
Description
The WLAN_EAP_TYPE enumeration is used to specify the EAP type.
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 471 of 680

WLAN_KEY_MATERIALS
Description
The WLAN_KEY_MATERIALS structure contains the network key information of WLAN profile.
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 472 of 680

WLAN_CONFIGURATION_DATA
Description
The WLAN_CONFIGURATION_DATA structure incorporates the configuration of WLAN profile

parameters.
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 473 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 474 of 680

WLAN Error Codes

#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 475 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 476 of 680

Functions List
Configuration Battery
• DiagConfigGetVersion • DiagBatBridgingBatteryStatus
• DiagBatGetMainBatteryStatus
Keyboard • DiagBatGetBkupBatteryStatus
• DiagKbAutomaticTest • DiagBatGetBatteryPackParams
• DiagSetKbLight Dock
• DiagGetKbLight • DiagDockGetStatus
• DiagSetKbBacklightIntenstity Scanner
• DiagGetKbBacklightIntenstity • DiagScanReadBarcode
Audio
Screen
• DiagAudioRecord
• DiagColorScrnPattern
• DiagAudioPlayBack
• DiagScrnSetBackLight
• DiagAudioGenerateTone
• DiagScrnGetBackLight
• DiagScrnSetBackLightIntensity RTC
• DiagScrnGetBackLightIntensity • DiagRtcTest
Touch Screen Media

• DiagTsDrawLine • DiagMediaTest
• DiagTsCalibration PM
• DiagPmGetWakeupSrc
Bluetooth • DiagPmGetSleepType
• DiagBtStartEcho • DiagPmGetSystemInit
• DiagBtStopEcho • DiagPmTestMode
• DiagBtTestLoopback
• DiagBtInternalTest WLAN
• DiagRadioWlanInternalTest
PIC • DiagRadioWlanNetworkRegisterTest
• DiagPicGetVersion • DiagRadioWlanStartEcho
• DiagPicSetLED • DiagRadioWlanStopEcho
• DiagRadioWlanTestLoopback
Page 477 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 478 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
Header: Declared in DiagAPI.h.
Import Library: Use DiagAPI.lib.
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 479 of 680

DWORD dwNumUnpressedKeys;
HWND hWnd = AfxGetMainWnd()->m_hWnd;
DiadKbAutomaticTest(hInstDLL , hWnd, keyboard_test_list, &dwNumUnpressedKeys);
15.1.3 DiagSetKbLight
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 fails, the return value is FAIL.
15.1.3.1.3 Comments
None
15.1.3.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
dwResult = DiagSetKbLight (BACKLIGHT_OFF);
15.1.4 DiagGetKbLight
The DiagGetKbLight function returns the keyboard backlight state: on/off.

DIAGAPI_API DWORD DiagGetKbLight(DWORD* pdwBacklightState)
Page 480 of 680
Parameters
[in] pdwBacklightState
DWORD pointer to pdwBacklightState value that contains the retrieved backlight
state (BACKLIGHT_ON or BACKLIGHT_OFF)
Return Value
15.1.4.1.3 Comments
None
15.1.4.1.5 Example
//Load the library
HINSTANCE hInstDLL;

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
The DiagSetKbBacklightIntenstity function sets the keyboard backlight Intensity.

DIAGAPI_API DWORD DiagSetKbBacklightIntenstity (DWORD dwBacklightIntensity)
Parameters
[in] dwBacklightIntensity
A dwBacklightIntensity value contains the backlight intensity level (1 - 32)
Return Value
Page 481 of 680
15.1.5.1.3 Comments
None
15.1.5.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
dwResult = DiagSetKbBacklightIntenstity (KBD_BACKLIGHT_INTENSITY_DEFAULT);
15.1.6 DiagGetKbBacklightIntenstity
The DiagGetKbBacklightIntenstity function retrieves the keyboard backlight current intensity and the
keyboard backlight max intensity levels.

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
15.1.6.1.3 Comments
None
15.1.6.1.5 Example
//Load the library
HINSTANCE hInstDLL;
Page 482 of 680

////////////////////////////////////////////////////////////////////////////////////////////////////////////
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 483 of 680

15.1.7 DiagColorScrnPattern
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.

DIAGAPI_API DWORD DiagColorScrnPattern(COLOR_PAT_TYPE dwTestType,
HWND hWnd)
Parameters
[in] hWnd
[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
15.1.7.1.3 Comments
None
15.1.7.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DiagScrnPattern (SCREEN_3_COLOR_PATTERN, hWnd)
15.1.8 DiagScrnSetBackLight
The DiagScrnSetBackLight function turns on/off the backlight state.

DIAGAPI_API DWORD DiagScrnSetBackLight(DWORD dwBacklightState)
Page 484 of 680

Parameters
[in] dwBacklightState
A dwBacklightState value contains the backlight action (BACKLIGHT_ON or
BACKLIGHT_OFF)
Return Value
15.1.8.1.3 Comments
None
15.1.8.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
dwResult = DiagScrnSetBackLight (BACKLIGHT_ON);
15.1.9 DiagScrnGetBackLight
The DiagScrnGetBackLight function retrieves the screen backlight state.

DIAGAPI_API DWORD DiagScrnGetBackLight(DWORD* pdwBacklightState)
Parameters
[in] pdwBacklightState
DWORD pointer contains the backlight state (BACKLIGHT_ON or BACKLIGHT_OFF)
Return Value
15.1.9.1.3 Comments
None
Page 485 of 680
15.1.9.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwBacklightState;
dwResult = DiagScrnSetBackLight (&dwBacklightState);
Page 486 of 680

DiagScrnSetBackLightIntensity
The DiagScrnSetBackLightIntensity function sets the front light intensity level of the Handheld
Terminal color display.

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
15.1.9.1.8 Comments
None
15.1.9.1.10 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwBacklightIntensity = 20;
dwResult = DiagScrnSetBackLightIntensity ( dwBacklightIntensity);
Page 487 of 680

DiagScrnGetBackLightIntensity
The DiagScrnGetBackLightIntensity function gets the current and maximum front light intensity
levels of the Handheld Terminal color display.
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
15.1.9.1.13 Comments
None
15.1.9.1.15 Example
//Load the library
HINSTANCE hInstDLL;
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 488 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 489 of 680

15.1.10 DiagTsDrawLine
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.

DIAGAPI_API DWORD DiagTsDrawLine(HINSTANCE hIns,
HWND hWnd,
DWORD dwStripLength)
Parameters
[in] hIns
[in] hWnd
[in] dwStripLength
The strip length in pixels.
Return Value
If the function fails, the return value is TS_USER_DRAW_LINE_INCORRECT.
None
15.1.10.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwStripLength =5;
DiagTsDrawLine (hInstDLL, hWnd, dwStripLength);
15.1.11 DiagTsCalibration
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 490 of 680

HWND hWnd);
Parameters
[in] hIns
[in] hWnd
Return Value
If the function fails, the return value is CALIBRATION_ERROR.
None
15.1.11.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwRes = DiagTsCalibration(hInstDLL, hWnd);
Page 491 of 680

Page 492 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
The DiagBtStartEcho function enters the HC700 device into Echo mode.
Function Prototype
DIAGAPI_API DWORD DiagBtStartEcho ()
Parameters
N/A.
Return Value
If the function fails, the return value is BT_ERROR_ECHO_MODE or
BT_ALREADY_IN_ECHO_MODE
None
15.1.12.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwRes = DiagBtSetEchoMode ();
Page 493 of 680

15.1.13 DiagBtStopEcho
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 fails, the return value is BT_ALREADY_STOPED_ECHO_MODE
None
15.1.13.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwRes = DiagBtEndEcho();
Page 494 of 680

15.1.14 DiagBtTestLoopBack
15.1.14.1.1
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 fails, the return value is BT_ERROR_LOOPBACK , BT_INVALID_ADDRESS or
BT_ILLEGAL_MODE.
None
15.1.14.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwRes = DiagBtTestLoopBack(tBluetoothAddres);
15.1.15 DiagBtInternalTest
The DiagBtInternalTest function checks the internal Bluetooth device status.
Function Prototype
DIAGAPI_API DWORD DiagBtInternalTest ()
Parameters
N/A.
Page 495 of 680
Return Value
None
15.1.15.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwRes = DiagBtInternalTest ();
Page 496 of 680

Page 497 of 680
15.1.16 DiagConfigGetVersion
15.1.16.1.1
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 fails, the return value is error value.
None
15.1.16.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DIAGAPI_API PLATFORM_INFO PlatformInfo;
DWORD dwResult;
dwResult = DiagConfigGetVersion(&PlatformInfo);
Page 498 of 680

15.1.17 DiagConfigGetBlPostResult
15.1.17.1.1
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
None
15.1.17.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwResult;
Page 499 of 680

15.1.18 DiagConfigGetBootFlags
15.1.18.1.1
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
None
15.1.18.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwResult;
Page 500 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 501 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 502 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 503 of 680

15.1.60 DiagPicGetVersion
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 fails, the return value is PIC_CANNOT_FIND_PIC_VESION.
None
15.1.60.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwResult = DiagPicGetVersion(&dwPicVersion);
15.1.61
Page 504 of 680

15.1.62 DiagPicSetLED
15.1.62.1.1
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 fails, the return value is PIC_LED_SET_ERROR.
None
15.1.62.1.5 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwRes = DiagPicSetLED(LED_ON, LED_GREEN);
15.1.63
Page 505 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 506 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
Functions List
• DiagBatBridgingBatteryStatus
• DiagBatGetMainBatteryStatus
• DiagBatGetBkupBatteryStatus
• DiagBatGetBatteryPackParams
• Data Types
Page 507 of 680

15.1.64 DiagBatGetMainBatteryStatus
15.1.64.1.1
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 fails, the return value is BAT_CANNOT_GET_POWER_STATE.
None
15.1.64.1.6 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
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 508 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 509 of 680

15.1.69 DiagBatGetBkupBatteryStatus
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 fails, the return value is BAT_CANNOT_GET_POWER_STATE.
None
15.1.69.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
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 510 of 680

15.1.71 DiagBatGetBatteryPackParams
15.1.71.1.1
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

None
15.1.71.1.6 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
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 511 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
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.

Page 512 of 680
None
15.1.75.1.6 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
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 513 of 680

15.1.77 DiagDockGetStatus
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 fails, the return value is
DOCK_CANNOT_GET_DOCK_STATUS.
When the HC700 is out of dock the LpType parameter is NULL.
15.1.77.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwStatus, dwType;
DWORD dwRes = DiagDockGetStatus(&dwStatus, & dwType);
Page 514 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 515 of 680

15.1.78 DiagScanReadBarcode
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
[in] hWnd
[out] pListOfScanEvents
List of scanner events.
Return Value
If the function fails, the return failed values.
None
15.1.78.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
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 516 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 517 of 680

15.1.79 DiagAudioRecord
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
None
15.1.79.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwTimeLen = 2;
DWORD dwResult = DiagAudioRecord(dwTimeLen, _T(“filename.wav”));
Page 518 of 680

15.1.80 DiagAudioPlayBack
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 fails, the return value is AUDIO_ERROR_PLAYBACK.
None
15.1.80.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwResult = DiagAudioPlayBack (_T(“filename”));
Page 519 of 680

15.1.81 DiagAudioGenerateTone
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 fails, the return value is AUDIO_ERROR_GENERATE_TONE.
None
15.1.81.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwFrequency;
DWORD dwLevel;
DWORD dwDuration ;
//Initialize dwFrequency, dwLevel, dwDuration.
DWORD dwRes = DiagAudioGenerateTone(dwFrequency, dwLevel, dwDuration)
15.1.82 DiagBuzzerGenerateBeep
This DiagBuzzerGenerateBeep function is used for beep generation using input parameters.
Function Prototype
DIAGAPI_API DWORD DiagBuzzerGenerateBeep (DWORD dwLevel)
Page 520 of 680

Parameters
[in] dwLevel Level (High or Low)
Return Value
If the function fails, the return value is AUDIO_BUZZER_FAIL.
None
15.1.82.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwLevel = HIGH;
//Initialize dwFrequency, dwLevel, dwDuration.
DWORD dwRes = DiagBuzzerGenerateBeep (dwLevel);
Page 521 of 680

RTC
Overview
The RTC diagnostic APIs checks RTC progress.
Functions List
• DiagRtcTest
Page 522 of 680

15.1.83 DiagRtcTest
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 fails, the return value is RTC_TIMER_INVALID.
None
15.1.83.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwRes = DiagRtcTest ();
Page 523 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 524 of 680

15.1.84 DiagMediaTest
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 fails, the return value is MEDIA_DRIVE_INVALID.
None
15.1.84.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwRes = DiagMediaTest(RAM_DISK);
Page 525 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 526 of 680

15.1.86 DiagPmTestMode
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.
None
15.1.86.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwTimeToWakeup = 2;
DiagPmTestMode(dwTimeToWakeup);
15.1.87 DiagPmGetWakeupSrc
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 527 of 680

Else it returns FAIL.
None
15.1.87.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD dwWakeupCause; // Wakeup mask returned from HAL IOCTL
DiagPmGetWakeupSrc(&dwWakeupCause);
Page 528 of 680

15.1.88 DiagPmGetSleepType
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
None
15.1.88.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
DWORD pdwSleepType;
DiagPmGetSleepType(&dwSleepType);
15.1.89 DiagPmGetSystemInit
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 529 of 680
Return Value
None
15.1.89.1.4 Example
//Load the library
HINSTANCE hInstDLL;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
// 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 530 of 680

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 fails, the function returns one of the Radio diagnostic error codes (see Diagnostic
radio error codes).
None
Page 531 of 680

15.1.91 DiagRadioWlanStopEcho
The DiagRadioWlanStopEcho function stops the WLAN Radio echo functionality
Function Prototype
DIAGAPI_API DWORD DiagRadioWlanStopEcho ()
Parameters
N/A.
Return Value
radio error codes).
None
Page 532 of 680

15.1.92 DiagRadioWlanTestLoopBack
15.1.92.1.1
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
radio error codes).
None
15.1.93 DiagRadioWlanInternalTest
The DiagRadioWlanInternalTest function retrieves the internal WLAN radio parameters.
Function Prototype
DIAGAPI_API DWORD DiagRadioWlanInternalTest (LPWLAN_EQUIPMENT_INFO_PARAM
Page 533 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
radio error codes).
None
15.1.94 DiagRadioWlanNetworkRegisterTest
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 534 of 680
ulWlanRSSI - Signal Strength of the WLAN adapter
Return Value
radio error codes).
None
Page 535 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 536 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 537 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 538 of 680

15.1.96
Page 539 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
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 540 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 541 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 542 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 543 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 544 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 545 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
T/he UPOS_GetVersion function obtains information about the UPOS
UPOS_GetVersion module version.
The UPOS_UpdateOs function initiated SYSTEM_UPDATE
UPOS_UpdateOs 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.
The UPOS_GetUpdateOsResult service obtains information about
UPOS_GetUpdateOsResult 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 546 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.
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.
Page 547 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
Header: Declared in UposCAPI.h.
Import Library: Use UposAPI32.lib.
UPOS_GetVersion Example
Page 548 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 549 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.
Comments
Before calling this function the user should allocate the UPOS_UPDATEOS_INFO and set the STRUCT_INFO
with valid data.
QuickInfo
See UPOS_UpdateOs Example
Page 550 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.
Page 551 of 680

Comments
Before calling this function the user should allocate the UPOS_UPDATEOSRESULT_INFO and set the
QuickInfo
See UPOS_GetUpdateOsResult Example
Page 552 of 680

Examples
The examples below demonstrate how to work with the UPOS APIs.
• UPOS_GetVersion Example
• UPOS_UpdateOs Example
• UPOS_GetUpdateOsResult Example
Page 553 of 680

UPOS_GetVersion Example
DWORD dwRetVal;
WCHAR Msg[100];
UPOS_VERSION_INFO upos_ver_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);
swprintf(Msg,TEXT(“%x,%x”), MajorVer, MinorVer);
// Inform the user about the UPOS version.
MessageBox(hDlg,Msg,TEXT("UPOS Version"),MB_OK);
Page 554 of 680

UPOS_UpdateOs Example
WCHAR Msg[500];
DWORD dwRetVal;
WCHAR SystemPackageFileName[MAX_PATH] = TEXT(“\\Storage Card\\UpdateOsDir\\Pack_R02_00_01.bin”);
POS_UPDATEOS_INFO UposInfo;
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 555 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 556 of 680

UPOS_GetUpdateOsResult Example
DWORD dwRetVal;
UPOS_UPDATEOSRESULT_INFO UposResult;
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 557 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 558 of 680
Data Types
• UPOS_VERSION_INFO
• UPOS_UPDATEOS_INFO
• UPOS_UPDATEOSRESULT_INFO
• STRUCT_INFO
Page 559 of 680

UPOS_VERSION_INFO
// UPOS Module SW Version information structure
typedef struct tagUPOS_VERSION_INFO{
[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] 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 560 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{
[out] UPOS_UPDATEOSRESULT ResultInfo;
} UPOS_UPDATEOSRESULT_INFO, FAR * LPUPOS_UPDATEOSRESULT_INFO;
Page 561 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.
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
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 562 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 563 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 564 of 680

System Update – Process
HC700
Cradle
HC700
Cradle
Customer
• •
HOST
• •
USB
•
12 Mbits/Sec
Ethernet
100 Mbits/Sec
Cradle
n
HC700
Page 565 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 566 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 567 of 680

• Choose the HC700 system package file which resides on the FLASH-FS (i.e. HC700_R02.00.02.bin) .
Page 568 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 569 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 570 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 571 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 572 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
The ForceApplicationDownload function forces download of 3rd party
ForceApplicationDownload 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.
The EnableLoader function enables or disables Application Loader.
EnableLoader
Page 573 of 680

Page 574 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
Header: Declared in AppLoaderAPI32.h.
Import Library: Use AppLoaderAPI32.lib.
Page 575 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
Header: Declared in AppLoaderAPI32.h.
Import Library: Use AppLoaderAPI32.lib.
Page 576 of 680

20. Application Loader Usage Scenario
Application Update Process
HC700
Cradle
HC700
Cradle
Customer
• •
Host
• •
Computer
•
USB
12 Mbits/Sec
Ethernet
100 Mbits/Sec Cradle
n
HC700
Page 577 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 Server TFTP Protocol Motorola Loader (TFTP

application client)
Application Protocol
Customer HC700 Loader/SMS Client
HOST Loader
application/
SMS server
HC700 main application
Page 578 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 579 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
;===================================
;----------------------------------
;-------------------------------------
[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
;==============================================
DIR “IPSM\startup”
;=====================================
;=====================================
[DOWNLOAD]
FILE CustomerApplication.CAB
;==============================================================
; list of files to open on the terminal after download is finished (used for installation)
;===============================================================
Page 580 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 ……
;===============================================
;===============================================
[REBOOT]
FALSE
;==============================================================
; list of files to RUN (executed in any case – regardless of download being performed or not
;==============================================================
[RUN]
;------------------------------------------
;-------------------------------------------
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.

Page 581 of 680
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 After the CRADLE will resume or next time the HC700 will be inserted in
the CRADLE the application will be re-downloaded.
Page 582 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 The application will be re-downloaded.
• Communication failure:
• TFTP server failure:
o Download session will be terminated by Motorola Loader.

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 The HC700 user will extract the HC700 from CRADLE and correct the ‘no
room’ situation on the IPSM card.
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 The HC700 user will extract the HC700 from CRADLE and correct the
‘Configuration File Error’ situation.
be re-downloaded.
Page 583 of 680

Configuration File Format
;=============================
;HC700_MULTI_CFG file
;=============================
;===================================
;===================================
[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”
;====================================================
; 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 584 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]
;===============================================
; (is performed only in case of downloading)
;===============================================
FALSE
;TRUE
Page 585 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 586 of 680

;===============================================
; directory on the terminal for downloaded files
;===============================================
DIR “IPSM\download”
[DOWNLOAD]
;===============================================
;===============================================
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]
;===============================================
;===============================================
FALSE
;TRUE
Page 587 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
;==========================================================
;==========================================================
Page 588 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 589 of 680

Terminal Power on
Terminal Loader starts
No
Exit Is Terminal Loader
enabled
Yes
Pressed Not Pressed

(Unconditional download) Check if terminal (Conditional download)
keys: Left Tab & Page-Up are pressed
DOWNLOAD
Establish connection and Not Found Look for configuration file
download configuration file in the terminal
from TFTP server
Found
Configuration file sequence

[CONFIGURATION] Section No
Is terminal serial number included in
[DOWNLOAD] Section this section?
download files from Is serial
TFTP server Yes number found
Yes
in other sub configurations
or in default
Establish No [CHECK] Section configuration
connection with Does all files exist in terminal
[OPEN] Section TFTP server , as detailed in No
Execute files in order this section?
specified in configuration file
Yes
[REBOOT] Section
Should the terminal reboot? False
(True/Faulse as specified [RUN] Section
in the configuration file)
True
Warm Boot Exit Exit
Page 590 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:
Generic Server Generic Service

Winsock Winsock
TCP/IP TCP/IP
RAS Server RAS Client
USB HOST CTRL USB Client CTRL
Cradle HC700
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:
Page 591 of 680

Functions List
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 592 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 593 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_NULLPTR, E_CRADLE_INVALID_PARAMETER,
Comments
None
See Also
CRADLE_Register
Page 594 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_NULLPTR, E_CRADLE_OUT_OF_CRADLE,
E_CRADLE_NOT_CONNECTED indicate failure.
Comments
None
See Also
CRADLE_Register
Page 595 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_NULLPTR, E_CRADLE_COMM_FAILURE, E_CRADLE_TIMEOUT,
E_CRADLE_OUT_OF_CRADLE, E_CRADLE_NOT_CONNECTED indicate failure.
Comments
None
See Also
CRADLE_GetTerminalInfo
Page 596 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
Comments
None
See Also
CRADLE_GetInfo
Page 597 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
Comments
None
See Also
CRADLE_GetInfo
Page 598 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
Comments
None
See Also
CRADLE_GetInfo CRADLE_GetTerminalInfo
Page 599 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_NULLPTR, E_CRADLE_COMM_FAILURE, E_CRADLE_FAILURE,
E_CRADLE_LINE_BUSY, E_CRADLE_TIMEOUT, E_CRADLE_OUT_OF_CRADLE,
Comments
None
See Also
CRADLE_GetInfo CRADLE_GetTerminalInfo CRADLE_HangUp
Page 600 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_COMM_FAILURE, E_CRADLE_FAILURE, E_CRADLE_TIMEOUT,
Comments
The Cradle will not terminate the connection unless all the Terminals, that requested
CRADLE_Dial(), demand CRADLE_HangUp().
See Also
CRADLE_Dial
Page 601 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
Comments
None
See Also
CRADLE_GetTimeout
Page 602 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_NULLPTR, E_CRADLE_FAILURE indicate failure.
Comments
None
See Also
CRADLE_SetTimeout
Page 603 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_NULLPTR, E_CRADLE_FILE_NOT_FOUND,
Comments
None
See Also
CRADLE_GetLastUpdateResult
Page 604 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_INVALID_PARAMETER, E_CRADLE_COMM_FAILURE,
E_CRADLE_FAILURE, E_CRADLE_TIMEOUT,
Comments
None
See Also
Page 605 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_NULLPTR, E_CRADLE_COMM_FAILURE,
E_CRADLE_FILE_NOT_FOUND, E_CRADLE_FAILURE,
Comments
None.
See Also
CRADLE_GetFile
Page 606 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_NULLPTR, E_CRADLE_COMM_FAILURE,
E_CRADLE_NOT_ENOUGH_MEMORY, E_CRADLE_FILE_NOT_FOUND,
E_CRADLE_FAILURE, E_CRADLE_OUT_OF_CRADLE,
Comments
None
See Also
CRADLE_StoreFile
Page 607 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_COMM_FAILURE, E_CRADLE_FAILURE, E_CRADLE_OUT_OF_CRADLE,
Comments
If CRADLE_SetBroadcastListenerPort is not called then Communication Cradle uses internal default
port .
See Also
Page 608 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_NULLPTR, E_CRADLE_FILE_NOT_FOUND,
Comments
None
See Also
CRADLE_UpdateFirmware
Page 609 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 610 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 611 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 612 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 613 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 614 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 615 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 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 616 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 617 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 618 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
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 619 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 620 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
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 621 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
Comments
This command will cold boot the device.
Page 622 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
Comments
None.
See Also
REG_RestoreFromFile
Page 623 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
Comments
This command will warm boot the device.
See Also
REG_StoreToFile
Page 624 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.
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.
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 625 of 680
if(ERROR_SUCCESS != dwRet)
{
RETAILMSG(1, (TEXT("REG_StoreToFile Failed.
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.
MessageBox(NULL,TEXT("Failed restore registry from
file!!!"),TEXT("Registry"),MB_OK|MB_ICONERROR);
return FALSE;
}
}
return TRUE;
}
Page 626 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 627 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 628 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 629 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 630 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 631 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 632 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 633 of 680

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 .
Window1
Window 2
RegisterKeyStateNotification call
Post Massage to
KeyBoard API DLL All registered windows
When Scan Up/Down
Occurs(indicated in wParam )
KeyBoard Driver Pool of

Registered
Handles
SCAN
Win1 hWnd
KEY/Up
Down Win2 hWnd
Recognition PostMassage
Win3hWnd
Scan Key
Press/Relaese
HC700
KeyBoard
Page 634 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 635 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 636 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:
Page 637 of 680
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:
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.
BackupBatteryFullLifeTime
Number of seconds of backup battery life when at full charge, or BATTERY_LIFE_UNKNOWN if full
lifetime of backup battery is unknown.
BatteryVoltage
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 638 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.
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.
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 639 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 640 of 680

Boot Sequence and related APIs
Overview
HC700 Boot Types
Key API
Combination
Cold Boot “S” + “X” +
“On/Off” SetSystemPowerState
for 5 seconds
Warm Boot “A” + “F” +
“ESC” SetSystemPowerState
for 5 seconds
Last boot N/A
status 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 641 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 642 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 643 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 644 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 645 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
Header: Declared in DiskCAPI.h.
Import Library: Use Fatutil.lib.
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 646 of 680

Parameters
hPartition
pSp
Pointer to a SCAN_PARAMS structure.
Return Values
Comments
None
QuickInfo
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
hWnd
Handle to parent window. Can be NULL if there is no parent.
Return Values
None.
Comments
None
QuickInfo
Example
HANDLE hStore = 0, hPartition = 0;
hStore = OpenStore(TEXT("DSK1:"));
if( ( hStore == INVALID_HANDLE_VALUE ) || ( hStore == NULL ) )
Page 647 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() );
break;
}
// We must to dismount partition before scanning
DismountPartition(hPartition);
ScanVolumeUI(hPartition, hWnd);
// Mount partition soon
MountPartition(hPartition);
CloseHandle(hPartition);
Function Prototype
This function formats a volume according to the options specified.
BOOL FormatVolume(HANDLE hPartition, PDISK_INFO pdi, PFORMAT_OPTIONS pFo,

Parameters
hPartition
pdi
pFo
Pointer to a FORMAT_OPTIONS structure.
pfnProgress
pfnMessage
Return Values
Comments
None
QuickInfo
Page 648 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
pFp
Pointer to a FORMAT_PARAMS structure.
Return Values
Comments
None
QuickInfo
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
hWnd
Return Values
None.
Comments
None
Page 649 of 680
QuickInfo
Example
{
break;
}

{
break;
}
// We must to dismount partition before formating

FormatVolumeUI(hPartition, hWnd);

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,

Parameters
hPartition
pdi
pDo
Pointer to a DEFRAG_OPTIONS structure.
pfnProgress
pfnMessage
Page 650 of 680

Return Values
Comments
None
QuickInfo
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
pDp
Pointer to a DEFRAG_PARAMS structure.
Return Values
Comments
None
QuickInfo
Example
None
Page 651 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
hWnd
Return Values
None.
Comments
None
QuickInfo
Example
{
break;
}

{
break;
}
// We must to dismount partition before formating

DefragVolumeUI(hPartition, hWnd);

Page 652 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 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 653 of 680

Unattended

• 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.

• This power state is entered during a critical battery state or battery removal.
Off
• In this state, the CPU is suspended.

• This power state is entered during a user request by two sec. ON/OFF button pressing.
Page 654 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.
1. ON/OFF button momentary pressing (on battery power only).

2. Suspend timeout expiration if Screen Off timeout is disabled.
No external power:
1. Battery removal
Critical Off 2. Critical battery state
1. ON/OFF button momentary

No external power: pressing (the battery is OK)
1. Battery removal 2.External power supply
2. Critical battery state presence
Suspend
Off
SW request
initiated by Wakeup:
user 2 sec. ON/OFF button pressing System
(on battery power only). Comm.
Reboot Warm boot On
Wakeup: User activity, RTC alarm
Screen Off
timeout
expiration Suspend
timeout
expiration
User activity
Unattended
User activity
Screen Off
Suspend timeout expiration (includes Screen Off timeout)
Page 655 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 656 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 657 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 658 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.
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.
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
sleep hours)
Page 659 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:
• Extraction from CRADLE
Backlight (Display, Keyboard)
Page 660 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 661 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 662 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.

• API: KBD_SetBacklightTimeout
• Control panel: ‘Battery Power’ and ‘External Power’ tabs in the Backlight applet in the
control panel (Settings/Control Panel/Backlight).
Page 663 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:
• Extraction from CRADLE
• 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.

• API: PM_SetTimeout
• Control Panel: ‘Display Off’ tab in the Display applet in the control panel
(Settings/Control Panel/Display).
Page 664 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 665 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 666 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 667 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 668 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
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.
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 669 of 680

If HC700 is not working from external power the following activities will cause “Suspend to Critical Off”
transition:
• Battery removal
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).

• 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)
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 670 of 680
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.

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.
If the previous resume from critical-off finished successfully then
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.
If the previous resume from suspend finished successfully then
Else (The previous resume has not finished)
• A warm boot will take place.

• A special sound will be played.
Page 671 of 680

Scanner
Scanning activity is ongoing while entering 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)

• 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.

• 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 672 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 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 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.
• 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 673 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.
• 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 file was not transferred.
• 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 registry was not transferred.
• 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 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 674 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.
• 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 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 Playing is stopped.
• The play operation needs to be re-initiated by the user.
Page 675 of 680

APPENDIX E
HC700 Available and Combination Keys
AVAILABLE KEYS
Key Action Symbolic HC700I/ HC700L

constant HC700G
26-characters Press key to generate a-z a–z √ √
alphabet a-z character
SHIFT Press SHIFT to toggle 0–9 √ √
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.
FUNC Function key assigns the VK_F1-VK_F12 √ √
F1-F12.
Function key is once use
key. The keys return to
previous state after
pressing F1-F12 key.
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 VK-SPACE √ √
produce a blank space.
BKSP Press BK-SP to erase the VK-BACK √ √
previews character in the
display.
OK Enter VK-RETURN √ √
Send Run the Phone VK_F3 √ —
application.
When phone application
runs this key starts a call.
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 VK_SCAN √ √

codes
PTT HC700I —
only
Page 676 of 680

Available Combination key
Key Action Symbolic HC700I/ HC700L

combination constant HC700G
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 + Press SHIFT + an A– Z √ √
alphabet key Alphabet key to generate an
uppercase letter. (Default is
lowercase letters)
SHIFT + Press SHIFT + Right Key √ √
Right key to increase the keyboard
backlight intensity
SHIFT + Press SHIFT + Right Key √ √
Left key to decrease the keyboard
backlight intensity
SHIFT + Press SHIFT + Up Key to √ √
Up key increase the Display
backlight intensity
SHIFT + Press SHIFT + Down Key √ √
Down key to decrease the Display
backlight intensity.
SPACE + Press SPACE + “E” Key to √
E key route call audio to Earpiece.
SPACE + Press SPACE + “S” Key to √
S key route call audio to Speaker.
SHIFT + SP 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.
Pressing “Scan” key will
launch the virtual keyboard.
Press S+ X+ ON/OFF to √ √
S+X+
produce Cold Reset
Press S+ X+ H after S+ X+ √
S+X+H ON/OFF to
Clean persistent registry
A + F + P2 Press A+ F+ P2 to √
Page 677 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 678 of 680

Page 679 of 680
APPENDIX F
HC700 - COM PORTS
COM # Name Purpose

COM0 Blue Tooth virtual port DUN profile
FFUART General (debug prints
27.1.32
COM1
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
BTC6 Blue Tooth virtual port. LAN Access Profile
BTC9 Blue Tooth virtual port. Reserved for MCIL. Optionally for ActiveSync over
Bluetooth in future.
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.
Page 680 of 680

HC700 SDK Specification

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

HC700 SDK Specification

Uploaded by

Copyright:

Available Formats

Data Design Center

Network & Enterprise Sector (NE)

SOFTWARE DEVELOPMENT KIT

COMPUTER SOFTWARE COPYRIGHTS

• Barcode Reader API

• Wireless Imager Scanning API

• Wireless Imager Usage Scenario

• Wireless imager specifications

• RCM API - Scan Trigger Key

• Product Parameters Service API

• Diagnostic API Library

• System-Update Service Usage

• Application Loader Usage Scenario

• Cradle interface usage scenario

• Registry API for HC700G-EPP

• Registry API Usage Scenario

E_SCN_INVALIDARG, E_SCN_NOTINITIALIZED, E_SCN_NOTENOUGHMEMORY,

// Indicate scanner not open

// Return the error

Click here for complete example

DWORD SCAN_FindClose(HANDLE hFindHandle);

Click here for complete example

Click here for complete example

Click here for complete example

// If the enable failed

Click here for complete example

Click here for complete example

LPDECODER lpDecoder, LPDECODER_PARAMS lpDecoderParams

Click here for complete example

Click here for complete example

Click here for complete example

Click here for complete example

Click here for complete example

Click here for complete example

Click here for complete example

LPSCAN_BUFFER lpScanBuffer,HANDLE hEvent,

DWORD dwTimeOut, LPDWORD lpdwRequestID

LPSCAN_BUFFER lpScanBuffer,HWND hWnd,

UINT uiMsgNo, DWORD dwTimeOut,

Click here for complete example

DWORD dwResult, dwBufferSize = MAX_IMAGE_BUFFER_SIZE;

// Call as blocking function

LPSCAN_IMAGE_DATA lpImageBuffer = (LPSCAN_IMAGE_DATA)bImageBuffer;

LPBYTE lpImageData = (LPBYTE)lpImageBuffer + lpImageBuffer->dwImageDataOffset;

DWORD dwResult, dwBufferSize = MAX_IMAGE_BUFFER_SIZE;

// Call as blocking function

LPSCAN_IMAGE_DATA lpImageBuffer = (LPSCAN_IMAGE_DATA)bImageBuffer;

LPBYTE lpImageData = (LPBYTE)lpImageBuffer + lpImageBuffer->dwImageDataOffset;

DWORD dwResult, dwBufferSize = MAX_IMAGE_BUFFER_SIZE;

// Call as blocking function

DWORD dwResult, dwBufferSize = MAX_IMAGE_BUFFER_SIZE;

// Call as blocking function

DWORD dwResult = SCAN_IsImagePresent(hScanner, &IsImgPresent, &IsImgPresentParams, NULL);

dwResult = SCAN_GetInternalImagerParams(hScanner, SCAN_IMAGER_INTERNAL_HHP,

dwResult = SCAN_SetInternalImagerParams(hScanner, SCAN_IMAGER_INTERNAL_HHP,

The regular user procedure is:

LPSCAN_IMAGE_DATA lpImageBuffer = (LPSCAN_IMAGE_DATA)bImageBuffer;

LPBYTE lpImageData = (LPBYTE)lpImageBuffer + lpImageBuffer->dwImageDataOffset;

DWORD dwResult = SCAN_IsImagePresent(hScanner, &IsImgPresent, &IsImgPresentParams, NULL);

if( dwResult != E_SCN_SUCCESS )

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

The SCAN_IMAGER data type specifies the internal imager type.

Specifies the decoding mode of internal imager.

Specifies the decoding mode parameter of internal imager.