Notification Meta Tag

PocketBrowser 3.x API

The Notification Meta Tag is an action tag used to control the notification objects such as the LEDs, beeper and pager on the device. While some devices are equipped more than one of a given object type, most have multiple LEDs, a single beeper and a single pager.

To control notification objects, it is first necessary to query the device to discover which objects are available. This is done using the Enumerate method and EnumNotificationsEvent, which returns a unique identifier for each available notification to be used to set the notification state. Notifications can be set as "on," "off" or "cycling." with the behaviour of 'on' or 'off' notification objects self explanatory; when set to cyclic LEDs will flash for the specified number of times whereas the beeper and pager will only activate once for the specified duration.

Notification (META Tag) Syntax 
<META HTTP-Equiv="Notification" content="[method / parameter>
 
<META HTTP-Equiv="Notification" content="EnumNotificationsEvent:url('[jsFunction | url]')">

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

Name Description
Default Value
Enumerate Immediately triggers an EnumNotificationsEvent containing the notification objects available on the current device N/A
Copy methods template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

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

Name Possible Values Description
Default Value
SetLEDOnDuration:[Value] Milliseconds Subsequent calls to cycle LED notifications will cause them to remain on for the specified number of milliseconds per cycle. This parameter has no effect if the LED State is set to 'On' or 'Off' 1000
SetLEDOffDuration:[Value] Milliseconds Subsequent calls to cycle LED notifications will cause them to remain off for the specified number of milliseconds per cycle. This parameter has no effect if the LED State is set to 'On' or 'Off' 1000
SetLEDNumberOfCycles:[Value] Positive Number Subsequent calls to cycle LED notifications will cause them to switch between on and off the specified number of times. 1
SetBeeperFrequency:[Value] Frequency in Hertz When the beeper next sounds it will do so at the specified number of Hertz, provided this is supported by the hardware. This parameter has an effect for both StateOn and StateCycle. 2000
SetBeeperVolume:[Value] Number between 0 and 3 When the beeper next sounds it will do so at the specified volume. 0 represents minimum volume and 3 is maximum volume, the decibels each volume level represents is device dependant 0
SetBeeperDuration:[Value] Milliseconds When the beeper is next instructed to cycle it will sound for the specified number of milliseconds 1000
SetVibrateDuration:[Value] Milliseconds When the pager is next instructed to cycle it will vibrate the device for the specified number of milliseconds 1000
StateOn:[Value] The index of the notification, obtained via the EnumNotificationsEvent Turns the specified notification object on. This will either light an LED, sound the beeper or vibrate the device depending on the type of the notification Device Specific
StateOff:[Value] The index of the notification, obtained via the EnumNotificationsEvent Turns the specified notification object off. This will either extinguish an LED, silence the beeper or stop the device from vibrating Device Specific
StateCycle:[Value] The index of the notification, obtained via the EnumNotificationsEvent Cycles the specified notification object. LEDs will alternate between on and off for the specified number of cycles. The beeper and pager will be invoked once for the specified number of milliseconds. Device Specific
Copy parameters template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

Modules return information back to their web pages via retrieval tags, for example the scanner has a retrieval tag called 'DecodeEvent' which is called whenever it decodes a barcode. To register to receive a retrieval tag call the module as follows: 

<META HTTP-Equiv="[Module]" content="[RetrievalTag]:url('[URI]')">
So to register to retrieve the Scanner's DecodeEvent the following syntax would be used: 
<META HTTP-Equiv="Scanner" content="DecodeEvent:url('Javascript:doScan('%6', '%s', %3, '%2');')">

Retrieval tags return information by replacing the text in place holders, defined as '%s' or '%<number>'. Each place holder represents 1 return value with '%s' being populated sequentially or '%<number>' providing direct acces to the desired value.

If the content for the Scanner's DecodeEvent is:

"url('Javascript:doScan('%6', '%s', %3, '%2');')"

The function would be called as follows:
"Javascript:doScan('Decode', '5449000053879', 0x35, 'SCN:EAN13');"


EnumNotificationsEvent
The EnumNotificationsEvent is triggered in response to calling the 'Enumerate' method and is used to obtain the notifications available on the device and their associated identifiers. There is a single return value for this event which is a two dimensional array, with one dimension listing the available notifications and the other dimension listing the attributes for each notification object

