BIXOLON SRP-275, SRP-F312, SRP-352plusII, SRP-350plusII, SRP-350III Reference Manual

...

Page 1

iOS SDK API Reference Guide

POS Printer

Rev. 2.00

SRP-F310 / SRP-F312 SRP-350plus / SRP-352plus SRP-350plusII / SRP-352plusII SRP-350II / SRP-350IIOBE SRP-350III / SRP-352III SRP-275 / SRP-275II

http://www.bixolon.com

Page 2

POS Printer

Rev. 2.00

- 2 -

■ Table of Contents

1. Manual Information ...................................................................................................................................... 4

1-1 Supported Platform & Development Environment ................................................................................... 4

1-2 Supported Platform & Supported Devices ............................................................................................... 4

1-3 Supported Properties List ........................................................................................................................ 4

1-4 Supported Properties List ........................................................................................................................ 5

2. Constant Definition ...................................................................................................................................... 6

2-1 Character Set ........................................................................................................................................... 6

2-2 International Character Set ...................................................................................................................... 7

2-3 Barcode/Image/Text Alignment ................................................................................................................ 7

2-4 Text Size................................................................................................................................................... 7

2-5 Text Attribute ............................................................................................................................................ 8

2-6 Bar Code Text Position ............................................................................................................................ 8

2-7 Bar Code Symbology ............................................................................................................................... 9

2-8 Image Width ............................................................................................................................................. 9

2-9 Power ..................................................................................................................................................... 10

2-10 State ..................................................................................................................................................... 10

2-11 Connection Control .............................................................................................................................. 10

2-12 Drawer kick-out connector pin .............................................................................................................. 11

2-13 Drawer open level ................................................................................................................................. 11

2-14 Model ID ................................................................................................................................................ 11

2-15 Connection Class .................................................................................................................................. 11

2-16 Result Code ......................................................................................................................................... 12

3. BXBarcode Class Reference .................................................................................................................... 14

3-1 Overview ................................................................................................................................................ 14

3-2 Properties ............................................................................................................................................... 14

3-2-1 barNumber ............................................................................................................................... 14

3-2-2 name ........................................................................................................................................ 14

3-2-3 support ..................................................................................................................................... 14

4. BXPrinter Class Reference ....................................................................................................................... 15

4-1 Overview ................................................................................................................................................ 15

4-2 Properties ............................................................................................................................................... 15

4-2-1 name ........................................................................................................................................ 15

4-2-2 address .................................................................................................................................... 15

4-2-3 port ........................................................................................................................................... 15

4-2-4 modelStr ................................................................................................................................... 16

4-2-5 versionStr ................................................................................................................................. 16

4-2-6 connectionClass ...................................................................................................................... 16

5. BXPrinterController Class Reference ...................................................................................................... 17

5-1 Overview ................................................................................................................................................ 17

5-2 Properties ............................................................................................................................................... 17

5-2-1 version ..................................................................................................................................... 17

5-2-2 delegate ................................................................................................................................... 17

5-2-3 target ........................................................................................................................................ 17

5-2-4 lookupDuration ......................................................................................................................... 18

5-2-5 lookupCount ............................................................................................................................. 18

5-2-6 alignment ................................................................................................................................. 18

5-2-7 attribute .................................................................................................................................... 18

5-2-8 textSize .................................................................................................................................... 19

5-2-9 characterSet............................................................................................................................. 19

5-2-10 internationalCharacterSet ...................................................................................................... 19

5-2-11 textEncoding .......................................................................................................................... 19

5-2-12 state ....................................................................................................................................... 20

5-2-13 power ..................................................................................................................................... 20

5-2-14 AutoConnection ..................................................................................................................... 20

5-2-15 drawerPin ............................................................................................................................... 20

5-2-16 drawerOpenLevel .................................................................................................................. 21

Page 3

POS Printer

Rev. 2.00

- 3 -

5-3 Instance Methods ................................................................................................................................... 21

5-3-1 getInstance .............................................................................................................................. 21

5-3-2 open ......................................................................................................................................... 21

5-3-3 close ......................................................................................................................................... 22

5-3-4 lookup ...................................................................................................................................... 22

5-3-5 selectTarget.............................................................................................................................. 22

5-3-6 connect .................................................................................................................................... 23

5-3-7 disconnect ................................................................................................................................ 23

5-3-8 enableLSB ............................................................................................................................... 23

5-3-9 printText ................................................................................................................................... 24

5-3-10 printBox .................................................................................................................................. 24

5-3-11 lineFeed ................................................................................................................................. 25

5-3-12 nextPrintPos .......................................................................................................................... 25

5-3-13 printBarcode .......................................................................................................................... 26

5-3-14 printBitmap ............................................................................................................................. 27

5-3-15 checkPrinter ........................................................................................................................... 27

5-3-16 msrReadReady ...................................................................................................................... 28

5-3-17 msrReadCancel ..................................................................................................................... 28

5-3-18 msrReadTrack ....................................................................................................................... 28

5-3-19 msrGetTrack .......................................................................................................................... 29

5-3-20 msrReadFullTrack .................................................................................................................. 29

5-3-21 directIO .................................................................................................................................. 30

5-3-22 icON ....................................................................................................................................... 30

5-3-23 icOFF ..................................................................................................................................... 30

5-3-24 icApdu .................................................................................................................................... 31

5-3-25 icGetStatus............................................................................................................................. 31

5-3-26 nvImageList............................................................................................................................ 32

5-3-27 downloadNVImage (Diffusion) ............................................................................................... 33

5-3-28 downloadNVImage (Normal) ................................................................................................. 34

5-3-29 printNVImage ......................................................................................................................... 34

5-3-30 removeNVImage .................................................................................................................... 35

5-3-31 removeAllNVImages .............................................................................................................. 35

5-3-32 openDrawer ........................................................................................................................... 35

5-3-33 isSupport_MSR ...................................................................................................................... 36

5-3-34 isSupport_IC .......................................................................................................................... 36

5-3-35 isSupport_Config ................................................................................................................... 36

5-3-36 isSupport_CashDrawer .......................................................................................................... 36

5-3-37 isSupport_LSB ....................................................................................................................... 37

5-3-38 getBarcodeSupportTable ....................................................................................................... 37

