How it Works
Hand Held Products
Loading...
4X00
User Manual
90 pgs2.69 Mb0
Table of contents
Loading...

Hand Held Products 4X00 User Manual

IMAGETEAM™ 4X00 Series
For Adaptus Imaging Technology Imagers:
IT4000, IT4100, and IT4300
Software Development Kit (SDK)
User’s Guide
Disclaimer
Hand Held Products 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 which 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 Hand Held Products.
© 2000-2005 Hand Held Products, Inc. All rights reserved. Web Address: www.handheld.com
Microsoft trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Other product names mentioned in this document may be trademarks or registered trademarks of other companies and are the property of their respective owners.
®
Visual C/C++®, Windows® 95, Windows® 98, Windows® 2000, Windows® CE, and Windows NT® are either registered

Table of Contents

Chapter 1 - Introduction
Design Overview.................................................................................................................................1-1
User Layer.....................................................................................................................................1-1
OEM API Layer............................................................................................................................1-1
Image Acquisition Layer...............................................................................................................1-1
Hardware Interface Layer .............................................................................................................1-1
Features of the 4X00 Series.................................................................................................................1-2
Target Operating Systems for the 4X00 Series.............................................................................1-2
Data Type Definitions .........................................................................................................................1-6
Chapter 2 - API Function Descriptions
oemAcquireImage ........................................................................................................................2-1
oemAimerOn ................................................................................................................................2-1
oemConnect .................................................................................................................................2-2
oemDefaultSymbology ................................................................................................................2-2
oemDisableSymbology ................................................................................................................2-2
oemDisableSymbologyAll ...........................................................................................................2-3
oemDisconnect .............................................................................................................................2-3
oemEnableSymbology .................................................................................................................2-3
oemEnableSymbologyAll ............................................................................................................2-3
oemGetAPIRevision ....................................................................................................................2-4
oemGetDecodeAttemptLimit .......................................................................................................2-4
oemGetDecodeCenteringWindow ...............................................................................................2-4
oemGetDecodeMode ...................................................................................................................2-5
oemGetDecoderRevision .............................................................................................................2-5
oemGetDecodeTime ....................................................................................................................2-5
oemGetErrorMessage ...................................................................................................................2-6
oemGetExposureSettings .............................................................................................................2-6
oemGetImage ...............................................................................................................................2-7
oemGetImageData .......................................................................................................................2-8
oemGetImagerInfo .......................................................................................................................2-8
oemGetImagerProperties .............................................................................................................2-9
oemGetLastImage ......................................................................................................................2-10
oemGetLastImageExt .................................................................................................................2-10
oemGetLastImageSize ...............................................................................................................2-11
oemGetLeaveLightsOn ..............................................................................................................2-11
oemGetLinearRange ..................................................................................................................2-12
oemGetMaxMessageChars ........................................................................................................2-12
oemGetPrintWeight ...................................................................................................................2-12
oemGetScanDriverRevision .......................................................................................................2-13
oemGetSearchTimeLimit ...........................................................................................................2-13
oemGetSetupAll .........................................................................................................................2-13
oemGetSetupAusPost .................................................................................................................2-14
oemGetSetupAztec .....................................................................................................................2-14
oemGetSetupBPO ......................................................................................................................2-14
oemGetSetupCanPost .................................................................................................................2-15
oemGetSetupChinaPost .............................................................................................................2-15
oemGetSetupCodabar ................................................................................................................2-16
oemGetSetupCodablock .............................................................................................................2-16
oemGetSetupCode11 .................................................................................................................2-17
oemGetSetupCode128 ...............................................................................................................2-18
oemGetSetupCode16K ............................................................................................................
oemGetSetupCode32 .................................................................................................................2-19
...2-18
i
oemGetSetupCode39 .................................................................................................................2-19
oemGetSetupCode49 .................................................................................................................2-20
oemGetSetupCode93 .................................................................................................................2-21
oemGetSetupComposite .............................................................................................................2-21
oemGetSetupCompositeEx ........................................................................................................2-22
oemGetSetupCouponCode .........................................................................................................2-23
oemGetSetupDataMatrix ...........................................................................................................2-23
oemGetSetupDutchPost .............................................................................................................2-24
oemGetSetupEAN8 ....................................................................................................................2-24
oemGetSetupEAN13 ..................................................................................................................2-25
oemGetSetupIATA25 ................................................................................................................2-26
oemGetSetupImager ...................................................................................................................2-27
oemGetSetupInt25 .....................................................................................................................2-27
oemGetSetupISBT .....................................................................................................................2-28
oemGetSetupJapost ....................................................................................................................2-28
oemGetSetupKoreanPost ...........................................................................................................2-28
oemGetSetupMaxicode ..............................................................................................................2-29
oemGetSetupMesa .....................................................................................................................2-30
oemGetSetupMicroPDF .............................................................................................................2-30
oemGetSetupMSI .......................................................................................................................2-31
oemGetSetupMx25 ....................................................................................................................2-32
oemGetSetupOCR ......................................................................................................................2-32
oemGetSetupPDF417 .................................................................................................................2-33
oemGetSetupPlanet ....................................................................................................................2-34
oemGetSetupPlessey ..................................................................................................................2-34
oemGetSetupPosiCode ...............................................................................................................2-35
oemGetSetupPostnet ..................................................................................................................2-36
oemGetSetupQR ........................................................................................................................2-36
oemGetSetupRSS .......................................................................................................................2-37
oemGetSetupStrt25 ....................................................................................................................2-37
oemGetSetupTelepen .................................................................................................................2-38
oemGetSetupTLC39 ..................................................................................................................2-38
oemGetSetupTrioptic .................................................................................................................2-39
oemGetSetupUPCA ...................................................................................................................2-39
oemGetSetupUPCE ....................................................................................................................2-40
oemGetVideoReverse ................................................................................................................2-41
oemImageStreamInit ..................................................................................................................2-42
oemImageStreamStart ................................................................................................................2-42
oemImageStreamRead ...............................................................................................................2-42
oemImageStreamStop ................................................................................................................2-43
oemLeaveLightsOn ....................................................................................................................2-43
oemLightsOn ..............................................................................................................................2-43
oemPowerOffImager ..................................................................................................................2-43
oemSetDecodeAttemptLimit .....................................................................................................2
-44
oemSetDecodeCenteringWindow ..............................................................................................2-44
oemSetDecodeMode ..................................................................................................................2-45
oemSetExposureMode ...............................................................................................................2-45
oemSetExposureSettings ............................................................................................................2-45
oemSetLinearRange ...................................................................................................................2-46
oemSetPrintWeight ....................................................................................................................2-46
oemSetScanningLightsMode .....................................................................................................2-46
oemSetSearchTimeLimit ...........................................................................................................2-47
oemSetupAztec ..........................................................................................................................2-47
oemSetupChinaPost ...................................................................................................................2-47
oemSetupCodabar ......................................................................................................................2-48
oemSetupCodablock ..................................................................................................................2-48
oemSetupCode11 .......................................................................................................................2-49
ii
oemSetupCode128 .....................................................................................................................2-49
oemSetupCode16K ....................................................................................................................2-50
oemSetupCode39 .......................................................................................................................2-50
oemSetupCode49 .......................................................................................................................2-51
oemSetupCode93 .......................................................................................................................2-52
oemSetupComposite ..................................................................................................................2-52
oemSetupCompositeEx ..............................................................................................................2-52
oemSetupDataMatrix .................................................................................................................2-53
oemSetupEAN8 .........................................................................................................................2-53
oemSetupEAN13 .......................................................................................................................2-54
oemSetupIATA25 ......................................................................................................................2-55
oemSetupInt25 ...........................................................................................................................2-55
oemSetupKoreanPost .................................................................................................................2-56
oemSetupMaxicode ....................................................................................................................2-56
oemSetupMesa ...........................................................................................................................2-57
oemSetupMicroPDF ...................................................................................................................2-57
oemSetupMSI .............................................................................................................................2-58
oemSetupMx25 ..........................................................................................................................2-58
oemSetupOCR ...........................................................................................................................2-59
oemSetupPDF417 ......................................................................................................................2-60
oemSetupPlanet ..........................................................................................................................2-60
oemSetupPlessey ........................................................................................................................2-60
oemSetupPosiCode ....................................................................................................................2-61
oemSetupPostnet ........................................................................................................................2-61
oemSetupQR ..............................................................................................................................2-61
oemSetupRSS .............................................................................................................................2-62
oemSetupStrt25 ..........................................................................................................................2-62
oemSetupTelepen .......................................................................................................................2-63
oemSetupUPCA .........................................................................................................................2-63
oemSetupUPCE .........................................................................................................................2-64
oemSetVideoReverse .................................................................................................................2-65
oemStartIntellImgXfer ...............................................................................................................2-65
oemWaitForDecode ...................................................................................................................2-67
oemWaitForDecodeRaw ............................................................................................................2-68
oemWaitMultipleDecode ...........................................................................................................2-69
oemWaitMultipleDecodeRaw ....................................................................................................2-70
Chapter 3 - Symbology Identifiers
Symbology Identifiers .........................................................................................................................3-1
Function Result Values........................................................................................................................3-2
Chapter 4 - Customer Support
Technical Assistance ...........................................................................................................................4-1
Online Technical Assistance.........................................................................................................4-1
iii
iv
1

