VeriFone e315 User guide

Brand: VeriFone

Model: e315

Type: User guide

VeriFone Part Number DOC087-070-EN-A, Revision A

e315 Barcode Application

Programmers Guide

permission of VeriFone, Inc.

The information contained in this document is subject to change without notice. Although VeriFone has attempted to ensure the

accuracy of the contents of this document, this document may include errors or omissions. The examples and sample programs are

for illustration only and may not be suited for your purpose. You should verify the applicability of any example or sample program

before placing the software into productive use. This document, including without limitation the examples and software programs, is

supplied “As-Is.”

VeriFone, Inc.

2099 Gateway Place, Suite 600

San Jose, CA, 95110 USA

www.verifone.com

VeriFone Part Number DOC087-070-EN-A, Revision A

e315 Barcode Application Programmers Guide

VeriFone, the VeriFone logo, Omni, VeriCentre, Verix, and ZonTalk are registered trademarks of VeriFone. Other brand names or

trademarks associated with VeriFone’s products and services are trademarks of VeriFone, Inc.

All other brand names and trademarks appearing in this manual are the property of their respective holders.

Comments? Please e-mail all comments on this document to your local VeriFone Support Team.

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 3

TABLE OF CONTENTS

PREFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Assumptions About the Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Conventions and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

CHAPTER 1

Verix Barcode

Application

Host Request Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Response Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Valid Host Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

CHAPTER 2

Barcode APIs Barcode Device Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Barcode Device Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Barcode Start Scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Barcode Stop Scan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Barcode Passthru. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Barcode Application Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Barcode Trigger Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Beep Immediate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Auto Beep Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Get Auto Beep Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Barcode Button Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Barcode Firmware Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Barcode Restore Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Barcode Picklist Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Barcode Scan Timeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Barcode Timeout – Same Symbol Decodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Barcode Timeout – Different Symbol Decodes . . . . . . . . . . . . . . . . . . . . . . . . . 28

Barcode Continuous Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Barcode Unique Code Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Barcode Mobile Phone/Display Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Barcode Scan Data Prefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Barcode Scan Data Suffix1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Barcode Scan Data Suffix2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Barcode Scan Data Transmit Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Barcode AIM Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Barcode Symbology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Barcode Disable All Symbologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

APPENDIX A Beeper Tone Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

sound() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

APPENDIX B Default Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

TABLE OF CONTENTS

4 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

APPENDIX C Example Header File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 5

PREFACE

This programmer’s manual describes the following features of the Barcode

application:

• Provides descriptions of the message packets

• Provides API descriptions and examples

This manual contains explicit information regarding use of these APIs with V/OS

and a peripheral or internal scanner.

Organization

This manual is organized as follows:

Audience

This document is of interest to application developers creating applications for use

on V/OS-based terminals.

Assumptions About

the Reader

It is assumed that the reader:

• understands Linux programming concepts and terminology.

• has access to a PC running Windows XP or Windows 7.

• has installed the Mentor Sourcery CodeBench DTK and VeriFone SDK on this

machine.

• has access to a running, configured V/OS terminal with the Barcode

application installed.

Conventions and

Acronyms

CHAPTER 1 Presents an overview of the Barcode application, and host request and

response data packets.

Chapter 2 Presents application APIs.

Appendix A Presents beep tone definitions.

Appendix B Presents default parameter values.

Appendix C Presents an example header file.

Abbreviation Definition

bps bits per second

Hz Hertz

LSB least-significant bit

MSB most-significant bit

msec millisecond

V/OS VeriFone Operating System

VRK VeriShield Remote Key

VSS VeriShield Security Scripts

PREFACE

Related Documentation

6 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Documentation

Beginning Linux Programming (4th Edition) by Neil Matthew and Richard Stones.

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 7

CHAPTER 1

Verix Barcode Application

The Host Control Interface defines the message packet format between the host

application on the phone and the Verix Barcode application. These message

packets reflect an encapsulated data field between the host application and the

Verix Barcode application.

