Imager - Zebra Technologies TechDocs

Overview

The Imager API allows a device to capture images using a 2D imager or camera on the device that appears as an imager. This API is not supported on Micro Kiosk devices.

imager (Module) <META> Syntax
<META HTTP-Equiv="imager" content="[parameter]">
<META HTTP-Equiv="imager" content="ImagerEvent:url('jsFunction or url')">
<META HTTP-Equiv="imager" content="ImagerEnumEvent:url('jsFunction or url')">

Imager JavaScript Object Syntax:
By default the JavaScript Object 'imager' will exist on the current page and can be used to interact directly with the imager.
To Invoke imager methods via JavaScript use the following syntax: imager.method(); e.g. imager.enable();
To Set imager parameters via JavaScript use the following syntax: imager.parameter = 'value'; remembering to enclose your value in quotes where appropriate. e.g. imager.enabled = 'value';
To Set imager return events via JavaScript use the following syntax: imager.event = JavaScript Function; e.g. imager.imagerEvent = 'doFunction(%json)';
To set multiple EMML parameters / events on a single line use the following syntax: imager.setEMML("[Your EMML Tags]"); e.g. imager.setEMML("enabled:value;imagerEvent:url('JavaScript:doFunction(%json)');enable");

Methods

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Name	Description	Default Value
enable	enables the imager device and shows the viewer window	N/A
disable	disables the imager device and hides the viewer window	N/A
capture	captures the current image and sends the file to the specified destination address. If an imagerCaptureEvent is specified the image will also be returned as a Data URI object.	N/A
enumerate	Return a list of imagers available on the device using ImagerEnumEvent. This tag will be actioned immediately	N/A

Parameters

Items listed in this section indicate parameters, or attributes which can be set.

Name	Possible Values	Description	Default Value
enabled:[Value]	enables referenced Imager. Imager IDs can be obtained via ImagerEnumEvent	enables the referenced imager device and shows the viewer window	N/A
desiredWidth:[Value]	numeric Value	Sets the desired width of the output image, in pixels. Depending on the camera hardware in use the closest matching image size will be chosen; the width of the chosen image will equal or exceed the value specified up to the capabilities of the hardware. On Zebra devices the imaging hardware (that hardware shared by the imager scanner) can not have its output image width configured. This parameter is only available in version 2.2 and higher	Hardware Specific
desiredHeight:[Value]	numeric Value	Sets the desired height of the output image, in pixels. Depending on the camera hardware in use the closest matching image size will be chosen; the height of the chosen image will equal or exceed the value specified up to the capabilities of the hardware. On Zebra devices the imaging hardware (that hardware shared by the imager scanner) can not have its output image height configured. This parameter is only available in version 2.2 and higher	Hardware Specific
left:[Value]	numeric Value (0 - ScreenWidth)	Sets the top left horizontal position of the viewer window in pixels	Device Specific
top:[Value]	Numeric values (0 - ScreenHeight)	Sets the top left vertical position of the viewer window in pixels	Device Specific
width:[Value]	Numeric values (0 - ScreenWidth)	Sets the width of the viewer window in pixels	Device Specific
height:[Value]	Numeric values (0 - ScreenHeight)	Sets the height of the viewer window in pixels	Device Specific
lamp:[Value]	ON/OFF	switches the lamp ON or OFF	OFF
aim:[Value]	ON/OFF	switches the imager's aim ON or OFF. This is not available on Android.	OFF
username:[Value]	http or ftp server user name	username for the http or ftp server if required	N/A
password:[Value]	http or ftp server password	password for the http or ftp server if required	N/A
sound:[Value]	wav file name	specifies the wave file to play when capturing an image	N/A
destination:[Value]	http,ftp or file path	the path of the destination	N/A

Events

Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.

imagerEvent

ID	Name	Description
1	transferResult	In response to an upload to an HTTP site, the reply from the web server will be returned. There will be no response to an upload to an FTP site

imagerCaptureEvent

Specifying an ImagerCaptureEvent will cause the captured image to be returned as a Data URI object when the capture() method is invoked. A Data URI is a base 64 encoding of the image and can be used to easily embed the image on the page, store the image in a database or transfer the image to a server.

ID	Name	Description
1	imageData	A DataURI representation of the captured Image.

imagerEnumEvent

ID	Name	Description
1	imagerArray (deviceName, friendlyName)	Two dimensional array of imagers present on the device