6. BXPrinterControllerDelegate Protocol Reference .................................................................................. 38

6-1 Overview ................................................................................................................................................ 38

6-2 Instance Methods ................................................................................................................................... 38

6-2-1 didStart ..................................................................................................................................... 38

6-2-2 didStop ..................................................................................................................................... 38

6-2-3 didFindPrinter .......................................................................................................................... 39

6-2-4 didConnect ............................................................................................................................... 39

6-2-5 didNotConnect ......................................................................................................................... 39

6-2-6 willLookupPrinters .................................................................................................................... 40

6-2-7 didLookupPrinters .................................................................................................................... 40

6-2-8 didNotLookup ........................................................................................................................... 40

6-2-9 didBeBrokenConnection .......................................................................................................... 41

6-2-10 msrArrived.............................................................................................................................. 41

6-2-11 didUpdateStatus ..................................................................................................................... 42

Page 4

POS Printer

Rev. 2.00

- 4 -

1. Manual Information

This SDK manual contains the descriptions of the Library required for the applications program development.

BIXOLON makes continuous improvements for better functions and quality of its products, and the specifications of the product and contents of the manual are subject to change without prior notice because of this reason.

1-1 Supported Platform & Development Environment

- Platform

• iOS 4.3 or higher

- Development environment

• XCode 3.2.6 or higher

1-2 Supported Platform & Supported Devices

Compatibilities of the following list of devices were verified. Besides the devices in the list, it is compatible with iPod touch second generation or later version.

• iPhone 3GS / 4G / 5G

• iPad / iPad2 / iPad mini

1-3 Supported Properties List

Method/Property

POS Printer

Version

delegate

Target

lookupDuration

lookupCount

alignment

attribute

textSize

characterSet

internationalCharacterSet

State

Power

AutoConnection

drawerPin

drawerOpenLevel

Page 5

POS Printer

Rev. 2.00

- 5 -

1-4 Supported Properties List

Method/Property

POS Printer

getInstance

open

lookup

selectTarget

connect

disconnect

enableLSB

printText

printBox

lineFeed

nextPrintPos

printBarcode

printBitmap

checkPrinter

msrReadReady

msrReadCancel

msrReadTrack

msrGetTrack

msrReadFullTrack

directIO

icON

icOFF

icApdu

icGetStatus

nvImageList

downloadNVImage (Diffusion)

downloadNVImage (Normal)

printNVImage

removeNVImage

removeAllNVImages

openDrawer

isSupport_MSR

isSupport_IC

isSupport_Config

isSupport_CashDrawer

isSupport_LSB

getBarcodeSupportTable

Page 6

POS Printer

Rev. 2.00

- 6 -

2. Constant Definition

Constants used in the provided SDK are defined in the “BXCode.h” file.

2-1 Character Set

This defines the code page and the default value is set to BXL_CS_437. Available Code Pages are as follows.

Code

Value

Description

BXL_CS_PC437

Code page PC437

BXL_CS_Katakana

Katakana

BXL_CS_PC850

Code page PC850

BXL_CS_PC860

Code page PC860

BXL_CS_PC863

Code page PC863

BXL_CS_PC865

Code page PC860

BXL_CS_WPC1252

Code page WPC1252

BXL_CS_PC866

Code page PC860

BXL_CS_PC852

Code page PC852

BXL_CS_PC858

Code page PC858

BXL_CS_PC864

Code page PC864

BXL_CS_THAI42

Code page THAI42

BXL_CS_WPC1253

Code page WPC1253

BXL_CS_WPC1254

Code page WPC1254

BXL_CS_WPC1257

Code page WPC1257

BXL_CS_FARSI

Code page FARSI

BXL_CS_WPC1251

Code page WPC1251

BXL_CS_PC737

Code page PC737

BXL_CS_PC775

Code page PC775

BXL_CS_THAI14

Code page THAI14

BXL_CS_PC862

Code page PC862

BXL_CS_PC855

Code page PC855

BXL_CS_PC857

Code page PC857

BXL_CS_PC928

Code page PC928

BXL_CS_THAI16

Code page THAI16

BXL_CS_WPC1256

Code page WPC1256

BXL_CS_USER

255

User set page

Page 7

POS Printer

Rev. 2.00

- 7 -

2-2 International Character Set

This defines the international character set and the default value is set to BXL_ICS_USA. Available International Character Sets are as follows.

Code

Value

Description

BXL_ICS_USA

U.S.A.

BXL_ICS_FRANCE

France

BXL_ICS_GERMANY

Germany

BXL_ICS_UK

U.K.

BXL_ICS_DENMARK1

Denmark I

BXL_ICS_SWEDEN

Sweden

BXL_ICS_ITALY

Italy

BXL_ICS_SPAIN

Spain

BXL_ICS_NORWAY

Norway

BXL_ICS_DENMARK2

Denmark II

2-3 Barcode/Image/Text Alignment

This defines the bar code/image/text alignment and the value is set to BXL_ALIGNMENT _LEFT.

Available settings are as follows.

Code

Value

Description

BXL_ALIGNMENT_LEFT

Left align

BXL_ALIGNMENT_CENTER

Center align

BXL_ALIGNMENT_RIGHT

Right align

2-4 Text Size

This defines the settings for the text size, and horizontal and vertical ratio can be defined simultaneously with OR operation.

Available settings are as follows.

Code

Value

Description

BXL_TS_0WIDTH

Set the ratio of horizontal width to X1

BXL_TS_1WIDTH

Set the ratio of horizontal width to X2

BXL_TS_2WIDTH

Set the ratio of horizontal width to X3

BXL_TS_3WIDTH

Set the ratio of horizontal width to X4

BXL_TS_4WIDTH

Set the ratio of horizontal width to X5

BXL_TS_5WIDTH

Set the ratio of horizontal width to X6

BXL_TS_6WIDTH

Set the ratio of horizontal width to X7

BXL_TS_7WIDTH

112

Set the ratio of horizontal width to X8

Page 8

POS Printer

Rev. 2.00

- 8 -

Code

Value

Description

BXL_TS_0HEIGHT

Set the ratio of vertical height to X1

BXL_TS_1HEIGHT

Set the ratio of vertical height to X2

BXL_TS_2HEIGHT

Set the ratio of vertical height to X3

