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

Imager Module

The Imager Module controls the imager functions and navigates to a URL or calls a JavaScript function in response to an HTTP image transfer carried out by the imager meta tag.

Syntax

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)';

For more details on the event syntax and parameters see the Retrieval Events page.
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");
Imager Ruby Object Syntax:
By default the Ruby Object 'Imager' will exist on the current page and can be used to interact directly with the Imager. All Methods, Parameters and Events are the same as JavaScript, however, notice 'Imager' needs to start with an uppercase letter. Another difference in Ruby is that methods do not end in '()'
To Invoke Imager methods via Ruby use the following syntax: Imager.method()

e.g. Imager.enable
To Set Imager parameters via Ruby 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 Ruby use the following syntax: Imager.event = url_for(:action => :event_callback)

e.g. Imager.imagerEvent = url_for(:action => :imager_event_callback)

For more details on the event syntax and parameters see the Retrieval Events page.

To access the event parameters in a Ruby callback function, you reference the @params object within the callback function. This object is simply a ruby hash {"parameter1 name" => "parameter1 value", "parameter2 name" => "parameter2 value", ...}

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

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.motorolasolutions.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>  
Back to Top