Multi Instance

When multiple RhoElememts applications are running the following considerations should be made: Only the foreground RhoElements application is given access to the imaging hardware, when an application is sent to the background its state will be saved and it will automatically relinquish control of the imager. When brought back to the foreground, an application previously using the imager will have its previous configuration (eg. whether it was enabled or not) reapplied to the imager automatically. Please note that any file transfer that is in progress continues even if the application is sent to the background and capture will not have any effect on an application that is in the background.

Remarks

ImagerArray attribute

The ImagerArray attribute returned from ImagerEnumevent retrieval tag will enumerate each imager present on the device in a 2D array, associating each Imager's device name with a user friendly name. The device ID can be passed as a parameter to "Imager" "Enabled:<deviceID>", the friendly name is a user readable description of the Imager, e.g: "IMG1", "Imager" "IMG2", "color Camera".

Scanning and Image Capture Interaction

In some device configurations the scanner and imager share the same hardware, e.g. the blockbuster scanner and top mounted imager on the MC75a. Where two modules share the same physical hardware they cannot be enabled simultaneously, once the scanner is enabled it must be disabled before the imager can be used, and vice versa.

Setting up a Transfer to a remote HTTP or FTP location

The Imager module is designed to be configured before any transfer is made to a remote location. If the 'Destination' paramter is specified as either HTTP or an FTP location the 'destination' / 'username' / 'password' parameters can not be guaranteed to stay the same after capture() has been called, therefore configure your destination for each capture. The above examples will work for a single transfer.

Stretching the Image

The image can only be stretched as far as the screen dimensions will allow, do not expect to be able to create an image larger than the dimensions of your screen.

Creating a fully qualified URL

The protocol, port number, username (optional) and password (optional) are all derived from the URL string and should be specified in the following manner:

[protocol]://[username]:[password@]Server[:Port]FileNameAndPath.
FTP Example: ftp://admin:root@192.168.1.1:2500/Folder/file.txt
HTTP Example: http://admin:root@192.168.1.1:8080/Folder/upload.aspx

Remember to also wrap the URL with url('') when being used as part of a meta tag, as shown in the examples above.

imagerEnumEvent Array Format

The imagerArray parameter in the imagerEnumEvent is defined as a 2D array:


(
   (            //  Array for Imager 1
      deviceName,    //  The internal name given to the Imager, use this when enabling a specific imager.
      friendlyName,  //  A human readable description of the Imager.
   )
   (            //  Array for Imager 2
      deviceName,
      friendlyName,
   )
)

Platform differences

On Android the height of the viewfinder cannot be set to any value less than 200.

Zebra Windows Mobile/CE Device Support

The Imager API is not supported from Enterprise Browser apps on the following Zebra devices running Windows Mobile/CE:

Workabout Pro 4
Omnii XT15
VH10

Requirements

RhoElements Version	1.0.0 or above
Supported Devices	All supported devices except Kiosk units.
Minimum Requirements	The device must have an Imager device or Color Camera.
Persistence	Partially Persistent - Changes to this module will persist when navigating to a new page with the exception of the view finder: this will be hidden on page navigation.

HTML/JavaScript Examples

The following example sets up the imager to capture an image and transfer it to an ftp site:

    
    <meta http-equiv="Imager" content="width:100">
    <meta http-equiv="Imager" content="height:100">
    <meta http-equiv="Imager" content="left:120">
    <meta http-equiv="Imager" content="Destination:url('software.uk.zebra.com')">
    <meta http-equiv="Imager" content="username:elementstest">
    <meta http-equiv="Imager" content="password:elements30">
    <meta http-equiv="Imager" content="sound:\windows\alarm2.wav">
    <meta http-equiv="Imager" content="aim:on">
    <meta http-equiv="Imager" content="lamp:off">
    <meta http-equiv="Imager" content="FTP">
    <meta http-equiv="Imager" content="imagerevent:url('javascript:alert('%s');')">
    <meta http-equiv="Imager" content="enabled">
    <meta http-equiv="onkey0x0d" content="KeyEvent:url('javascript:doCapture(0);')">

    <SCRIPT>
       function doCapture()
       {
          imager.capture();
       }
    </SCRIPT>

