BRPtouchPrinter

BRPtouchPrinter class provides APIs to print data or get information from the printer.

Instance Methods

initWithPrinterIPAddress:IPAddress:

Initialize the object with the printer name. Then you need to set CONNECTION_TYPE and the identifier based on the connection type. Usually, using initWithPrinterName:interface: is recommended.

Declaration

- (id)initWithPrinterIPAddress:(NSString *)IPAddress;

initWithPrinterName:strPrinterName:

Initialize the object with the printer name and an identifier based on the connection type. Then you need to set CONNECTION_TYPE. Usually, using initWithPrinterName:interface: is recommended.

Info

For the TD-23XX series, strPrinterName must include the resolution, such as "TD-2320D_203", "TD-2350DFSA_300", etc. If the resolution is unknown, use setPrinterNameFromStatus.

Declaration

- (id)initWithPrinterName:(NSString*)strPrinterName;

initWithPrinterName:interface:

Initialize the object with the printer name (e.g. @"QL-1110NWB") and CONNECTION_TYPE. After that, you need to set the identifier based on the connection type.

• setIPAddress:
• setupForBluetoothDeviceWithSerialNumber:
• setBLEAdvertiseLocalName:

Info

For the TD-23XX series, strPrinterName must include the resolution, such as "TD-2320D_203", "TD-2350DFSA_300", etc. If the resolution is unknown, use setPrinterNameFromStatus.

Declaration

- (id)initWithPrinterName:(NSString *)strPrinterName interface:(CONNECTION_TYPE)type;

printerName

A getter of the printer name set when initialized.

Declaration

- (NSString *)printerName;

setPrinterName:strPrinterName

A setter of the printer name set when initialized. The printer name must follow the format like @"QL-1110NWB".

Info

For the TD-23XX series, strPrinterName must include the resolution, such as "TD-2320D_203", "TD-2350DFSA_300", etc. If the resolution is unknown, use setPrinterNameFromStatus.

Declaration

- (BOOL)setPrinterName:(NSString*)strPrinterName;

setPrintInfo:

Set BRPtouchPrintInfo object to configure print settings.

Declaration

- (void)setPrintInfo:(BRPtouchPrintInfo *)printInfo;

Parameters

Parameter	Description
printInfo	The print setting information.

setCustomPaperFile:

Set the custom paper information from the file. This is required for RJ/TD series printer. Also refer to the guide for those series.

Declaration

- (BOOL)setCustomPaperFile:(NSString *)strFilePath;

Parameters

Parameter	Description
strFilePath	The absolute file path of the custom paper file.

Return Value

YES if the file exists, otherwise NO.

setCustomPaperInfoCommand:

Set BRCustomPaperInfoCommand object to configure custom paper information parameters. This is required for RJ/TD series printer. Also refer to the guide for those series.

Declaration

- (NSArray *)setCustomPaperInfoCommand:(BRCustomPaperInfoCommand *)customPaperInfoCommand;

Parameters

Parameter	Description
customPaperInfoCommand	The custom paper information parameters

Return Value Array of NSDictionary, which contains two elements.

Key	Value
@"errorParameter"	ErrorParameterName
@"errorDetail"	ErrorParameterDetail

If NSArray* is empty, it's no error .

getSupportPaperArray

Get label/paper information of your printer.

Declaration

- (NSArray *)getSupportPaperArray;

Return Value NSArray<BRPtouchLabelParam *>*

getCurrentLabelParam

Get label/paper information of connected your printer.

Declaration

- (BRPtouchLabelParam *)getCurrentLabelParam;

Return Value BRPtouchLabelParam

getLabelInfoStatus

Get label information of connected your printer. This if for PT only.

Declaration

- (BRPtouchLabelInfoStatus *)getLabelInfoStatus;

Return Value BRPtouchLabelInfoStatus

getStatus:

Get the status from the printer as BRPtouchPrinterStatus.

Declaration

- (int)getStatus:(BRPtouchPrinterStatus **)status;

Parameters

Parameter	Description
status	A double pointer of BRPtouchPrinterStatus.

Return Value

0 if failed, non zero if success.

getStatus:errorCode:

Get the status from the printer as BRPtouchPrinterStatus and error codes.

Declaration

- (int)getStatus:(BRPtouchPrinterStatus**)status errorCode:(int *)errorCode;

getModelName

Get the model name of connected your printer. This is only for CONNECTION_TYPE_WLAN (cf. CONNECTION_TYPE).

Declaration

- (NSString *)getModelName;

Return Value NSString that is gotten from your printer through WLAN.

getFirmVersion

Get the firmware version of the specified printer as a string.

Declaration

- (NSString *)getFirmVersion;

Return Value For example, @"0102". This means "ver.1.02".

getMediaVersion

Get the media version in the firmware of connected your printer.

Declaration

- (NSString *)getMediaVersion;

Return Value For example, @"0102". This means "ver.1.02".

getMediaFileVersion:filepath

Get the firmware version from the firmware data file.

Declaration

- (NSString *)getMediaFileVersion:(NSString *)filepath;

Return Value For example, @"0102". This means "ver.1.02".

getDeviceSerialNumber

Get the serial number from connected your printer.

Declaration

- (NSString *)getDeviceSerialNumber;

getSystemReport:

Get the system report from the printer as string.

Declaration

- (int)getSystemReport:(NSString **)report;

sendTemplateFile:

Send template files. See also sendTemplate:.

Declaration

- (BOOL)sendTemplateFile:(NSArray*)sendFileArray;

sendFirmwareFile:

Send firmware files.

Declaration

- (BOOL)sendFirmwareFile:(NSArray*)sendFileArray;

sendTemplate:connectionType:

Transfers P-touch Template files. Use P-touch Transfer Manager on PC to make .blf files.

Declaration

- (int)sendTemplate:(NSString *)sendtemplateFilePath connectionType:(CONNECTION_TYPE) type;

Parameters

Parameter	Description
sendtemplateFilePath	The absolute file path of the file.
type	The connection type to the printer.

Return Value

One of the error code.

sendDatabase:

Send the database data described in .csv format. In addition, this updates the database for printers that have templates and databases created and linked by P-touch Editor.

.csv data format restrictions :

• the delimiter is ,(comma) only
• Alphanumeric & symbol in ASCII only

Declaration

- (int)sendDatabase:(NSString *)databaseFilePath;

Parameters

Parameter	Description
databaseFilePath	The path of the .csv file.

Return Value

One of the error code.

startPTTPrint:encoding:

Start creating the command and print data string for a P-touch Template. Specify a template and the character encoding. This function assumes the default P-touch Template settings. Your application may not be able to print if the printer's settings differ from the defaults. If necessary, use the P-touch Template Setting Tool to configure the printer.

Declaration

- (BOOL)startPTTPrint:(int)key encoding:(NSStringEncoding)encoding;

Parameters

Parameter	Description
key	Key number assigned to the template. The key starts from 1.
encode	NSShiftJISStringEncoding for printer models with Japanese fonts, CFStringConvertEncodingToNSStringEncoding(kCFStringEncodingGB_18030_2000) for printer models with Chinese fonts, NSUTF8StringEncoding for all other printer models.

Return Value

false if the printer doesn't support P-touch template, otherwise true.

replaceText:

Replaces the next replaceable text in a P-touch Template. Text strings are replaced in order from small object number.

Declaration

- (BOOL)replaceText:(NSString *)data;

Parameters

Parameter	Description
data	Replacement text.

Return Value

false if the printer doesn't support P-touch template, otherwise true.

replaceTextIndex:objectIndex:

Replaces the text in an object of a P-touch Template, specified by its object number.

Declaration

- (BOOL)replaceTextIndex:(NSString *)data objectIndex:(int)objIndex;

Parameters

Parameter	Description
data	Replacement text.
objIndex	Object number in which to replace the text. The range depends on models.

Return Value

false if the index is out of range or the printer doesn't support P-touch template, otherwise true.

replaceTextName:objectName:

Replaces the text in an object of a P-touch Template, specified by the object's name.

Declaration

- (BOOL)replaceTextName:(NSString *)data objectName:(NSString *)objName;

Parameters

Parameter	Description
data	Replacement text.
objName	Object name of the object in which to replace the text.

