The Push Module is used to receive data over an HTTP connection.
| push (Module) <META> Syntax |
|---|
<META HTTP-Equiv="Push" content="[Parameter]"> |
<META HTTP-Equiv="Push" content="[Parameter:Attribute]"> |
<META HTTP-Equiv="Push" contents="detected:url('[jsFunction | url]')"> |
| Push JavaScript Object Syntax: |
|---|
| By default the JavaScript Object 'push' will exist on the current page and can be used to interact directly with the push. |
| To Invoke push methods via JavaScript use the following syntax: push.method(); e.g. push.start(); |
| To Set push parameters via JavaScript use the following syntax: push.parameter = 'value'; remembering to enclose your value in quotes where appropriate. e.g. push.port = 'value'; |
| To Set push return events via JavaScript use the following syntax: push.event = JavaScript Function; e.g. push.detected = '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: push.setEMML("[Your EMML Tags]"); e.g. push.setEMML("port:value;detected:url('JavaScript:doFunction(%json)');start"); |
| Push Ruby Object Syntax: |
|---|
| By default the Ruby Object 'Push' will exist on the current page and can be used to interact directly with the Push. All Methods, Parameters and Events are the same as JavaScript, however, notice 'Push' needs to start with an uppercase letter. Another difference in Ruby is that methods do not end in '()' |
| To Invoke Push methods via Ruby use the following syntax: Push.method() e.g. Push.start |
| To Set Push parameters via Ruby use the following syntax: Push.parameter = 'value' remembering to enclose your value in quotes where appropriate. e.g. Push.port = 'value' |
|
To Set Push return events via Ruby use the following syntax: Push.event = url_for(:action => :event_callback)
e.g. Push.detected = url_for(:action => :push_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", ...} |
Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.
| Name | Description | Default Value |
|---|---|---|
| start | Starts the server. Must be after the <port> tag. | N/A |
| stop | Stops the server. | N/A |
Items listed in this section indicate parameters, or attributes which can be set.
| Name | Possible Values | Description | Default Value |
|---|---|---|---|
| port:[Value] | 0 - 65535 in Windows and 1025 - 65535 in Android | Port number to listen on. | 8081 |
| passKey:[Value] | Any string | If specified then the client must include passkey=value in the passed parameters. Case sensitive. | Empty (no passkey required) |
| response:[Value] | Filename | Name of the HTML file to return to the client after a successful request. | Empty (a short default HTML response is sent) |
| path:[Value] | Virtual path | The client must include this in the HTTP request (after the address and before the parameters). The forward slash '/' should be used as the directory delimiter. | Empty (any path is accepted) |
| unattended:[Value] | enabled or disabled | Enables or disables unattended mode - see Remarks for details. | disabled |
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.
| ID | Name | Description |
|---|---|---|
| 1 | Whatever is defined as 'name' in each name=value pair in the HTTP request. | One value is returned for each name=value pair in the HTTP request, you access this in JSON using the names you provided in the request. An example is provided in the examples section below. |
The push server accepts both GET and POST requests. For GET requests the parameters and values are specified in the URL, while for POST requests the request body should hold the parameters and values in url encoded form. The virtual path in the URL must be as specified by the <path> tag, or can be anything if the tag isn’t present. The parameters must include ‘passkey’ with the correct value if the <passkey> tag is present.
When a valid request is received the specified destination URL is called with one ‘%s’ per parameter/value pair in the request. Only the values are returned; the parameter names are discarded. The ‘passkey’ parameter and value are ignored if present. Parameter names are only applicable if you are accessing your return values via JSON.
Only alphanumeric characters and the characters $-_.!*‘(), are allowed in a URL (see RFC 1738). Any other characters will cause undefined behaviour. Ensure that the passkey uses only valid characters.
Normally when a device enters suspend mode, either because it has been idle for a certain time or because the power key was pressed, all the device subsystems are switched off, including the wireless network. When unattended mode is enabled however the device keeps enough subsystems powered that applications continue to run, and it can still respond to Push requests. Note that unattended mode uses significantly more battery power.
In version 2.2 of RhoElements for WM / CE the default push port was changed from ‘80’ to ‘8081’ to match RhoElements for Android. Applications developed for RhoElements 2.1 and previous which rely on the default port number being 80 should add the default meta tag <MetaTag VALUE=“Push~port:80”> to their configuration.
| RhoElements Version | 1.0.0 or above |
|---|---|
| Supported Devices | All supported devices |
| Minimum Requirements | None. |
| Persistence | Persistent - Changes to this module will persist when navigating to a new page. |
The code below configures the server to listen on port 8081, to accept only requests to the virtual path \push and to require a passkey of ‘secret’. Assuming the device has IP address 1.2.3.4 then browsing to the following URL will cause the JavaScript function onPush() to be called with the parameters ‘hello’ and ‘world’: http://1.2.3.4:8081/push?name1=hello&name2=world&passkey=secret. The browser will receive the contents of the file \ok.html as response.
<META HTTP-Equiv="Push" Content="Port:8081">
<META HTTP-Equiv="Push" Content="Passkey:secret">
<META HTTP-Equiv="Push" Content="Path:/push">
<META HTTP-Equiv="Push" Content="Response:/ok.html">
<META HTTP-Equiv="Push-detected" Content="url('JavaScript:onPush('%s','%s');')">
<META HTTP-Equiv="Push" Content="Start">
The following code shows a very simple push server which just responds by executing a JavaScript function, but does show how to process the push request in JSON. Similarly to the previous example the following URL has been browsed to: http://1.2.3.4:8081/push?name1=hello&myname=world
<HEAD>
<META HTTP-Equiv="Push" Content="Port:1234">
<META HTTP-Equiv="Push-detected" Content="url('JavaScript:pushDetectJSON(%json);')">
<META HTTP-Equiv="Push" Content="Start">
<TITLE>Push Tests</TITLE>
<script type="text/javascript">
function pushDetectJSON(jsonObject)
{
// The following will show an Alert box with 'hello - world'
alert('Push Via JSON: ' + jsonObject.name1 + ' - ' + jsonObject.myname);
}
</script>
</HEAD>
To enable unattended mode:
<META HTTP-Equiv="push" Content="unattended:enable">