Network

Enterprise Browser 3.5

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