Introduction

This document is an overview of the structure of the IT4X00 Series OEM imaging software provided by Hand Held Products. Detailed information that describes the Hand Held Products OEM Application Programming Interface is provided as a part of the 4X00 Series.

Design Overview

The Hand Held Products OEM imaging software supports a number of different Hand Held Products imaging engines, while exposing the user to a common programming interface for all supported imagers. This approach provides Hand Held Products with a simple way of adding support for new imaging hardware, while allowing user software to remain largely unchanged. In support of this design approach, the software components implemented in the Hand Held Products OEM imaging software have been organized in the following layered format:

User Layer

OEM API Layer

Image Acquisition Layer

Hardware Interface Layer

Of the four layers, Hand Held Products supplies the OEM API and Image Acquisition layers.
User Layer
The User Layer can be the application that is written by a developer or end user that accesses the imaging system by using the OEM API functions. The User Layer can alternatively be an abstraction layer provided by an OEM that allows the OEM to customize the level of API functionality exposed to their end user. Either option has access to all the applicable 4X00 Series functions that access and control the imaging subsystem
OEM API Layer
The OEM API Software is supplied by Hand Held Products and is the primary interface to the imaging system. For Windows
©
CE
applications, the OEM API Software functionality is provided in the form of a Windows Dynamic Link Library. For non­Windows CE applications, the form of the OEM API is to be determined. Full explanation of the 4X00 Series is provided later in this document.
Image Acquisition Layer
The Image Acquisition Software layer is the software supplied by Hand Held Products that is responsible for imager auto detection, initialization, state management, exposure control, and image acquisition. During application execution, this software maintains the state and control of the imager, processes requests for images, and executes configuration and control requests. For Windows CE applications, this layer is implemented in a stream device driver and is used by the OEM API layer. For non­Windows CE applications, the form of this layer and its interface to the OEM API layer is to be determined.
Hardware Interface Layer
The Hardware Interface Software is the hardware-specific software provided by the system developer and used by the Image Acquisition Software to access the physical imaging hardware and run hardware-specific tasks on the system. This software is called upon by Image Acquisition Software to handle physical control of the hardware, such as communication with the imager, timing functionality, low level interrupt service routine control, DMA initialization and control, system specific memory control, and illumination functionality. For Windows CE applications, this layer is provided in the form of a Windows Dynamic Link Library that is loaded by the Imaging device driver. For non-Windows CE applications, the form of this layer and its interface to the Image Acquisition Software is to be determined.
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 1 - 1

