Skip to content

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.

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.