Figure 1 illustrates the host request and response packet length and sequence.

The maximum size of the host request and response packets are 2048 bytes.

Figure 1 Host Request and Response Packet Format

The sequence number is in the packet header before the payload, and is

generated by the host device. It is used for proper handshaking and error

handling.

HOST REQUEST PACKET IN BYTES

COMMAND PACKET BYTES

211

OPTIONAL PARAMETER PACKETS 1...n

1 1 VARIABLE

REQUEST

LENGTH

SEQUENCE

REQUEST

VERSION

PROTOCOL

COMMAND

LENGTH

COMMAND

NUMBER

PARAMETER

LENGTH

RESPONSE PACKET (BYTES)

4 4 4 VARIABLE

RESPONSE

LENGTH

SEQUENCE

RESPONSE

STATUS

OPTIONAL

RESPONSE

DATA

PARAMETER

VALUE

NOTE

Reference this manual with the header file Barcode_host.h.

VERIX BARCODE APPLICATION

Host Request Packet

8 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Host Request

Packet

As shown in Figure 1, the Host Request packet is comprised of the following data

packets:

• Request Length–The total size of the host request packet, including this

packet (maximum 2048 bytes).

• Request Sequence–Supplied by the host and unique per command, each

response packet sequence number is linked to the sequence number of the

Request packet. However, asynchronous Response packets have random

sequence numbers. Asynchronous responses are sent after the following

events:

• A successful barcode scan

• A button change-status notification are sent in edge, level, and soft trigger

mode

• Command Packet–This structure comprises the command length, protocol

version, command number, and parameter packets.

• Parameter Packet–There are a variable number of Parameter packets in the

Command packet. The format of the Parameter packet is parameter length,

parameter ID, and parameter value.

Multiple parameter packets can be sent in the same Host Request packet,

which is useful for sending more than one symbology configuration in a single

Command packet.

Response

Packet

The Response packet is comprised of the following data packets:

• Response Length–The total size of host response packet (maximum 2048

bytes).

• Response Sequence–This is usually the sequence number that the host

supplied in a Request packet. However, asynchronous responses have a

random sequence number, which cannot be related to the request sequence

number.

• Response Status–The process status of the previous request:

• 0x00000000 = Success

• 0x00000001 = Failure

• 0x80000000= Asynchronous scanned data

• 0x80000001= Asynchronous buttons change status

Sometimes when response data is available immediately, the data and status

are sent in a single response packet.

• Response Data (optional)–Some responses have optional data with the status

update.

VERIX BARCODE APPLICATION

Valid Host Requests

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 9

Figure 2 illustrates the data format of asynchronous responses:

Figure 2 Asynchronous Response Packet Format

Valid Host

Requests

The following lists valid host request calls:

BARCODE SCAN DATA (BYTES)

444112 VARIABLE

LENGTH

SEQUENCE CODE ID

STATUS AIM ID

SYMBOL

NAME

LENGTH

SEQUENCE

STATUS

BUTTON

STATUS

SCAN DATA

BUTTON CHANGE STATUS (BYTES)

4441

• BAR_DEV_OPEN • BAR_DEV_CLOSE

• START_SCAN • STOP_SCAN

• PASS_THRU • GET_APP_VER

• SET_TRIG_MODE • BEEP_IMMEDIATE

• AUTO_ BEEP_CONFIG • GET_AUTO_BEEP_CONFIG

• BUTTON_STATUS • GET_FIRM_VER

• RESTORE_DEFAULTS • EN_PICKLIST_MODE

• SCAN_TIMEOUT • TIMEOUT_BW_SAME_SYM

• TIMEOUT_BW_DIFF_SYM • EN_CONTINUOUS_RD

• EN_UNIQUE_CODE_REPO • EN_MOBILE_PH_MODE

• EN_PREFIX • EN_SUFFIX1

• EN_SUFFIX2 • EN_XMIT_FMT

• EN_AIM_PATTERN • SYMBOLOGY

