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
• Methods
• Parameters
• Events
• Multi Instance
• Remarks
• Requirements
• HTML/JavaScript Examples

Syntax

Methods

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

Parameters

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

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

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.

imagerEnumEvent

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

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>