NetworkBearerSelection API

The Network Bearer Selection (NBS) API defines interfaces and methods providing Web applications to access the devices.

This API provides interfaces and methods for users to set network bearer selection. Since Tizen 2.3, the "http://tizen.org/privilege/internet" privilege is additionally required.
If not declared in config.xml of wgt file, UnknownError occurs.

Since: 2.1

Table of Contents

Summary of Interfaces and Methods

Interface Method
NetworkBearerSelectionObject
NetworkBearerSelection
void requestRouteToHost (NetworkType networkType, DOMString domainName, NetworkSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void releaseRouteToHost (NetworkType networkType, DOMString domainName, SuccessCallback successCallback, optional ErrorCallback? errorCallback)
NetworkSuccessCallback
void onsuccess ()

1. Type Definitions

1.1. NetworkType

Specifies the type of a network. 
  enum NetworkType { "CELLULAR", "UNKNOWN" };

Since: 2.1

  • CELLULAR - corresponds to cellular network type.
  • UNKNOWN - corresponds to unknown network type.

2. Interfaces

2.1. NetworkBearerSelectionObject

Specifies what is instantiated the Tizen object from the Tizen Platform. 
  [NoInterfaceObject] interface NetworkBearerSelectionObject {
    readonly attribute NetworkBearerSelection networkbearerselection;
  };
  Tizen implements NetworkBearerSelectionObject;

Since: 2.1

There is a tizen.networkbearerselection object that allows accessing the functionality of the Network Bearer Selection API.

Attributes

  • readonly NetworkBearerSelection networkbearerselection
    Object representing a network bearer selection.

    Since: 2.1

2.2. NetworkBearerSelection

The NetworkBearerSelection entry interface provides methods to query the network bearer selection. 
  [NoInterfaceObject] interface NetworkBearerSelection {
    void requestRouteToHost(NetworkType networkType, DOMString domainName, NetworkSuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
    void releaseRouteToHost(NetworkType networkType, DOMString domainName, SuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
  };

Since: 2.1

This API offers methods for network bearer selection.

Methods

requestRouteToHost
Requests a specific network connection. 
void requestRouteToHost(NetworkType networkType, DOMString domainName, NetworkSuccessCallback successCallback,
                        optional ErrorCallback? errorCallback);

Since: 2.1

The function must asynchronously acquire success or fail.

When called, it starts a request process defined with these set of steps:

  • 1. Open "networkType" network connection.
  • 2. Resolve "domainName" to IP.
  • 3. Change the routing path bound to domainName's IP to use the specific network type.
  • 4. If previous steps have been successfully accomplished, call the onsuccess() callback function.
    If previous steps have failed, call the ondisconnected() callback function.
    If network is disconnected, the routing path will be deleted and ondisconnected() is called.

The ErrorCallback method is launched with these error types:

  • UnknownError : If the "http://tizen.org/privilege/internet" privilege is not declared in config.xml or any other platform error occurs.

Privilege level: partner

Privilege: http://tizen.org/privilege/networkbearerselection

Privilege level: public

Privilege: http://tizen.org/privilege/internet

Remark: The "http://tizen.org/privilege/internet" privilege is required since Tizen 2.3.

Parameters:

  • networkType: The network type.
  • domainName: The domain name.
  • successCallback: Callback function that is called when data network connection is connected.
  • errorCallback [optional] [nullable]: Callback function that is called when the request is failed.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

var statuscb =
{
  onsuccess: function()
  {
    console.log("onsuccess func is called");
  },
  ondisconnected: function()
  {
    console.log("ondisconnected func is called");
  }
};
function ecb(e)
{
  console.log("error callback is called: " + e.message + ": " + e.code);
}
tizen.networkbearerselection.requestRouteToHost("CELLULAR", "www.tizen.org", statuscb, ecb);
releaseRouteToHost
Releases a specific network connection. 
void releaseRouteToHost(NetworkType networkType, DOMString domainName, SuccessCallback successCallback,
                        optional ErrorCallback? errorCallback);

Since: 2.1

The function must asynchronously acquire success or fail.

When called, it closes a network connection.

The ErrorCallback method is launched with these error types:

  • UnknownError : If the "http://tizen.org/privilege/internet" privilege is not declared in config.xml or any other platform error occurs.

Privilege level: partner

Privilege: http://tizen.org/privilege/networkbearerselection

Privilege level: public

Privilege: http://tizen.org/privilege/internet

Remark: The "http://tizen.org/privilege/internet" privilege is required since Tizen 2.3.

Parameters:

  • networkType: Network type.
  • domainName: Domain name.
  • successCallback: Callback function that is called when data network connection is released.
  • errorCallback [optional] [nullable]: Callback function that is called when the releasing fails.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

function scb()
{
  console.log("success callback is called");
}
function ecb(e)
{
  console.log("error callback is called: " + e.message + ": " + e.code);
}
var statuscb =
{
  onsuccess: function()
  {
    console.log("onsuccess func is called");
    tizen.networkbearerselection.releaseRouteToHost("CELLULAR", "www.google.com", scb, ecb);
  },
  ondisconnected: function()
  {
    console.log("ondisconnected func is called");
  }
};
tizen.networkbearerselection.requestRouteToHost("CELLULAR", "www.google.com", statuscb, ecb);

2.3. NetworkSuccessCallback

The NetworkSuccessCallback interface provides a success callback specific to NetworkBearerSelection. 
  [Callback, NoInterfaceObject] interface NetworkSuccessCallback {
    void onsuccess();
    void ondisconnected();
  };

Since: 2.1

It is used in asynchronous operations with requestRouteToHost().

Methods

onsuccess
Called when a network is connected successfully. 
void onsuccess();

Since: 2.1

ondisconnected
Called when a network is disconnected. 
void ondisconnected();

Since: 2.1

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee that the NBS application runs on a device with telephony feature, declare the following feature requirements in the config file:

  • http://tizen.org/feature/network.telephony

    • For more information, see Application Filtering.

    4. Full WebIDL

    module NetworkBearerSelection {
  enum NetworkType { "CELLULAR", "UNKNOWN" };
  Tizen implements NetworkBearerSelectionObject;
  [NoInterfaceObject] interface NetworkBearerSelectionObject {
    readonly attribute NetworkBearerSelection networkbearerselection;
  };
  [NoInterfaceObject] interface NetworkBearerSelection {
    void requestRouteToHost(NetworkType networkType, DOMString domainName, NetworkSuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
    void releaseRouteToHost(NetworkType networkType, DOMString domainName, SuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
  };
  [Callback, NoInterfaceObject] interface NetworkSuccessCallback {
    void onsuccess();
    void ondisconnected();
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.