• DISABLE_ALL_SYMB •

VERIX BARCODE APPLICATION

Valid Host Requests

10 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 11

CHAPTER 2

Barcode APIs

Barcode Device Open

Powers barcode device and opens the communication port for communication.

Example

Raw data in hex format (MSB to LSB): 0x0000000C000000010004011A

NOTE

This command must be sent before sending any other command.

Length

(4 bytes)

Sequence

(4 bytes) Length

(2 bytes) Protocol Version

(1 byte)

Command#

(1 byte)

0x0C – 0x04 0x01 BAR_DEV_OPEN

BARCODE APIS

Barcode Device Close

12 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Barcode Device Close

Powers down the barcode device and closes the communication port.

Example

Raw data in hex format (MSB to LSB): 0x0000000C000000010004011B

Length

(4 bytes)

Sequence

(4 bytes) Length

(2 bytes) Protocol Version

(1 byte)

Command#

(1 byte)

0x0C – 0x04 0x01 BAR_DEV_CLOSE

BARCODE APIS

Barcode Start Scan

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 13

Barcode Start Scan

Activates the scan by sending a START_SCAN command to the barcode reader.

The host initially waits for an ACK/NAK response for this command. After

receiving the ACK, the host waits for an asynchronous scan data response

packet. Besides soft and passive trigger modes, edge and level trigger modes

require START_SCAN to activate the barcode button(s).

Example

Raw data in hex format (MSB to LSB): 0x0000000C0000000100040101

NOTE

The ACK response is null, but a 0x00 status value is in the response packet. The

NAK response is null, but a 0x01 status value is in the response packet.

Length

(4 bytes)

Sequence

(4 bytes) Length

(2 bytes) Protocol Version

(1 byte)

Command#

(1 byte)

0x0C – 0x04 0x01 START_SCAN

BARCODE APIS

Barcode Stop Scan

14 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Barcode Stop Scan

Deactivates scanner by sending a STOP_SCAN command to the barcode reader.

The host receives an ACK/NAK response packet for this command.

Example

Raw data in hex format (MSB to LSB): 0x0000000C0000000100040102

Length

(4 bytes)

Sequence

(4 bytes) Length

(2 bytes) Protocol Version

(1 byte)

Command#

(1 byte)

0x0C – 0x04 0x01 STOP_SCAN

BARCODE APIS

Barcode Passthru

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 15

Barcode Passthru

Reserved

BARCODE APIS

Barcode Application Version

16 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Barcode Application Version

Returns a null-terminated 6-byte ASCII version ID for the barcode reader.

Example

Raw data in hex format (MSB to LSB): 0x0000000C0000000100040104

Length (4 bytes)

Sequence

(4 bytes) Length

(2 bytes) Protocol Version

(1 byte)

Command#

(1 byte)

0x0C – 0x04 0x01 GET_APP_VER

BARCODE APIS

Barcode Trigger Mode

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 17

Barcode Trigger Mode

Sets the barcode trigger mode using the 1-byte (8-bit) parameter value. The

terminal reverts to the default Level mode at every terminal power cycle and

restart.

• The EDGE parameter enables Edge Trigger mode, where the scan session

starts when the barcode button(s) is pressed and released, and stays on until

the timeout period expires or the barcode button(s) is pressed again and

released.

• The LEVEL parameter enables Level Trigger mode, where the scan session

starts when the barcode button(s) is pressed, and stays on until the button is

released. The scan session turns off automatically when the specified timeout

period is reached.

• The SOFT parameter enables Soft Trigger mode, where the host device

issues a command to start the scan session, and the barcode button(s) have

no control during the scan session.

• The PASSIVE parameter enables Passive Trigger mode that behaves the

same as Soft Trigger mode, except that a BUTTON_STATUS command is not

initiated. Button status is obtained by the host using the BUTTON_STATUS

command.

• By default, Continuous mode is enabled. If Continuous mode is disabled, a

single scan mode is enabled, where this mode scan session is turned off after

