Table of Contents

Chapter 1 - Introduction

i

Chapter 3 - Enumerated Types and Definitions

ii

Chapter 6 - Program Samples

iii

1

Introduction

The 5X10/5X80 Software Development Kit (5X00 Series) provides a set of libraries, tools, and sample source code to help soft- ware developers create an interface between their host system and a Honeywell miniature image scan engine. The 5X00 Series consists of:

???The API Definition and Documentation

???API Libraries

???Sample Code

Features of the 5X00 Series

???The 5X00 Series contains software libraries that interact with image/data capture engines using a documented API (Application Programming Interface). The API functions are defined on a higher level so they can be easily understood and integrated into your applications, so you don???t have to learn minute details of the engine interface protocol. You simply compile your code with the library header files and link in the library for your platform. Afterward, all engine functionality is at your disposal.

???The image/data capture engine is easily integrated into a variety of host platforms.

???The 5X00 Series captures images and returns them as unformatted data, or as one of the standard file formats (BMP, TIFF, and JPG). Captured images can then be saved to disk and easily imported into a variety of common tools and applications.

???A single API is used for all Honeywell decoding engines. The libraries for all engines are identical for a given host platform. There are different libraries for each platform, but the API interface is the same for all of them, so you only need to learn a single API.

???Libraries are available for the Microsoft?? Windows?? family of operating systems. This includes both the Windows?? CE operating system, Windows?? 9x, and Windows NT?? derivatives.

???Sample code is included that demonstrate how to use specific aspects of the 5X00 Series, as well as the buildable source and executable code for a demo application.

???The communication driver library is separate from the main engine API library.

Target Operating Systems for the 5X00 Series

The 5X00 Series is designed for use with the following operating systems:

???Windows??CE versions WinCE 4.2, WinCE 5.0, Windows?? Pocket PC 2000, and Pocket PC 2002 supporting the following processors:

Pocket PC 2000ARM, MIPS, SH3 PocketPC 2002ARM

PocketPC 2003ARMV4

CE.Net Standard SDK ARMV4, ARMV4I, ARMV4T, SH3, SH4, X86

???Windows?? 9x, Windows NT?? 4.0, Windows?? 2000 and Windows?? XP

1 - 1

Interface Diagram

The following diagram shows the interface between the 5X00 Series and the Image Engine:

User Application

SDK Driver Interface Layer - hhpImgrSdk.dll

SDK API Interface Layer - commDrv.dll

OS Communications Driver

Physical Connection: RS-232, USB, etc.

Image Engine

5X00 Series Library Files

The SDK API and SDK communications layers are provided in the dynamic link libraries, hhpImgrSdk.dll and commDrv.dll, respectively. The library link file hhpImgrSdk.lib and the include files hhpImgrSdk.h, hhpSymCfg.h and hhpImgrCfg.h are also provided. In order to use the 5X00 Series, you must include hhpImgrSdk.h in any source files that call the SDK functions. The library include files must be in the include path for the application???s project. This means that the files must either be in the source file build directory, or in the developer???s Studio include path. Also, the library link file, hhpImgrSdk.lib, must be added to the application project link list and link path. Since the .dll and .lib files are operating system and processor type dependent, care must be taken to use the proper files for the chosen target environment.

1 - 2

5X00 Series API Library Summary

The following is a summary of the API functions. The full description of each function is found on the page noted.

Core Functions

Connection Functions

These functions open, close, and verify a connection to an imager.

Asynchronous Notification and Control Functions

Image and barcode capture can be either blocking (synchronous) or non-blocking (asynchronous).

In blocking (synchronous) mode, the SDK function call does not return until the barcode or image is received, the request times out, or an error occurs. In non-blocking (asynchronous) mode, the capture call returns immediately. Your application is notified of the completion when either a barcode or an image was received, the time-out for the call was reached, or an error was detected. You can specify which notification methods you wish to receive.

Your application can subscribe to one or more of the following notification methods: Windows Event, Windows Message, and/or Callback Function. When notification is received, your application can call hhpGetAsyncResult (see page 2-4) to retrieve the return code as well as the image, barcode, or text data. The asynchronous interface is also the manor in which imager-initiated barcode capture data, such as from a hardware trigger, is returned.

There is also a cancel function (see hhpCancelIo on page 2-2) that allows you to cancel any ongoing operation. You should be aware that when the callback function method is used, any processing done during the callback is run within the context of the SDK???s asynchronous read thread. This means that the SDK is unable to receive images or barcodes until the callback returns.

Imaging and General Configuration Functions

The imaging and configuration functions provide a simplified API for modifying the imager setup, image/barcode capture configuration, and symbology configuration. In order to limit the number of functions a developer must master, the design philosophy is to allow configuration control using only a small number of setup functions. The imager configuration is broken down into functional groups with structures containing the configurable items for each. Individual configuration items are specified within structures by use of a bit field mask. In this way, single configuration items can be read or written using minimal communication traffic. There are functions for reading and writing parts or all of the HHP_CONFIG imager configuration structure as well as writing the setup/configuration for individual symbologies. If the specified symbology is not available in the imager???s version of the symbol decoder, (e.g., Data Matrix in a linear and PDF417 decoder), the symbology functions return RESULT_ERR_UNSUPPORTED. Finally, to facilitate easy configuration management from device to device and application to application, the 5X00 Series also provides methods for retrieving and setting the whole imager configuration as a single stream so it can be saved to disk and restored at a later time.

1 - 3

Core Functions (Continued)

Barcode Capture Functions