Features of the 4X00 Series

The 4X00 Series consists of the following:
• The API Definition and Documentation
• API Libraries
• Sample Code The 4X00 Series functions are defined on a higher level so they can be easily understood and integrated into your applications.
• The image/data capture engine is easily integrated.
• A single API is used for all Hand Held Products engines.
• Libraries are available for Windows CE 2.x and Windows CE 3.x.
• Sample source code is provided so you can see an example of how to use the API functions.

Target Operating Systems for the 4X00 Series

The 4X00 Series is designed for use with Microsoft Windows CE version 2.0 and above
1 - 2 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide
Image Engine API Library Summary
The following is a summary of the API functions. The full description of each of function is found on the page noted.
Core Function Summary Description Page
oemAimerOn Turn on/off the engine's aiming LEDs 2-1 oemConnect Initialize connection with engine device 2-2 oemDisconnect Close the connection to the engine device 2-3
oemGetAPIRevision Retrieve the API library's software revision information oemGetDecodeMode Retrieve the decoding mode of the engine 2-5 oemGetErrorMessage oemGetImagerProperties Returns information about the imager 2-9 oemGetLeaveLightsOn
oemGetScanDriverRevision
oemLeaveLightsOn
oemPowerOffImager
Given an error number, returns a string describing the error condition
Return parameter reflecting operation mode of illumination LEDs during scanning
Returns the revision of the scan driver component that interfaces to the OEM API layer
Configure illumination LEDs to be always on or in normal mode during scanning
Allows the application to fully power down the imager for additional power control
Decoder Functions
oemDefaultSymbology oemDisableSymbology Disable decoding of specific bar code symbologies 2-2 oemDisableSymbologyAll oemEnableSymbology Enable decoding of specific bar code symbologies 2-3 oemEnableSymbologyAll oemGetDecodeAttemptLimit Retrieves the current decode attempt maximum time limit 2-4
oemGetDecodeCenteringWindow Enable decode centering mode 2-4 oemGetDecodeTime Returns time to decode in milliseconds 2-5 oemGetDecoderRevision Retrieve decoder’s current revision 2-5
oemGetLinearRange
oemGetMaxMessageChars oemGetPrintWeight Retrieve the current or default print weight the decoder expects 2-12
oemGetSearchTimeLimit Retrieves the current search maximum time limit 2-13 oemGetSetupAll Gets all symbology decoding options 2-13 oemGetSetupAusPost Gets the Australian Postal Code symbology decoding options 2-14
oemGetSetupAztec oemGetSetupBPO Gets the British Postal Code symbology decoding options 2-14
oemGetSetupCanPost Gets the Canadian Postal Code symbology decoding options 2-15 oemGetSetupChinaPost Gets the Chinese Postal Code symbology decoding options 2-15
Return some or all symbology options back to factory default settings
Disable decoding of all symbologies, including unknown symbologies
Enable decoding of all symbologies, including unknown symbologies
Get the size of the window used in Advanced Linear decoding mode
Retrieve the size of the largest possible message (in characters)
Gets the Aztec and Aztec Mesa Code symbology-specific decoding options
2-4
2-6
2-11
2-13
2-43
2-43
2-2
2-3
2-3
2-12
2-12
2-14
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 1 - 3
oemGetSetupCodabar Gets the Codabar symbology decoding options 2-16 oemGetSetupCodablock Gets the Codablock symbology decoding options 2-16 oemGetSetupCode11 Gets the Code 11 symbology decoding options 2-17 oemGetSetupCode128 Gets the Code 128 symbology decoding options 2-18 oemGetSetupCode16K Gets the Code 16K symbology decoding options 2-18 oemGetSetupCode32 Gets the Code 32 symbology decoding options 2-19 oemGetSetupCode39 Gets the Code 39 symbology decoding options 2-19 oemGetSetupCode49 Gets the Code 49 symbology decoding options 2-20 oemGetSetupCode93 Gets the Code 93 symbology decoding options 2-21 oemGetSetupComposite Gets the EANoUCC Composite symbology decoding options 2-21
oemGetSetupCompositeEx oemGetSetupCouponCode Gets the Coupon Code symbology decoding options 2-23
oemGetSetupDataMatrix Gets the Data Matrix symbology decoding options 2-23 oemGetSetupDutchPost Gets the Dutch Postal Code symbology decoding options 2-24 oemGetSetupEAN8 Gets the EAN 8 symbology decoding options 2-24 oemGetSetupEAN13 Gets the EAN 13 symbology decoding options 2-25 oemGetSetupIATA25 Gets the IATA 2 of 5 symbology decoding options 2-26 oemGetSetupInt25 Gets the Interleaved 2 of 5 symbology decoding options 2-27 oemGetSetupISBT Gets the ISBT symbology decoding options 2-28 oemGetSetupJapost Gets the Japanese Postal Code symbology decoding options 2-28 oemGetSetupKoreanPost Gets the Korean Postal Code symbology decoding options 2-28 oemGetSetupMaxicode Gets the MaxiCode symbology decoding options 2-29 oemGetSetupMesa Gets the Aztec Mesa symbology decoding options 2-30 oemGetSetupMicroPDF Gets the MicroPDF417 symbology decoding options 2-30 oemGetSetupMSI Gets the MSI symbology decoding options 2-31 oemGetSetupMx25 Gets the Matrix 2 of 5 symbology decoding options 2-32 oemGetSetupOCR Gets the OCR symbology decoding options 2-32 oemGetSetupPDF417 Gets the PDF417 symbology decoding options 2-33 oemGetSetupPlanet Gets the Planet Code symbology decoding options oemGetSetupPlessey Gets the Plessey symbology decoding options 2-34 oemGetSetupPosiCode Gets the Posicode symbology decoding options 2-35 oemGetSetupPostnet Gets the Postnet symbology decoding options 2-36 oemGetSetupQR Gets the QR Code symbology decoding options 2-36 oemGetSetupRSS Gets the RSS symbology decoding options 2-37 oemGetSetupStrt25 Gets the Straight 2 of 5 symbology decoding options 2-37 oemGetSetupTelepen Gets the Telepen symbology decoding options 2-38 oemGetSetupTLC39 Gets the TLC39 symbology decoding options 2-38 oemGetSetupTrioptic Gets the Trioptic symbology decoding options 2-39 oemGetSetupUPCA Gets the UPC version A symbology decoding options 2-39 oemGetSetupUPCE Gets the UPC version E0 & E1 symbology decoding options 2-40 oemGetVideoReverse Determines if decoding of inverted symbols is enabled 2-41 oemLightsOn Turns the engine's illumination LEDs on and off. 2-43 oemSetDecodeAttemptLimit Sets the decode attempt maximum time limit. 2-44 oemSetDecodeCenteringWindow Enables/Setup decode centering mode. 2-44
Gets the EANoUCC Composite as well as other Composite symbology decoding options
2-22
2-34
1 - 4 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide
oemSetDecodeMode Sets the decoding mode of the engine 2-45 oemSetLinearRange
oemSetPrintWeight
oemSetSearchTimeLimit oemSetupAztec Set the Aztec Code symbology decoding options 2-47
oemSetupChinaPost Set the Chinese Postal Code symbology decoding options 2-47 oemSetupCodabar Set the Codabar symbology decoding options 2-48 oemSetupCodablock Set the Codablock symbology decoding options 2-48 oemSetupCode11 Set the Code 11 symbology decoding options 2-49 oemSetupCode128 Set the Code 128 symbology decoding options 2-49 oemSetupCode16K Set the Code 16K symbology decoding options 2-50 oemSetupCode39 Set the Code 39 symbology decoding options 2-50 oemSetupCode49 Set the Code 49 symbology decoding options 2-51 oemSetupCode93 Set the Code 93 symbology decoding options 2-52 oemSetupComposite Set the EANoUCC Composite symbology decoding options 2-52
oemSetupCompositeEx oemSetupDataMatrix Set the Data Matrix symbology decoding options 2-53
oemSetupEAN8 Set the EAN 8 symbology decoding options 2-53 oemSetupEAN13 Set the EAN 13 symbology decoding options 2-54 oemSetupIATA25 Set the IATA 2 of 5 symbology decoding options 2-55 oemSetupInt25 Set the Interleaved 2 of 5 symbology decoding options 2-55 oemSetupKoreanPost Set the Korean Postal Code symbology decoding options 2-56 oemSetupMaxicode Set the MaxiCode symbology decoding options 2-56 oemSetupMesa Set the Aztec Mesa symbology decoding options 2-57 oemSetupMicroPDF Set the MicroPDF417 symbology decoding options 2-57 oemSetupMSI Set the MSI symbology decoding options 2-58 oemSetupMx25 Set the Matrix 2 of 5 symbology decoding options 2-58 oemSetupOCR Set the OCR symbology decoding options 2-59 oemSetupPDF417 Set the PDF417 symbology decoding options 2-60 oemSetupPlanet Set the Planet Code symbology decoding options 2-60 oemSetupPlessey Set the Plessey Code symbology decoding options 2-60 oemSetupPosiCode oemSetupPostnet Set the Postnet symbology decoding options 2-61 oemSetupQR Set the QR Code symbology decoding options 2-61 oemSetupRSS Set the RSS symbology decoding options 2-62 oemSetupStrt25 Set the Straight 2 of 5 symbology decoding options 2-62 oemSetupTelepen Set the Telepen symbology decoding options 2-63 oemSetupUPCA Set the UPC version A symbology decoding options 2-63 oemSetupUPCE Set the UPC version E0 & E1 symbology decoding options 2-64 oemSetVideoReverse Enables/disables the decoding of inverted symbols 2-65
oemWaitForDecode
Sets the size of the window used in the Advanced Linear decoding mode
Adjust the print weight or relative blackness that the decoder expects
Sets the maximum time limit for the decoders search processing
Set the EANoUCC Composite as well as other Composite symbology decoding options
Set the PosiCode symbology decoding options 2-61
The engine scans until a symbol is decoded, or a timeout is reached
2-46
2-46
2-47
2-52
2-67
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 1 - 5
oemWaitForDecodeRaw oemWaitMultipleDecode Reads multiple symbols using a single function call 2-69 oemWaitMultipleDecodeRaw
The engine scans until a symbol is decoded, or a timeout is reached - decoded message is returned in raw form
Reads multiple symbols using a single function call - decoded message is returned in raw form
2-68
2-70
Imaging Functions
oemAcquireImage Acquires an image but does not return it. 2-1 oemGetExposureSettings Retrieves image parameters used during image acquisition. 2-6 oemGetImage Retrieve an image from the engine 2-7 oemGetImageData Get image data from the Imager 2-8
oemGetImagerInfo oemGetLastImage Retrieves the last image acquired 2-10 oemGetLastImageExt
oemGetLastImageSize
oemGetSetupImager Gets the current imager setup values. 2-27 oemImageStreamInit Intialize image streaming interface. 2-42 oemImageStreamRead Retrieve current image 2-42 oemImageStreamStart Start imager acquiring images 2-42 oemImageStreamStop Tell imager to stop acquiring images 2-43 oemStartIntellImgXfer Starts an IQ image transfer 2-65
Retrieve the pixel dimensions and bit depth of the engine's Imager
Retrieves the last image and the exposure parameters acquired by the image engine
Retrieve the rows, columns and size of the last image returned by oemAcquireImage, oemGetImage, or oemImageStreamRead.
2-8
2-10
2-11

