Overview
The Network Module is used to determine whether the device is able to connect to a specified server URL or IP address.
Syntax
| network (Module) <META> Syntax |
|---|
<META HTTP-Equiv="Network" content="[method / parameter]"> |
<META HTTP-Equiv="Network" content="NetworkEvent:url('[jsFunction | url]')"> |
| Network JavaScript Object Syntax: |
|---|
| By default the JavaScript Object 'network' will exist on the current page and can be used to interact directly with the network. |
|
To Invoke network methods via JavaScript use the following syntax: network.method();
e.g. network.start(); |
|
To Set network parameters via JavaScript use the following syntax: network.parameter = 'value'; remembering to enclose your value in quotes where appropriate.
e.g. network.host = 'value'; |
|
To Set network return events via JavaScript use the following syntax: network.event = Javascript Function;
e.g. network.networkEvent = '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: network.setEMML("[Your EMML Tags]");
e.g. network.setEMML("host:value;networkEvent:url('JavaScript:doFunction(%json)');start"); |
Methods
Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.
| Name | Description | Default Value |
|---|---|---|
| start | Begins polling the specified host on the specified URL to check if there is a network connection available. The connection status is reported back via the NetworkEvent. | Not Started |
| stop | Stops polling for a network connection | Not Started |
| disconnectWan | Disconnects the current WAN connection. DisconnectWan will only affect connections established by RhoElements so if you have not previously called connectWan this function will have no effect. | Not Started |
Parameters
Items listed in this section indicate parameters, or attributes which can be set.
| Name | Possible Values | Description | Default Value |
|---|---|---|---|
| host:[Value] | URL or IP address | The URL or IP address of the server to attempt to connect to | www.motorola.com |
| port:[Value] | Any valid port | The port on the host on which to connect to | 80 |
| networkPollInterval:[Value] | Milliseconds | The time, in milliseconds, between each check for a connection. Note that the actual connection report interval will be the sum of the NetworkPollInterval and the ConnectionTimeout. | 5000 |
| connectionTimeout:[Value] | Milliseconds | The amount of time the network plugin will attempt to connect to the specified URL before it gives up and assumes 'disconnected' | 1000 |
| connectWan:[Value] | Connection Destination | Connects RhoElements through a Wide Area Network. The connection destination must be first configured through the Connection Manager and the destination name provided as the value to this parameter. If a connection is already established, you must first call disconnectWan before attempting another connection. A list of available connection destinations is written to the log file when either connectWan, disconnectWan or wanStatusEvent are first specified. Specify the connection as 'Internet' to use the default internet connection defined on the device. If the specified destination does not exist no connection attempt will be made and an entry will be made in the log file. | Not Specified |
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.
networkEvent
The network events notifies the user when a connection to the specified URL is gained or lost. A connection check is performed every [NetworkPollInterval] milliseconds but the user is only informed of a change of connection
| ID | Name | Description |
|---|---|---|
| 1 | connectionInformation | Either "Connected" or "Disconnected" |
wanStatusEvent
The WAN Status Event notifies the user whenever any parameter associated with data connectivity changes. The WAN Status Event is called when it is first declared (for the initial state) and again whenever any of the associated parameters change.
| ID | Name | Description |
|---|---|---|
| 1 | phoneSignalStrength | The signal strength of the phone as a percentage of maximum strength. Returned as a number between 0 and 100. If there is no phone service this field will be 0. |
| 2 | networkOperator | The name of the current network operator associated with the SIM card |
| 3 | connectionTypeAvailable | The current data connection type available to RhoElements as provided by the Network. Values can be 'Unavailable', GPRS, 1XRTT, EVDO, EDGE, UMTS, EVDV or HSDPA |
| 4 | connectionTypeConnected | The data connection type to which Rhoelements is currently connected. The values returned are identical to connectionTypeAvailable, with the exception that 'Not Connected' replaces 'Unavailable'. |
| 5 | connectionManagerMessage | This is the last received status from the Connection Manager. Do NOT use this parameter to determine if you are able to physically send / receive data to a remote host, it only provides an indication of whether the Connection Manager believes the connection is available. To determine if you are connected to a remote host use the networkEvent. |
Remarks
Connecting through Proxies
Because the network module is protocol agnostic, it will not communicate through HTTP proxies to reach a specified URL. In order to determine if you are connected when sitting behind a proxy you should configure the network plugin to attempt to connect to your proxy on the appropriate port. A successful connection to the proxy should be taken to assume the device is connected to a network. When configuring your WAN connection bear in mind that the proxy settings defined in the RhoElements configuration file will take precedence.
Maintaining an 'always on' WAN connection
To instruct RhoElements to connect to a Wide Area Network automatically define a default meta tag with the required connection information, e.g. <DefaultMetaTags><MetaTag VALUE="Network~ConnectWAN:MyConnection"/></DefaultMetaTags>. See the Configuration Settings page for more information.
NetworkEvent over WAN
When defining a network event which will take place over WAN bear in mind if you specify a very low networkPollInterval your device will frequently have an active data connection. 'NetworkPollInterval's sufficiently low (in the region of 1000) can prevent the device from accepting incoming phone calls.
Preventing access to the device
Receiving phone calls or texts whilst running RhoElements will cause the start button to be displayed on Windows Embedded Handheld devices, potentially offering users access to the operating system. It is recommended to set the following registry keys to disable Operating System access on Windows Embedded Handheld as required. The registry keys will be applied after a warm boot, omit them entirely to restore the Start and 'X' icons.
[HKEY_LOCAL_MACHINE\Software\Microsoft\Shell\BubbleTiles] Location in Registry
"HardwareStartKeyEnabled"=dword:00000001 Prevents the Start icon from appearing in the bottom left
"HardwareDoneKeyEnabled"=dword:00000001 Prevents the 'X' icon from appearing in the bottom right
Platform differences
On Android connectWan can be treated as a method with no parameters as its only effect is enabling mobile data from the device general settings; any parameter passed to connectWan is ignored. Likewise, disconnectWan disables mobile data from the general settings, therefore executing disconnectWan on Android is not restricted to the scope of a RhoElements application, but may affect the connectivity of any other running application using mobile data.
Requirements
| RhoElements Version | 1.0.0 or above |
|---|---|
| Supported Devices | All supported devices. WAN Connectivity is only available on devices which support data connections through the Windows Connection Manager. |
| Minimum Requirements | None. |
| Persistence | Partially Persistent - Changes to this module will persist when navigating to a new page with the exception of the NetworkEvent and WANStatusEvent which only apply to the current page. |
HTML/Javascript Examples
The following example checks for a connection to motorola.com on the default port and notifies the user when connection is gained / lost:
<meta http-equiv="Network" content="Host:url('http://www.motorola.com')">
<meta http-equiv="Network" content="networkEvent:url('Javascript:onNetworkEvent(%json);');Start">
<SCRIPT>
function onNetworkEvent(jsonObject)
{
var html = "<b>Network Event Returned:</b> ";
html += jsonObject.connectionInformation;
networkOutput.innerHTML=html;
}
</SCRIPT>
<div id="networkOutput">Connection Information goes Here</div>
The following example checks for a connection to a proxy server and notifies the user when connection is gained / lost:
<BODY onload='onStartChecking()'>
<SCRIPT>
function onNetworkEvent(jsonObject)
{
var html = "<b>Network Event Returned:</b> ";
html += jsonObject.connectionInformation;
networkOutput.innerHTML=html;
}
function onStartChecking()
{
network.networkEvent = onNetworkEvent(%json);
network.host = 'wwwexampleproxy.com';
network.port = '1050';
network.start();
}
</SCRIPT>
<div id="networkOutput">Connection Information goes Here</div>
The following example shows how to establish and monitor a WAN connection
<HTML><HEAD>
<META HTTP-Equiv="Network" Content="WANStatusEvent:url('javascript:fnWANStatus(%json);')">
<meta http-equiv="Network" content="NetworkEvent:url('Javascript:onNetworkEvent(%json);')">
<meta http-equiv="Network" content="networkPollInterval:5000;connectionTimeout:1500">
<meta http-equiv="Network" content="Host:url('http://www.motorola.com')">
<script type="text/javascript">
var count = 0;
function onNetworkEvent(jsonObject)
{
count = count + 1;
var html = "<b>Network Event Returned:</b> ";
html += jsonObject.connectionInformation + " - " + count;
networkOutput.innerHTML=html;
}
function fnWANStatus(jsonObject)
{
var html = "Signal Strength: " + jsonObject.phoneSignalStrength + "%";
html += "<BR> Operator: " + jsonObject.networkOperator;
html += "<BR> Cell Connection Available: " + jsonObject.connectionTypeAvailable;
html += "<BR> Cell Connection Connected?: " + jsonObject.connectionTypeConnected;
html += "<BR> Connection Manager Message: " + jsonObject.connectionManagerMessage;
outputDiv.innerHTML = html;
}
function fnConnect(destination)
{
network.connectWan = "" + destination;
}
function fnDisconnect()
{
network.disconnectWan();
}
function fnStartNetworkCheck()
{
network.start();
}
function fnStopNetworkCheck()
{
network.stop();
networkOutput.innerHTML = "Not Polling Network";
}
</script>
</HEAD>
<H1>WAN Tests</H1>
<P><div id="networkOutput">Network Connection Information goes Here</div><br>
<b><div id="outputDiv">Network Check Started</div></b><P>
<input type="button" onclick="fnConnect('Internet')" Value="Connect (Default)" />
<input type="button" onclick="fnConnect('My Connection')" Value="Connect ('My Connection')" />
<input type="button" onclick="fnDisconnect()" Value="Disconnect" />
<input type="button" onclick="fnStartNetworkCheck()" Value="Start Network Checking" />
<input type="button" onclick="fnStopNetworkCheck()" Value="Stop Network Checking" />
</BODY></HTML>