BXL_TS_3HEIGHT

Set the ratio of vertical height to X4

BXL_TS_4HEIGHT

Set the ratio of vertical height to X5

BXL_TS_5HEIGHT

Set the ratio of vertical height to X6

BXL_TS_6HEIGHT

Set the ratio of vertical height to X7

BXL_TS_7HEIGHT

112

Set the ratio of vertical height to X8

2-5 Text Attribute

This is a text property and each property can be combined with OR operation. Available settings are as follows.

Code

Value

Description

BXL_FT_DEFAULT

Default setting NOT BOLD, FONTA, NOT UNDERLINE, NOT REVERSE

BXL_FT_FONTB

Use FONTB

BXL_FT_FONTC

Use FONTC

BXL_FT_BOLD

Use Bold font

BXL_FT_UNDERLINE

Set Underline property

BXL_FT_REVERSE

Set Reverse property

BXL_ExFT_CHINA_FONTB

2-6 Bar Code Text Position

This is for setting the position where bar code data is printed. Available settings are as follows.

Code

Value

Description

BXL_BC_TEXT_NONE

Do not print bar code data

BXL_BC_TEXT_ABOVE

Print bar code data above bar code

BXL_BC_TEXT_BELOW

Print bar code data below bar code

Page 9

POS Printer

Rev. 2.00

- 9 -

2-7 Bar Code Symbology

This defines the bar code type. Available settings are as follows.

Code

Value

Number of data

Range of data

BXL_BCS_UPCA

101

11 <= n <= 12

48 <= data <= 57

BXL_BCS_UPCE

102

11 <= n <= 12

48 <= data <= 57

BXL_BCS_EAN13

103

12 <= n <= 13

48 <= data <= 47

BXL_BCS_JAN13

104

7 <= n <= 8

48 <= data <= 57 64 <= data <= 90 data = 32,36,37,43,45,46,47

BXL_BCS_EAN8

105

7 <= n <= 8

48 <= data <= 57

BXL_BCS_JAN8

106

7 <= n <= 8

48 <= data <= 57

BXL_BCS_Code39

107

1 <= n <= 255

48 <= data <= 57 65 <= data <= 68 data = 32,36,37,43,45,46,47

BXL_BCS_ITF

108

1 <= n <= 255 (Even)

48 <= data <= 57

BXL_BCS_Codabar

109

1 <= n <= 255

48 <= data <= 57 65 <= data <= 68 data = 36,43,45,46,47,58

BXL_BCS_Code93

110

1 <= n <= 255

0 <= data <= 127

BXL_BCS_Code128

111

2 <= n <= 255

0 <= data <= 127

BXL_BCS_PDF417

200

2 <= n <= 928

0 <= data <= 255

BXL_BCS_QRCODE

202~203

2 <= n <= 928

0 <= data <= 255

BXL_BCS_DATAMATRIX

204

2 <= n <= 928

0 <= data <= 255

BXL_BCS_MAXICODE

205~6

2 <= n <= 928

0 <= data <= 255

2-8 Image Width

Set the width of image and valid range is 0~ max width. Image is resized for the conditions according to the given conditions when the following values are set.

Available settings are as follows.

Code

Value

Description

BXL_WIDTH_FULL

-1

Value is set to max width and the image is resized to the full paper size

BXL_WIDTH_NONE

-2

Image is not resized

Page 10

POS Printer

Rev. 2.00

- 10 -

2-9 Power

This indicates the remaining battery capacity of the printer. It is read only and a change of battery status is automatically shown.

Support Device : Only Mobile printer, POS Printer is not support. The remaining battery capacity status values are as follows.

Code

Value

Description

BXL_PWR_HIGH

Remaining battery capacity is 95%

BXL_PWR_MIDDLE

Remaining battery capacity is 85%

BXL_PWR_LOW

Remaining battery capacity is 50%

BXL_PWR_SMALL

Remaining battery capacity is 25%

BXL_PWR_NOT

Remaining battery capacity is less than 25%

2-10 State

This indicates the status of the printer. It is read only and the status of the printer is automatically shown when printer status is checked by calling the CheckPrinter function. Status values can be combined and each setting can be checked through bit operation.

Printer status settings are as follows.

Code

Value

Description

BXL_STS_NORMAL

Normal

BXL_STS_PAPEREMPTY

No paper

BXL_STS_CONVEROPEN

Printer cover open

BXL_STS_POWEROVER

Not enough remaining battery of printer

BXL_STS_MSR_READY

No printing MSR read only mode

BXL_STS_PRINTING

Printer is printing or receiving data

BXL_STS_ERROR

Error in communication with printer

BXL_STS_NOT_OPEN

Open method of BXPrinterControl was not called

BXL_STS_ERROR_OCCUR

128

Printer internal error

BXL_STS_NOT_CONNECTED

-1

Currently printer is not connected

2-11 Connection Control

This defines the type of printer connection. Available settings are as follows.

Code

Value

Description

BXL_CONNECTIONMODE_AUTO

Automatic connect mode

BXL_CONNECTIONMODE_NOAUTO

100

Not automatic connect mode

Page 11

POS Printer

Rev. 2.00

- 11 -

2-12 Drawer kick-out connector pin

This defines the number of drawer kick-out connector pin. Available settings are as follows.

Code

Value

Description

BXL_CASHDRAWER_PIN_2

Drawer kick-out connector pin 2

BXL_CASHDRAWER_PIN_5

Drawer kick-out connector pin 5

2-13 Drawer open level

This defines the type of cash drawer Available settings are as follows.

Code

Value

Description

BXL_CASHDRAWER_OPENLEVEL_LOW

If Cash drawer is open, Drawer kick-out connector pin 3 is LOW

BXL_CASHDRAWER_OPENLEVEL_HIGH

If Cash drawer is open, Drawer kick-out connector pin 3 is HIGH

2-14 Model ID

This defines the type of printer. Available settings are as follows.

Code

Value

Description

BXL_MODEL_ID_SPPR200II

0x12000002

SPP-R200II

BXL_MODEL_ID_SRPR300

0x13000000

SPP-R300

BXL_MODEL_ID_SPPR400

0x14000000

SPP-R400

BXL_MODEL_ID_SRP350II

0x23500002

SRP-350II

BXL_MODEL_ID_SRP350plus