Return Value

false if the data length longer than 20 or the printer doesn't support P-touch template, otherwise true.

flushPTTPrintWithCopies:

Transmits command and print data used to print a P-touch Template.

Declaration

- (int)flushPTTPrintWithCopies:(int)nCopy;

Return Value RET_TRUE if success, otherwise RET_FALSE.

removeTemplate:

Remove templates data from your printer with specifying the template key. It can be gotten by getTemplateList:.

Declaration

- (int)removeTemplate:(NSArray<NSNumber*> *)keyList;

Return Value RET_TRUE if success, otherwise RET_FALSE.

getTemplateList:

Get template list in your printer.

Declaration

- (int)getTemplateList:(NSArray<BRPtouchTemplateInfo*>*__autoreleasing *)templateList;

Return Value RET_TRUE if success, otherwise RET_FALSE.

searchAvailableSSID:

Get available SSIDs on your printer.

Warning

This is beta function and is not guaranteed to work.

*Declaration

- (NSArray <NSString *>*)searchAvailableSSID:(int)waitTime;

setIPAddress:

Set the IP address of the printer.

Declaration

- (void)setIPAddress:(NSString*)strIP;

setupForBluetoothDeviceWithSerialNumber:

Set the serial number of the printer to connect via Bluetooth.

Declaration

- (void)setupForBluetoothDeviceWithSerialNumber:(NSString*)serialNumber;

setBluetooth Low EnergyAdvertiseLocalName:

Set the advertise local name of the printer to connect via Bluetooth Low Energy.

Declaration

- (void)setBLEAdvertiseLocalName:(NSString*)advertiseLocalName;

startCommunication

Open a session to communicate with the printer based on the connection type. You need to call it before calling any API communicating with the printer. You need to call endCommunication when it becomes unnecessary.

Declaration

- (BOOL)startCommunication;

Return Value

YES if success, otherwise NO.

endCommunication

Close the session opened via startCommunication.

Declaration

- (void)endCommunication;

Parameters

Parameter	Description
report	A double pointer of NSString.

Return Value

One of the error code.

sendFile:

Send the contents of the file to the printer.

Warning

If you pass a file including raster commands customized by yourself, automatic status notification mode must be turned off (Do not notify). Any notifications from printers are not received in this function. For information on the mode, see a command reference for your printer.

Declaration

- (int)sendFile:(NSString *)filePath;

Parameters

Parameter	Description
filePath	The absolute file path of the file.

Return Value

One of the error code.

sendData:

Send the binary data to the printer.

Declaration

- (int)sendData:(NSData *)data;

Parameters

Parameter	Description
data	The binary data.

Return Value

One of the error code.

sendFileEx:

Same as sendFile:.

sendDataEx:

Same as sendData:.

printPDFAtPath:pages:length:copy:

Print the PDF file using print settings set by setPrintInfo:.

Declaration

- (int)printPDFAtPath:(NSString *)pdfPath pages:(NSUInteger [])indexes length:(NSUInteger)length copy:(int)nCopy;

Parameters

Parameter	Description
pdfPath	The PDF file path to be printed.
indexes	The page index array.
length	The length of indexes. All pages are printed if this parameter is 0.
nCopy	The number of copies.

Return Value

One of the error code.

printImage:copy:

Print the image using print settings set by setPrintInfo:.

Declaration

- (int)printImage:(CGImageRef)imageRef copy:(int)nCopy;

Parameters

Parameter	Description
imageRef	The reference to the image to be printed.
nCopy	The number of copies.

Return Value

One of the error code.

printFiles:copy:

Print the image files using print settings set by setPrintInfo:.

Declaration

- (int)printFiles:(NSArray *)filePaths copy:(int)nCopy;

Parameters

Parameter	Description
filePaths	The path array of image file to be printed.
nCopy	The number of copies.

Return Value

One of the error code.

cancelPrinting

Cancels the print job. The job is cancelled after transmission if this is executed while print data is being transmitted.

Declaration

- (int)cancelPrinting;

Return Value One of the error code.

setInterface:

Set interface you use to connect your printer.

Declaration

- (void)setInterface:(CONNECTION_TYPE)strInterface;