The 5X00 Series captures barcodes from imagers that have hardware triggers or some other non-SDK initiated barcode captures without having to poll the imager to see if there is any data to read. This allows the imager to be put into low power mode without having to wake up to answer the polling message.

All barcode result strings are returned in TCHAR arrays, which, if running on a WinCE device or if using a Unicode Desktop build, are 2 bytes per character. You can specify a Unicode code page other than the default ANSI code page (CP_ACP).

Image Capture Functions

The image capture functions provide both synchronous and asynchronous operation.

A synchronous capture is specified by setting the bWait parameter of hhpAcquireImage or hhpGetLastImage to TRUE. For synchronous operation, the function will not return until an image has been captured and transferred (hhpAcquireImage), just transferred (hhpGetLastImage), or an error has occurred.

Asynchronous captures are specified by setting bWait to FALSE. The function call returns immediately and the caller is notified on request completion as long as at least one of the event notification methods has been enabled. You can receive transfer progress updates by Windows messages or by providing a pointer to a DWORD. Both hhpAcquireImage and hhpGetLastImage allow the caller to override the current imager transfer configuration in the imager.

1 - 4

Core Functions (Continued)

Intelligent Imaging (Signature Capture) Functions

Intelligent imaging is barcode capture combined with an image window capture. The image window is cut from the same image used to capture a barcode. This is how the SDK provides the ability to capture a signature associated with a barcode. In fact, a successful barcode capture is required before the intelligent image window is sent by the imager. You can specify whether the image is returned grayscale or black and white.

Data Types, Structures, and Enumerated Types

The 5X00 Series API uses structures (see Structures and Mask Definitions beginning on page 4-1) and enumerated types (see Enumerated Types and Definitions beginning on page 3-1) extensively . The definitions are in the include files in the 5X00 Series package. All 5X00 Series-specific structures have a dwStructSize member that must be set to sizeof( struct name ). This insures that the structure being passed to a given function is the structure type expected by the function and, if writing is done to the structure, that the structure size boundary is not exceeded. Furthermore, all imager configuration structures (except the all inclusive structure HHP_CONFIG) have a DWORD member dwMask. The mask allows you to specify only certain mem- bers within a structure. Set the mask value by ORing together the appropriate masks for the given structure for the particular items within the structure that should be read/written. Samples of programs that demonstrate this can be found in Program

Samples beginning on page 6-1. This technique is also used by Microsoft?? in their Windows?? SDK (for example, see Win- dows?? SDK structure CHARFORMAT).

The following Windows?? data types are included for clarity.

Note: A ???P??? in front of a data type means a pointer to the type.

Windows Data Types

1 - 5

Windows Data Types (Continued)

1 - 6

SDK Structure Types

A full description of the SDK structure types can be found in Enumerated Types and Definitions beginning on page 3-1.

Note: Important: Make sure to set the structure members dwStructSize and dwMask.

Individual Symbology Structures

All symbologies, except OCR, use either SymFlagsOnly_t or SymFlagsRange_t for configuration. There is a define for each symbology (except OCR) that points to one of these two structures.

Configuration Structures

1 - 7

2

API Function Descriptions