0x23507000

SRP-350plus

BXL_MODEL_ID_SRP352plus

0x23527000

SRP-352plus

BXL_MODEL_ID_SRP350plusII

0x23507002

SRP-350plusII

BXL_MODEL_ID_SRP352plusII

0x23527002

SRP-352plusII

BXL_MODEL_ID_SRP350III

0x23500003

SRP-350III

BXL_MODEL_ID_SRP352III

0x23520003

SRP-352III

BXL_MODEL_ID_SRP275

0x32750000

SRP-275, SRP-275II

BXL_MODEL_ID_SRPF310

0x93100000

SRP-F310

BXL_MODEL_ID_SRPF312

0x93120000

SRP-F312

2-15 Connection Class

When the method named 'didFindPrinter' is called, This value is updated to connectionClass in BXPrinter class

Refer to 6-2-3 didFindPrinter

Code

Value

Description

BXL_CONNECTIONCLASS_WIFI

0x0000

WIFI Connection

BXL_CONNECTIONCLASS_ETHERNET

0x0001

Ethernet Connection

Page 12

POS Printer

Rev. 2.00

- 12 -

2-16 Result Code

Code DEFINE

Value

Description

BXL_SUCCESS

Success

BXL_NOT_CONNECTED

-1

Printer is not connected

BXL_NOT_OPENED

101

SDK is not open

BXL_STATUS_ERROR

103

Error in status check

BXL_CONNECT_ERROR

105

Connection failure

BXL_NOT_SUPPORT

107

Not supported

BXL_BAD_ARGUMENT

108

Wrong function arguments

BXL_BUFFER_ERROR

109

Error in MSR buffer

BXL_NOT_CONNECTED

110

Printer is not connected

BXL_RGBA_ERROR

111

Error while converting image file to RGBA data

BXL_MEMORY_ERROR

112

Memory allocation failure

BXL_TOO_LARGE_IMAGE

113

Size of image file is too big while downloading image to NV area

BXL_NOT_SUPPORT_DEVICE

114

The printer device does not support

BXL_READ_ERROR

301

Failure in data reception

BXL_WRITE_ERROR

300

Failure in data transmission

BXL_BITMAPLOAD_ERROR

400

Fail to read image file

BXL_BC_DATA_ERROR

500

Error in bar code data

BXL_BC_NOT_SUPPORT

501

Unsupported bar code type

BXLMSR_NOTREADY

602

Not MSR READY state

BXLMSR_FAILEDMODE

601

Not automatic read mode

BXLMSR_DATAEMPTY

603

No data read from MSR

1001H

Unknown command

1002H

Command cannot be executed

1003H

Incorrect number of arguments

1004H

First byte of unknown command of invalid command

1005H

Response time out

1010H

Response error due to card reset, or first byte of response is not valid

1012H

Message limit is exceeded. Maximum is 254 bytes, and card data is 248 bytes

1013H

Error in reading bytes from asynchronous routine

1015H

Card mode is terminated Card mode command needs to be transmitted

101BH

Transmission of command with incorrect arguments

101DH

Incorrect TCK check byte

10A0H

Error in card reset response (unknown protocol or TA1 byte recognition error), unsupported card, no card response value for card reset

10A1H

Card protocol error (T=0/T=1)

10A2H

Time out due to no card response

10A3H

Parity error

10A4H

Card has aborted chaining (T=1)

10A5H

Reader has aborted chaining (T=2)

Page 13

POS Printer

Rev. 2.00

- 13 -

Code DEFINE

Value

Description

10A6H

Successful execution of IC module and RESYNCH

10A7H

PPS error

10A8H

IC module has already been set to IC CARD mode

10B0H

PC link command is not supported

10E4H

The card has just sent an invalid “Procedure

byte”

10E5H

The card has interrupted an exchange

10E7H

Card returns an error

10F7H

Card is removed while executing a command

10F8H

Card is not useable because it is electrically damaged

10FBH

Card recognition failure or car entry failure

Page 14

POS Printer

Rev. 2.00

- 14 -

3. BXBarcode Class Reference

Inherits from

NSObject

Confirms to

Framework

BXPrinter.a

[Availability]

iOS 4.3 and later

Declared

BXBarcodeInfo.h

3-1 Overview

BXBarcode class is an object that contains information about which barcode types are supported for each printer to control.

3-2 Properties

3-2-1 barNumber

Barcode Define Number @property int barNumber

[Discussion]

Printer name is saved automatically by collecting information from the connected printer.

[Availability]

SDK 3.0.3 and later

3-2-2 name

Barcode Name @property(readwrite) NSString * address

[Discussion]

Printer name is saved automatically by collecting information from the connected printer.

[Availability]

SDK 3.0.3 and later

3-2-3 support

The availability of the barcode. @property BOOL support

[Discussion]

Printer name is saved automatically by collecting information from the connected printer.

[Availability]

SDK 3.0.3 and later

Page 15

POS Printer

Rev. 2.00

- 15 -

4. BXPrinter Class Reference

Inherits from

NSObject

Confirms to

Framework

BXPrinter.a

[Availability]

iOS 4.3 and later

Declared

BXPrinterObject.h

4-1 Overview

BXPrinter Class contains the information of control target printer (name / network address / port).

4-2 Properties

4-2-1 name

Printer name @property(readonly) NSString * name

[Discussion]

Printer name is saved automatically by collecting information from the connected printer.

[Availability]

SDK 0.6.0 and later

4-2-2 address

Network address of printer @property(readwrite) NSString * address

[Discussion]

Network address of the printer should be assigned first before connection.

[Availability]

SDK 0.6.0 and later

4-2-3 port

Network port of printer @property(readwrite) unsigned short port

[Discussion]

Network port of the printer should be assigned first before connection.

[Availability]

SDK 0.6.0 and later

Page 16

POS Printer

Rev. 2.00

- 16 -

4-2-4 modelStr

Model name of printer Name is provided by the firmware, and it is _SRP-350II in case of SRP-350II printer. @property(readwrite) NSString * modelStr

[Discussion]

This value is updated by the checkPrinter method of BXPrinterController.

[Availability]

SDK 0.8.0 and later

4-2-5 versionStr

Firmware version of printer Version name is provided by firmware, and it is in the form of _V01.00 STOB 040711. @property(readwrite) NSString * versionStr

