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>