The following is an alphabetic listing of each API function with its complete description and a prototype for each function. All API functions (with the exception of hhpEngineConnected (page 2-4) return a result code of type Result_t. See Error Codes on page 3-1 for the result code values.

hhpAcquireImage

This function causes the imager to capture an image and transfer it to the host. Values to be used from the structures are specified by setting the appropriate bit mask for each item in the structure???s mask member.

hhpAcquireImage(

PHHP_IMAGE pImg, PHHP_IMAGE_TRANSFER pImgTrans, PHHP_IMAGE_ACQUISITION pImgAcqu, BOOL bWait

)

hhpAcquireIntelligentImage

The location of the window of interest must be provided in units of minimum barcode widths. This allows the imager to grab the same physical window, no matter how far the imager is from the page. The resultant image window is always squared with the X and Y axis of the returned image, so even if the barcode page is rotated relative to the imager, the resultant image appears square to the image edges.

There is only one intelligent image call that supports both synchronous and asynchronous capture. If synchronous capture is used, all members of this structure must be valid. If asynchronous capture is used, you will receive HHP_INTELIMG_BARCODE_EVENT for the barcode data, and HHP_INTELIMG_IMAGE_EVENT for the image data. The barcode data is returned in a normal barcode structure (HHP_DECODE_MSG), while the intelligent image data is returned in an HPP_IMAGE structure.

hhpAcquireIntelligentImage(

PHHP_INTEL_IMG pIntelImg, PHHP_DECODE_MSG pDecodeMsg, DWORD dwTimeout,

PHHP_IMAGE pImg, BOOL bWait

)

2 - 1

hhpCancelIo

Cancels the current barcode or image capture.

hhpCancelIo(

void

)

hhpCaptureBarcode

This function causes the imager to capture images and attempt to decode them. Decoded data returned is translated by code page and locale. Barcode capture can be synchronous or asynchronous. Synchronous capture is specified by setting the bWait parameter hhpCaptureBarcode to TRUE. In this case, the function will not return until a barcode is read, an error occurs, or the decode timeout is reached. Asynchronous capture is specified by setting the bWait parameter hhpCaptureBarcode to FALSE, or whenever a barcode capture is initiated other than by the 5X00 Series (e.g., from a hardware trigger). In order to be notified of an asynchronous transfer, you must enable at least one of the notification methods (see hhpSetAsyncMethods on page 2-10).

hhpCaptureBarcode(

PHHP_DECODE_MSG pDecodeMsg, DWORD dwTimeout,

BOOL bWait

)

hhpCaptureRawBarcode

This function causes the imager to capture images and attempt to decode them. Decoded data returned is unmodified 8 bit ASCII data. Barcode capture can be synchronous or asynchronous. Synchronous capture is specified by setting the bWait parameter hhpCaptureRawBarcode to TRUE. In this case, the function will not return until a barcode is read, an error occurs, or the decode timeout is reached. Asynchronous capture is specified by setting the bWait parameter hhpCaptureRawBarcode to FALSE, or whenever a barcode capture is initiated other than by the 5X00 Series (e.g., from a hardware trigger). In order to be notified of an asynchronous transfer, you must enable at least one of the notification methods (see hhpSetAsyncMethods on page 2-10).

2 - 2

hhpCaptureBarcode( PHHP_RAW_DECODE_MSG pDecodeMsg, DWORD dwTimeout,

BOOL bWait

)

hhpConnect

This function opens a connection to an imager. The connection must be closed by calling hhpDisconnect(). The caller can verify that the imager is connected by calling hhpEngineConnected().

Opens the selected communications port and establishes connection with the imager and starts the read data thread.

hhpConnect( HHP_CONNECT_TYPE connectType, PVOID pStruct

)

hhpDisconnect

Closes the communications port and stops the read data thread.

hhpDisconnect(

void

)

hhpEnableDisableSymbology

Enables/disables an individual symbology or all symbologies.

hhpEnableDisableSymbology( int nSymId,

BOOL bEnable

)

2 - 3

hhpEngineConnected

This function determines whether the imager is connected. This function checks to to see if the imager has lost power (due to the host going into a suspended state), or if the imager has been removed.

hhpEngineConnected(

void

)

hhpGetAsyncResult

Retrieves the data from the last signal event (image/barcode capture). This function can be called with pResultStruct set to NULL to obtain the event type. This is useful when the notification method is a Windows event.

Result_t hhpGetAsyncResult(

hhpEventType_t *pEventType, PVOID pResultStruct

)

hhpGetErrorMessage

This function returns a text message describing the meaning of a Result_t error code. See Error Codes on page 3-1 for complete descriptions.

hhpGetErrorMessage( Result_t nErrorCode, PTCHAR ptcErrorMsg, int nMaxChars

)

hhpGetLastImage

This function causes the imager to transfer the last image captured to the host. If bWait is TRUE, the function will not return until the image is fully received or an error occurs. If bWait is FALSE, the function returns immediately and you are notified when image transfer has completed or an error has occurred. pImgTrans is an optional parameter and can be NULL. Setting the appropriate bit mask for each item specifies active members of this structure. This function can be used to obtain the image from the last barcode capture attempt as well as the last image from an image capture attempt.

hhpGetLastImage(

PHHP_IMAGE pImg, PHHP_IMAGE_TRANSFER pImgTrans, BOOL bWait

)

2 - 4

hhpNamedConnect

This function opens a connection to an imager. The connection must be closed by calling hhpDisconnect (page 2-3). The caller can verify that the imager is connected by calling hhpEngineConnected (page 2-4).

hhpNamedConnect( PTCHAR ptcConnectName, PVOID pStruct

)

hhpRawAcquireIntelligentImage

Captures a portion of the image in which a barcode is decoded. The position of the image is specified relative to the center of the barcode. This function differs from hhpAcquireIntelligentImage (page 2-1) in that the barcode data is returned as a raw (untranslated) byte data array.

hhpRawAcquireIntelligentImage(

PHHP_INTEL_IMG pIntelImg, PHHP_RAW_DECODE_MSG pRawDecodeMsg, DWORD dwTimeout,

PHHP_IMAGE pImg, BOOL bWait

)

2 - 5

hhpReadConfigItem

Reads the configuration items for one or all of the configuration structures found in the main 5X00 Series configuration structure

HHP_CONFIG.

hhpReadConfigItem(

SetupType_t cfgType, ConfigItems_t item, PVOID pStruct

)

2 - 6

HHP_DECODER_CONFIG

HHP_POWER_SETTINGS

HHP_VERSION_INFO

HHP_SYM_CONFIG

HHP_SERIAL_PORT_CONFIG

HP_IMAGE_ACQUISITION

HHP_IMAGE_TRANSFER

HHP_SEQUENCE

HHP_CONFIG

hhpReadConfigStream

Reads the full imager configuration as a single stream of data into a buffer. The buffer contains all the configuration items in an ASCII stream so that it can be written to a disk for storage. No interpretation is done on the data stream, therefore, the data stream contains both read only, and read/write data.

2 - 7

hhpReadConfigStream( PBYTE puchCfgStream, int nMaxLen,

PINT pnBytesReturned

)

hhpReadEngineInfo

Reads information about the image engine contained in the image engine PSOC. This call is only valid for imagers that have a PSOC. If the attached imager is not an 5X80 image engine, or the engine does not have a PSOC, the function returns the error code RESULT_ERR_UNSUPPORTED.

hhpReadEngineInfo(

PHHP_ENGINE_INFO pEngInfo

hhpReadImagerCapabilities

Returns the fixed imager capabilities, such as imager bits per pixel or image capture width and height.

Note: As with all other HHP structures, the dwStructSize member of the structure must be set before calling this function. (Set to sizeof (HHP_IMAGER_CAPS).)

hhpReadImagerCapabilities( HHP_IMAGER_CAPS pImgrCaps

)

hhpReadSymbologyConfig

Reads configuration items for a single symbology or for all symbologies. Individual items to be read are specified by adding the appropriate mask bit (OR it) to the mask member of the structure to which it belongs. Only items whose bits are set are read; all other items are ignored.

hhpReadSymbologyConfig(

SetupType_t cfgType, int nSymbol,

PVOID pvSymStruct

)

2 - 8

hhpReadSymbologyRangeMaxMin

Returns the specified symbology range maximum and minimum values. If a symbology has no range values, the function returns -1 for the minimum and maximum values.

hhpReadSymbologyRangeMaxMin(

int symbol,

PLONG pnRangeMin, PLONG pnRangeMax

)

hhpSendActionCommand

This command allows the application to modify some of the imager hardware states. The items that can be modified include turning the illumination LEDs on/off, turning the aimer LEDs on/off, or causing the device???s beeper to beep/double beep.

hhpSendActionCommand(

HHP_ACTION actionCmd, int nVal )

hhpSendMessage

The SDK API provides access to almost all of the imager command set. hhpSendMessage allows applications to send menu (imager) commands directly to the imager (both wrapped and unwrapped) and to receive the actual uninterpreted imager response. This command allows a developer to send debug commands to the imager.

hhpSendMessage(

PBYTE puchMsg, int nLen,

BOOL bSendRaw, PBYTE puchReply, int nLenToRead, PINT pnRetLen

)

2 - 9

hhpSetAsyncMethods

hhpSetAsyncMethods sets the methods by which the caller wishes to be notified upon receipt of a barcode or image. hhpSetAsyncMethods(

hhpSetBarcodeDataCodePage

This function changes the code page used when translating the decoded data from a string of bytes to Unicode. The default value is CP_ACP (ANSI code page). There is no error checking on the values sent to this function, so you must determine whether or not a code page is valid on the given system.

hhpSetBarcodeDataCodePage(

DWORD dwCodePage

)

hhpSetConfigItemToDefaults

Defaults a configuration group or individual group structure items.

hhpSetConfigItemToDefaults( ConfigItems_t item

)

2 - 10

hhpSetHardwareLineDllFileName

The SDK API provides the ability to provide OEM device-dependent extensions to support the imager hardware sleep lines, and hardware trigger and/or special COM port driver configuration/initialization. The definitions and function prototype are located in the header file OemDll.h. Also see OEM-Configurable SDK Functionality on page 5-1.

hhpSetHardwareLineDllFileName(

PTCHAR ptcHwrFilename

)

hhpSetSymbologyDefaults

Resets an individual symbology or all symbologies to their default values.

hhpSetSymbologyDefaults(

int nSymId

)

hhpUpgradeFirmware

The 5X00 Series provides the ability to update the firmware application running on the imager. hhpUpgradeFirmware checks the file contents to verify that it is a firmware application file before the file is downloaded to the imager. The firmware file is transferred to the imager compressed (lossless) unless the SDK has determined that the imager is running in bootstrap code instead of the current firmware application. In this case, the file is transferred uncompressed. This function only supports synchronous operation, so it does not return until the firmware file has been transferred to the imager and the imager has burned the new code into flash memory. When this function returns, the connection (host COM port) is connected at the default baud rate of 115200.

2 - 11

hhpUpgradeFirmware(

const PTCHARptcFirmwareFilename, PDWORD DpdwTransferPercent, HWND hTransferNotifyHwnd

)

hhpWriteConfigItem

Writes the configuration items for one or all of the configuration structures found in the main 5X00 Series configuration structure HHP_CONFIG. Individual items can be specified by adding the appropriate mask bit by ORing it with the dwMask member of the structure. Only items whose bits are set are written; all other items are ignored.

hhpWriteConfigItem(

ConfigItems_t item, PVOID pStruct

)

2 - 12

HHP_POWER_SETTINGS

HHP_SYM_CONFIG

HHP_IMAGE_ACQUISITION

HHP_IMAGE_TRANSFER

HHP_SEQUENCE

HHP_CONFIG

hhpWriteConfigStream

Writes an entire data stream of programmable parameters to the device.

hhpWriteConfigStream( PBYTE puchCfgStream, int nLen

)

2 - 13

hhpWriteSymbologyConfig

Writes configuration items for a single symbology or for all symbologies. Individual items to be written are specified by adding the appropriate mask bit (OR it) to the mask member of the structure to which it belongs. Only items whose bits are set are written; all other items are ignored.

hhpWriteSymbologyConfig(

int nSymId,

PVOID pvSymStruct

)

Symbology Identifiers

Note: Please consult the appropriate symbology specification for discussion of AIM symbology IDs and modifiers.

2 - 14

2 - 15

3

Enumerated Types and Definitions

Error Codes

3 - 1

Error Codes (Continued)

Setup Type Enumerated Type

Symbology ID Enumeration

3 - 2

Symbology ID Enumeration (Continued)

Supported OCR Fonts

These are mutually exclusive. Only one font can be enabled at one time.

Image Formats

3 - 3

Image Formats (Continued)

Compression Mode Formats

Capture Illumination Duty Cycle

Auto Exposure Type

Gain Values Enum

Only used when in manual capture mode.

HHP_GAIN_1x=1,

HHP_GAIN_2x,

HHP_GAIN_4x=4,

Frame Rates Enum

Only used when in manual capture mode.

HHP_1_FRAMES_PER_SEC=1,

HHP_2_FRAMES_PER_SEC,

HHP_3_FRAMES_PER_SEC,

HHP_4_FRAMES_PER_SEC,

HHP_5_FRAMES_PER_SEC,

HHP_6_FRAMES_PER_SEC,

HHP_10_FRAMES_PER_SEC=10,

HHP_12_FRAMES_PER_SEC=12,

HHP_15_FRAMES_PER_SEC=15,

HHP_20_FRAMES_PER_SEC=20,

3 - 4

HHP_30_FRAMES_PER_SEC=30

Beeper Volume Enum

Decoder Mode Enum

System (MPU) Clock Speeds

Note: CPU clock speed must always be greater than system clock speed.

POWER_SYS_SPEED_96MHZ=0,

POWER_SYS_SPEED_48MHZ,

POWER_SYS_SPEED_32MHZ

Configuration Structure Item Enum for hhpReadConfigItem() and hhpWriteConfigItem()

3 - 5

Trigger Modes Enum

Sequence Mode

Serial Port Baud Rates

// Baud Rates that Require USB Serial or SIO950 Compatible Serial Port Driver

Baud Rates that Require USB Serial or SIO950 Compatible Serial Port Driver

3 - 6

Serial Data Bits

Parity

Stop Bits

Connection Types

Currently limited to serial ports.

3 - 7

Decoder Symbology Support

HHP Action Commands

On/Off Enum

Beep Execute Enum

Imager Type Enum

Illumination Color Enum (5X10/5X80 engines only)

3 - 8

4

Structures and Mask Definitions

Important: All structures have a dwStructSize member that MUST BE SET before calling any of the 5X00 Series API functions. This insures that the proper structure has been passed to the function being called.

Most structures have a dwMask member. This specifies which structure members are active (to be read or written). Select structure items by ORing the individual structure masks for each of the items you wish to be active together.

Symbology Structures and Defines

All symbology structures are 1 of 3 possibilities.

Important: Symbology configuration definitions for each symbology are ORed together in the dwFlags member of the symbology structure. The applicable flags are dependent on symbology. For example, Aztec Code accepts only SYMBOLOGY_ENABLE, while Postnet accepts SYMBOLOGY_ENABLE and SYMBOLOGY_CHECK_TRANSMIT.

Flags for Aztec Mesas are reused, since Aztec Mesas have no addenda, extended UPC-E, or UPC-E1 enable flags.

There is only one symbology ID for RSE, RSL, and RSS, so 3 flags are used for enable.

4 - 1

Symbology structure sets masks to specify which items of config structure are to be set or read.

Structure for symbologies with no specified minimum or maximum length:

} SymFlagsOnly_t, *PSymFlagsOnly_t;

4 - 2

Min/Max barcode lengths for symbologies that have length settings:

4 - 3

} SymCodeOCR_t, *PSymCodeOCR_t;

Structure of all Symbology Structures

There is one structure for each symbology. This info is stored in imager config.

Define aliases for each symbology structure:

4 - 4

Linear Codes - Flags supported for this code:

4 - 5

} SymCfg_t, HHP_SYM_CONFIG, *PSymCfg_t, *PHHP_SYM_CONFIG;