getBatteryStatus

Get Battery degradation level from your printer.

Declaration

- (int)getBatteryStatus;

Return Value -1 if occur any errors. 0 if not supported. Positive integer if succeeded.

getBatteryInfo:

Get the battery info from the printer as BRPtouchBatteryInfo.

Declaration

- (int)getBatteryInfo:(BRPtouchBatteryInfo **)batteryInfo;

Parameters

Parameter	Description
batteryInfo	A double pointer of BRPtouchBatteryInfo.

Return Value

One of the error code.

getPrinterBootMode

Declaration

- (int)getPrinterBootMode;

Return Value 1 if the printer is on boot mode.successfullyprinter have started up without any errors. This will be useful to check if your pritner reboot successfully after sending firmware file.

setAutoConnectBluetooth:

Change the printer configuration of Bluetooth auto connection from the printer. This API is available only when connected with the printer via Bluetooth/Bluetooth Low Energy.

Declaration

- (int)setAutoConnectBluetooth:(BOOL)flag;

Parameters

Parameter	Description
flag	On/Off of auto connection

Return Value

0 if failed, non zero if success.

isAutoConnectBluetooth

Retrieves the Bluetooth auto connection configuration from the printer. This API is available only when connected with the printer via Bluetooth/Bluetooth Low Energy.

Declaration

- (int)isAutoConnectBluetooth;

Return Value

1 if the auto connection is enabled, 0 if disabled or ERROR_COMMUNICATION_ERROR_ if fail to retrieve.

setPrinterSettings:

Change the printer configurations.

Declaration

- (int)setPrinterSettings:(NSDictionary *)printerSettings;

Parameters

Parameter	Description
printerSettings	Settings list you want to change. The key is NSNumber of PrinterSettingItem and the value is NSString. See Printer Configurations for available values.

Return Value

RET_TRUE if success, otherwise RET_FALSE.

getPrinterSettings:require:

Retrieves the current printer settings.

Declaration

- (int)getPrinterSettings:(NSDictionary **)printerSettings require:(NSArray *)require;

Parameters

Parameter	Description
printerSettings	A double pointer of NSDictionary to store the results. The key is NSNumber of PrinterSettingItem and the value is NSString. See Printer Configurations for available values.
require	Settings list you want to retrieve. The values of the array should be NSNumber of PrinterSettingItem.

Return Value

One of the error code.

setPrinterNameFromStatus:

Set printer name from BRPtouchPrinterStatus instead of from setPrinterName.

It is used when the model name cannot be determined by the search API, such as TD-2350D.

Declaration

- (void)setPrinterNameFromStatus:(BRPtouchPrinterStatus*)status;

Parameters

Parameter	Description
status	Status returned by getStatus:

Types

CONNECTION_TYPE

enum to indicate connection types to the printer.

Declaration

typedef NS_ENUM(NSUInteger, CONNECTION_TYPE) {
    CONNECTION_TYPE_WLAN,
    CONNECTION_TYPE_BLUETOOTH,
    CONNECTION_TYPE_BLE,
};

Error Codes

Error codes are defined as macro in BRPtouchPrinter.h.