[Discussion]

This value is updated by the checkPrinter method of BXPrinterController.

[Availability]

SDK 0.8.0 and later

4-2-6 connectionClass

Printer interface type. This value represents the way that the printer is connected.

Refer 2-15 Connection Class. @property(readwrite) unsigned short * connectionClass

[Availability]

SDK 3.0.3 and later

Page 17

POS Printer

Rev. 2.00

- 17 -

5. BXPrinterController Class Reference

Inherits from

NSObject

Confirms to

Framework

BXPrinter.a

[Availability]

iOS 4.3 and later

Declared

BXPrinter.h

5-1 Overview

BXPrinterController Class is the main object for printer control.

5-2 Properties

5-2-1 version

SDK version @property(readonly) NSString * version

[Discussion]

It is a string in the form of “1.0.0” and it is read only.

[Availability]

SDK 0.6.0 and later

5-2-2 delegate

Assign the object to apply BXPrinterControlDelegate method @property(readwrite) id<BXPrinterControlDelegate> delegate

[Availability]

SDK 0.6.0 and later

5-2-3 target

Control target printer object @property(readwrite) BXPrinter * target

[Discussion]

It is a control target printer object and should be assigned before starting printer control.

[Availability]

SDK 0.6.0 and later

Page 18

POS Printer

Rev. 2.00

- 18 -

5-2-4 lookupDuration

Printer lookup time (unit: second) @property(readwrite) CGFloat lookupDuration

[Discussion]

It could be a fractional number such as 0.5.

[Availability]

SDK 0.6.0 and later

5-2-5 lookupCount

Number of repeat on signal transmission for printer search @property(readwrite) unsigned lookupCount

[Discussion]

Default value is set to 1. When it is set to a number bigger than 1, the printer search signal transmission is repeated by this number at intervals of 0.2 seconds.

[Availability]

SDK 0.6.0 and later

5-2-6 alignment

Horizontal alignment setting @property(readwrite) int alignment

[Discussion]

Default value is set to left alignment, and this setting affects all output printing including text and bar code.

[Availability]

SDK 0.8.0 and later

5-2-7 attribute

Text printing property @property(readwrite) int attribute

[Discussion]

Refer to 2-5 Text Attribute

[Availability]

SDK 0.8.0 and later

Page 19

POS Printer

Rev. 2.00

- 19 -

5-2-8 textSize

Size of the printed text @property(readwrite) int textSize

[Discussion]

Refer to 2-4 Text Size

[Availability]

SDK 0.6.0 and later

5-2-9 characterSet

Defines the code page of printer @property(readwrite) CGFloat lookupDuration

[Discussion]

Refer to 2-1 Character Set Default value is set to BXL_CS_437.

[Availability]

SDK 0.6.0 and later

5-2-10 internationalCharacterSet

@property(readwrite) char internationalCharacterSet

[Discussion]

Refer to 2-2 International Character Set. Default value is set to BXL_CS_437.

[Availability]

SDK 0.6.0 and later

5-2-11 textEncoding

Type of the text Encoding. @property(readwrite) long textEncoding

[Discussion]

Refer to NSStringEncoding in NSString.h

[Availability]

SDK 3.0.2 and later

Page 20

POS Printer

Rev. 2.00

- 20 -

5-2-12 state

Printer state code This value is updated when checkPrinter method of BXPrinterController is called.

@property(readonly) long state

[Discussion]

Refer to 2-10 State

[Availability]

SDK 0.6.0 and later

5-2-13 power

@property(readonly) long state

[Discussion]

Refer to 2-9 Power

[Availability]

SDK 0.6.0 and later

5-2-14 AutoConnection

@property(assign) int AutoConnection

[Discussion]

Refer to 2-11 Connection Control

[Availability]

SDK 2.0.2 and later <Note>

※ Printer connection is controlled automatically without using connect/disconnect

function in the automatic connection mode.

※ Consecutive use of printText function may slow down the printing speed because

most functions have a connect/disconnect job at the beginning and end of it. Use the manual connection mode to address this issue.

5-2-15 drawerPin

@property(assign) int drawerPin

[Discussion]

Refer to 2-12 Drawer kick-out connector pin.

[Availability]

SDK 3.0.1 and later

Page 21

POS Printer

Rev. 2.00

- 21 -

5-2-16 drawerOpenLevel

@property(assign) int drawerOpenLevel

[Discussion]

Refer to 2-13 Drawer open level

[Availability]

SDK 3.0.1 and later

5-3 Instance Methods

5-3-1 getInstance

Method to obtain the BXPrinterController class instance

[Function prototype]

- (BXPrinterController)getInstance [Return Value]

BXPrinterController class is created and returned automatically when this method is called first time, and the existing BXPrinterController class is returned from the next time.

[Discussion]

Since BXPrinterController class uses only one instance in one process, user should obtain and use it using this method instead of creating it.

[Availability]

SDK 0.8.0 and later

5-3-2 open

Initialization task for using BXPrinterController class (memory allocation and background thread operation)

[Function prototype]

- (void)open [Discussion]

- It should be called before calling main delegate of applications like

(void)applicationDidBecomeActive:(UIApplication *) application.

[Availability]

SDK 0.6.0 and later

Page 22

POS Printer

Rev. 2.00

- 22 -

5-3-3 close

Resources are de-allocated for stopping or terminating the use of BXPrinterController class.

[Discussion]

- It should be called before calling main delegate of applications like (void)applicationWillResignActive:(UIApplication *) application. When close method is not called and applications using BXPrinterController are running in the background, simultaneous use of BXPrinterController by other applications could be restricted.

[Availability]

SDK 0.6.0 and later

5-3-4 lookup

Printers in the same WiFi network where iPhone is connected are searched.

[Function prototype]

- (void)lookup [Discussion]

Stat/End of search and searched printers can be obtained through BXPrinter ControlDelegate. Each iPhone has two network adaptors including 3G and WiFi networks, and the lookup method searches WiFi only. No operation takes place when there is no connected WiFi.

[Availability]

SDK 0.6.0 and later

5-3-5 selectTarget

Initialization task for object of specified target.

[Function prototype]

- (long)selectTarget

- (long)selectTarget : (int) modelID

[Parameters]

