Network

Overview

This API class allows you to interact with either the WAN or WiFI network of the device.

Enabling the API

There are two methods of enabling the Network API:

• Include all ebapi modules
• Include only the required API modules

For either of these methods, you'll need to include files from the /Enterprise Browser/JavaScript Files/Enterprise Browser directory on the computer that you installed the Enterprise Browser.

Include all JS API modules

To include all JS APIs, copy the ebapi-modules.js file to a location accessible by the app's files and include a reference to the JavaScript file in the app's HTML. For instance, to include the modules file in the app's index.html, copy the file to the same directory as that index.html and add the following line to the HTML's HEAD section:

<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>

Note: that the pathing for this file is relative to the current page.

This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion.

Include only the required modules

To include single APIs, you must first include the ebapi.js in your HTML as well as the API file you want to use. For instance, to use the Network API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML.

<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.network.js"></script>

The ebapi.js file is necessary for all single API inclusions.

Methods

cancel()

Cancel the request identified by callback. If callback is not specified then all requests will be canceled.

Parameters

• callback : CallBackHandler

Returns

Synchronous Return:

• Void

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.cancel()

connectWan(STRING connectionDestination)

Connects the device to a Wide Area Network. The connection destination must be first configured through the Connection Manager (on the device) and the destination name provided to this method. 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 or disconnectWan 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.

Parameters

• connectionDestination : STRING

  The connection in the Windows Connection manager to use, specify 'Internet' to use the default internet connection.

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• phoneSignalStrength : STRING

  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.

• networkOperator : STRING

  The name of the current network operator associated with the SIM card.

• connectionTypeAvailable : STRING

  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.

• connectionTypeConnected : STRING

  The data connection type to which the device is currently connected. The values returned are identical to connectionTypeAvailable, with the exception that 'Not Connected' replaces 'Unavailable'.

• connectionManagerMessage : STRING

  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 detectConnection method.

Returns

Synchronous Return:

• Void

Platforms

• Windows Mobile

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.connectWan(STRING connectionDestination)

detectConnection(HASH propertyMap)

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 provided callback. Note that callback will be called only if connection status has changed compared to previous polling. Multiple concurrent detectionConnection is not supported.

Parameters

• propertyMap : HASH

  Properties map.

• host : STRING Default: www.zebra.com

  When detecting a network connection, this is the URL or IP address of the server to attempt to connect to.

• port : INTEGER Default: 80

  When detecting a network connection, this is the port on the host to connect to.

• pollInterval : INTEGER Default: 30000

  The time, in milliseconds, between each check for a connection. Note that the actual connection report interval will be the sum of the poll interval and the detection timeout. The minimum allowed value is 5000ms.

• detectionTimeout : INTEGER Default: 1000

  The amount of time to attempt to connect to the specified URL before giving up and assuming 'disconnected'. Value is specified in milliseconds.

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• connectionInformation : STRING

  Whether the device is connected to the specified host and port. Either 'Connected' or 'Disconnected'.

• failureMessage : STRING

  If the device is disconnected this field will contain information about why the connection failed.

Returns

Synchronous Return:

• Void

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.detectConnection(HASH propertyMap)

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.

Parameters

• callback : CallBackHandler

Returns

Synchronous Return:

• Void

Platforms

• Windows Mobile

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.disconnectWan()

downloadFile(HASH propertyMap)

Download a file to the specified filename. Note: if 'overwriteFile' flag is default or false, the HEAD request to the server will be performed before actual download to retrieve 'last-modified' header which is used to support resuming interrupted download. If targeted server doesn't support HEAD requests, 'overwriteFile' should be set to true.

Parameters

• propertyMap : HASH

  Properties to be used in this request.

• url : STRING

  URL of file to be downloaded. HTTP and HTTPS protocols are supported.

• filename : STRING

  The path and name of the file to be uploaded.

• overwriteFile : BOOLEAN Default: false

  OverWriteFile will overwrite the destination file if it already exists.

• createFolders : BOOLEAN Default: false

  CreateFolders can automatically create the directory path.

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• body : STRING

  The body of the HTTP response.

• headers : HASH

  A hash containing the response headers.

• cookies : STRING

  The server cookies, parsed and usable for subsequent requests.

• http_error : INTEGER

  HTTP error code if response code was not 200.

• fileExists : BOOLEAN

  When overwriteFile is false and file exists, when error return and this flag set to true.

Returns

Synchronous Return:

• HASH
  • body : STRING

    The body of the HTTP response.

  • headers : HASH

    A hash containing the response headers.

  • cookies : STRING

    The server cookies, parsed and usable for subsequent requests.

  • http_error : INTEGER

    HTTP error code if response code was not 200.

  • fileExists : BOOLEAN

    When overwriteFile is false and file exists, when error return and this flag set to true.

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.downloadFile(HASH propertyMap)

get(HASH propertyMap)

Perform a HTTP GET request.

Note: This method will perform a POST if you send a body with it. If performing a GET, do not add a body to the call.

Parameters

• propertyMap : HASH

  Properties map. Valid `properties` for this parameter are the properties available to this API module. Check the property section for applicable properties.

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• body : STRING

  The body of the HTTP response.

• headers : HASH

  A hash containing the response headers.

• cookies : STRING

  The server cookies, parsed and usable for subsequent requests.

• http_error : INTEGER

  HTTP error code if response code was not 200.

Returns

Synchronous Return:

• HASH
  • body : STRING

    The body of the HTTP response.

  • headers : HASH

    A hash containing the response headers.

  • cookies : STRING

    The server cookies, parsed and usable for subsequent requests.

  • http_error : INTEGER

    HTTP error code if response code was not 200.

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.get(HASH propertyMap)

hasCellNetwork()

Returns true if the device is connected to a cell network. Not supported on Windows CE.

Parameters

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: BOOLEAN

Returns

Synchronous Return:

• BOOLEAN

Platforms

• Android
• Windows Mobile

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.hasCellNetwork()

hasNetwork()

Returns true if the device is connected to a network. Not supported on Windows CE.

Parameters

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: BOOLEAN

Returns

Synchronous Return:

• BOOLEAN

Platforms

• Android
• Windows Mobile

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.hasNetwork()

hasWifiNetwork()

Returns true if the device is connected to a WiFi network. Not supported on Windows CE.

Parameters

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: BOOLEAN

Returns

Synchronous Return:

• BOOLEAN

Platforms

• Android
• Windows Mobile

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.hasWifiNetwork()

post(HASH propertyMap)

Perform a HTTP Post.

Parameters

• propertyMap : HASH

  The properties for the Network module can be used in this hash along with the following:

• body : STRING

  The message body of the HTTP request.

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• body : STRING

  The body of the HTTP response.

• headers : HASH

  A hash containing the response headers.

• cookies : STRING

  The server cookies, parsed and usable for subsequent requests.

• http_error : INTEGER

  HTTP error code if response code was not 200.

Returns

Synchronous Return:

• HASH
  • body : STRING

    The body of the HTTP response.

  • headers : HASH

    A hash containing the response headers.

  • cookies : STRING

    The server cookies, parsed and usable for subsequent requests.

  • http_error : INTEGER

    HTTP error code if response code was not 200.

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.post(HASH propertyMap)

startStatusNotify()

Start network status notifications. Notifications are sent when WiFi or Cell network appear / disappear. To check real Internet connectivity use detectConnection method. Not supported on Windows CE.

Parameters

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• current_status : STRING

  Current status of network connection. Can be "connected" or "disconnected".

• prev_status : STRING

  Previous status of network connection. Can be "connected", "disconnected" or "unknown"."

Returns

Synchronous Return:

• Void

Platforms

• Android
• Windows Mobile

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.startStatusNotify()

stopDetectingConnection()

Ceases network detection. Callback is no longer supported; it has been made optional to preserve backward compatibility.

Parameters

• callback : CallBackHandler

Returns

Synchronous Return:

• Void

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.stopDetectingConnection()

stopStatusNotify()

Stop network status notifications. Not supported on Windows CE.

Parameters

• callback : CallBackHandler

Returns

Synchronous Return:

• Void

Platforms

• Android
• Windows Mobile

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.stopStatusNotify()

uploadFile(HASH propertyMap)

Upload the specified file using HTTP POST.

Parameters

• propertyMap : HASH

  The properties for the Network module can be used in this hash along with the following:

• filename : STRING

  The path and name of the file to be uploaded.

• body : STRING

  The message body of the HTTP request.

• fileContentType : STRING

  Content-Type header for the file, defaults to "application/octet-stream".

• multipart : ARRAY

  Array of hashes containing file information.

• Object : HASH

  Multipart properties.

• filename : STRING

  The path and name of the file to be uploaded.

• contentType : STRING

  Content-Type header, defaults to "application/octet-stream".

• filenameBase : STRING

  Base directory containing the :filename.

• name : STRING

  File type, defaults to "blob".

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• body : STRING

  The body of the HTTP response.