Error Code	Description
ERROR_NONE_	Success
ERROR_TIMEOUT	Timeout
ERROR_CREATESTREAM	Failed to create a stream.
ERROR_OPENSTREAM	Failed to open a stream.
ERROR_FILENOTEXIST	Specified file does not exist.
ERROR_PAGERANGEERROR	Specified page range exceeds the maximum.
ERROR_NOT_SAME_MODEL_	Different printer model
ERROR_BROTHER_PRINTER_NOT_FOUND_	No Brother printer can be found.
ERROR_PAPER_EMPTY_	No paper
ERROR_BATTERY_EMPTY_	Insufficient battery level
ERROR_COMMUNICATION_ERROR_	Failed to retrieve printer status.
ERROR_OVERHEAT_	Overheating error
ERROR_PAPER_JAM_	Paper jam
ERROR_HIGH_VOLTAGE_ADAPTER_	High-voltage adapter
ERROR_CHANGE_CASSETTE_	Replace paper cassette while printing.
ERROR_FEED_OR_CASSETTE_EMPTY_	Feeding error or end of paper
ERROR_SYSTEM_ERROR_	System error
ERROR_NO_CASSETTE_	No paper cassette during a printing operation.
ERROR_CREATE_SOCKET_FAILED_	Failed to create socket.
ERROR_CONNECT_SOCKET_FAILED_	Failed to connect.
ERROR_GET_OUTPUT_STREAM_FAILED_	Failed to retrieve output stream.
ERROR_GET_INPUT_STREAM_FAILED_	Failed to retrieve input stream.
ERROR_CLOSE_SOCKET_FAILED_	Failed to close socket.
ERROR_OUT_OF_MEMORY_	Insufficient memory
ERROR_SET_OVER_MARGIN_	Exceeded the specified margin.
ERROR_NO_SD_CARD_	No SD card
ERROR_FILE_NOT_SUPPORTED_	Unsupported file
ERROR_EVALUATION_TIMEUP_	Trial period for PDF printing has ended.
ERROR_WRONG_CUSTOM_INFO_	Incorrect custom paper settings
ERROR_NO_ADDRESS_	IP address and MAC address are not specified.
ERROR_FILE_NOT_FOUND_	File does not exist.
ERROR_TEMPLATE_FILE_NOT_MATCH_MODEL_	Template file and printer model are incompatible.
ERROR_TEMPLATE_NOT_TRANS_MODEL_	Model incompatible with template transfer
ERROR_COVER_OPEN_	Cover open
ERROR_WRONG_LABEL_	Incorrect roll type
ERROR_PORT_NOT_SUPPORTED_	Unsupported interface
ERROR_WRONG_TEMPLATE_KEY_	A template with the specified key does not exist.
ERROR_BUSY_	Busy
ERROR_TEMPLATE_NOT_PRINT_MODEL_	Model incompatible with P-touch template printing
TEMPLATE_NOT_PRINT_MODEL_	Cancel
ERROR_PRINTER_SETTING_NOT_SUPPORTED_	Device settings function not supported
ERROR_INVALID_PARAMETER_	Invalid parameter
ERROR_INTERNAL_ERROR_	Internal device error
ERROR_TEMPLATE_NOT_CONTROL_MODEL_	Model incompatible with template deleting and retrieving
ERROR_TEMPLATE_NOT_EXIST_	Template does not exist.
ERROR_BUFFER_FULL_	Buffer full
ERROR_TUBE_EMPTY_	Tube empty
ERROR_TUBE_RIBBON_EMPTY_	Tube ribbon empty
ERROR_MINIMUM_LENGTH_LIMIT_	The length is too short to print
ERROR_RESOLUTION_MODE_	You can not use the High-resolution / draft printing
ERROR_UNSUPPORTED_USB_CHARGER_	The USB connected has not enough power supply capacity to print
ERROR_UNSUPPORTED_OPTIONAL_EQUIPMENT_	The optional equipment is not compatible with the printer.

PrinterSettingItem

The printer setting keys used in getPrinterSettings:require and setPrinterSettings:.