Data Type Definitions

Throughout this document the following variable types are used. These data types are defined in the Oemdecodece.h header file.
Variable Description
BOOL OS-dependent-size Boolean variable (1 = true, 0 = false). BYTE 8 bit unsigned variable. DecodeMsg_t Typedef structure used to define decoded bar code message information. DecodeMsgRaw_t Typedef structure used to define decoded bar code message information in raw format. DWORD 32 bit unsigned integer variable.
ExposureMode_t
ExposureSettings_t FileFormat_t Enumerated integer type identifying possible image data formats.
ImagerDesc_t Typedef structure used to set the format of the images returned from the engine. ImagerSetup_t Typedef structure used to set imager parameters used during image acquisition. IntellImgDesc_t T ypedef structure used to set parameters used during an IQ image transfer. OCRDirection_t Enumerated integer identifying OCR character orientation. OCRMode_t Enumerated integer identifying the OCR font to be decoded.
Enumerated integer type used to select the exposure mode used during image acquisition. The mode options are: fixed, on chip, and Hand Held Products exposure mode.
Typedef structure used to hold all possible exposure setting parameters used during image acquisition.
1 - 6 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide
Variable Description
Result_t
ScanIlluminat_t SetupType_t Enumerated integer type that identifies setup type for configuration functions.
TCHAR OS-dependent character variable. 16 bit for Unicode systems, otherwise 8 bits. WORD 16 bit unsigned integer variable.
Enumerated integer type that defines API function result values. See Function Result
Values on page 3-2.
Enumerated integer type that identifies possible illumination modes used during image acquisition.
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 1 - 7
1 - 8 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide
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 return a result code of type Result_t. See Function Result Values on page 3-2 for a table of result code values.