Data structures for decoded barcode message: hhpCaptureBarcode() and hhpGetAsyncResults(). Not stored in imager.

} HHP_RAW_DECODE_MSG, RawDecodeMsg_t, *PHHP_RAW_DECODE_MSG;

Imaging Structures and Defines

4 - 6

4 - 7

} HHP_IMAGE_TRANSFER, *PHHP_IMAGE_TRANSFER;

Data structure for captured image: hhpAcquireImage(), hhpGetLastImage() and hhpGetAsyncResult(). Not stored in im- ager.

typedef struct _tagHHP_IMAGE

{

4 - 8

Other Imager Configuration Structures and Defines

4 - 9

4 - 10

4 - 11

Revision information:

#define MAX_VERSION_STRING_LEN64 #define MAX_DEVICE_TYPE_STRING_LEN16 typedef struct _tagHHP_VERSION_INFO

{

} HHP_VERSION_INFO, *PHHP_VERSION_INFO;

Structure that includes all structures used to configure imager. See ConfigItems_t when specifying structure to call hh- pReadConfigItem() and hhpWriteConfigItem().

4 - 12

} HHP_SERIAL_PORT_CONFIG, *PHHP_SERIAL_PORT_CONFIG;

4 - 13

4 - 14

5

OEM-Configurable SDK Functionality

