Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

PrinterZebra

The PrinterZebra API provides Zebra specific API access Zebra Bluetooth and WiFi Network printers. This API inherits all methods,properties,constants from the Printer API

Enabling the API

In order to use this API you must include the following extension in your build.yml.

extensions: ["printing","printing_zebra"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

connect(CallBackHandler callback)

Connect to a printer using default options. Works asynchronously, use callback to check the result. If connection is successful printer state and properties are automatically updated. NB: default options are defined by printer SDK and platform and may vary between different devices.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.connect(CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.connect(CallBackHandler callback)
- Ruby: Rho::PrinterZebra.connect(CallBackHandler callback)

connectWithOptions(HASH options, CallBackHandler callback)

Connect to a printer using user options. Works asynchronously, use callback to check the result. After this function call state is automatically updated.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

options : HASH

Connect options.

timeout : INTEGER Optional Default: 15000

Connection timeout in milliseconds. Must be larger 0 !
Platforms:WM, iOS, Android
additionalStringOption : STRING Optional

Any additional info. This is currently not being used.

callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.connectWithOptions(HASH options, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.connectWithOptions(HASH options, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.connectWithOptions(HASH options, CallBackHandler callback)

disconnect(CallBackHandler callback)

Disconnect from a printer and release OS resources. Works asynchronously, use callback to check the result.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.disconnect(CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.disconnect(CallBackHandler callback)
- Ruby: Rho::PrinterZebra.disconnect(CallBackHandler callback)

enumerateSupportedControlLanguages(CallBackHandler callback)

Return array with languages supported by this printer.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: ARRAY

Object : STRING

Language. See – PRINTER_LANGUAGE_… constants.

Synchronous Return:

ARRAY :
Array of supported printer control languages.
: this method also supports async callbacks - check the Callback tab for callback return parameters.
- Object : STRING
  
  Language. See – PRINTER_LANGUAGE_… constants.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.enumerateSupportedControlLanguages(CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.enumerateSupportedControlLanguages(CallBackHandler callback)
- Ruby: Rho::PrinterZebra.enumerateSupportedControlLanguages(CallBackHandler callback)

enumerateSupportedTypes(CallBackHandler callback)

Returns array with supported printer types immediately. The result depends on your build configuration. Each extension is linked to application during build. If you want to add or remove support of any printer type please update extension list in the build.yml.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: ARRAY

Object : STRING

Type of device.

Synchronous Return:

ARRAY :
Array of currently supported printer types. Depends on build settings. May contain PRINTER_TYPE_ZEBRA, PRINTER_TYPE_EPSON, PRINTER_TYPE_APD, PRINTER_TYPE_NATIVE or any combination of them.
: this method also supports async callbacks - check the Callback tab for callback return parameters.
- Object : STRING
  
  Type of device.

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.PrinterZebra.enumerateSupportedTypes(CallBackHandler callback)
- Ruby: Rho::PrinterZebra.enumerateSupportedTypes(CallBackHandler callback)

getAllProperties(CallBackHandler callback)

This method will return all of object/value pairs for the propertyNames of the API class.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

: STRING

Synchronous Return:

HASH :
Map of all available properties
: this method also supports async callbacks - check the Callback tab for callback return parameters.
- : STRING

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.getAllProperties(CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.getAllProperties(CallBackHandler callback)
- Ruby: Rho::PrinterZebra.getAllProperties(CallBackHandler callback)

getDefault()

This method will return an object that represents the default instance of the API Class. For example Camera.getDefault will return a Camera object that represents the default camera.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Synchronous Return:

SELF_INSTANCE :
Default object of Module.

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.PrinterZebra.getDefault()
- Ruby: Rho::PrinterZebra.getDefault()

getPrinterByID(STRING printerId)

Return printer instance specified by printerId. If there is no printers with this ID null is returned. To get valid printerId please use searchPrinters function.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

printerId : STRING

Synchronous Return:

SELF_INSTANCE

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.PrinterZebra.getPrinterByID(STRING printerId)
- Ruby: Rho::PrinterZebra.getPrinterByID(STRING printerId)

getProperties(ARRAY arrayofNames, CallBackHandler callback)

This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

arrayofNames : ARRAY

List of properties I want to know about

Object : STRING

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

: STRING

Synchronous Return:

HASH :
Map of properties I want to know about
: this method also supports async callbacks - check the Callback tab for callback return parameters.
- : STRING

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.getProperties(ARRAY arrayofNames, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.getProperties(ARRAY arrayofNames, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.getProperties(ARRAY arrayofNames, CallBackHandler callback)

getProperty(STRING propertyName, CallBackHandler callback)

This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyName : STRING

The property to return info about.
callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

STRING :
The property to return info about.
: this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.getProperty(STRING propertyName, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.getProperty(STRING propertyName, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.getProperty(STRING propertyName, CallBackHandler callback)

printFile(STRING filePathOnDevice, HASH options, CallBackHandler callback)

Prints file. Works asynchronously, use callback to check the result. File extension is used to determine its type. Supported types: JPEG and PNG images.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

filePathOnDevice : STRING

Full path to local image file on the device.
options : HASH Optional

Not providing properties to this function will print with default settings. Reserved for future use.

propertyWithStringValue : STRING Optional

This is currently not being used.
propertyWithIntValue : INTEGER Optional

This is currently not being used.

callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.printFile(STRING filePathOnDevice, HASH options, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.printFile(STRING filePathOnDevice, HASH options, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.printFile(STRING filePathOnDevice, HASH options, CallBackHandler callback)

printImageFromFile(STRING filePathOnDevice, INTEGER x, INTEGER y, HASH options, CallBackHandler callback)

Prints an image from mobile digital device’s file system to the connected printer as a monochrome image. Works asynchronously, use callback to check the result. Note: if the image resolution is large (e.g. 1024x768) this method may take a long time to execute. It is not guaranteed that files larger than 1024x1024 could be printed correctly.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

filePathOnDevice : STRING

Full path to local image file on the device. (The image must be either a PNG or JPG, all other types are platform depend).
x : INTEGER

Horizontal starting position in dots.
y : INTEGER

Vertical starting position in dots.
options : HASH Optional

Provide a set of optional parameters.

width : INTEGER

Desired width of the printed image. Passing -1 will preserve original width.
height : INTEGER

Desired height of the printed image. Passing -1 will preserve original height.
isInsideFormat : BOOLEAN

Boolean value indicating whether this image should be printed by itself (false), or is part of a format being written to the connection (true).

callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.printImageFromFile(STRING filePathOnDevice, INTEGER x, INTEGER y, HASH options, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.printImageFromFile(STRING filePathOnDevice, INTEGER x, INTEGER y, HASH options, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.printImageFromFile(STRING filePathOnDevice, INTEGER x, INTEGER y, HASH options, CallBackHandler callback)

printRawString(STRING command, HASH options, CallBackHandler callback)

Send raw string to printer. Works asynchronously, use callback to check the result.

In Windows Mobile/CE using Zebra printers, this will not print ZPL commands, but just line mode (or raw text).

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

command : STRING

Raw string to print. Could be any valid command in printer supported programming language.
options : HASH Optional

Not providing properties to this function will print with default settings.

propertyWithStringValue : STRING Optional

This is currently not being used.
propertyWithIntValue : INTEGER Optional

This is currently not being used.

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

status : STRING

PRINTER_STATUS_SUCCESS, PRINTER_STATUS_ERROR.
message : STRING Optional

Error message, only if status = ERROR.
stringResponce : STRING Optional

Response from printer if received, converted to string from byteArray(original data)
Platforms:Android, WM
byteArrayResponce : ARRAY Optional

Response from printer if received.
Platforms:Android

Object : INTEGER

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.printRawString(STRING command, HASH options, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.printRawString(STRING command, HASH options, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.printRawString(STRING command, HASH options, CallBackHandler callback)

printStoredFormatWithArray(STRING formatPathOnPrinter, Array vars, CallBackHandler callback)

Prints a stored format on the printer, filling in the fields specified by the array. Works asynchronously, use callback to check the result.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

formatPathOnPrinter : STRING

The location of the file on the printer (e.g. “E:FORMAT.ZPL”).
vars : Array

An array of strings representing the data to fill into the format. For ZPL formats, index 0 of the array corresponds to field number 2 (^FN2). For CPCL, the variables are passed in the order that they are found in the format
callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.printStoredFormatWithArray(STRING formatPathOnPrinter, Array vars, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.printStoredFormatWithArray(STRING formatPathOnPrinter, Array vars, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.printStoredFormatWithArray(STRING formatPathOnPrinter, Array vars, CallBackHandler callback)

printStoredFormatWithHash(STRING formatPathOnPrinter, HASH vars, CallBackHandler callback)

Prints a stored format on the printer, filling in the fields specified by the Hash. Works asynchronously, use callback to check the result.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

formatPathOnPrinter : STRING

The location of the file on the printer (e.g. “E:FORMAT.ZPL”).
vars : HASH

An Hash which contains the key/value pairs for the stored format. For ZPL formats, the key number should correspond directly to the number of the field in the format. Number keys should be passed as String: ‘1’:‘field1’ etc. CPCL format do not supported – only ZPL!
callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.printStoredFormatWithHash(STRING formatPathOnPrinter, HASH vars, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.printStoredFormatWithHash(STRING formatPathOnPrinter, HASH vars, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.printStoredFormatWithHash(STRING formatPathOnPrinter, HASH vars, CallBackHandler callback)

requestState(ARRAY listOfParameters, CallBackHandler callback)

Requests printer state with a list of parameters.

Works asynchronously and uses the callback to check the result.
Returns hash with status, and parameters as keys.

On the Windows Mobile / Windows CE platform, this method does not work in the case of a bluetooth connection.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

listOfParameters : ARRAY

List of parameters for request from printer device.

Object : STRING

Parameter name – see consts with PRINTER_STATE_…

callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

status : STRING

PRINTER_STATUS_SUCCESS, PRINTER_STATUS_ERROR.
message : STRING Optional

Error message, only if status = ERROR.
propertyWithIntValue : INTEGER Optional

This is currently not being used.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.requestState(ARRAY listOfParameters, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.requestState(ARRAY listOfParameters, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.requestState(ARRAY listOfParameters, CallBackHandler callback)

retrieveFileNames(CallBackHandler callback)

Retrieves the names of the files which are stored on the printer. Works asynchronously, use callback to check the result.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

status : STRING

PRINTER_STATUS_SUCCESS, PRINTER_STATUS_ERROR
fileNames : ARRAY

Object : STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.retrieveFileNames(CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.retrieveFileNames(CallBackHandler callback)
- Ruby: Rho::PrinterZebra.retrieveFileNames(CallBackHandler callback)

retrieveFileNamesWithExtensions(ARRAY extensions, CallBackHandler callback)

This method only returns files which have the extensions in “extensions”. Works asynchronously, use callback to check the result.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

extensions : ARRAY

The list of extensions that should be returned.

Object : STRING

callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

status : STRING

PRINTER_STATUS_SUCCESS, PRINTER_STATUS_ERROR
fileNames : ARRAY

Object : STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.retrieveFileNamesWithExtensions(ARRAY extensions, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.retrieveFileNamesWithExtensions(ARRAY extensions, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.retrieveFileNamesWithExtensions(ARRAY extensions, CallBackHandler callback)

searchPrinters(HASH options, CallBackHandler callback)

Search printers connected to this device, available Bluetooth® or Network printers. It is highly recommended to search for a particular Bluetooth® address or IP address for Network connections. Also this method could be used to get printerID for known network/bluetooth printer, in this case you should specify deviceAddress parameter in options. Result is returned asynchronously using callback. Callback is called for each discovered printer. Search is finished if printerID is not set in callback hash. Note: discovery is not guaranteed to return all the available devices. Please run this method at least 2-3 times to get result with good accuracy.

on Android platfrom due to HW specific, when you call searchPrinters() for Bluetooth or for TCP and Bluetooth both, Application can freeze for few seconds – if user touch screen Android system can show Alert about “application not responded” – user should select [continue waiting] button.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

options : HASH Optional

Options for discover.

printerType : STRING Optional Default: PRINTER_TYPE_ANY

Printer types to search. Make sure that Printer type is supported by calling enumerateSupportedTypes method.
connectionType : STRING Optional Default: CONNECTION_TYPE_ANY

Interfaces for search (Bluetooth/TCP/All)
timeout : INTEGER Optional Default: 30000

Maximum search interval in milliseconds, applies to network discovery. This is the maximum interval for wait during connection attempt. Note: if no printer was found even with timeout property status will be set to PRINTER_STATUS_SUCCESS, but without any printerId.
deviceAddress : STRING Optional

Printer address (mac or ip). Can be used for setting either subnet mask or full address of printer. For TCP if address is not specified /8 subnet will be used for search.
devicePort : INTEGER Optional Default: 6101

Override default printer port number. Applicable for network discovery only.

callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

status : STRING

Status of network discovery, can be following: * PRINTER_STATUS_SUCCESS – when printer is discovered or operation is finished; * PRINTER_STATUS_ERROR – general error * PRINTER_STATUS_ERR_UNSUPPORTED – in case if printer type is not supported * PRINTER_STATUS_ERR_NOT_CONNECTED – in case if deviceAddress was specified in options and device was unable to connect to printer.
printerID : STRING Optional

Printer ID, valid only if status equals to ‘PRINTER_STATUS_SUCCESS’. If there are no more printers available printerID will not be defined.
message : STRING Optional

Error message, only if status = ERROR.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.PrinterZebra.searchPrinters(HASH options, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.searchPrinters(HASH options, CallBackHandler callback)

sendFileContents(STRING path, CallBackHandler callback)

Sends the contents of a file on the device to the printer. Equals to printing raw string with content of specified file. Should be used to print ZPL and CPCL commands stored inside predefined filed. Works asynchronously, use callback to check the result.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

path : STRING

Location of file to print. This path must be fully qualified path to local file on the device.
callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.sendFileContents(STRING path, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.sendFileContents(STRING path, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.sendFileContents(STRING path, CallBackHandler callback)

setDefault(SELF_INSTANCE: Rho::PrinterZebra defaultInstance)

This method allows you to set the attributes of the default object instance by passing in an object of the same class.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

defaultInstance : SELF_INSTANCE: Rho::PrinterZebra

An instance object that is of the same class.

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.PrinterZebra.setDefault(SELF_INSTANCE: Rho::PrinterZebra defaultInstance)
- Ruby: Rho::PrinterZebra.setDefault(SELF_INSTANCE: Rho::PrinterZebra defaultInstance)

setProperties(HASH propertyMap)

This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyMap : HASH

Map of properties I want to set

Object : STRING

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.setProperties(HASH propertyMap)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.setProperties(HASH propertyMap)
- Ruby: Rho::PrinterZebra.setProperties(HASH propertyMap)

setProperty(STRING propertyName, STRING propertyValue)

This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyName : STRING

The one property name that I want to set
propertyValue : STRING

The one property value that I want to set

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.setProperty(STRING propertyName, STRING propertyValue)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.setProperty(STRING propertyName, STRING propertyValue)
- Ruby: Rho::PrinterZebra.setProperty(STRING propertyName, STRING propertyValue)

stopSearch()

Stop all active and pending search requests. Function does not return any results. All running search requests are canceled immediately.

Javascript Ruby Android iphone, ipod touch, ipad

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.PrinterZebra.stopSearch()
- Ruby: Rho::PrinterZebra.stopSearch()

storeImage(STRING printerDriveAndFileName, STRING imageFilePathOnDevice, INTEGER width, INTEGER height, CallBackHandler callback)

Stores the specified image to the connected printer as a monochrome image. Works asynchronously, use callback to check the result. The image will be stored on the printer at printerDriveAndFileName with the extension GRF. If a drive letter is not supplied, E will be used as the default (e.g. FILE becomes E:FILE.GRF). If an extension is supplied, it is ignored (E:FILE.BMP becomes E:FILE.GRF). Note: if the image resolution is large (e.g. 1024x768) this method may take a long time to execute. There are device OS limitations on supported file formats and image sizes. iOS, Android and WM are supporting only JPG and PNG files. WM can fail to handle large (>1024x1024 pixel) images.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

printerDriveAndFileName : STRING

Path on the printer where the image will be stored.
imageFilePathOnDevice : STRING

Path to the local image file containing the bitmap image to send.
width : INTEGER

Desired width of the printed image, in dots. Passing -1 will preserve original width.
height : INTEGER

Desired height of the printed image, in dots. Passing -1 will preserve original height.
callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.storeImage(STRING printerDriveAndFileName, STRING imageFilePathOnDevice, INTEGER width, INTEGER height, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.storeImage(STRING printerDriveAndFileName, STRING imageFilePathOnDevice, INTEGER width, INTEGER height, CallBackHandler callback)
- Ruby: Rho::PrinterZebra.storeImage(STRING printerDriveAndFileName, STRING imageFilePathOnDevice, INTEGER width, INTEGER height, CallBackHandler callback)

Properties

Unique printer ID during application lifetime.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.ID
Default Instance: This property can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.ID
- Ruby: Rho::PrinterZebra.ID

connectionType : STRING Read Only 4.1.0

Description
Access

Type of connection to printer.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.connectionType
Default Instance: This property can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.connectionType
- Ruby: Rho::PrinterZebra.connectionType

deviceAddress : STRING Read Only 4.1.0

Description
Access

Bluetooth mac/TCP IP address.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.deviceAddress
Default Instance: This property can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.deviceAddress
- Ruby: Rho::PrinterZebra.deviceAddress

deviceName : STRING Read Only 4.1.0

Description
Access

Bluetooth/Network name of printer.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.deviceName
Default Instance: This property can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.deviceName
- Ruby: Rho::PrinterZebra.deviceName

devicePort : INTEGER 4.1.0

Description
Access

Default port when connecting using TCP/IP.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.devicePort
Default Instance: This property can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.devicePort
- Ruby: Rho::PrinterZebra.devicePort

isConnected : BOOLEAN Read Only 4.1.0

Description
Access

Connection status flag. All other properties are valid only if isConnect equals to true. Please keep in mind: this property do not guarantee real connection, because all real device functionality processed in separated thread asynchronously. If you want real check physical connection – use requestState() method with receive result in callback. Only this way process real request to device and analyze answer from device.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.isConnected
Default Instance: This property can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.isConnected
- Ruby: Rho::PrinterZebra.isConnected

printerType : STRING Read Only 4.1.0

Description
Access

Type of printer – see PRINTER_TYPE_… consts.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.printerType
Default Instance: This property can be accessed via the default instance object of this class.
- Javascript: Rho.PrinterZebra.printerType
- Ruby: Rho::PrinterZebra.printerType

Constants

PRINT_MODE_APPLICATOR: Applicator print mode
PRINT_MODE_CUTTER: Cutter print mode
PRINT_MODE_DELAYED_CUT: Delayed cut print mode
PRINT_MODE_KIOSK: Kiosk print mode
PRINT_MODE_LINERLESS_PEEL: Linerless peel print mode
PRINT_MODE_LINERLESS_REWIND: Linerless rewind print mode
PRINT_MODE_PARTIAL_CUTTER: Partial cutter print mode
PRINT_MODE_PEEL_OFF: Peel-off print mode
PRINT_MODE_REWIND: Rewind print mode
PRINT_MODE_RFID: RFID print mode
PRINT_MODE_TEAR_OFF: Tear-off print mode (this also implies Linerless Tear print mode)
PRINT_MODE_UNKNOWN: Unknown print mode
DISCOVERY_MODE_MULTICAST
DISCOVERY_MODE_SUBNET_SEARCH
DISCOVERY_MODE_DIRECTED_BROADCAST
DISCOVERY_MODE_LOCAL_BROADCAST
ERROR_NO_CONNECTION: Unable to create a connection to a printer
ERROR_WRITE_FAILURE: Write to a connection failed
ERROR_READ_FAILURE: Read from a connection failed
ERROR_UNKNOWN_PRINTER_LANGUAGE: Unable to determine the control language of a printer
ERROR_MALFORMED_NETWORK_DISCOVERY_ADDRESS: Malformed discovery address
ERROR_NETWORK_ERROR_DURING_DISCOVERY: Network error during discovery
ERROR_INVALID_DISCOVERY_HOP_COUNT: Invalid multicast hop count
ERROR_MALFORMED_PRINTER_STATUS_RESPONSE: Malformed status response – unable to determine printer status
ERROR_INVALID_FORMAT_NAME: Invalid format name
ERROR_BAD_FILE_DIRECTORY_ENTRY: Bad file directory entry
ERROR_MALFORMED_FORMAT_FIELD_NUMBER: ‘^FN' integer must be between 1 and 999
ERROR_INVALID_PRINTER_LANGUAGE: Invalid printer language
ERROR_INVALID_FILE_NAME: Invalid file name
ERROR_INVALID_PRINTER_DRIVE_LETTER: Invalid drive specified
PRINTER_STATE_IS_HEAD_COLD: use this name for requestState(), true if the head is cold
PRINTER_STATE_IS_HEAD_OPEN: use this name for requestState(), true if the head is open
PRINTER_STATE_IS_HEAD_TOO_HOT: use this name for requestState(), true if the head is too hot
PRINTER_STATE_IS_PARTIAL_FORMAT_IN_PROGRESS: use this name for requestState(), true if there is a partial format in progress
PRINTER_STATE_IS_PAUSED: use this name for requestState(), true if the printer is paused
PRINTER_STATE_IS_RECEIVE_BUFFER_FULL: use this name for requestState(), true if the receive buffer is full
PRINTER_STATE_IS_RIBBON_OUT: use this name for requestState(), true if the ribbon is out
PRINTER_STATE_LABEL_LENGTH_IN_DOTS: use this name for requestState(), The length of the label in dots
PRINTER_STATE_LABELS_REMAINING_IN_BATCH: use this name for requestState(), The number of labels remaining in the batch
PRINTER_STATE_NUMBER_OF_FORMATS_IN_RECEIVE_BUFFER: use this name for requestState(), The number of formats currently in the receive buffer of the printer
PRINTER_STATE_PRINT_MODE: use this name for requestState(), The print mode
PRINTER_LANGUAGE_ZPL: Printer control language ZPL.
PRINTER_LANGUAGE_CPCL: Printer control language CPCL.
PRINTER_LANGUAGE_EPS: Printer control language EPS. Not Supported in 4.1
PRINTER_TYPE_ANY
PRINTER_TYPE_NATIVE: Not supported in 4.1
PRINTER_TYPE_ZEBRA
PRINTER_TYPE_EPSON: Not supported in 4.1
PRINTER_TYPE_APD: Not supported in 4.1
CONNECTION_TYPE_ANY
CONNECTION_TYPE_ON_BOARD: Not supported in 4.1
CONNECTION_TYPE_BLUETOOTH
CONNECTION_TYPE_TCP
PRINTER_STATUS_SUCCESS
PRINTER_STATUS_ERROR
PRINTER_STATUS_ERR_IO
PRINTER_STATUS_ERR_MEMORY
PRINTER_STATUS_ERR_NETWORK
PRINTER_STATUS_ERR_NOT_CONNECTED
PRINTER_STATUS_ERR_NOT_FOUND
PRINTER_STATUS_ERR_PARAM
PRINTER_STATUS_ERR_PROCESSING
PRINTER_STATUS_ERR_RESPONSE
PRINTER_STATUS_ERR_TIMEOUT
PRINTER_STATUS_ERR_UNSUPPORTED
PRINTER_STATE_IS_READY_TO_PRINT: Use this name for requestState(), return true if printer ready to print.
PRINTER_STATE_IS_COVER_OPENED: Use this name for requestState(), return true if cover is opened.
PRINTER_STATE_IS_DRAWER_OPENED: Use this name for requestState(), return true if drawer is opened.
PRINTER_STATE_IS_PAPER_OUT: Use this name for requestState(), return true if paper out.
PRINTER_STATE_IS_BATTERY_LOW: Use this name for requestState(), return true if battery low.

Examples

Printing via Bluetooth

To print to the Zebra printer we must first search for the device. In this example we are using the searchPrinters method and passing in options to limit the search to Bluetooth and also look for Zebra printers only. If we knew the printer Bluetooth address we could have added the ‘deviceAddress’ parameter. The callback function will be executed for each printer found. When a printer is found the callback object will contain a ‘printerID’ property. This ID is an internal RhoMobie ID used. If no printerID property is there for the successful callback object, then it means that the search has finished.

Javascript

var printers = [];

Rho.Printer.searchPrinters({ 
    connectionType:Rho.Printer.CONNECTION_TYPE_BLUETOOTH,  
    printerType: Rho.Printer.PRINTER_TYPE_ZEBRA
    }, function (cb){
        if(cb.status == 'PRINTER_STATUS_SUCCESS')
        {
            if (typeof cb.printerID != "undefined")
            {
                console.log('Found: ' + cb.printerID)
                printers.push(cb.printerID);
            }
            else
            {
                console.log('Done Searching');
            }
        }
        else
        {
            console.log(cb.status);
        }
    }
);

Now that we have found a printer. The printers array will contain the printerID we need to create an instance object that we will use for all communications. Upon first connection to the printer via Bluetooth, you may see a prompt to enter the Bluetooth PIN. Check the manufacturers guide for details. Normally the default is ‘0000’ or ‘1111’ or ‘1234’. Once it is connected, you should see some indication in the printer (like a blue light).

Javascript

var myPrinter = Rho.Printer.getPrinterByID(printers[0]);

// Let's try connecting
myPrinter.connect(function (cb){
    console.log(cb);
    // This will be the Zebra's `Friendly Name` 
    // by default it is the serial number
    console.log(myPrinter.deviceName);

    // This will be the BT MC Address 
    since we are connecting via BlueTooth
    console.log(myPrinter.deviceAddress);
});

Now we can just print a test string and read some properties of the printer to make sure the communications is working.

Javascript

// If my printer was in line mode I would see this text printed
myPrinter.printRawString('This is a test print');

// Example of sending a Zebra CPCL Command
// changing from linemode to ZPL mode
myPrinter.printRawString('! U1 setvar "device.languages" "ZPL"\r\n');

//Get state - this is realtime status of printer
// reading a property of the myPrinter instance will
// show last known status
myPrinter.requestState(['PRINTER_STATE_IS_READY_TO_PRINT',
    'PRINTER_STATE_IS_PAPER_OUT'],function (cb){
        console.log(cb.status);
        console.log(cb.PRINTER_STATE_IS_PAPER_OUT);
        console.log(cb.PRINTER_STATE_IS_READY_TO_PRINT);

    });

Remarks

iOS Notes

To use a Bluetooth connection on iOS devices you should take into account the following preconditions:

It will only work with Zebra printers which have the Made For iPod/iPhone certification.
Before using the printer you should pair it using the iOS system Bluetooth settings.
You need to include the External Accessory framework in your project (this is automatically added when you first generate the iPhone project file)
You need to include the Zebra printer protocol string “com.zebra.rawport” in your info.plist file ([project root]/project/iphone/Info.plist) under “Supported external accessory protocols”:
```
  <key>UISupportedExternalAccessoryProtocols</key>
  <array>
      <string>com.zebra.rawport</string>
  </array>
```
You need to set the key Required Background modes to App Communicates with an accessory in your app’s plist file
```
  <key>UIBackgroundModes</key>
  <array>
      <string>external-accessory</string>
  </array>
```

Android Notes

When you call searchPrinters() with Bluetooth search (with CONNECTION_TYPE_ANY or CONNECTION_TYPE_BLUETOOTH) then all Bluetooth devices around you will be discovered. You may see a lot of pairing requests to non-printer devices and should just cancel or ignore them. This happens because we can not detect that the device is a printer until the device is paired. It is recommended that the BT Address or WiFi MAC Address is also used when searching for printers.

Windows Mobile/CE Notes

You must set your app_type as “rhoelements” in your build.yml as shown here.
Requires a Printing Service application to be running. This is described in the Printing Guide
You should avoid navigating from the current page using the printer without disconnecting from the printer first. You can use the window.onunload event:
```
  window.onunload = function(){
      printer.disconnect();
  }
```
When you call searchPrinters() with Bluetooth search (with CONNECTION_TYPE_ANY or CONNECTION_TYPE_BLUETOOTH) then all Bluetooth devices around you will be discovered. You may see a lot of pairing requests to non-printer devices and should just cancel or ignore them. This happens because we can not detect that the device is a printer until the device is paired. It is recommended that the BT Address or WiFi MAC Address is also used when searching for printers.