typedef NS_ENUM(NSUInteger, PrinterSettingItem) {
    PSI_NET_BOOTMODE = 1,
    PSI_NET_INTERFACE = 2,
    PSI_NET_USED_IPV6 = 3,
    PSI_NET_PRIORITY_IPV6 = 4,
    PSI_NET_IPV4_BOOTMETHOD = 5,
    PSI_NET_STATIC_IPV4ADDRESS = 6,
    PSI_NET_SUBNETMASK = 7,
    PSI_NET_GATEWAY = 8,
    PSI_NET_DNS_IPV4_BOOTMETHOD = 9,
    PSI_NET_PRIMARY_DNS_IPV4ADDRESS = 10,
    PSI_NET_SECOND_DNS_IPV4ADDRESS = 11,
    PSI_NET_IPV6_BOOTMETHOD = 12,
    PSI_NET_STATIC_IPV6ADDRESS = 13,
    PSI_NET_PRIMARY_DNS_IPV6ADDRESS = 14,
    PSI_NET_SECOND_DNS_IPV6ADDRESS = 15,
    PSI_NET_IPV6ADDRESS_LIST = 16,
    PSI_NET_COMMUNICATION_MODE = 17,
    PSI_NET_SSID = 18,
    PSI_NET_CHANNEL = 19,
    PSI_NET_AUTHENTICATION_METHOD = 20,
    PSI_NET_ENCRYPTIONMODE = 21,
    PSI_NET_WEPKEY = 22,
    PSI_NET_PASSPHRASE = 23,
    PSI_NET_USER_ID = 24,
    PSI_NET_PASSWORD = 25,
    PSI_NET_NODENAME = 26,
    PSI_WIRELESSDIRECT_KEY_CREATE_MODE = 27,
    PSI_WIRELESSDIRECT_SSID = 28,
    PSI_WIRELESSDIRECT_NETWORK_KEY = 29,
    PSI_BT_ISDISCOVERABLE = 30,
    PSI_BT_DEVICENAME = 31,
    PSI_BT_BOOTMODE = 34,
    PSI_PRINTER_POWEROFFTIME = 35,
    PSI_PRINTER_POWEROFFTIME_BATTERY = 36,
    PSI_PRINT_JPEG_HALFTONE = 37,
    PSI_PRINT_JPEG_SCALE = 38,
    PSI_PRINT_DENSITY = 39,
    PSI_PRINT_SPEED = 40,
    PSI_BT_POWERSAVEMODE = 41,
    PSI_BT_SSP = 42,
    PSI_BT_AUTHMODE = 43,
    PSI_BT_AUTO_CONNECTION = 44,
} ;

Notifications

Transmission Progress Notification

The following notification is sent immediately after the data could be transmitted on an each connection. If BRBytesWrittenKey is used, the cumulative total number of bytes in data transmitted to the printer is retrieved. This is the same if you want to retrieve the total number of bytes necessary for transmission.

• BRWLanConnectBytesWrittenNotification
• BRBluetoothSessionBytesWrittenNotification
• BRBLEBytesWrittenNotification

Event Notification

BRPtouchPrinterKitMessageNotification is sent for following events. Using BRMessageKey from userInfo, the event type can be retrieved as NSString.

Event	Description
@"MESSAGE_START_COMMUNICATION_"	Transmission started
@"MESSAGE_START_CONNECT_"	Socket connection started
@"MESSAGE_END_CONNECTED_"	Socket connected successfully
@"MESSAGE_START_SEND_STATUS_REQUEST_"	Status request transmission started
@"MESSAGE_END_SEND_STATUS_REQUEST_"	Status request transmission finished
@"MESSAGE_START_READ_PRINTER_STATUS_"	Status reception started
@"MESSAGE_END_READ_PRINTER_STATUS_"	Status reception finished
@"MESSAGE_START_CREATE_DATA_"	Data creation started
@"MESSAGE_END_CREATE_DATA_"	Data creation finished
@"MESSAGE_START_SEND_DATA_"	Data transmission started
@"MESSAGE_END_SEND_DATA_"	Data transmission finished
@"MESSAGE_START_SEND_TEPLATE_"	Template file transmission started
@"MESSAGE_END_SEND_TEPLATE_"	Template file transmission finished
@"MESSAGE_PRINT_COMPLETE_"	Printed successfully
@"MESSAGE_PRINT_ERROR_"	Error occurred
@"MESSAGE_PAPER_EMPTY_"	No paper
@"MESSAGE_START_COOLING_"	Cooling started
@"MESSAGE_END_COOLING_"	Cooling finished
@"MESSAGE_WAIT_PEEL_"	Waiting for peeling of label
@"MESSAGE_CANCEL_"	Job canceled

Notes

API Compatibility

Some APIs of BRPtouchPrinter are supported only by specific printers. Refer to the following table.

Properties	Supported Printer
getBatteryInfo:	RJ-4200 series

Template Object Number Range

Object Number Range	Printer Model
1 - 50	MW series, PT-P9xx, QL series
1 - 200	PJ-663
1 - 99	TD series, RJ series
1 - 255	PJ-7xx

Deprecates

Deprecated

isPrinterReady

Please use startCommunication instead.

getPTstatus:

Please use getStatus: instead.