Network Module

The Network Module is used to determine whether the device is able to connect to a specified server URL or IP address.

• Syntax
• Methods
• Parameters
• Events
• Remarks
• Requirements
• HTML/Javascript Examples
• Ruby 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.

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

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.

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

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>

Ruby Examples

The following example tests the network with the default values. It attaches the network event to a listener and starts polling for an internet connection. If the connection is successful or when the connection times out, the ‘networkEventListener’ function is called with the appropriate result:

def connect
    Network.networkEvent = url_for(:action => :networkEventListener)
    Network.start
end

To call the this function from HTML, use the following code:

<li onclick="testConnection(); ">Test connection on default port</li>

Where ‘testConnection()’ is a JavaScript function which looks like:

function testConnection() {
     $.get('/app/NetworkModule/connect', { });
     return false;
}

The ‘networkEventListener’ looks like the following:

def networkEventListener
    networkInfo = @params['connectionInformation']
    WebView.execute_js("setFieldValue('"+networkInfo+"'); ")
end

The following example tests network connection via a proxy. It attaches an event listener for network events, sets up a proxy host and a proxy port and starts polling. It can be called from HTML in a fashion similar to the one described above. Note that the ‘networkEventListener’ callback function is the same as described above.

def connectToProxy
    Network.networkEvent = url_for(:action => :networkEventListener)
    Network.host = 'exampleproxy.com'
    Network.port = 1050
    Network.start
end

The following example connects to the internet using Wide Area Network (WAN). It attaches a listener for the WAN status event and the network event, sets the polling interval and connection timeout, sets the host address to connect to and sets the connection mechanism for RhoElements. Using ‘Internet’ in the destination parameter connects RhoElements via the default internet connection. Specifying a destination enables RhoElements to connect via a specific connection. For more information on this, please refer to the Parameters section at the top of this page.

def connectWan  
    destination = @params['destination]
    Network.wanStatusEvent = url_for(:action => :wanStatusEventListner)
    Network.networkEvent = url_for(:action => :networkEventListener)
    Network.networkPollInterval = 5000
    Network.connectionTimeout = 1500
    Network.host = 'www.motorola.com'  
    Network.connectWan = destination
end

This function can be called from HTML using any of the following ways:

<li onclick="connectToDestination('Internet'); ">Connect WAN (default connection)</li> 
<li onclick="connectToDestination('myConnection'); ">Connect WAN (specified connection)</li>

The ‘connectToDestination’ is a JavaScript function that looks like:

function connectToDestination(destination) {
    $.get('/app/NetworkModule/connectWan', {destination: destination });
    return false;
}

The ‘wanStatusEventListener’ looks like the following:

def wanStatusEventListner
    buf = 'Signal strength: '
    buf += @params['phoneSignalStrength']
    buf += '<BR> Cell Operator: '
    buf += @params['networkOperator']
    buf += '<BR> Cell Connection available: '
    buf += @params['connectionTypeAvailable']
    buf += '<BR> Connection connected? '
    buf += @params['connectionTypeConnected']
    buf += '<BR> Connection Manager message: '
    buf += @params['connectionManagerMessage']  
    WebView.execute_js("setOutput('"+buf+"'); ")
end

The following example disconnects the current WAN connection:

def disconnect
    Network.disconnectWan
    WebView.execute_js("setFieldValue('Test results go here ...'); ")
end