The 5X80 accommodates a variety of PDA/PDT, static mount, and "gun" type installations, so the 5X00 Series has included the flexibility to modify some SDK behaviors. You can provide a DLL that affords the SDK access to the hardware trigger, hardware sleep lines, and access to the open driver handle and registry entries, which can be used to specify high speed baud rates (greater than 115200). You can also specify whether to force a Y-modem communications protocol for image transfers.

OEM Supplied DLL

The OEM DLL interface is described in SDK header file OemDll.h. The DLL can export some or all of the available functionality. If the DLL is named ImgrHwrLines.dll and is located in the default library search path, it will be loaded automatically by the SDK. Otherwise, it can by loaded manually by calling the SDK function hhpSetHardwareLineDllFileName. The DLL exports are described in the following list:

ConfigureCommPort

ConfigureCommPort performs any special driver configuration that needs to be done to support the specified communication port settings. Configuring the communications driver requires the current driver handle, so you must also support SetCommDriverHandle(). The function is called by the SDK whenever you set/change the communication port settings. It is called after the SDK is finished processing pConfig, so any changes you make will not be overridden.

bool ConfigureCommPort( PCommPortConfig pConfig

)

ImagerPoweredDown

ImagerPoweredDown checks the imager powered down hardware line for the imager power state. The powered down hardware line is active high. ImagerPoweredDown returns true if the hardware line is high, false if it is low.