oemAcquireImage

This function tells the Imager to acquire an image, but does not return the image.
Result_t oemAcquireImage (
const ImagerSetup_t *pImagerSetup )
Return Values
RESULT_SUCCESS RESULT_ERR_UNSUPPORTED RESULT_ERR_NOIMAGE RESULT_ERR_PARAMETER
Parameters
pImagerSetup
Pointer to a data structure that sets up the Imager.
typedef struct {
int NumUpdates; int Exposure; int Gain; int TargetWhite; int TargetWhiteWindow; int Reserved;
} ImagerSetup _t; NumUpdates: The Imager takes multiple images attempting to reach a target white value in the image, while
adjusting its gain and exposure settings. This limits the number of attempts. Exposure : Maximum allowable exposure setting for the Imager. The greater the exposure, the more light,
and hence the brighter the image. However, it also increases motion sensitivity. Gain: Maximum allowable gain for the Imager. Higher gain will yield a brighter image, at the expense of
added noise. This will not affect motion sensitivity. TargetWhite: The Imager takes multiple images attempting to reach this target white value in the image, plus
or minus the TargetWhiteWindow value. TargetWhiteWindow: The acceptable target white value falls within the range TargetWhite +/-
TargetWhiteWindow. Reserved: Must be set to -1.

oemAimerOn

This function turns the engine's aiming mechanism on or off.
Result_t oemAimerOn (
BOOL bEnable )
Return Values
RESULT_SUCCESS RESULT_ERR_DRIVER RESULT_ERR_NORESPONSE
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 2 - 1
Parameters
bEnable
If TRUE, the aiming mechanism is turned on; otherwise the aiming mechanism is turned off.

oemConnect

The application should call this function before any other API functions. Once an application has connected to the engine, all other API functions can be successfully called. The application does not need to re-connect to the engine unless it has called oemDisconnect (page 9).
Result_t oemConnect ( ) Return Values
RESULT_SUCCESS RESULT_ERR_DRIVER
Parameters
All Reserved, should be NULL

oemDefaultSymbology

This function sets the specified symbologies to their factory default configurations. See the individual setup functions to determine the factory default setting for a particular symbology.
Result_t oemDefaultSymbology (
BOOL *pSymbology, )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
Parameters
pSymbology
Points to an array of symbologies you want to default. For example, if a value is set to 1 (i.e., pSymbology [SYM_AZTEC]=1), then Aztec symbology is defaulted.
Note: The array must be of size MAX_SYMBOLOGIES (Defined in Oemdecodece.h). You must initialize the entire array before
calling this function.