one successful barcode scan or when the timeout period expires.

Prototype

enum {

EDGE = 0, LEVEL, SOFT, PASSIVE

};

Example

Raw data in hex format (MSB to LSB): 0x0000000F000000010007010503FE01

NOTE

In Edge and Level Trigger modes, the START_SCAN command activates

barcode buttons, and the STOP_SCAN command deactivates barcode buttons.

Length

(4 bytes)

Sequence

(4 bytes) Length

(2 bytes) Protocol Version

(1 byte)

Command#

(1 byte)

0x0F – 0x07 0x01 SET_TRIG_MODE

Length

(1 byte) ID (1 byte) Value (1 byte)

0x03 PID_SET_TRIG_MODE 0x00-0x03

BARCODE APIS

Beep Immediate

18 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Beep

Immediate

Provides beep parameters for an immediate beep sequence. Specify the

parameter value in the beep format shown below. This format requires the number

of beeps (maximum of 6) followed by the values in the beep definition. Setting the

beep frequency to zero disables beeping. See Appendix A for the supported

range of beep frequencies.

Figure 3 Beep Command Packet

Example

BEEP FORMAT (BYTES)

1 SIZE OF BEEP DEFINITION

NUMBER OF

BEEP 1 ... BEEP 6

BEEPS

FREQUENCY

DURATION

PAUSE

BEEP DEFINITION (BYTES)

444

Length

(4 bytes)

Sequence

(4 bytes) Length

(2 bytes) Protocol Version

(1 byte)

Command#

(1 byte)

? – ? 0x01 BEEP_IMMEDIATE

Length

(1 byte) ID Value

(size of T_BEEP)

? PID_BEEP_IMMEDIATE Value in BEEP FORMAT

BARCODE APIS

Auto Beep Configuration

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 19

Auto Beep Configuration

Enables and disables auto beep. When enabled, the terminal beeps after a

successful scan and when an error is detected. This API also allows scan beep

and error beep parameter configuration.

This API requires up to three input parameters. The first parameter is in sequential

order and must always be beep mode. The second parameter can be either a

scan beep or an error beep, depending on how beep mode is set. The third

parameter is an error beep when beep mode is set to 3.

Valid values for beep mode are 0, 1, 2, and 3:

• 0 = auto beep disabled

• 1 = auto beep enabled; configures scan beeps only

• 2 = auto beep enabled; configures error beeps only

• 3 = auto beep enabled; configures both scan and error beeps

Only one parameter is required in the Command packet to disable or enable auto

beep. Two parameters are required to configure either scan beeps or error beeps.

Three parameters are required to configure both scan and error beeps.

Figure 4 Beep Packet Definitions

Default Values

FREQUENCY

DURATION

BEEP (BYTES)

BEEP 1

PAUSE

BEEP 2

T_BEEP_DEF (BYTES)

848

(SIZE OF BEEP)

NOTE

Default auto beep configuration settings are enforced at terminal power cycle

and restart.

Scan Beep Error Beep

Frequency 64 (2217 Hz) Frequency 58 (1568 Hz)

Duration 50 msec Duration 100 msec

Pause 50 msec Pause 75 msec

Frequency 50 (988 Hz) Frequency 50 (988 Hz)

Duration 50 msec Duration 100 msec

BARCODE APIS

Auto Beep Configuration

20 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Example

Command# (1 byte) Length (1 byte) ID (1 byte) Value (1 byte)

AUTO_BEEP_CONFIG 0x03 PID_AUTO_BEEP_MODE 0x00–0x03

Length (22 bytes) ID (1 byte) Value (20 bytes)

0x16 PID_AUTO_BEEP_SCAN Value in format T_BEEP_DEF

Length (22 bytes) ID (1 byte) Value (20 bytes)

0x16 PID_AUTO_BEEP_ERROR Value in format T_BEEP_DEF

Page is loading ...

VeriFone e315 User guide

VeriFone e315 User guide

Related papers

Other documents