• headers : HASH

  A hash containing the response headers.

• cookies : STRING

  The server cookies, parsed and usable for subsequent requests.

• http_error : INTEGER

  HTTP error code if response code was not 200.

Returns

Synchronous Return:

• HASH
  • body : STRING

    The body of the HTTP response.

  • headers : HASH

    A hash containing the response headers.

  • cookies : STRING

    The server cookies, parsed and usable for subsequent requests.

  • http_error : INTEGER

    HTTP error code if response code was not 200.

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Network.uploadFile(HASH propertyMap)

Properties

authPassword

Type

STRING

Description

Password for basic authentication. You must also specify `authType='basic'

Access

• Class: This property can only be accessed via the API class object.
  • EB.Network.authPassword

This property cannot be accessed via setter or getter methods. It can be used in methods that allow a HASH or Array of properties to be passed in.

Platforms

• Android
• Windows Mobile
• Windows CE

authType

Type

STRING

Description

Type of authentication used for this request. Check the list of available options below. Leaving blank will result in no authentication type.

Values

Possible Values (STRING):

• Constant: EB.Network.AUTH_BASIC - String: basic Basic Authentication Type. uses authUser and authPassword.

Access

• Class: This property can only be accessed via the API class object.
  • EB.Network.authType

This property cannot be accessed via setter or getter methods. It can be used in methods that allow a HASH or Array of properties to be passed in.

Platforms

• Android
• Windows Mobile
• Windows CE

authUser

Type

STRING

Description

User name for basic authentication. You must also specify authType='basic'

Access

• Class: This property can only be accessed via the API class object.
  • EB.Network.authUser

This property cannot be accessed via setter or getter methods. It can be used in methods that allow a HASH or Array of properties to be passed in.

Platforms

• Android
• Windows Mobile
• Windows CE

headers

Type

HASH

Description

List of HTTP headers to be used in the network request.

Access

• Class: This property can only be accessed via the API class object.
  • EB.Network.headers

This property cannot be accessed via setter or getter methods. It can be used in methods that allow a HASH or Array of properties to be passed in.

Platforms

• Android
• Windows Mobile
• Windows CE

httpVerb

Type

STRING

Description

Replaces:http_command HTTP verb to be used in the network request.

Access

• Class: This property can only be accessed via the API class object.
  • EB.Network.httpVerb

This property cannot be accessed via setter or getter methods. It can be used in methods that allow a HASH or Array of properties to be passed in.

Platforms

• Android
• Windows Mobile
• Windows CE

responseTimeout

Type

INTEGER

Description

Timeout of network requests in seconds. This property has module scope. Do not pass it as hash parameter to methods, use property accessors instead.

Params

Default: 30

Access

• Class: This property can only be accessed via the API class object.
  • EB.Network.responseTimeout

This property cannot be accessed via setter or getter methods. It can be used in methods that allow a HASH or Array of properties to be passed in.

Platforms

• Android
• Windows Mobile
• Windows CE

url

Type

STRING

Description

URL of the request. This should be fully formatted URL like http://domain.com/

Access

• Class: This property can only be accessed via the API class object.
  • EB.Network.url

This property cannot be accessed via setter or getter methods. It can be used in methods that allow a HASH or Array of properties to be passed in.

Platforms

• Android
• Windows Mobile
• Windows CE

verifyPeerCertificate

Type

BOOLEAN

Description

Replaces:ssl_verify_peer Verify SSL certificates. When set to false it will allow untrusted certificates.

Params

Default: true

Access

• Class: This property can only be accessed via the API class object.
  • EB.Network.verifyPeerCertificate

This property cannot be accessed via setter or getter methods. It can be used in methods that allow a HASH or Array of properties to be passed in.

Platforms

• Android
• Windows Mobile
• Windows CE

Remarks

Detecting a connection through proxies

Because the detectConnection method 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 call the method 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.

Detecting a connection over WAN

When detecting a network connection over WAN bear in mind if you specify a low networkPollInterval your device will frequently have an active data connection and may prevent the device occasionally from accepting incoming calls.

Preventing access to the device (WEH / WM)

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

SSL Connection Failure in iOS Platform

Due to a limitation in curl for iOS, an appropriate timeout is not used in 'select' system calls for a curl SSL conection. To avoid this SSL connection issue, it is recommended that the iOS native Network library be used instead of curl. To do this, add the two lines below to the rhoconfig.txt file.

For more information, please refer to Avoiding Common Networking Mistakes in the Apple developer reference.

ios_net_curl = 0
ios_direct_local_requests = 0