modelID

- Select to type of printer.

- If you were not input, This is allocated automatically. Refer to 2-14 Model ID.

[Return Value]

Refer to 2-16 Result Code

[Discussion]

Target of BXPrininterController property should be set in advance.

[Availability]

SDK 2.0.2 and later

Page 23

POS Printer

Rev. 2.00

- 23 -

5-3-6 connect

Connect to target printer.

[Function prototype]

- (BOOL)connect

[Discussion]

This method not works when AutoConnection is setting in BXL_CONNECTIONMODE_AUTO(default, == 0)

Target of BXPrininterController property should be set in advance.

[Availability]

SDK 2.0.2 and later

5-3-7 disconnect

Disconnect to connected printer.

[Function prototype]

- (void)disconnect

[Discussion]

This method not works when AutoConnection is setting in BXL_CONNECTIONMODE_AUTO(default, == 0).

[Availability]

SDK 2.0.2 and later

5-3-8 enableLSB

Enable to Last status back.

[Function prototype]

- (long)enableLSB:(BOOL)bEnable

[Parameters]

bEnable

LSB Enable. FALSE : LSB Disable TRUE : LSB Enable

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 3.0.0 and later

Page 24

POS Printer

Rev. 2.00

- 24 -

5-3-9 printText

Print text. No operation takes place when there is no connected printer.

[Function prototype]

- (long)printText:(NSString *)string [Parameters]

string

Unicode data with null terminator. Print target text string

[Return Value]

Refer to 2-16 Result Code

[Discussion]

Tex alignment property should be set in advance.

[Availability]

SDK 0.6.0 and later

5-3-10 printBox

Print box shape text. No action takes place if no printer is connected.

[Function prototype]

(long)printText:(int)width height: (int)height;

[Parameters]

int

Specify the width of the box. 1 == width equivalent to that of one character

int

Specify the length of the box. 1 == length equivalent to that of one character

[Return Value]

Refer to 2-16 Result Code

[Discussion]

Alignment and properties of the text should be defined in advance.

[Availability]

SDK 3.0.3 and later

Page 25

POS Printer

Rev. 2.00

- 25 -

5-3-11 lineFeed

Perform line feed

[Function prototype]

- (void)linefeed:(int)lines [Parameters]

lines

Number of lines to advance

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

5-3-12 nextPrintPos

Feed the paper to the beginning of the next label paper.

[Function prototype]

- (long)nextPrintPos [Return Value]

Refer to 2-16 Result Code

[Discussion]

This method works only when in label mode.

[Availability]

SDK 0.6.0 and later

Page 26

POS Printer

Rev. 2.00

- 26 -

5-3-13 printBarcode

Print one-dimensional and two-dimensional bar code.

[Function prototype]

- (long)printBarcode:(char *)data

symbology:(long)symbology width:(long)width height:(long)height alignment:(long)alignment textPosition:(long)textPosition

[Parameters]

data

ANSI code data with null terminator. Transfer bar code data to print

symbology

Define bar code type.

height

Height of bar code, unit is number of dot, range is 1~255

This setting does not affect 2-dimensional bar code.

width

Width of barcode, valid range is 2~7 Barcode printing may not work properly if the width of barcode print exceeds the

printer paper width.

This setting does not affect 2-dimensional bar code.

alignment

Barcode alignment setting Refer to 2-3 Barcode/Text Alignment

textPosition

Barcode text position setting Refer to 2-6 Barcode Text Position

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

Page 27

POS Printer

Rev. 2.00

- 27 -

5-3-14 printBitmap

Print image file

[Function prototype]

- (long)printBitmap:(NSString *)path

width:(long)width

alignment:(long)alignment level:(long)level

[Parameters]

path

Path of image file

width

Width of image file to convert, valid setting range is 0 ~ max width Image is resized with the given condition when the value is less than 0 Refer to 2-8 Image Width

alignment

Image alignment setting Refer to 2-3 Image Alignment

level

Color level and diffusion processing option of image

Value

Description

0 ~ 100

Color level value

If fourth digit is 1

Enable diffusion processing

If fifth digit is 1

Image print using ESC * command

<Note> What is Error Diffusion? It is a method to present the color image or black and white image with less number of bits/pixel, which may produce few visible patterns such as a snake-like pattern for a certain type of image but in general the capability of sharp representation is excellent. Disadvantage is long processing type and this is because errors are measured and amount of computing required for distribution the errors to neighbor pixels.

It is recommended to use the diffusion algorithm with this SDK.

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

5-3-15 checkPrinter

Check the printer states and update the printer state property

[Function prototype]