ID Name Description
1 Notifications Array 2 Dimensional array of notifications, see remarks
Copy this return value template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript



The following example stores the available notifications in a javascript array and displays them to the user in an HTML table. Note that a 2 dimensional array is returned in the EnumNotificationsEvent.

<HTML>
<HEAD>
<META HTTP-Equiv="Notification" content="EnumNotificationsEvent:url('javascript:setupNtfyArr(%s)');">
</HEAD>
<script>
var ntfyArr = new Array();
var notType = new Array('LED', 'BEEPER', 'PAGER');
var NTFY_INDEX = 0;
var NTFY_TYPE = 1;
var NTFY_NAME = 2;

function setupNtfyArr(notArr)
{
ntfyArr = notArr;
var html = "";

for(i=0; i<ntfyArr.length; i++)    
{
html += '' + ntfyArr[i][NTFY_INDEX] + ', ' 
+ notType[ntfyArr[i][NTFY_TYPE]] + '' 
+ ntfyArr[i][NTFY_NAME] + '';
}

html += "";
htmDiv.innerHTML = html;
}

function onListNotifications()
{
var Generic = new ActiveXObject("PocketBrowser.Generic");
Generic.InvokeMetaFunction("Notification", "Enumerate");
}
</script>
<BODY>
<div id="htmDiv">
<INPUT TYPE="button" VALUE="List Notification Objects" ONCLICK="onListNotifications();">
</div>
</BODY>
</HTML>
Copy example to clipboard Copy example to clipboard

The following function takes a notification index and a notification type. Depending on the type of notification it invokes it appropriately. The index and type of each notification can be obtained via the EnumNotificationsEvent as demonstrated in the previous example

<script>
var Generic = new ActiveXObject("PocketBrowser.Generic");
function annoyUser(index, type)
{
if (type == 0)
{
//  If the Type of Notification is an LED flash it 10 times, on for 1 second off for 1 second.
Generic.InvokeMetaFunction("Notification", "SetLEDOnDuration:1000");
Generic.InvokeMetaFunction("Notification", "SetLEDOffDuration:1000");
Generic.InvokeMetaFunction("Notification", "SetLEDNumberOfCycles:10");
//  Flash the LED
Generic.InvokeMetaFunction("Notification", "StateCycle:" + index);
}
else if (type == 1)
{
//  If the Type of the Notification is a Beeper emit a continuous high pitch tone at maximum volume
Generic.InvokeMetaFunction("Notification", "SetBeeperFrequency:8000");
Generic.InvokeMetaFunction("Notification", "SetBeeperVolume:3");
//  Start the Beeper
Generic.InvokeMetaFunction("Notification", "SetOn:" + index);
}
else if (type == 2)
{
//  If the type of the notification is a Pager then vibrate the device for 15 seconds
Generic.InvokeMetaFunction("Notification", "SetVibrateDuration");
Generic.InvokeMetaFunction("Notification", "StateCycle:" + index);
}
}
</script>
Copy example to clipboard Copy example to clipboard
No Notification Objects
If the device has no notification objects the array returned by EnumNotificationsEvent will be empty


Notification State


If PocketBrowser is exited after applying notifications, the settings will not revert.




EnumNotificationsEvent Array Format


Thre is a single return value for this event which is a two dimensional array with the format below:


(
(                      //  Array for Notification 1
NotificationIndex,  //  Unique Identifier for each notification.
NotificationType,   //  Type of the notification.  '0' Indicates an LED; '1' indicates a Beeper and '2' indicates a pager
NotificationName    //  Human readable name of the notification, e.g. "Green LED"
)
(                      //  Array for Notification 2
NotificationIndex,
NotificationType,
NotificationName
)
)



Behavior of Notification Objects


In some cases, notification object may either not be turned ON or may not be turned ON for infinite time as the notification behavior depends on the underlying hardware.




LED Notification Object


On some devices, the LED objects activated through the Notification API are not supported, despite being enumerated through the enumerate() function call.














Supported Platforms
Windows CE, Windows Mobile




Persistence
This tag is persistent except for the EnumNotificationsEvent which is page specific.




Min. Requirements
None