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

PrinterZebra

Constants71

The PrinterZebra API provides Zebra-specific API access to Zebra’s Bluetooth and Wi-Fi network printers, and to USB-capable printers for Android and Windows Mobile/CE. This API inherits all methods, properties and constants from the Printer API.

Notes

  1. Unless using the printer’s ‘line mode’ (for sending raw text strings), Zebra recommends sending ZPL only.
  2. USB printing is supported for Android and Windows Mobile/CE.

Enabling the API

To use this API you must include the following extensions 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. **Note: Default options are defined by printer SDK and platform and may vary between different devices.

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 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, iOS, Android
      • additionalStringOption : STRING Optional

        Any additional info; currently unused.

    • 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.

      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)
        getAllProperties
        (CallBackHandler callback)

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

        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.

        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)

        Returns printer instance specified by printerId. Returns null is no printers contains the ID. To get valid printerId, use searchPrinters function.

        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.

        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.

        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 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 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 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 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. **Note: This method will not print ZPL commands from Windows Mobile/CE 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 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.

              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.

                Parameters

                • formatPathOnPrinter : STRING

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

                • vars : HASH

                  A Hash containing 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 Strings, i.e. ‘1’:‘field1’ etc. Only ZPL format is supported; CPCL format is not supported.

                • 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 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 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

                      Currently unused.

                  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.

                  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.

                  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)

                  Searches for printers connected to the device via Bluetooth®, 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 Mandatory

                  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**.

                  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.

                  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.

                    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.

                    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.

                    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
                    ()

                    Immediately stops all active search requests and cancels pending search requests. Does not return a result.

                    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 that 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.

                    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

                      ID
                      : STRING Read Only

                      Unique printer ID during application lifetime.

                      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

                      Type of connection to printer.

                      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

                      IP address for Wi-Fi connection, Bluetooth® MAC address or device serial number. Note: iOS uses device serial number instead of MAC address. If you need to get device MAC you can use CPCL command ! U1 getvar “bluetooth.address”

                      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

                      Bluetooth/Network name of printer.

                      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

                      Default port when connecting with TCP/IP.

                      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

                      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. If you want 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.

                      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

                      Type of printer – see PRINTER_TYPE_… constants.

                      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 multi-cast 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 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.

                      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. We don’t have any API to identify whether it is zebra or non zebra printer, so we are checking as per the friendly name of the device, If friendly name contains “zebra” then we confirm printer type as PRINTER_TYPE_ZEBRA.

                      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);
                              }
                          }
                      );
                      
                                                  
                      @printers = []
                      
                      Rho::Printer.searchPrinters({ connectionType  => Rho::Printer::CONNECTION_TYPE_BLUETOOTH,
                                                    printerType     => Rho::Printer::PRINTER_TYPE_ZEBRA },
                                                    url_for(:action => :printer_callback) )
                      
                      def find_printer_callback
                        if @params['status'] == 'PRINTER_STATUS_SUCCESS'
                          if defined? @params['printerID']
                            puts "Found: #{@params['printerID']}"
                            @printers.push @params['printerID']
                          else
                            puts "Done Searching"
                          end
                        else
                          puts @params['status']
                        end
                      end
                      
                                                  

                      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).

                      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);
                      });
                      
                                                  
                      @my_printer = Rho::Printer.getPrinterByID printers[0]
                      
                      # Let's try connecting
                      @my_printer.connect url_for(:action => :printer_connect_callback)
                      
                      def printer_connect_callback
                        puts @params.to_s
                      
                        # This will be the Zebra's `Friendly Name`
                        # by default it is the serial number
                        puts @my_printer['deviceName']
                      
                        # This will be the BT MAC Address
                        # since we are connecting via BlueTooth
                        puts @my_printer['deviceAddress']
                      end
                      
                                                  

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

                      // 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 real-time 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);
                      
                          });
                                         
                                                  
                      # If my printer was in line mode I would see this text printed
                      @my_printer.printRawString 'This is a test print'
                      
                      # Example of sending a Zebra CPCL Command
                      # changing from linemode to ZPL mode
                      @my_printer.printRawString '! U1 setvar "device.languages" "ZPL"\r\n'
                      
                      # Get state - this is real-time status of printer.
                      # reading a property of the @my_printer instance will
                      # show last known status
                      @my_printer.requestState([Rho::Printer::PRINTER_STATE_IS_READY_TO_PRINT,
                                                Rho::Printer::PRINTER_STATE_IS_PAPER_OUT],
                                                url_for(:action => :request_state_callback));
                      
                      def request_state_callback
                        puts @params['status']
                        puts @params['PRINTER_STATE_IS_PAPER_OUT']
                        puts @params['PRINTER_STATE_IS_READY_TO_PRINT']
                      end
                      
                                                  

                      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
                      • To use a Bluetooth connection on Android devices you should take into account the following preconditions: Before using the printer you should pair it using the Android system Bluetooth settings.
                      • 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.
                      • When you call searchPrinters() with USB search (with CONNECTION_TYPE_ANY or CONNECTION_TYPE_USB) then you should configure your device USB controller as “USB Host mode” and should reboot device after the configuration. USB connection is not supported on the Zebra QLn320 printer. The searchPrinters method should not return any non-printer devices. If USB printers are not supported by the SDK or device, the searchPrinters function should return PRINTER_STATUS_ERR_UNSUPPORTED. For example, executing searchPrinters on an Android device with connectionType set to CONNECTION_TYPE_USB should return PRINTER_STATUS_ERR_UNSUPPORTED.
                      Windows Mobile/CE Notes
                      • You must set your app_type as “rhoelements” in your build.yml as shown the build-time settings guide.

                      • 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.

                      Supported Zebra Printers

                      Only printers listed in supported models in Zebra SDK description (click “Compatible Printers” link) are supported for use with this API. For example, the QL 320 (old model) is not supported but, QLn320 and QL320 plus are supported.