oemDisableSymbology

This function disables specified symbologies from decoding.
Result_t oemDisableSymbology (
BOOL *pSymbology )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
Parameters
pSymbology
Points to an array of symbologies you want to disable. For example, if a value is set to 1 (i.e., pSymbology [SYM_AZTEC]=1), then Aztec decoding is disabled.
Note: The array must be of size MAX_SYMBOLOGIES (Defined in Oemdecodece.h). You must initialize the entire array before
calling this function.
2 - 2 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide

oemDisableSymbologyAll

This function disables all symbologies from decoding, including any unknown symbologies.
Result_t oemDisableSymbologyAll (
void )
Return Values
RESULT_SUCCESS
Parameters
None.

oemDisconnect

This function terminates the connection with the engine. Any resources used by the connection device driver are freed.
Result_t oemDisconnect (
void )
Return Values
RESULT_SUCCESS
Parameters
None.

oemEnableSymbology

This function enables specified symbologies for decoding.
Result_t oemEnableSymbology (
BOOL *pSymbology )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
Parameters
pSymbology
Points to an array of symbologies you want to enable. For example, if a value is set to 1 (i.e., pSymbology [SYM_AZTEC]=1), then Aztec decoding is enabled.
Note: The array must be of size MAX_SYMBOLOGIES (Defined in Oemdecodece.h). You must initialize the entire array before
calling this function.

oemEnableSymbologyAll

This function enables all symbologies for decoding, including any unknown symbologies.
Result_t oemEnableSymbologyAll (
void )
Return Values
RESULT_SUCCESS
Parameters
None.
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 2 - 3

oemGetAPIRevision

This function returns an ASCII string containing the API's current revision.
Result_t oemGetAPIRevision (
TCHAR *pszRev )
Return Values
RESULT_SUCCESS always
Parameters
pszRev
Upon successful return, this null-terminated string is filled in with the revision level of the API. The caller must allocate at least ENGINE_API_RESPONSE_LEN bytes for this string.

oemGetDecodeAttemptLimit

This function is used to retrieve the current decode attempt maximum time limit. The limit, specified in milliseconds, is the maximum amount of time the decoder may use to attempt a decode on the current image.
Result_t oemGetDecodeAttemptLimit (
SetupType_t SetupType, WORD *nLimit )
Return Values
RESULT_SUCCESS RESULT_ERR_UNSUPPORTED RESULT_ERR_PARAMETER
Parameters
Setup Type
SETUP_TYPE_CURRENT for current settings, or SETUP_TYPE_DEFAULT for default settings.
pnLimit
Points to a word variable that upon return of RESULT_SUCCESS will contain the decode attempt maximum time limit. A value of zero indicates no limit.

oemGetDecodeCenteringWindow

This function returns the Enabled/Setup information for decode centering mode. In this mode, a decode call is only successful if the area bounding the decoded symbol intersects a caller defined rectangle located about the center of the captured image.
Note: This function allows the engine to discriminate symbols that are located physically close to each other so only one symbol
is captured during decode. Only the symbol intersecting the intersection rectangle is returned.
Result_t oemGetDecodeCenteringWindow (
SetupType_t SetupType, BOOL *pbEnabled, RECT *pIntersectRect )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
2 - 4 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide
Parameters
SetupType
SETUP_TYPE_CURRENT for current settings, or SETUP_TYPE_DEFAULT for default settings.
PbEnabled
Pointer to a BOOL which returns TRUE if centering mode enabled or FALSE if it's not.

oemGetDecodeMode

This function retrieves the decoding mode of the engine.
Result_t oemGetDecodeMode (
SetupType_t SetupType, WORD *pnMode )
Return Values
RESULT_SUCCESS RESULT_ERR_UNSUPPORTED
Parameters
SetupType
SETUP_TYPE_CURRENT for current settings, or SETUP_TYPE_DEFAULT for default settings.
pnMode
Points to a WORD variable that will be filled in with status for the decode mode: 1 = Standard 2 = Advanced Linear 4 = Quick Omni

oemGetDecoderRevision

This function returns an ASCII string containing the decoder’s current revision.
Result_t oemGetDecoderRevision (
TCHAR *pszRev )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
Parameters
pszRev
Upon successful return, this null terminated string is filled with the revision level of the decoder software. The caller must allocate at least ENGINE_API_RESPONSE_LENGTH bytes for this string.

oemGetDecodeTime

This function the time in milliseconds that it took to decode the barcode data returned by oemWaitForDecode().
Result_t oemGetDecodeTime (
DWORD *pdwTime, )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
Parameters
pdwTime
Points to an unsinged 32 bit integer into which the last time to decode is returned.
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 2 - 5

oemGetErrorMessage

This function returns a string containing the description of the error corresponding to the nError parameter.
Result_t oemGetErrorMessage (
TCHAR *pszErrorMsg, Result_t nError )
Return Values
RESULT_SUCCESS always
Parameters
pszErrorMsg
Upon successful return, this null-terminated string is filled in with text describing the error identified by the nError parameter. The caller must allocate at least ENGINE_API_RESPONSE_LEN bytes for this string.
nError
A value returned from another API function call.

oemGetExposureSettings

This function is used to retrieve the various image parameters that are used during image acquisition.
Result_t oemGetExposureSettings (
ExposureSettings_t *pExpsoureSettings )
Return Values
RESULT_SUCCESS RESULT_ERR_UNSUPPORTED RESULT_ERR_DRIVER RESULT_ERR_PARAMETER
Parameters
pExposureSettings
A pointer to an exposure settings structure that has been initialized to zero. Upon return the structure will contain the current exposure parameters used during image acquisition.
2 - 6 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide

oemGetImage

This function retrieves an image from the engine and stores it in memory pointed to by pImageBuffer.
Result_t oemGetImage (
BYTE *pImageBuffer, DWORD *pdwSize, WORD nTop, WORD nLeft, WORD nRight, WORD nBottom, WORD nSkip, WORD nBits, FileFormat_t nFormat, WORD nWhiteValue, WORD nExposeAttempts, WORD nGap, BOOL Invert void ( *fpProgress ) (WORD) )
Return Values
RESULT_SUCCESS RESULT_ERR_UNSUPPORTED RESULT_ERR_DRIVER RESULT_ERR_PARAMETER RESULT_ERR_NORESPONSE RESULT_ERR_BADREGION RESULT_ERR_MEMORY RESULT_ERR_FILE
Parameters
pImageBuffer
Memory pointer to where the image should be stored. The caller must allocate this buffer before calling oemGetImage.
pdwSize
Upon successful return, the number of bytes of image data stored in pImageBuffer.
nTop, nLeft
Coordinates relative to the image engine's pixel grid for first pixel of the transferred image. The upper left pixel has both an nLeft and an nTop value of 0.
nRight, nBottom
Coordinates relative to the image engine's pixel grid for last pixel of the transferred image.
nSkip:
When transferring an image, transfer every nSkip pixel.
nBits
The color depth for the transferred image. Valid values are typically only 8 or 1, but this depends on the engine hardware. Independent of the bits used, a lower value is darker than a higher value. For example, if 8 bits are chosen, then a pixel value of 255 indicates pure white, and a pixel value of 0 indicates pure black. Values in between are to be interpreted as incremental levels of gray.
nFormat: FF_RAW_BINARY
The black and white data stored in the pImageBuffer is stored 1 bit per pixel starting with the upper left pixel and proceeding sequentially left to right and top to bottom.
FF_RAW_GRAY
The grayscale data stored in the pImageBuffer is stored 8 bit per pixel starting with the upper left pixel and proceeding sequentially left to right and top to bottom.
nWhiteValue
The target white value when performing auto exposure control.
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 2 - 7
nExposeAttempts
The number of attempts the unit makes to get the image to the correct exposure level.
nGap
How close the white value of the image must be to the nWhiteValue for the image to be accepted. A value of 0 (zero) can be passed in to cause the unit to use its pre-defined value. For example, if you want to use 10 for the nGap, and the default value for nWhiteValue, then pass in 10 for nGap, and 0 for nWhite.
Invert
The image is rotated 180° (upside down). This allows you to invert images for platforms where the imager is mounted upside down.
fpProgress
Reserved. Must be NULL.

oemGetImageData

This function gets data from the Imager. Each subsequent call fills the supplied buffer with image data. The end of the image data is identified by a GetImageData() call that does not fill the buffer (less than BufferSize bytes were placed in the buffer) and has a return of RESULT_SUCCESS.
Prototype Result_t oemGetImageData (
DWORD dwNumberToRead, BYTE *pBuffer, DWORD *pNumBytesRead )
Return Values
RESULT_SUCCESS RESULT_ERR_DRIVER RESULT_ERR_PARAMETER
Parameters
dwNumberToRead
Size of the user supplied buffer to be filled with image data.
pBuffer
Pointer to the user supplied buffer that holds the image data.
pNumBytesRead:
Returns the number of bytes of image data read.

oemGetImagerInfo

This function returns information about imaging capability of the connected device.
Result_t oemGetImagerInfo (
WORD *pnCols, WORD *pnRows, WORD *pnBits )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
2 - 8 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide
Parameters
pnCols
Upon successful return, this variable points to the number of column pixels in the Imager.
pnRows
Upon successful return, this variable points to the number of row pixels in the Imager.
pnBits
Upon successful return, this variable points to the number of bits per pixel supported by the Imager.

oemGetImagerProperties

This function returns information about the imager.
Result_t oemGetImagerProperties (
ImagerProperties_t *pImgProp )
Return Values
RESULT_ERR_PARAMETER RESULT_ERR_SUCCESS
Parameters
pImgProp
Pointer to structure to be filled by this function with information about the imager.
typedef struct {
DWORD dwSize;
DWORD dwEngineID;// 0 DWORD dwImagerRows; DWORD dwImagerCols; DWORD dwBitsPerPixel;
DWORD dwRotation;
DWORD dwAimerXoffset;
DWORD dwAimerYoffset;
DWORD dwYDepth;
} ImagerProperties_t; dwSize: Size of structure dwEngineID: EngineIDs values
TYPE_NONE =0 (No imager hardware) TYPE_IT4200 =1 TYPE_IT4000 =5 TYPE_IT4100 =6
TYPE_IT4300 =7 dwImagerRows: Number of rows for a given imager dwImagerCols: Number of columns for a given imager. dwBitsPerPixel: Typically this is 8 for byte pixels. dwRotation: RIGHT_SIDE_UP = 0
ROTATED_RIGHT UPSIDE_DOWN
ROTATED_LEFT dwAimerXoffset: This value represents the X coordinate for the center of the aimer pattern. dwAimerYoffset: This value represents the Y coordinate for the center of the aimer pattern.
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 2 - 9

oemGetLastImage

This function is used to retrieve the last image acquired by the image engine.
Result_t oemGetLastImage (
BYTE *pImageBuffer DWORD *pImageSize )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER RESULT_ERR_NOIMAGE
Parameters
pImageBuffer
Pointer to the user supplied buffer to be filled with the image data. The buffer must be at least MAX_IMAGE_SIZE in size.
pImageSize
Pointer to a DWORD that returns the size of the image.

