Honeywell 5380, 5180, 5080 User Manual
5X80 Series
Software Development Kit (SDK) for 5080, 5180, and 5380
Decoded Miniature Image Scan Engines
User’s Guide
Disclaimer
Honeywell International Inc. (“HII”) reserves the right to make changes in specifications and other information contained in this document without prior notice, and the reader should in all cases consult HII to
determine whether any such changes have been made. The information in this publication does not represent a commitment on the part of HII.
HII shall not be liable for technical or editorial errors or omissions contained herein; nor for incidental or
consequential damages resulting from the furnishing, performance, or use of this material.
This document contains proprietary information that is protected by copyright. All rights are reserved.
No part of this document may be photocopied, reproduced, or translated into another language without
the prior written consent of HII.
© 2007-2011 Honeywell International Inc. All rights reserved.
Other product names or marks mentioned in this document may be trademarks or registered trademarks
of other companies and are the property of their respective owners.
Web Address: www.honeywellaidc.com
Table of Contents
Chapter 1 - Introduction
Features of the 5X00 Series ................................................................................................1-1
Target Operating Systems for the 5X00 Series ...................................................................1-1
Interface Diagram ................................................................................................................1-2
5X00 Series Library Files.....................................................................................................1-2
5X00 Series API Library Summary ......................................................................................1-3
Data Types, Structures, and Enumerated Types.................................................................1-5
Chapter 2 - API Function Descriptions
hhpAcquireImage ..........................................................................................................2-1
hhpAcquireIntelligentImage ...........................................................................................2-1
hhpCancelIo ..................................................................................................................2-2
hhpCaptureBarcode ......................................................................................................2-2
hhpCaptureRawBarcode ...............................................................................................2-2
hhpConnect ...................................................................................................................2-3
hhpDisconnect ..............................................................................................................2-3
hhpEnableDisableSymbology .......................................................................................2-3
hhpEngineConnected ....................................................................................................2-4
hhpGetAsyncResult ......................................................................................................2-4
hhpGetErrorMessage ....................................................................................................2-4
hhpGetLastImage ..........................................................................................................2-4
hhpNamedConnect .......................................................................................................2-5
hhpRawAcquireIntelligentImage ...................................................................................2-5
hhpReadConfigItem ......................................................................................................2-6
hhpReadConfigStream ..................................................................................................2-7
hhpReadEngineInfo ......................................................................................................2-8
hhpReadImagerCapabilities ..........................................................................................2-8
hhpReadSymbologyConfig ...........................................................................................2-8
hhpReadSymbologyRangeMaxMin ...............................................................................2-9
hhpSendActionCommand .............................................................................................2-9
hhpSendMessage .........................................................................................................2-9
hhpSetAsyncMethods .................................................................................................2-10
hhpSetBarcodeDataCodePage ...................................................................................2-10
hhpSetConfigItemToDefaults ......................................................................................2-10
hhpSetHardwareLineDllFileName ...............................................................................2-11
hhpSetSymbologyDefaults ..........................................................................................2-11
hhpUpgradeFirmware .................................................................................................2-11
hhpWriteConfigItem ....................................................................................................2-12
hhpWriteConfigStream ................................................................................................2-13
hhpWriteSymbologyConfig ..........................................................................................2-14
Symbology Identifiers.........................................................................................................2-14
i
Chapter 3 - Enumerated Types and Definitions
Error Codes ...................................................................................................................3-1
Setup Type Enumerated Type.......................................................................................3-2
Symbology ID Enumeration........................................................................................... 3-2
Supported OCR Fonts ................................................................................................... 3-3
Image Formats............................................................................................................... 3-3
Compression Mode Formats .........................................................................................3-4
Capture Illumination Duty Cycle ....................................................................................3-4
Auto Exposure Type ...................................................................................................... 3-4
Gain Values Enum.........................................................................................................3-4
Frame Rates Enum........................................................................................................ 3-4
Beeper Volume Enum.................................................................................................... 3-5
Decoder Mode Enum.....................................................................................................3-5
System (MPU) Clock Speeds ........................................................................................ 3-5
Configuration Structure Item Enum for hhpReadConfigItem() and hhpWriteConfigItem()3-5
Trigger Modes Enum ..................................................................................................... 3-6
Sequence Mode............................................................................................................. 3-6
Serial Port Baud Rates .................................................................................................. 3-6
Baud Rates that Require USB Serial or SIO950 Compatible Serial Port Driver............ 3-6
Serial Data Bits.............................................................................................................. 3-7
Parity.............................................................................................................................. 3-7
Stop Bits ........................................................................................................................3-7
Connection Types..........................................................................................................3-7
Decoder Symbology Support.........................................................................................3-8
HHP Action Commands.................................................................................................3-8
On/Off Enum..................................................................................................................3-8
Beep Execute Enum...................................................................................................... 3-8
Imager Type Enum ........................................................................................................ 3-8
Illumination Color Enum (5X10/5X80 engines only) ...................................................... 3-8
Chapter 4 - Structures and Mask Definitions
Symbology Structures and Defines ..................................................................................... 4-1
Imaging Structures and Defines .......................................................................................... 4-6
Other Imager Configuration Structures and Defines ........................................................... 4-9
Chapter 5 - OEM-Configurable SDK Functionality
OEM Supplied DLL.............................................................................................................. 5-1
ConfigureCommPort ..................................................................................................... 5-1
ImagerPoweredDown ................................................................................................... 5-1
ModifyCommPortDCB .................................................................................................. 5-1
SetCommDriverHandle ................................................................................................. 5-1
SetHardwareTrigger ..................................................................................................... 5-2
WakeUpImager ............................................................................................................. 5-2
Registry Entries ................................................................................................................... 5-2
Baud Rate...................................................................................................................... 5-2
ForceHmodem............................................................................................................... 5-2
ii
Chapter 6 - Program Samples
Configuration Management ................................................................................................. 6-1
Barcode Capture .................................................................................................................6-2
Image Capture..................................................................................................................... 6-5
Chapter 7 - Customer Support
Product Service and Repair................................................................................................. 7-1
Online Product Service and Repair Assistance ............................................................. 7-1
Technical Assistance........................................................................................................... 7-2
Online Technical Assistance.......................................................................................... 7-2
iii
iv
1
Introduction
The 5X10/5X80 Software Development Kit (5X00 Series) provides a set of libraries, tools, and sample source code to help software 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
operating system, Windows
• 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.
®
9x, and Windows NT® derivatives.
®
Windows® family of operating systems. This includes both the Windows® CE
Target Operating Systems for the 5X00 Series
The 5X00 Series is designed for use with the following operating systems:
•Windows
processors:
Pocket PC 2000ARM, MIPS, SH3
PocketPC 2002ARM
PocketPC 2003ARMV4
CE.Net Standard SDK ARMV4, ARMV4I, ARMV4T, SH3, SH4, X86
•Windows
®
CE versions WinCE 4.2, WinCE 5.0, Windows® Pocket PC 2000, and Pocket PC 2002 supporting the following
®
9x, Windows NT® 4.0, Windows® 2000 and Windows® XP
1 - 1
Interface Diagram
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
SDK API Interface Layer - commDrv.dll
Physical Connection: RS-232, USB, etc.
The following diagram shows the interface between the 5X00 Series and the 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.
SDK Library
File
commDrv.dll
hhpImgrSdk.dll
hhpImgrSdk.lib Project Link Path
hhpSymCfg.h Project Include Path
hhpImgrCfg.h Project Include Path
hhpImgrSdk.h Project Include Path
OemDll.h Project Include Path
Where Resides Function
Target Device
Windows Folder
Target Device
Windows Folder
1 - 2
Sends commands from API to the appropriate OS driver. Handles low level
communications protocols.
Contains the exported SDK API. Formats requests into imager commands,
then calls commDrv layer.
Library exports file. Allows your application to link without actually including
the SDK code at link time.
Definitions, structures, and enumerated types related to symbology setup.
Automatically included when hhpImgrSdk.h is included.
Definitions, structures, and enumerated types for imaging as well as all
other imager configurations, except communications. Automatically
included when hhpImgrSdk.h is included.
Include file that must be included in application code. Contains definitions,
structures, and enumerated types for communication configuration, as well
as the SDK error codes and SDK function API prototypes.
Only necessary if you create a helper dll for the SDK to provide access to
the imager hardware sleep and trigger lines.
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
Core Function Summary
Page
Error Management Function
hhpGetErrorMessage Returns a descriptive text string for the specified SDK error code. 2-4
Connection Functions
These functions open, close, and verify a connection to an imager.
hhpConnect
hhpDisconnect Closes down the open imager connection. 2-3
hhpEngineConnected Checks if the connection to the imager is valid. 2-4
hhpNamedConnect
Establishes and initializes a connection to the imager at the specified port and
connection settings.
Establishes and initializes a connection to the imager at the specified driver
name and connection settings.
2-3
2-5
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.
hhpCancelIo Cancels any synchronous or asynchronous I/O in process. 1-3
hhpGetAsyncResult
hhpSetAsyncMethods
Retrieves the results (image/barcode, etc.) of an asynchronous
I/O event.
Allows the application to select how it wishes to be notified on completion of
an asynchronous I/O event.
2-4
2-10
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.
hhpReadConfigItem
hhpReadConfigStream
Retrieves a single configuration group or whole imager configuration from the
imager.
Retrieves the current whole imager configuration as a single buffer. This
buffer can be saved to a file and later restored.
2-6
2-7
1 - 3
Core Functions (Continued)
Core Function Summary
hhpReadImagerCapabilities
hhpReadEngineInfo
hhpSetConfigItemToDefaults
hhpWriteConfigItem
hhpWriteConfigStream
Retrieves the imager settings (fixed) for image size, image bit depth, and
maximum message length.
Reads information about the image engine contained in the image engine
PSOC.
Sets a selected symbology, or all symbology configurations, to their default
values.
Writes some or all of the configuration items for a single configuration group or
for all configuration groups, with the exception of version and communication
groups.
Writes an entire data stream of programmable parameters from a previous
call to hhpReadConfigStream.
Page
2-8
2-8
2-10
2-12
2-13
Symbology Configuration Functions
These functions allow you to read and set the symbology configurations.
hhpEnableDisableSymbology Enables or disables a single symbology, or all symbologies. 2-3
hhpReadSymbologyConfig
hhpReadSymbologyRangeMaxMin Returns the specified symbology range maximum and minimum values. 2-9
hhpSetSymbologyDefaults Defaults a single symbology, or all symbologies. 2-11
hhpWriteSymbologyConfig
Retrieves the current or default symbology configuration for a specified
symbology, or for all symbologies.
Writes some or all of a single symbology, or all symbologies’ configuration
items.
2-8
2-14
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).
Initiates a synchronous (wait for finish before returning from call) or
hhpCaptureBarcode
hhpSetBarcodeDataCodePage
hhpCaptureRawBarcode
asynchronous (return immediately) barcode capture. Decoded data returned
is translated by code page and locale.
Specifies the code page used to convert the barcode characters to Windows
text. The default is the ANSI code page.
Initiates a synchronous (wait for finish before returning from call) or
asynchronous (return immediately) barcode capture. Decoded data returned
is unmodified 8 bit (ASCII) data.
2-2
2-10
2-2
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.
Initiates a synchronous (wait for finish before returning from call) or
hhpAcquireImage
asynchronous (return immediately) image capture. The image acquisition and
transfer parameters can also be specified.
2-1
1 - 4
Core Functions (Continued)
Core Function Summary
Initiates transfer of the last image captured. (This includes images captured
hhpGetLastImage
during barcode scan.) The call can be made synchronously or
asynchronously, and the transfer parameters can be specified.
Page
2-4
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.
hhpAcquireIntelligentImage Barcode capture combined with an image window capture. 2-1
hhpRawAcquireIntelligentImage Captures portion of the image in which a barcode is decoded. 2-5
Miscellaneous Functions
hhpSendActionCommand
hhpSendMessage Sends menu commands to the imager. 2-9
hhpUpgradeFirmware Upgrades the current imager firmware with a new firmware file. 2-11
hhpSetHardwareLineDllFileName
Turns on illumination LEDs, Aimers, (and sound beeper for imagers that have
one) outside the image or barcode capture.
Allows you to specify the name of an OEM dll file. This file can contain some
or all of the OemDll exports that provide support for hardware trigger and low
power mode hardware lines.
2-9
2-11
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 members 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
®
dows
SDK structure CHARFORMAT).
The following Windows
Note: A “P” in front of a data type means a pointer to the type.
®
data types are included for clarity.
®
in their Windows® SDK (for example, see Win-
Windows Data Types
BOOL 32 bit signed integer used by most Microsoft SDK functions in place of a true Boolean.
BYTE 8 bit unsigned variable.
DWORD 32 bit unsigned integer variable.
HANDLE
HWND A Windows handle to an application window.
PVOID 32 bit unsigned integer that points to void data type (generic pointer).
TCHAR OS-dependent character variable. 16 bit for Unicode systems, otherwise 8 bits.
WORD 16 bit unsigned integer variable.
A Windows WIN32 handle type. Returned from opening files, creating events, semaphores, or
mutexes.
1 - 5
Windows Data Types (Continued)
HHP_EVENT_CALLBACK
Pointer to a callback function (see hhpImgrSdk.h) called in response to the completion of an
asynchronous 5X00 Series function call or event. (See example on page 6-4.)
SDK Enumerated Types
Beep Options Enumeration (not an enumerated type) that can be used with an hhpSendActionCommand.
Compression_t
ConfigItems_t
DECODE_METHOD Enumerated type of decode methods available to decode symbols.
DECODER_TYPE Enumeration of types of decoders and, by extension, what symbologies can be decoded.
EngineType_t Describes the connection, the imager, and the type of engine.
FileFormat_t Enumerated type for specifying the format of the data returned in the HHP_IMAGE structure.
HP_ACTION
HHP_AIMER_MODES Enumerated type to specify the aimer mode.
HHP_AUTOEXPOSURE
HHP_BAUD_RATE
HHP_BEEPER_VOLUME
HHP_CONNECT_TYPE
HHP_DATA_BITS Enumerated type for number of serial data bits.
HHP_DUTY_CYCLE
HHP_EVENT_TYPE Enumerated type that describes the type of asynchronous event being reported.
HHP_FRAME_RATE
HHP_GAIN
HHP_PARITY Enumerated type for serial parity.
HHP_SEQ_MODES Enumerated type to specify the sequence acquisition mode.
HHP_STOP_BITS Enumerated type for number of serial stop bits.
HHP_SYS_SPEED
HHP_TRIG_MODES Enumerated type to specify the trigger mode.
OCRDirection_t Enumerated type for setting the text direction for OCR decoding.
OCRMode_t Enumerated type for setting the font for OCR symbology decoding.
On Off Enumeration (not an enumerated type) that can be used with hhpSendActionCommand.
Result_t
SetupType_t
Symbology ID enumeration
Enumerated type for specifying the form of compression (if any) to use when transferring an
image from the imager to the SDK. See Compression Mode Formats on page 3-4.
Enumerated type to specify that the configuration structure is being sent to the Read/Write
config item functions.
Enumerated type whose items describe which imager command functionality (beeper, aimers,
lights) is to be acted upon.
Enumerated type to specify whether the imager tries to auto adjust the image exposure and, if
so, how.
Enumerated type of the supported baud rates for serial devices.
Note: A special driver is required if a baud rate greater than 115200 is selected.
Enumerated type to select the imager beeper volume when sounding the beeper. This structure
is ignored for products that do not have a beeper.
Enumerated type used in hhpConnect to specify the connection type and connection port where
the imager is connected.
Enumerated type to specify the behavior of the illumination and aimer LEDs during image
capture.
Enumerated type to select the image capture frame rate. Only valid when no auto exposure is
selected.
Enumerated type to select the image capture gain. This type is only valid when no auto
exposure is selected.
Enumerated type to specify the rate (in Mhz) at which all components other than the CPU are
to be clocked.
Enumerates the function result codes returned by the SDK functions. See Error Codes on page
3-1.
Enumerated type for specifying whether a read configuration item call should return the current
settings or the imager default setting.
Enumerates all the available symbologies supported in the imager decoder. Non-data type
used in the symbology configuration functions.
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.
SymFlagsOnly_t Structure for symbologies that don’t have minimum and maximum data lengths.
SymFlagsRange_t Structure for symbologies that have minimum and maximum data lengths.
SymCodeOCR_t or OCR_T Structure to configure OCR symbology.
Configuration Structures
HHP_BEEPER
HHP_CONFIG Super structure whose members are all the other configuration structures.
HHP_DECODE_MSG Returns decoded, code page and locale-translated data output from the SDK.
HHP_DECODER_CONFIG Configures decoding behavior other than symbology setup.
HHP_ENGINE_INFO
HHP_IMAGE
HHP_IMAGE_ACQUISITION
HHP_IMAGE_TRANSFER
HHP_IMAGER_CAPS
HHP_INTEL_IMG
HHP_POWER_SETTINGS Configures the power management options of the imager.
HHP_RAW_DECODE_MSG Returns raw (8 bit ASCII) decoded data output from the SDK.
HHP_SERIAL_PORT_CONFIG Specifies serial port configuration for serial imagers.
HHP_SEQUENCE Specifies how the sequence acquisition mode is configured.
HHP_SYM_CONFIG Contains a list of all the structures for all the symbologies.
HHP_TEXT_MSG
HHP_TRIGGER Configures the trigger mode of the imager.
HHP_VERSION_INFO Queries imager and SDK software revisions.
Configures whether the beeper sounds on power up, decode, or command processing.
This is ignored if the imager does not have a beeper.
Structure used by the hhpReadEngineInfo (page 2-8) call that returns information about
the image engine. (5X80 engines with PSOC only.)
Returns image data from the SDK. It also specifies the format in which the image data is
returned.
Specifies how images are captured by the imager. This includes gain, exposure, frame
rates, and illumination.
Specifies how images are shipped from the imager to the SDK. This includes image
processing items such as cropping, subsampling, histogram stretching, and transfer
compression.
Retrieves the fixed characteristics of the imager: full image size, capture bits per pixel, and
maximum text/barcode message size (sent from imager). Structure in which
hhpReadImagerCapabilities returns requested capabilities information.
Specifies the location and size of the image returned as part of an intelligent image
capture. The location information is specified in minimum bar widths of the barcode
portion of the intelligent image.
Returns non-decoded data output from the SDK. The data is translated by code page and
locale.
1 - 7
1 - 8
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
)
Parameter Description
pImg Pointer to an HHP_IMAGE structure if bWait is TRUE. If bWait is FALSE, the parameter
is ignored and should be NULL.
pImgTrans Optional pointer to an HHP_IMAGE_TRANSFER structure. This structure overrides (just
for this call) the current imager configuration, and specifies the pixel subsample, cropping
rectangle, transfer compression type, compression factor (for JPEG lossy transfer), and
progress notification method. If this parameter is NULL, the current imager configuration
settings are used except for the progress notification methods that must be specified for
each call if notification is desired.
pImgAcqu Optional pointer to an HHP_IMAGE_ACQUISITION structure. This structure overrides
(just for this call) the current imager configuration, to specify and configure the image
capture method (type of autoexposure control or manual mode). If this parameter is NULL,
the current imager configuration settings are used.
bWait If TRUE, do not return until the image is received or an error occurs. If FALSE, return
immediately. One of the event notification methods must be enabled to receive notification
on completion. (See hhpSetAsyncMethods on page 2-10.)
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.
Note: Since the HHP_INTEL_IMG structure requires that image offsets and size be specified in barcode units, the
HHP_INTEL_IMG structure has a size member that allows you to specify (in pixels) the maximum allowable width and
height for the returned image.
hhpAcquireIntelligentImage(
PHHP_INTEL_IMG pIntelImg,
PHHP_DECODE_MSG pDecodeMsg,
DWORD dwTimeout,
PHHP_IMAGE pImg,
BOOL bWait
)
2 - 1
Parameter Description
pIntelImg Pointer to an HHP_INTEL_IMG structure that contains the setup parameters describing
the location of the intelligent image relative to the barcode.
pDecodeMsg Pointer to an HHP_DECODE_MSG structure if bWait is TRUE. If bWait is FALSE, the
parameter is ignored and should be NULL. The intelligent image barcode information is
returned here.
dwTimeout Maximum time (in milliseconds) to attempt to decode before declaring a no decode.
pImg Pointer to an HHP_IMAGE structure if bWait is TRUE. If bWait is FALSE, the parameter
is ignored and should be NULL.
bWait If TRUE, do not return until the image is received or an error occurs. If FALSE, return
immediately. One of the event notification methods must be enabled to receive notification
on completion. (See hhpSetAsyncMethods on page 2-10.)
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
)
Parameter Description
pDecodeMsg Pointer to an HHP_DECODE_MSG structure if bWait is TRUE.
If bWait is FALSE, the parameter is ignored and should be NULL. (HHP_DECODE_MSG
will be passed to hhpGetAsyncMethods() call instead.) The function returns immediately,
and you are notified when symbols are decoded, an error occurs, or decoding times out
(no barcode) using the specified event notification method(s).
dwTimeout Maximum time (in milliseconds) to attempt to decode before declaring a no decode. A
value of CURRENT_DECODE_TIMEOUT specifies that the timeout is whatever is
currently set on the imager. A value of 0 indicates no timeout.
bWait If TRUE, wait for capture to complete before returning. If FALSE, one of the event
notification methods must be enabled to receive notification upon completion.
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
)
Parameter Description
pDecodeMsg Pointer to an HHP_RAW_DECODE_MSG structure if bWait is TRUE.
If bWait is FALSE, the parameter is ignored and should be NULL. (HHP_DECODE_MSG
will be passed to hhpGetAsyncMethods() call instead.) The function returns immediately,
and you are notified when symbols are decoded, an error occurs, or decoding times out
(no barcode) using the specified event notification method(s).
dwTimeout Maximum time (in milliseconds) to attempt to decode before declaring a no decode. A
value of CURRENT_DECODE_TIMEOUT specifies that the timeout is whatever is
currently set on the imager. A value of 0 indicates no timeout.
bWait If TRUE, wait for capture to complete before returning. If FALSE, one of the event
notification methods must be enabled to receive notification upon completion.
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
)
Parameter Description
connectType Describes the type of connection and hardware port, e.g., HHP_COM1, HHP_COM2,
HHP_COM3.
pStruct An optional structure that contains setup information for the hardware port, or NULL.
PHHP_SERIAL_PORT_CONFIG is used to configure a serial port connection.
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
)
Parameter Description
nSymId One of the symbology enumerated types, e.g., SYM_CODE39, SYM_OCR, or SYM_ALL
to enable/disable all symbologies.
bEnable TRUE to enable symbology, FALSE to disable symbology.
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
)
Parameter Description
hEventType Type of data causing the event notification. The valid values are:
HHP_BARCODE_EVENT
HHP_IMAGE_EVENT
HHP_TEXT_ MSG_EVENT
HHP_INTELIMG_BARCODE_EVENT
HHP_INTELIMG_IMAGE_EVENT
pResultStruct An HHP_DECODE_MSG, HHP_IMAGE, or HHP_TEXT_MSG structure pointer,
depending on the value of hEventType. This parameter can be NULL if just the event type
is desired. This is of use when the Event Handle notification is used.
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
)
Parameter Description
nErrorCode Error code returned from one of the other 5X00 Series functions.
ptcErrMsg TCHAR buffer to hold error message string.
nMaxChars Maximum number of characters that can fit in ptcErrorMsg including NULL.
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
Parameter Description
pImg Pointer to an HHP_IMAGE structure if bWait is TRUE. If bWait is FALSE, the parameter
is ignored and should be NULL.
pImgTrans Optional pointer to an HHP_IMAGE_TRANSFER structure. This structure overrides (just
for this call) the current imager configuration, and specifies the pixel subsample, cropping
rectangle, transfer compression type, compression factor (for JPEG lossy transfer), and
progress notification method. If this parameter is NULL, the current imager configuration
settings are used except for the progress notification methods that must be specified for
each call if notification is desired.
bWait If TRUE, do not return until the image is received or an error occurs. If FALSE, return
immediately. One of the event notification methods must be enabled to receive notification
on completion.
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
)
Parameter Description
ptcConnectName The name of driver for the hardware port, e.g., "COM1:" or "\\.\COM12."
pStruct An optional structure that contains setup information for the hardware port, or NULL.
HHP_SERIAL_PORT_CONFIG is used to configure a serial port connection.
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.
Note: Since the HHP_INTEL_IMG structure requires that image offsets and size be specified in barcode units, the
HHP_INTEL_IMG structure has a size member that allows you to specify (in pixels) the maximum allowable width and
height for the returned image.
hhpRawAcquireIntelligentImage(
PHHP_INTEL_IMG pIntelImg,
PHHP_RAW_DECODE_MSG pRawDecodeMsg,
DWORD dwTimeout,
PHHP_IMAGE pImg,
BOOL bWait
)
Parameter Description
pIntelImg Pointer to an HHP_INTEL_IMG structure that contains the setup parameters describing
the location of the intelligent image relative to the barcode.
pRawDecodeMsg Pointer to an HHP_RAW_DECODE_MSG structure if bWait is TRUE. If bWait is FALSE,
the parameter is ignored and should be NULL. The intelligent barcode raw data
(untranslated) is returned here.
dwTimeout Maximum time (in milliseconds) to attempt to decode before declaring a no decode.
pImg Pointer to an HHP_IMAGE structure if bWait is TRUE. If FALSE, the parameter is ignored
and should be NULL.
bWait If TRUE, do not return until the image is received, the decode timeout is reached, or an
error occurs. If FALSE, return immediately. One of the event notification methods must
be enabled to receive notification of completion (see hhpSetAsyncMethods on page 2-10).
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
Parameter Description
cfgType Use SETUP_TYPE_CURRENT for the current settings, or SETUP_TYPE_DEFAULT for
the customer default settings.
item One of the members of the enumerated type ConfigItems_t. The valid values are:
BEEPER_CONFIG Returns beeper control settings for devices with audible
beepers. The settings include volume, beep on decode,
and beep on reset.
TRIGGER_CONFIG Returns values for all trigger timeouts and current
trigger mode.
DECODER_CONFIG Returns the decoder setup. This includes single
decode, multiple decodes, print weight, centered
decode, and aimer.
POWER_CONFIG Contains low power configuration settings: trigger
mode, low power timeout, low power imaging, LED
brightness, aimer LED settings, and system clock
speed.
VERSION_INFO Returns the SDK, imager firmware, and imager boot
code versions.
SYMBOLOGY_CONFIG Returns the enable and setup parameters for all
symbologies. Individual symbologies can be read by
calling hhpReadSymbologyConfig.
SERIAL_PORT_CONFIG If using a serial connection imager, this returns the
serial port setup parameters of the imager.
IMAGE_ACQUISITION Returns the current imager settings for capture mode,
manual exposure, manual gain, manual frame rate,
target white value, target window, aimer and
illumination duty cycle, and triggering mode (hardware
trigger dependent).
IMAGE_TRANSFER Returns the current image transfer protocols, such as
cropping window, pixel subsample, and transfer
compression.
SEQUENCE_CONFIG Returns the sequence mode enable/disable state and
the data sequence command string.
ALL_CONFIG All of the above except serial port config.
pStruct Pointer to the appropriate structure based on parameter “item:”
HHP_BEEPER
HHP_TRIGGER
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
Loading...