The following example sets up the imager to capture an image when the JavaScript function 'doCapture' is called:

    
    <meta HTTP-Equiv="Imager" Content="enabled;left:30;top:50;width:160;height:100;aim:off;lamp:off">
    <meta HTTP-Equiv="Imager" Content="destination:url('http://ds-laptop/PHTest/Received/HTTP/Upload.aspx')">
    <meta http-equiv="Imager" content="sound:\windows\alarm2.wav">
    <meta http-equiv="Imager" content="imagerevent:url('javascript:alert('%s');')">

    <script>
       function doCapture()
       {
          imager.capture();
       }
    </script>

The following ASP.NET example receives a file from the imager and saves it in a new filename:

    
    <%@ Import namespace="System.Web.UI.HtmlControls" %>
    <%@ Import namespace="System.IO" %>

    <script runat="server" language="C#">
       //called when the file is submitted  
       protected void Page_Load(object o, EventArgs e) 
       {
          //check we have submitted a file
          if( elementsImagerFile.PostedFile != null )
          {
             // Get a reference to PostedFile object
             HttpPostedFile myFile = elementsImagerFile.PostedFile;

             // Get size of uploaded file
             int nFileLen = myFile.ContentLength; 

             // make sure the size of the file is > 0
             if(nFileLen > 0 )
             {
                //Allocate a buffer for reading of the file
                byte[] myData = new byte[nFileLen];

                // Read uploaded file from the Stream
                myFile.InputStream.Read(myData, 0, nFileLen);

                // Create a name for the file to store
                string strFilename = Path.GetFileName(myFile.FileName);

                // Write data into a file
                WriteToFile(Server.MapPath(strFilename), ref myData);

                // Write a response back to sender
                Response.Write("File Received");
             }
          }
       }

       // Writes file to current folder
       private void WriteToFile(string strPath, ref byte[] Buffer)
       {
          // Create a file
          FileStream newFile = new FileStream(strPath, FileMode.Create);

          // Write data to the file
          newFile.Write(Buffer, 0, Buffer.Length);

          // Close file
          newFile.Close();
       }
    </script>

    <form name="elementsImagerForm" method="post" action="upload.aspx" id="elementsImagerForm" enctype="multipart/form-data">
       <input id="elementsImagerFile" type="file" runat="server" Visible="false">
    </form>

The following is a useful desktop html file for testing the example above:


<form name="elementsImagerForm" method="post" action="upload.aspx" id="elementsImagerForm" enctype="multipart/form-data">
   <input name="elementsImagerFile" id="elementsImagerFile" type="file" />
   <input type="submit" value="submit">
</form>

The following example displays the available imagers on screen:

    
    <html>
    <head>
    <meta HTTP-Equiv="imager" Content="imagerEnumEvent:url('JavaScript:Enumimagers(%s);')">
    <meta HTTP-Equiv="quitbutton" Content="left:200;top:0;visibility:visible">
    </head>

    <body BGCOLOR="#FFFFEA" TEXT="#0000A0" LINK="#FF0000" VLINK="#808080" ALINK="#008040" onLoad="setImagerEnumTimer();">
    <a HREF="./Index.html">Back</a><br>
    <div ID="message"></div>
    </body>
    </html>

    <SCRIPT LANGUAGE="JavaScript">

    function Enumimagers(imagerArray)
    {
        var imagerInfo = "Imagers On Device: " + imagerArray.length + "<BR>ID  --  Name<BR>" 

        for (i=0; i < imagerArray.length; i++)
        {
            imagerInfo = imagerInfo + imagerArray[i][0] + ' -- ' + imagerArray[i][1] + '<BR>';
        }
        message.innerHTML = imagerInfo;
    }

    //  We can not call Scanner:Enumerate during page load on WM so give the page 3 seconds to finish loading
    function setImagerEnumTimer()
    {
        message.innerHTML = "getting data...";
        setTimeout("onImagerEnable()", 3000);
    }
    function onImagerEnable()
    {
        imager.enumerate();
    }
    </SCRIPT>

The following example shows image being captured as a Data URI and displayed on the page:

    
    <META HTTP-Equiv="Imager" Content="imagerCaptureEvent:url('JavaScript:onImageCapture(%json)');">

    <script type="text/javascript">
    function onImageCapture(jsonObject)
    {
        imagerImage.src = jsonObject.imageData;
    }
    </script>

    </HEAD>
      <BODY>
      <BR><BR><BR><BR>
      <img src="" id="imagerImage"<>/img>
    </BODY>