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.
- body : STRING
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.
- body : STRING
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.
- body : STRING
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.
- body : STRING
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