Overview
The Printer API module provides access to find, connect, and print over Bluetooth, Wi-Fi and USB from Android and Windows Mobile devices.
Enabling the API
There are two methods of enabling the Printer API:
- Include all 'ebapi' modules
- Include only the required API modules
Both methods are explained below.
Either way, the included files will be from:
/Enterprise Browser/JavaScript Files/Enterprise Browser
,
a directory on the computer that contains the Enterprise Browser installation.
Include all JS API modules
To include all JavaScript APIs, copy the ebapi-modules.js
file to a location accessible by the app's files and include the JavaScript modules file in the app. For instance, to include the modules file in the app's index.html
, copy the modules file to the same directory as the index.html and add the following line to the HEAD section of the app's index.html file:
<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>
This will define the EB class within the page. Note that the path for this file is relative to the current page (index.html). Any page on which the modules are required will need to have the required .js file(s) included in this fashion.
Include only the required modules
To include individual APIs, include the ebapi.js
in the HTML, and then the additional required API file(s). For instance, to use the Printer API, add the following code to the HTML file(s). Again, this assumes that relevant API files have been copied to the same directory as the HTML.
<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.printer.js"></script>
In the code lines above, notice that
ebapi.js
is included first, followed byeb.printer.js
, which is the Printer API for Enterprise Browser. This coding is required on each HTML page whenever an individual API will be called from that page.
Methods
connect()
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. **Note: Default options are defined by printer SDK and platform and may vary between different devices.
Parameters
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: STRING
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.connect()
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.connect()
connectWithOptions(HASH options)
Connect to a printer with user options. Works asynchronously; use callback to check the result. After this function call, the printer state is automatically updated.
Parameters
- options : HASH
Connect options.
- timeout : INTEGER Optional Default: 15000
Connection timeout in milliseconds. Must be larger than 0. Platforms: WM, CE, Android
- additionalStringOption : STRING Optional
Any additional info; currently unused.
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: STRING
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.connectWithOptions(HASH options)
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.connectWithOptions(HASH options)
disconnect()
Disconnect from a printer and release OS resources. Works asynchronously; use callback to check the result.
Parameters
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: STRING
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.disconnect()
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.disconnect()
enumerateSupportedControlLanguages()
Returns an array with languages supported by this printer.
Parameters
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: ARRAY
- Object : STRING
Language. See - PRINTER_LANGUAGE_... constants.
Returns
Synchronous Return:
- ARRAY : Array of supported printer control languages.
- Object : STRING
Language. See - PRINTER_LANGUAGE_... constants.
- Object : STRING
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.enumerateSupportedControlLanguages()
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.enumerateSupportedControlLanguages()
enumerateSupportedTypes()
Immediately returns an array with supported printer types. The result depends on the build configuration. Each extension is linked to application during build. To add or remove support for any printer type, update extension list in the build.yml
.
Parameters
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: ARRAY
- Object : STRING
Type of device.
Returns
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 in any combination.
- Object : STRING
Type of device.
- Object : STRING
Platforms
- Android
- Windows Mobile
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Printer.enumerateSupportedTypes()
getAllProperties()
This method will return all of object/value pairs for the propertyNames of the API class.
Parameters
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: HASH
- : STRING
Returns
Synchronous Return:
- HASH : Map of all available properties
- : STRING
- : STRING
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.getAllProperties()
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.getAllProperties()
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.
Parameters
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: SELF_INSTANCE
Returns
Synchronous Return:
- SELF_INSTANCE : Default object of Module.
Platforms
- Android
- Windows Mobile
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Printer.getDefault()
getPrinterByID(STRING printerId)
Returns printer instance specified by printerId. Returns null is no printers contains the ID. To get valid printerId, use searchPrinters function.
Parameters
- printerId : STRING
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: SELF_INSTANCE
Returns
Synchronous Return:
- SELF_INSTANCE
Platforms
- Android
- Windows Mobile
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Printer.getPrinterByID(STRING printerId)
getProperties(ARRAY arrayofNames)
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.
Parameters
- arrayofNames : ARRAY
List of properties I want to know about
- Object : STRING
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: HASH
- : STRING
Returns
Synchronous Return:
- HASH : Map of properties I want to know about
- : STRING
- : STRING
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.getProperties(ARRAY arrayofNames)
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.getProperties(ARRAY arrayofNames)
getProperty(STRING propertyName)
This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.
Parameters
- propertyName : STRING
The property to return info about.
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: STRING
Returns
Synchronous Return:
- STRING : The property to return info about.
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.getProperty(STRING propertyName)
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.getProperty(STRING propertyName)
printFile(STRING filePathOnDevice, HASH options)
Prints file. Works asynchronously; use callback to check the result. File extension is used to determine its type. Supported image types: JPEG and PNG.
Parameters
- filePathOnDevice : STRING
Full path to local image file on the device.
- options : HASH Optional
Providing no 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
Currently unused.
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: STRING
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.printFile(STRING filePathOnDevice, HASH options)
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.printFile(STRING filePathOnDevice, HASH options)
printImageFromFile(STRING filePathOnDevice, INTEGER x, INTEGER y, HASH options)
Prints an image from a device's file system to the connected printer as a monochrome image. Works asynchronously; use callback to check the result. Images larger than 1024x768 might take a long time or print incorrectly. Consult printer documentation for image printing parameters.
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
Callback
Async Callback Returning Parameters: STRING
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
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)
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.printImageFromFile(STRING filePathOnDevice, INTEGER x, INTEGER y, HASH options)
printRawString(STRING command, HASH options)
Send raw string to printer. Works asynchronously, use callback to check the result. **Note: This method will not print ZPL commands from Windows Mobile devices to Zebra printers; compatible with line mode or raw text only.
Parameters
- command : STRING
Raw string to print. Could be any valid command in printer supported programming language.
- options : HASH Optional
Providing no properties to this function will print with default settings.
- propertyWithStringValue : STRING Optional
This is currently not being used.
- propertyWithIntValue : INTEGER Optional
Currently unused.
- callback : CallBackHandler
Callback
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
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.printRawString(STRING command, HASH options)
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.printRawString(STRING command, HASH options)
requestState(ARRAY listOfParameters)
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. **NOTE: On the Windows Mobile / Windows CE platform, this method does not work in the case of a Bluetooth and USB connection.
Parameters
- listOfParameters : ARRAY
List of parameters for request from printer device.
- Object : STRING
Parameter name - see constants with PRINTER_STATE_...
- callback : CallBackHandler
Callback
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
Currently unused.
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
Method Access:
- Instance Method: This method can be accessed via an instance object of this class:
myObject.requestState(ARRAY listOfParameters)
- Default Instance: This method can be accessed via the default instance object of this class.
EB.Printer.requestState(ARRAY listOfParameters)
searchPrinters(HASH options)
Searches for printers connected to the device via Bluetooth(R), Wi-Fi or USB. To reduce search times, it is highly recommended that searches for wireless connections be done by specific MAC address (Bluetooth) or IP address (Wi-Fi). This method also can be used to retrieve the printerID for a known Bluetooth or network printer specifying the deviceAddress
options parameter. Result is returned asynchronously using a callback called for each discovered printer. Search is finished if printerID is not set in callback hash. Note that discovery is not guaranteed to return all the available devices. It is therefore recommended that this method run 2-3 times for maximum accuracy.
Note: On certain Android devices, calling searchPrinters() over Bluetooth or TCP can cause the application to freeze momentarily or to display an alert that "The application has stopped responding." In such cases, it is recommended that the user tap the "Continue waiting" button.
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 that 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, device serial number or IP address)** 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
Callback
Async Callback Returning Parameters: HASH
- status : STRING
Status of network discovery, can be the 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 = 'PRINTER_STATUS_SUCCESS'. If no more printers are available, printerID will be undefined.
- message : STRING Optional
Error message if status = ERROR.
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Printer.searchPrinters(HASH options)
setDefault(SELF_INSTANCE: EB.Printer defaultInstance)
This method allows the attributes of the default object instance to be set by passing in an object of the same class.
Parameters
- defaultInstance : SELF_INSTANCE: EB.Printer
An instance object that is of the same class.
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Printer.setDefault(SELF_INSTANCE: EB.Printer 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.
Parameters
- propertyMap : HASH
Map of properties I want to set
- Object : STRING
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
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.
EB.Printer.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.
Parameters
- propertyName : STRING
The one property name that I want to set
- propertyValue : STRING
The one property value that I want to set
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
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.
EB.Printer.setProperty(STRING propertyName, STRING propertyValue)
stopSearch()
Immediately stops all active search requests and cancels pending search requests. Does not return a result.
Parameters
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Printer.stopSearch()
Properties
ID
Type
STRING Read Only
Description
Unique printer ID during application lifetime.
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.
EB.Printer.ID
Platforms
- Android
- Windows Mobile
connectionType
Type
STRING Read Only
Description
Type of connection to printer.
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.
EB.Printer.connectionType
Platforms
- Android
- Windows Mobile
deviceAddress
Type
STRING Read Only
Description
IP address for Wi-Fi connection, Bluetooth(R) MAC or device serial number. To get a device MAC, use CPCL command ! U1 getvar "bluetooth.address"
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.
EB.Printer.deviceAddress
Platforms
- Android
- Windows Mobile
deviceName
Type
STRING Read Only
Description
Bluetooth/Network name of printer.
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.
EB.Printer.deviceName
Platforms
- Android
- Windows Mobile
devicePort
Type
INTEGER
Description
Default port when connecting with TCP/IP.
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.
EB.Printer.devicePort
Platforms
- Android
- Windows Mobile
isConnected
Type
BOOLEAN Read Only
Description
Connection status flag. All other properties are valid only if isConnect = true. Note: This property does not guarantee a real connection, because all real device functionality is processed in separate thread asynchronously. For a real physical connection, use requestState()
method with receive result in the callback. This is the only guaranteed method of processing real requests to the device and analyzing answers from the device.
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.
EB.Printer.isConnected
Platforms
- Android
- Windows Mobile
printerType
Type
STRING Read Only
Description
Type of printer - see PRINTER_TYPE_... constants.
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.
EB.Printer.printerType
Platforms
- Android
- Windows Mobile
Constants
- PRINTER_LANGUAGE_ZPL Printer control language ZPL
- PRINTER_LANGUAGE_CPCL Printer control language CPCL
- PRINTER_LANGUAGE_EPS Printer control language EPS. Not Supported in RMS 4.1
- PRINTER_TYPE_ANY
- PRINTER_TYPE_NATIVE Not supported in RMS 4.1
- PRINTER_TYPE_ZEBRA
- PRINTER_TYPE_EPSON Not supported in RMS 4.1
- PRINTER_TYPE_APD Not supported in RMS 4.1
- CONNECTION_TYPE_ANY
- CONNECTION_TYPE_ON_BOARD Not supported in RMS 4.1
- CONNECTION_TYPE_USB Supported in RMS 5.1, EB 1.3
- 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.
Remarks
Android Notes
When calling searchPrinters() with Bluetooth search (CONNECTION_TYPE_ANY or CONNECTION_TYPE_BLUETOOTH), all local Bluetooth devices--including non-printers--will be discovered and send pairing requests. Just cancel or ignore them. This happens because the software cannot detect non-printers until after the device is paired. It is recommended that the BT or Wi-Fi MAC address also be used when searching for printers.
When calling searchPrinters() with USB search (with CONNECTION_TYPE_ANY or CONNECTION_TYPE_USB), all USB Printers connected to the device will be discovered. If USB printers are not supported by SDK or device, searchPrinters function should return PRINTER_STATUS_ERR_UNSUPPORTED.
Windows Mobile Notes
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 calling searchPrinters() with Bluetooth search (CONNECTION_TYPE_ANY or CONNECTION_TYPE_BLUETOOTH), all local Bluetooth devices--including non-printers--will be discovered and send pairing requests. Just cancel or ignore them. This happens because the software cannot detect non-printers until after the device is paired. It is recommended that the BT or Wi-Fi MAC address also be used when searching for printers.
Before calling searchPrinters() with USB search (CONNECTION_TYPE_ANY or CONNECTION_TYPE_USB), configure the device's USB controller for "USB Host mode" and reboot.
When calling searchPrinters() with USB search (with CONNECTION_TYPE_ANY or CONNECTION_TYPE_USB), all USB Printers connected to the device will be discovered. If USB printers are not supported by SDK or device, searchPrinters function should return PRINTER_STATUS_ERR_UNSUPPORTED.
USB connection is not supported on QLn320;
printer.searchPrinters
should return no non-printer devices. If USB printers are not supported by SDK or device, searchPrinters function should return PRINTER_STATUS_ERR_UNSUPPORTED; For example, executing searchPrinters on Android device with connectionType set to CONNECTION_TYPE_USB should return PRINTER_STATUS_ERR_UNSUPPORTED.