bool ImagerPoweredDown(

void

)

ModifyCommPortDCB

ModifyCommPortDCB receives the RS-232 configuration (DCB) structure just before it's sent to the serial driver. You can then modify the RTS/CTS and DTR/DTS settings if they are used for the imager???s power or trigger.

void ModifyCommPortDCB(

LPDCB lpDCB

SetCommDriverHandle

SetCommDriverHandle receives the handle to the open communications port. The handle can then be used to access private driver ioctl calls.

void SetCommDriverHandle(

HANDLE hDriver

)

5 - 1

SetHardwareTrigger

SetHardwareTrigger triggers the imager hardware trigger line, depending on bEnable. The hardware trigger line is active low.

void SetHardwareTrigger( bool bEnable

)

WakeUpImager

WakeUpImager toggles the imager hardware wakeup line from low to high, delay, (see Integration Manual for timing), then from high back to low.

void ImagerPoweredDown(

void

)

Registry Entries

There are two registry entries used to modify the SDK default behavior. The values are both located in the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Hand Held Products\MatrixDemos.

Baud Rate

The SDK will not normally allow high speed serial connections (connections greater than 115200 baud) unless it recognizes the driver name in the registry. The first registry value, BaudRate, specifies the first baud rate at which the demos will attempt to connect. It also overrides the normal block that sets high speed baud rates. This lets you specify a baud rate greater than 115200.

ForceHmodem

The SDK does not normally use its Y-Modem variant, Hmodem, if a high speed serial connection is specified. However, if your driver does not support true hardware RTS flow control, there is a substantial risk of communication buffer overruns. These overruns can cause data loss, especially during image transfer. The registry value ForceHmodem lets you force the use of the communications protocol, preventing data buffer overflow.

5 - 2

6

Program Samples

Configuration Management

if( (nResult = hhpReadSymbologyConfig( SETUP_TYPE_DEFAULT,SYM_CODE39,&code39 )) ==

RESULT_SUCCESS )

{

code39.dwFlags |= SYMBOLOGY_ENABLE_FULLASCII;// OR flags with Enable Full ASCII flag to turn on code 39.

nResult = hhpWriteSymbologyConfig( SYM_CODE39,&code39 );

// Set the structure size and structure mask imgTrans.dwStructSize = sizeof( HHP_IMAGE_TRANSFER); imgTrans.dwMask = IMAGE_CAPTURE_MODE_MASK;

//Turn on photo image mode. ImgTrans.captureMode = HHP_AUTOEXPOSURE_PHOTO;

//Call the write configuration function specifying the HHP_ACQUISITION_STRUCTURE. nResult = hhpWriteConfigItem( IMAGE_ACQUISITION,&imgTrans );

//Display error code (NOTE: RESULT_SUCCESS error code returns string SUCCESS. hhpGetErrorMessage( nResult,tcErrMsg );

_tprintf( _T(???Change Imager Config To Photo Capture Mode: %s\n???),tcErrMsg;

6 - 1

Barcode Capture

//Make sure to set the structure size! decodeInfo.dwStructSize = sizeof( HHP_DECODE_MSG );

//Call the SDK function to capture a barcode setting the bWait parameter to TRUE, 6 second timeout.

if ( (nResult = hhpCaptureBarcode( &decodeInfo,6000,TRUE ) == RESULT_SUCCESS )

{

_tprintf( _T(???Barcode: %s\n???),decodeInfo.pchMessage );

_tprintf( _T(???Barcode Length: %d\n???),decodeInfo.nLength );

_tprintf( _T(???AIM Id : %cn???),decodeInfo.chCodeID );

_tprintf( _T(???HHP Id: %cn???),decodeInfo.chSymLetter );

_tprintf( _T(???Symbol Modifier: %c\n???),decodeInfo.chSymModifier );

}

else

{

hhpGetErrorMessage( nResult,tcErrMsg );

_tprintf( _T(???Capture Barcode Returned: %s\n???),tcErrMsg );

// Verify the event is valid (or you won???t get any notification) If( hEvent != NULL )

{

// Register the event with the SDK.

if ( (nResult = hhpSetAsyncMethods( hEvent,NULL,NULL ) == RESULT_SUCCESS )

{

// Call the SDK function to capture a barcode setting the bWait parameter to FALSE, 6 second timeout.

if ( (nResult = hhpCaptureBarcode( NULL,6000,FALSE ) == RESULT_SUCCESS )

{

//Make sure to set the structure size! decodeInfo.dwStructSize = sizeof( HHP_DECODE_MSG );

//Wait on event being set by SDK then call SDK to get results. if( WaitForSingleObject( hEvent,7000 ) == WAIT_OBJECT_0 ) nResult = hhpGetAsyncResult( &event,&decodeInfo );

}

}

}

if( nResult == RESULT_SUCCESS )

{

_tprintf( _T(???Barcode: %s\n???),decodeInfo.pchMessage );

_tprintf( _T(???Barcode Length: %d\n???),decodeInfo.nLength );

_tprintf( _T(???AIM Id : %cn???),decodeInfo.chCodeID );

_tprintf( _T(???HHP Id: %cn???),decodeInfo.chSymLetter );

_tprintf( _T(???Symbol Modifier: %c\n???),decodeInfo.chSymModifier );

6 - 2

sent. (note: this example is MFC c++)

// Register the message window with the SDK.

if ( (nResult = hhpSetAsyncMethods( NULL,hWnd,NULL ) == RESULT_SUCCESS )

{

// Call the SDK function to capture a barcode, 6 second timeout. Unless call fails, you will get a message when command completes.

if ( (nResult = hhpCaptureBarcode( NULL,6000,FALSE ) != RESULT_SUCCESS )

{

hhpGetErrorMessage( nResult,tcErrMsg );

_tprintf( _T(???Capture Barcode Returned: %s\n???),tcErrMsg );

}

// Verify the event type is barcode if( eventType == HHP_BARCODE_EVENT )

{

// Make sure to set the structure size! decodeInfo.dwStructSize = sizeof( HHP_DECODE_MSG );

if( (nResult = hhpGetAsyncResult( &eventType,&decodeInfo )) == RESULT_SUCCESS )

{

_tprintf( _T(???Barcode: %s\n???),decodeInfo.pchMessage );

_tprintf( _T(???Barcode Length: %d\n???),decodeInfo.nLength );

_tprintf( _T(???AIM Id : %cn???),decodeInfo.chCodeID );

_tprintf( _T(???HHP Id: %cn???),decodeInfo.chSymLetter );

_tprintf( _T(???Symbol Modifier: %c\n???),decodeInfo.chSymModifier );

}

else

{

hhpGetErrorMessage( nResult,tcErrMsg );

_tprintf( _T(???Capture Barcode Returned: %s\n???),tcErrMsg );

}

}

}

6 - 3

Sample 6 - An asynchronous barcode capture using Callback function

// Message Handler function

BOOL CALLBACK EventCallback(HHP_EVENT_TYPE eventType,DWORD dwBytes )

{

// Verify the event type is barcode if( eventType == HHP_BARCODE_EVENT )

{

//Make sure to set the structure size! decodeInfo.dwStructSize = sizeof( HHP_DECODE_MSG );

//Retrieve the barcode event data.

If( (nResult = hhpGetAsyncResult( &eventType,&decodeInfo )) == RESULT_SUCCESS )

{

_tprintf( _T(???Barcode: %s\n???),decodeInfo.pchMessage );

_tprintf( _T(???Barcode Length: %d\n???),decodeInfo.nLength );

_tprintf( _T(???AIM Id : %cn???),decodeInfo.chCodeID );

_tprintf( _T(???HHP Id: %cn???),decodeInfo.chSymLetter );

_tprintf( _T(???Symbol Modifier: %c\n???),decodeInfo.chSymModifier );

}

else

{

hhpGetErrorMessage( nResult,tcErrMsg );

_tprintf( _T(???Capture Barcode Returned: %s\n???),tcErrMsg );

// Register the callback function with the SDK.

if ( (nResult = hhpSetAsyncMethods( NULL,NULL,&EventCallback ) == RESULT_SUCCESS )

{

// Call the SDK function to capture a barcode, 6 second timeout. Unless call fails, we will get a message when command completes.

if ( (nResult = hhpCaptureBarcode( NULL,6000,FALSE ) != RESULT_SUCCESS )

{

hhpGetErrorMessage( nResult,tcErrMsg );

_tprintf( _T("Capture Barcode Returned: %s\n"),tcErrMsg );

}

}

6 - 4

Image Capture

Sample 7 - A synchronous image capture

// Capture image specifies:

for capture - Photo Mode and Lights On During Frames.

for Transfer - Subsample value of 1 and Lossless transfer.

Note: You don???t really have to pass anything except the HHP_IMAGE structure as long as you want the imager config settings for capture and transfer. Also, no progress feedback will be received.

//Make sure to set imgAcqu structure size! imgAcqu.dwStructSize = sizeof( HHP_IMAGE_ACQUISITION );

//Set the mask to activate captureMode and illuminatCycle (lights). ImgAcqu.dwMask = (ILLUMINATION_DUTY_CYCLE_MASK | IMAGE_CAPTURE_MODE_MASK);

//Set values

ImgAcqu.captureMode = HHP_AUTOEXPOSURE_PHOTO;

ImgAcqu. IlluminatCycle = HHP_DUTY_CYCLE_ON;

//Make sure to set imgTrans structure size! imgTrans.dwStructSize = sizeof( HHP_IMAGE_TRANSFER );

//Set the subsample and compression masks.

ImgTrans.dwMask = (SUBSAMPLE_VALUE_MASK | COMPRESSION_MODE_MASK);

//Set values imgTrans.dwSubSample = 1;

imgTrans. compressionMode = COMPRESSION_LOSSLESS;

//Set the HHP_IMAGE structure size and allocate a buffer for the data, set the buffer size and how you want to receive the data in the buffer.

// Call the SDK function to capture an image setting the bWait parameter to TRUE for blocking/synchronous behavior.

if ( (nResult = hhpAcquireImage( &image,&imgTrans, &imgAcqu,TRUE ) == RESULT_SUCCESS )

{

// Display the image. NOTE: you could specify FF_BMP_GRAY. The data would come as a BMP file.

}

else

{

hhpGetErrorMessage( nResult,tcErrMsg );

_tprintf( _T(???Image Capture Failed: %s\n???),tcErrMsg );

6 - 5

//Make sure to set imgTrans structure size! imgTrans.dwStructSize = sizeof( HHP_IMAGE_TRANSFER );

//Set the subsample, compression, and, since you???re specifying lossy compression (JPEG), add the compression factor masks. You are also asking to receive both a Windows message with progress information, as well as having the SDK update a DWORD with the percentage of transfer completion. For the latter, it is important the DWORD not lose scope or be deleted before the asynchronous call completes. You might have a thread or timer that looks at this value periodically before altering the user.

ImgTrans.dwMask =( SUBSAMPLE_VALUE_MASK | COMPRESSION_MODE_MASK | COMPRESSION_FACTOR_MASK

| TRANSFER_UPDATE_HWND | TRANSFER_UPDATE_DWORD);

imgTrans.dwPercentComplete = &g_dwPercentComplete; //Tell SDK to update this DWORD as data is received.

// Call the SDK function to capture an image setting the bWait parameter to FALSE for asynchronous behavior.

if ( (nResult = hhpAcquireImage( NULL,&imgTrans,NULL,FALSE ) == RESULT_SUCCESS )

{

// Display the image. NOTE: You could specify FF_BMP_GRAY. The data would come as a BMP file.

}

else

{

hhpGetErrorMessage( nResult,tcErrMsg );

_tprintf( _T(???Image Capture Failed: %s\n???),tcErrMsg );

}

// Message Handler for transfer progress message LRESULT OnProgressMsg( WPARAM wParam,LPARAM lParam )

{

DWORDdwBytesSoFar = wParam;// Number of bytes receive to this point. DWORDdwBytesToRead = lParam;// Total number of bytes expected.

6 - 6

return( 0 );

}

// Message Handler for image acquisition ended function (can be result of a failure as well)

LRESULT OnEventMsg( WPARAM wParam,LPARAM lParam )

{

// Verify the event type is barcode if( eventType == HHP_IMAGE_EVENT )

{

// Set the HHP_IMAGE structure size and allocate a buffer for the data, set the buffer size and how we want to receive the data in the buffer.

Image.dwStructSize = sizeof( HHP_IMAGE );

if( (nResult = hhpGetAsyncResult( &eventType,&Image )) == RESULT_SUCCESS )

{

// save image data to a bmp file and/or display it

}

else

{

hhpGetErrorMessage( nResult,tcErrMsg );

_tprintf( _T(???Capture Image Failed: %s\n???),tcErrMsg );

}

}

// Remember to delete your buffer delete [ ] image.puchBuffer;

return( 0 );

}

6 - 7

7

Customer Support

Product Service and Repair

Honeywell International Inc. provides service for all its products through service centers throughout the world. To obtain warranty or non-warranty service, contact the appropriate location below to obtain a Return Material Authorization number (RMA #) before returning the product.

North America

Telephone: (800) 782-4263

E-mail: hsmnaservice@honeywell.com

Latin America

Telephone: (803) 835-8000

Telephone: (800) 782-4263

Fax: (239) 263-9689

E-mail: laservice@honeywell.com

Brazil

Telephone: +55 (11) 5185-8222

Fax: +55 (11) 5185-8225

E-mail: brservice@honeywell.com

Mexico

Telephone: 01-800-HONEYWELL (01-800-466-3993)

Fax: +52 (55) 5531-3672

E-mail: mxservice@honeywell.com

Europe, Middle East, and Africa

Telephone: +31 (0) 40 2901 633

Fax: +31 (0) 40 2901 631

E-mail: euroservice@honeywell.com

Hong Kong

Telephone: +852-29536436

Fax: +852-2511-3557

E-mail: apservice@honeywell.com

Singapore

Telephone: +65-6842-7155

Fax: +65-6842-7166

E-mail: apservice@honeywell.com

China

Telephone: +86 800 828 2803

Fax: +86-512-6762-2560

E-mail: apservice@honeywell.com

Japan

Telephone: +81-3-6730-7344

Fax: +81-3-6730-7222

E-mail: apservice@honeywell.com

Online Product Service and Repair Assistance

You can also access product service and repair assistance online at www.honeywellaidc.com.

7 - 1

Technical Assistance

If you need assistance installing or troubleshooting your device, please call your distributor or the near- est technical support office:

North America/Canada

Telephone: (800) 782-4263

E-mail: hsmnasupport@honeywell.com

Latin America

Telephone: (803) 835-8000

Telephone: (800) 782-4263

E-mail: hsmlasupport@honeywell.com

Brazil

Telephone: +55 (11) 5185-8222

Fax: +55 (11) 5185-8225

E-mail: brsuporte@honeywell.com

Mexico

Telephone: 01-800-HONEYWELL (01-800-466-3993)

E-mail: soporte.hsm@honeywell.com

Europe, Middle East, and Africa

Telephone: +31 (0) 40 7999 393

Fax: +31 (0) 40 2425 672

E-mail: hsmeurosupport@honeywell.com

Hong Kong

Telephone: +852-29536436

Fax: +852-2511-3557

E-mail: aptechsupport@honeywell.com

Singapore

Telephone: +65-6842-7155

Fax: +65-6842-7166

E-mail: aptechsupport@honeywell.com

China

Telephone: +86 800 828 2803

Fax: +86-512-6762-2560

E-mail: aptechsupport@honeywell.com

Japan

Telephone: +81-3-6730-7344

Fax: +81-3-6730-7222

E-mail: aptechsupport@honeywell.com

Online Technical Assistance

You can also access technical assistance online at www.honeywellaidc.com.

7 - 2

Honeywell Scanning & Mobility

9680 Old Bailes Road

Fort Mill, SC 29707

www.honeywellaidc.com

???

5X10-80SDK-UG Rev D

4/11