oemGetLastImageExt

This function is used to retrieve the last image acquired by the image engine and the exposure parameters associated with that image.
Result_t oemGetLastImageExt (
BYTE *pImageBuffer, DWORD *pImageSize, ImageAttributes_t *pImageAttributes )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER RESULT_ERR_NOIMAGE
Parameters
pImageBuffer
Pointer to the user-supplied buffer to be filled with the image data. The buffer must be at least MAX_IMAGE_SIZE in size.
pImageSize
Pointer to a DWORD that will return the size of the image.
pImageAttributes
Pointer to an ImageAttributes_t structure that has been initialized to zeros. Upon successful return the structure will contain the specific values for the returned image. Please see the engnapi.h header file for details of the ImageAttributes_t structure.
2 - 10 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide

oemGetLastImageSize

This function returns the number of rows, number of columns and size in bytes of the last image returned by one of the other imaging functions: oemAcquireImage, oemGetImage/oemGetImageData or oemImageStreamRead.
Result_t oemGetLastImageSize (
WORD *pwCols, WORD *pwRows, DWORD *pdwSize )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
Parameters
pwCols
Upon successful return, this variable points to the number of column pixels in the Image.
pwRows
Upon successful return, this variable points to the number of row pixels in the Image.
pdwBytes
Upon successful return, this variable points to the total number of Image bytes.

oemGetLeaveLightsOn

This function returns a parameter reflecting the operational mode of the illumination LEDs during scanning.
Result_t oemGetLeaveLightsOn (
SetupType_t SetupType, BOOL *pbEnable )
Return Values
RESULT_SUCCESS RESULT_ERR_NOTCONNECTED RESULT_ERR_UNSUPPORTED RESULT_ERR_DRIVER RESULT_ERR_PARAMETER RESULT_ERR_NORESPONSE
Parameters
SetupType
SETUP_TYPE_CURRENT for current settings, or SETUP_TYPE_DEFAULT for default settings.
pbEnable
Upon successful return, this variable reflects the operational mode of the illumination LEDs during scanning. If FALSE, the illumination LEDs will be in normal operational mode and will be flashed on and off during scanning. If TRUE, the illumination LEDs are always on during scanning and will not flash.
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 2 - 11

oemGetLinearRange

This function is used to get the size of the window used in the Advanced Linear decoding mode.
Result_t oemGetLinearRange (
SetupType_t SetupType, WORD *pnLinearRange )
Return Values
RESULT_SUCCESS RESULT_ERR_UNSUPPORTED
Parameters
SetupType
SETUP_TYPE_CURRENT for current settings, or SETUP_TYPE_DEFAULT for default settings.
pnLinearRange
Points to a WORD variable where the range value will be placed.

oemGetMaxMessageChars

This function returns the size of the largest possible decode message in characters.
Result_t oemGetMaxMessageChars (
WORD *pnChars )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
Parameters
pnChars
Upon successful return, this variable points to the number of characters (not bytes) required for the largest possible decode message. In WindowsCE the character size is 2 bytes (wchar_t)

oemGetPrintWeight

This function returns the current or default "Print Weight" (relative contrast) expected by the decoder for barcodes or OCR text.
Result_t oemGetPrintWeight (
SetupType_t SetupType, WORD *pnPrintWeight )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
Parameters
SetupType
SETUP_TYPE_CURRENT for current settings, or SETUP_TYPE_DEFAULT for default settings.
pnPrintWeight
Upon successful return, this variable points to the print weight (relative blackness) that the decoder expects to see when attempting to decode symbols or OCR text from an image.
2 - 12 IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide

oemGetScanDriverRevision

This function returns the revision of the scan driver component that interfaces to the OEM API layer.
Result_t oemGetScanDriverRevision(
TCHAR *pszRev )
Return Values
RESULT_ERR_PARAMETER RESULT_ERR_UNSUPPORTED RESULT_ERR_SUCCESS
Parameters
pszRev
Pointer to string that will contain the revision string. This should be allocated prior to the call and contain 80 characters.

oemGetSearchTimeLimit

This function is used to retrieve the current search maximum time limit. The limit, specified in milliseconds, is the maximum amount of time the search process may use to look for potential labels in the current image.
Result_t oemGetSearchTimeLimit (
SetupType_t SetupType, WORD *pnLimit )
Return Values
RESULT_SUCCESS RESULT_ERR_UNSUPPORTED RESULT_ERR_PARAMETER
Parameters
Setup Type
SETUP_TYPE_CURRENT for current settings, or SETUP_TYPE_DEFAULT for default settings.
pnLimit
Points to a word variable that upon return of RESULT_SUCCESS will contain the maximum search time limit. A value of zero indicates no limit.

oemGetSetupAll

This function is used to get all symbology options.
Result_t oemGetSetupAll (
SetupType_t SetupType, BOOL *pEnabled )
Return Values
RESULT_SUCCESS RESULT_ERR_PARAMETER
Parameters
SetupType
SETUP_TYPE_CURRENT for current settings, or SETUP_TYPE_DEFAULT for default settings.
pEnabled
Points to an array of symbologies with a size of MAX_SYMBOLOGIES. This array should be declared and cleared. Upon return, this array will contain the enable/disable status of each symbology.
IMAGETEAM™ 4X00 Series Software Development Kit (SDK) User’s Guide 2 - 13
Loading...
+ 63 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use