- (long)checkPrinter [Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

Page 28

POS Printer

Rev. 2.00

- 28 -

5-3-16 msrReadReady

Switch the printer to MSR Ready state. Printing is not allowed in Ready state. Support Device : Only Mobile printer, POS Printer is not support.

[Function prototype]

- (long)msrReadReady [Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

5-3-17 msrReadCancel

Release the MSR Ready state of printer Support Device : Only Mobile printer, POS Printer is not support.

[Function prototype]

- (long)msrReadCancel

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

5-3-18 msrReadTrack

Read MSR data. It is MSR read mode. If BXLMSR_DATAEMPTY is returned, card is not read in MSR. Scan the card with MSR again or use the msrReadCancel method to cancel the read mode. Support Device : Only Mobile printer, POS Printer is not support.

[Function prototype]

- (long)msrReadTrack:(NSData **)data1 data2:(NSData **)data2 data3:(NSData **)data3

[Parameters]

data1

Read MSR Data Track 1 and save it.

data2

Read MSR Data Track 2 and save it.

data3

Read MSR Data Track 3 and save it.

[Return Value]

Refer to 2-16 Result Code

[Discussion]

All of data1, data2, data3 carry unallocated NSData *data, and NSData object is allocated inside the method. The allocated data1, data2, data3 are auto release ones and users do not have to release them explicitly.

Page 29

POS Printer

Rev. 2.00

- 29 -

[Availability]

SDK 0.6.0 and later

5-3-19 msrGetTrack

[Function prototype]

- (long)msrGetTrack:(int)track

response:(NSData **)response

[Parameters]

track

MSR Data Track number 1 ~ 3

response

MSR Data Track value

[Return Value]

Refer to 2-16 Result Code

[Discussion]

Response carries unallocated NSData *data, and NSData object is allocated inside the method. The response is auto release one and users do not have to release it explicitly.

[Availability]

SDK 0.9.0 and later

5-3-20 msrReadFullTrack

Read entire MSR data. It is MSR read mode. If BXLMSR_DATAEMPTY is returned, card is not read in MSR. Scan the card with MSR again or use the msrReadCancel method to cancel the read mode. Support Device : Only Mobile printer, POS Printer is not support.

[Function prototype]

- (long)msrReadFullTrack:(NSData **)response

[Parameters]

response

MSR Data Track value

[Return Value]

Refer to 2-16 Result Code

[Discussion]

Response carries unallocated NSData *data, and NSData object is allocated inside the method. The response is auto release one and users do not have to release it explicitly.

[Availability]

SDK 0.9.0 and later

Page 30

POS Printer

Rev. 2.00

- 30 -

5-3-21 directIO

Send or read user defined data.

[Function prototype]

- (long)directIO:(NSData *)request

response:(NSData **)response

[Parameters]

request

Data to be sent to printer, ANSI CODE data

response

response sent from printer is returned

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

5-3-22 icON

Apply power to smart card reader of printer Support Device : Only Mobile printer, POS Printer is not support.

[Function prototype]

- (long)icON:(NSData **)response

[Parameters]

response

ATR (Answer to Reset) value is returned.

[Return Value]

Refer to 2-16 Result Code

[Discussion]

Response is saved as auto release type inside the method, and users do not have to release it explicitly.

[Availability]

SDK 0.6.0 and later

5-3-23 icOFF

Turn off the power of the smart card reader of printer Support Device : Only Mobile printer, POS Printer is not support.

[Function prototype]

- (long)icOFF

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

Page 31

POS Printer

Rev. 2.00

- 31 -

5-3-24 icApdu

Send APDU command and get response. It works only when the power is applied to the printer smart card. Support Device : Only Mobile printer, POS Printer is not support.

[Function prototype]

- (long)icApdu:(NSData **)request

response:(NSData **)response

[Parameters]

request APDU command data to send to printer, ANSI CODE data response

APDU response sent from printer is returned

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

5-3-25 icGetStatus

Read the status of card inserted into the smart card reader of printer Support Device : Only Mobile printer, POS Printer is not support.

[Function prototype]

- (long)icGetStatus:(NSData **)response

[Parameters]

response Card status value is returned

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 0.6.0 and later

Page 32

POS Printer

Rev. 2.00

- 32 -

5-3-26 nvImageList

Read the list of image addresses saved in NV area.

[Function prototype]

- (long)nvImageList:(NSArray **)images

[Parameters]

images

Address list is provided. Each address is saved in the form of NSNumber *. The images are provided in the form of autorelease, and developers do not have to release it explicitly.

[Return Value]

Refer to 2-16 Result Code

[Discussion]

<Example > NSArray *images;

[[BXPrinterController getInstance()] nvImageList:&images]; for( NSNumber *n in images) { NSLog(@”%d”, [NSNumber intValue]); }

[Availability]

SDK 1.0.0 and later

Page 33

POS Printer

Rev. 2.00

- 33 -

5-3-27 downloadNVImage (Diffusion)

Download the image data corresponding to the address saved in the NV area.

[Function prototype]

- (long)downloadNVImage:(int)address

withImage:(UIImage *)image width:(long)width level:(long)level

[Parameters]

address

Image address in the range of 0 ~ 99. If there is an image saved for the

corresponding address, the existing image is replaced by the new image.

images

Download target image object

width

Width of the image to print

When the setting is BXL_WIDTH_FULL, the image is printed with the

maximum width that can be printed by the printer.

Image is enlarged when the width of the image is smaller than the setting, and reduced when it is bigger than the setting.

level

Color level and diffusion processing option of image

Value

Description

0 ~ 100

Color level value

If fourth digit is 1

Enable diffusion processing

If fifth digit is 1

Image print using ESC * command

It is recommended to use the diffusion algorithm with this SDK.

[Return Value]

Refer to 2-16 Result Code

[Discussion]

When the width of the image is wider than the width of printer, the image is resized automatically.

[Availability]

SDK 1.0.0 and later

Page 34

POS Printer

Rev. 2.00

- 34 -

5-3-28 downloadNVImage (Normal)

Download the image data to the designated address in NV area.

[Function prototype]

- (long)downloadNVImage:(int)address

withImage:(UIImage *)image

[Parameters]

address

Image address in the range of 0 ~ 99. If there is an image saved for the

corresponding address, the existing image is replaced by a new image.

images

Download target image object

[Return Value]

Refer to 2-16 Result Code

[Discussion]

When the width of the image is wider than the width of printer, the image is resized automatically. The width value is set to BXL_WIDTH_FULL and the image data processed with 1050 of level, 50% of brightness and error diffusion algorithm enable settings is downloaded.

[Availability]

SDK 1.0.0 and later

5-3-29 printNVImage

Print the image data to the designated address in NV area다.

[Function prototype]

- (long)printNVImage:(int)address

[Parameters]

address

Image address in the range of 0 ~ 9

[Return Value]

Refer to 2-16 Result Code

[Discussion]

Image is not printed if image does not exist in the corresponding address.

[Availability]

SDK 1.0.0 and later

Page 35

POS Printer

Rev. 2.00

- 35 -

5-3-30 removeNVImage

Delete image data from the designated address in NV area.

[Function prototype]

- (long)removeNVImage:(int)address

[Parameters]

address

Image address in the range of 0 ~ 99

[Return Value]

Refer to 2-16 Result Code

[Discussion]

No action takes place if image does not exist in the corresponding address

[Availability]

SDK 1.0.0 and later

5-3-31 removeAllNVImages

Delete all image data from the designated address in NV area.

[Function prototype]

- (long)removeAllNVImages

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 1.0.0 and later

5-3-32 openDrawer

Open to the Cash Drawer.

[Function prototype]

- (long)openDrawer

[Return Value]

Refer to 2-16 Result Code

[Availability]

SDK 3.0.0 and later

Page 36

POS Printer

Rev. 2.00

- 36 -

5-3-33 isSupport_MSR

Check whether a specific feature of the MSR is supported.

[Function prototype]

- (BOOL)isSupport_MSR

[Return Value]

If the feature of the MSR is supported, return TRUE.

[Availability]

SDK 3.0.0 and later

5-3-34 isSupport_IC

Check whether a specific feature of the IC is supported.

[Function prototype]

- (BOOL)isSupport_IC

[Return Value]

If the feature of the IC is supported, return TRUE.

[Availability]

SDK 3.0.0 and later

5-3-35 isSupport_Config

Check whether a specific feature of the Config is supported.

[Function prototype]

- (BOOL)isSupport_Config

[Return Value]

If the feature of the config is supported, return TRUE.

[Availability]

SDK 3.0.0 and later

5-3-36 isSupport_CashDrawer

Check whether a specific feature of the CashDrawer is supported.

[Function prototype]

- (BOOL)isSupport_CashDrawer

[Return Value]

If the feature of the CashDrawer is supported, return TRUE.

[Availability]

SDK 3.0.0 and later

Page 37

POS Printer

Rev. 2.00

- 37 -

5-3-37 isSupport_LSB

Check whether a specific feature of the LSB is supported.

[Function prototype]

- (BOOL)isSupport_MSR

[Return Value]

If the feature of the LSB is supported, return TRUE.

[Availability]

SDK 3.0.0 and later

5-3-38 getBarcodeSupportTable

Check that the barcode print function is supported.

[Function prototype]

- (NSMutableArray*)getBarcodeSupportTable

[Return Value]

NSMutableArray that contains BXBarcode is returned.

[Availability]

SDK 3.0.3 and later

Page 38

POS Printer

Rev. 2.00

- 38 -

6. BXPrinterControllerDelegate Protocol Reference

Inherits from

NSObject

Confirms to

Framework

BXPrinter.a

[Availability]

iOS 4.3 and later

Declared

BXPrinteControlDelegater.h

6-1 Overview

This receives events occurring in the BXPrinterController class.

6-2 Instance Methods

6-2-1 didStart

It is called when class starts to be used using open method of BXPrinterController. It is called after printer connection is completed.

[Function prototype]

- (void) didStart

[Parameters]

controller

BXPrinterController object that generates events

[Discussion]

It can be used to indicate the beginning of the use of printer class to users.

[Availability]

SDK 0.6.0 and later

6-2-2 didStop

It is called when class use is stopped using open method of BXPrinterController.

[Function prototype]

- (void) didStop

[Parameters]

controller

BXPrinterController object that generates events

[Discussion]

It can be used to indicate the termination of the use of printer class.

[Availability]

SDK 0.6.0 and later

Page 39

POS Printer

Rev. 2.00

- 39 -

6-2-3 didFindPrinter

This method is called for each individual printer when a printer is discovered from the same network.

[Function prototype]

- (void)didFindPrinter:(BXPrinterController *)controller

printer:(BXPrinter *)printer

[Parameters]

controller

BXPrinterController object that generates events

printer

Information of discovered printer

[Discussion]

If same printer responds multiple time during the printer lookup process, this method is called only once the first time.

[Availability]

SDK 0.6.0 and late

6-2-4 didConnect

This method is called when connection to printer finished.

[Function prototype]

- (void)didConnect:(BXPrinterController *)controller [Discussion]

If you need to have more information about target printers, please refer to target properties in BXLPrinterController.

[Availability]

SDK 2.0.2 and later

6-2-5 didNotConnect

This method is called when connection to printer cannot be made.

[Function prototype]

- (void)didNotConnect:(BXPrinterController *)controller

withError:(NSError *)error

[Parameters]

controller

BXPrinterController object that generates events

error

Information of cause of failure

[Discussion]

This can be used when there is error during printer connection stage.

[Availability]

SDK 0.6.0 and later

Page 40

POS Printer

Rev. 2.00

- 40 -

6-2-6 willLookupPrinters

This method is called before starting printer search.

[Function prototype]

- (void)willLookupPrinters:(BXPrinterController *)controller

[Parameters]

controller

BXPrinterController object that generates events

[Discussion]

This can be used to indicate the start of printer search.

[Availability]

SDK 0.6.0 and later

6-2-7 didLookupPrinters

This method is called when printer search is completed.

[Function prototype]

- (void)didLookupPrinters:(BXPrinterController *)controller

[Parameters]

controller

BXPrinterController object that generates events

[Discussion]

It can be used to indicate the search status to users.

[Availability]

SDK 0.6.0 and later

6-2-8 didNotLookup

This method is called when printer search cannot be performed.

[Function prototype]

- (void)didNotLookup:(BXPrinterController *)controller

withError:(NSError *)error

[Parameters]

controller

BXPrinterController object that generates events

error

Information of cause of failure

[Discussion]

Lookup fails when printer is connected to WiFi.

[Availability]

SDK 0.6.0 and later

Page 41

POS Printer

Rev. 2.00

- 41 -

6-2-9 didBeBrokenConnection

This method is called when the connection to printer is broken.

[Function prototype]

- (void)didBeBrokenConnection:(BXPrinterController *)controller

withError:(NSError *)error

[Parameters]

controller

BXPrinterController object that generates events

error

Information of cause of failure

[Discussion]

This is not called when user breaks the connection by calling the close method of BXPrinterController explicitly. This method is called only when the connection is interrupted by external problem other than user intervention. Refer to the target property of BXPrinterController for the information of target printer.

[Availability]

SDK 0.6.0 and later

6-2-10 msrArrived

This method is called when MSR data arrives correctly in MSR Read mode.

[Function prototype]

- (void)msrArrived:(BXPrinterController *)controller

track:(NSNumber *)track

[Parameters]

controller

BXPrinterController object that generates events

track

Track number 1 ~ 3 for MSR data

[Discussion]

After this method is called, the MSR data of the corresponding track can be obtained through the getTrack: method of BXPrinterController.

[Availability]

SDK 0.6.0 and later

Page 42

POS Printer

Rev. 2.00

- 42 -

6-2-11 didUpdateStatus

This method is called when printer status variable has changed.

[Function prototype]

- (void)didUpdateStatus:(BXPrinterController *)controller

Status(NSNumber*) status

[Parameters]

controller

BXPrinterController object that generates events

status

printer status.

[Availability]

SDK 3.0.0 and later