Network Usage

The following sections describe how to create applications that have
cost-efficient control over their usage of network resources. If your
application performs a lot of network operations, you must provide user
settings that allow the user to control your application’s data
behavior, such as how often the application syncs data, whether to
perform uploads or downloads only when Wi-Fi is switched on, and whether
to use data while roaming. With these controls available to them, users
are much less likely to disable your application’s access to background
data when they approach their limits, because they can instead precisely
control how much data your application uses.

Required Privileges and Features

Applications that access network information and statistics must declare
the required privileges in the tizen-manifest.xml file. For more
information on the Tizen privileges, see Security and API
Privileges
.

To perform the network operations, the application manifest must include
the following privileges:

<privileges>
   <privilege>http://tizen.org/privilege/network.get</privilege>
</privileges>

To perform the network operations, the device must support the following
features:

  • To use Wi-Fi:
    • http://tizen.org/feature/network.wifi
    • http://tizen.org/feature/network.wifi.direct
    • http://tizen.org/feature/network.wifi.direct.display
    • http://tizen.org/feature/network.wifi.direct.service_discovery
  • To use the mobile network:
    • http://tizen.org/feature/network.telephony

Monitoring Connection Type Changes

When the network connection is changed, the application must receive a
notification. For instance, if the Wi-FI network is changed to a visited
mobile network (roaming), the user can pay for the mobile data without
user recognition.

The Connection API (in
mobile
and
wearable
applications) provides a function that provides a notification about the
connection status. The application can download or upload files only
when Wi-Fi is connected by checking the network type in the triggered
callback.

The Connection API supports the following network types:

  • CONNECTION_TYPE_DISCONNECTED
  • CONNECTION_TYPE_WIFI
  • CONNECTION_TYPE_CELLULAR (indicates the mobile network)
  • CONNECTION_TYPE_ETHERNET
  • CONNECTION_TYPE_BT

The following example demonstrates how to monitor network connection
changes:

#include <net_connection.h>

static void
connection_changed_cb(connection_type_e type, void* user_data)
{
    dlog_print(DLOG_INFO, LOG_TAG, "Type changed callback, connection type: %d", type);
}

int
get_network_connection()
{
    int error_code;
    static connection_h connection;
    void *user_data;

    error_code = connection_create(&connection);
    if (error_code != CONNECTION_ERROR_NONE)
        return;

    error_code = connection_set_type_changed_cb(connection, connection_changed_cb, user_data);
    if (error_code != CONNECTION_ERROR_NONE)
        return;

    error_code = connection_destroy(connection);
    if (error_code != CONNECTION_ERROR_NONE)
        return;
}

Monitoring Mobile (Cellular) Network Service Changes

Sometimes, the application must check the state of the mobile network
service to make the user experience better by protecting against running
tasks in the background when the device is, for example, roaming.
Downloading or uploading content without user awareness in that
situation can incur charges, and result in unreasonable use of the
mobile network resources. The application must use the data transport
network efficiently, providing a better user experience for the mobile
data network.

Getting the State of Mobile Network Service

The Telephony Information API (in
mobile
and
wearable
applications) is composed of Call (in
mobile
and
wearable
applications), SIM (in
mobile
and
wearable
applications), Network (in
mobile
and
wearable
applications), and Modem (in
mobile
and
wearable
applications) APIs for the mobile network service.

The Telephony Network API provides the detailed mobile network
information: LAC, Cell ID, RSSI, roaming state, MCC, MNC, network
provider name, PS type, and network type. The
telephony_network_get_service_state() function gets the current
network state of the telephony service. It returns one of the
telephony_network_service_state_e enumerator values (in
mobile
and
wearable
applications).

The following table indicates the telephony_network_service_state_e
enumeration that has the mobile network service state.

Table: Mobile network service states

Enumeration Description
TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE In service
TELEPHONY_NETWORK_SERVICE_STATE_OUT_OF_SERVICE Out of service
TELEPHONY_NETWORK_SERVICE_STATE_EMERGENCY_ONLY Only emergency call is allowed

The following example demonstrates how to get the mobile network service
state:

/* Convert network telephony_network_service_state_e to string */
char*
_telephony_network_state_to_string(telephony_network_service_state_e network_state)
{
    switch (network_state) {
    case TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE:
        return "TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE";
    case TELEPHONY_NETWORK_SERVICE_STATE_OUT_OF_SERVICE:
        return "TELEPHONY_NETWORK_SERVICE_STATE_OUT_OF_SERVICE";
    case TELEPHONY_NETWORK_SERVICE_STATE_EMERGENCY_ONLY:
        return "TELEPHONY_NETWORK_SERVICE_STATE_EMERGENCY_ONLY";
    default:
        return "Unknown";
    }
}

void
get_telephony_information(appdata_s *ad, Evas_Object *obj, void *event_info)
{
    /* Create a telephony handle */
    telephony_handle_list_s handle_list;
    /* In the case of a single SIM, you get only one handle */
    ret = telephony_init(&handle_list);

    /* Print */
    for (i = 0; i < app_data->handle_list.count; i++) {
        dlog_print(DLOG_INFO, "TEST", "telephony handle[%p] for subscription[%d]",
                   app_data->handle_list.handle[i], i);
    }

    /* Get the network service state */
    telephony_network_service_state_e network_service_state;
    char *state = NULL;
    ret = telephony_network_get_service_state(handle_list.handle[0], &network_service_state);
    state = _telephony_network_state_to_string(network_service_state);
    if (ret != TELEPHONY_ERROR_NONE)
        dlog_print(DLOG_DEBUG, LOG_TAG, "[telephony_network_get_service_state] failed");
    else
        dlog_print(DLOG_DEBUG, LOG_TAG, "Network Service State [%s]", state);
}

static void
app_terminate(void *data)
{
    /* Release and free the created telephony handle */
    telephony_deinit(&handle_list);
}

/* Auto-generated functions (from Tizen Studio) are not included */

int
main(int argc, char* argv[])
{
    AppData app_data;  /* Store telephony handle here */
    service_app_lifecycle_callback_s event_callback;
    app_event_handler_h handlers[5] = {NULL,};

    event_callback.create = service_app_create;
    event_callback.terminate = service_app_terminate;
    event_callback.app_control = service_app_control;

    service_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY,
                                  service_app_low_battery, &app_data);
    service_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY,
                                  service_app_low_memory, &app_data);
    service_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED,
                                  service_app_lang_changed, &app_data);
    service_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED,
                                  service_app_region_changed, &app_data);

    /* Set AppData as a user_data */
    return service_app_main(argc, argv, &event_callback, &app_data);
}

Monitoring Mobile Network Changes

Another way to get the mobile network state and protect the user against
unreasonable use of the mobile network resources is to register a
notification callback.

The telephony_set_noti_cb() function allows the application to listen
for the changes in the mobile network state, and also provides mobile
network information by specifying the notification ID when the mobile
network state changes.

The following table indicates the available notification IDs.

Table: Notification IDs

Changed state Notification ID
Network service state TELEPHONY_NOTI_NETWORK_SERVICE_STATE
Cell ID TELEPHONY_NOTI_NETWORK_CELLID
Roaming status TELEPHONY_NOTI_NETWORK_ROAMING_STATUS
Signal strength TELEPHONY_NOTI_NETWORK_SIGNALSTRENGTH_LEVEL
Network name TELEPHONY_NOTI_NETWORK_NETWORK_NAME
Packet-switched type TELEPHONY_NOTI_NETWORK_PS_TYPE
Default data subscription TELEPHONY_NOTI_NETWORK_DEFAULT_DATA_SUBSCRIPTION
Default subscription TELEPHONY_NOTI_NETWORK_DEFAULT_SUBSCRIPTION

The telephony_noti_e enumerator (in
mobile
and
wearable
applications) defines the available notification IDs. The callback
function registered by the telephony_set_noti_cb() function
(network_service_state_noti_cb() in the following example) delivers
change notifications for a network asynchronously.

The following example demonstrates how to register a notification for
the mobile network state change:

/* Convert network telephony_network_service_state_e to string */
char*
_telephony_network_state_to_string(telephony_network_service_state_e network_state)
{
    switch (network_state) {
    case TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE:
        return "TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE";
    case TELEPHONY_NETWORK_SERVICE_STATE_OUT_OF_SERVICE:
        return "TELEPHONY_NETWORK_SERVICE_STATE_OUT_OF_SERVICE";
    case TELEPHONY_NETWORK_SERVICE_STATE_EMERGENCY_ONLY:
        return "TELEPHONY_NETWORK_SERVICE_STATE_EMERGENCY_ONLY";
    default:
        return "Unknown";
    }
}

/* This function is triggered, if the mobile network status is changed */
void
network_service_state_noti_cb(telephony_h handle, telephony_noti_e noti_id, void *data, void *user_data)
{
    telephony_network_service_state_e network_state = *(int *)data;
    char *network_state_string = _telephony_network_state_to_string(network_state);
    dlog_print(DLOG_DEBUG, LOG_TAG, "Network service state: [%s]", network_state_string);
}

void
monitor_telephony_information(appdata_s *ad, Evas_Object *obj, void *event_info)
{
    /*  Create a telephony handle */
    telephony_handle_list_s handle_list;
    /* In the case of a single SIM, you get only one handle */
    ret = telephony_init(&handle_list);

    /*
       Register the network_service_state_noti_cb() callback function
       to be notified if the Network Service state is changed
    */
    ret = telephony_set_noti_cb(handle_list.handle[0], TELEPHONY_NOTI_NETWORK_SERVICE_STATE, network_service_state_noti_cb, NULL);
    if (ret != TELEPHONY_ERROR_NONE)
        dlog_print(DLOG_DEBUG, LOG_TAG, "[telephony_set_noti_cb] failed");
}

static void
app_terminate(void *data)
{
    /* Release and free the created telephony handle */
    telephony_deinit(&handle_list);
}

Getting Connection Information

The connection state can be changed depending on various mobile
environments, such as the settings of the mobile phone or the signal
strength received by the mobile phone from the cellular network or Wi-Fi
AP (access point). The Connection API (in
mobile
and
wearable
applications) provides a function that gets the current state of the
mobile network service and Wi-Fi network.

Getting the Mobile (Cellular) Network Connection State

The application can use the connection_get_cellular_state() function
to get the mobile connection state.

The network connection can be in one of the following states:

  • CONNECTION_CELLULAR_STATE_OUT_OF_SERVICE
  • CONNECTION_CELLULAR_STATE_FLIGHT_MODE
  • CONNECTION_CELLULAR_STATE_ROAMING_OFF
  • CONNECTION_CELLULAR_STATE_CALL_ONLY_AVAILABLE
  • CONNECTION_CELLULAR_STATE_AVAILABLE
  • CONNECTION_CELLULAR_STATE_CONNECTED

The following example demonstrates how to get the mobile network state:

connection_cellular_state_e cellular_state;
connection_get_cellular_state(connection, &cellular_state);
switch (cellular_state) {
case CONNECTION_CELLULAR_STATE_OUT_OF_SERVICE:
    dlog_print(DLOG_INFO, LOG_TAG, "Out of service");
    break;
case CONNECTION_CELLULAR_STATE_FLIGHT_MODE:
    dlog_print(DLOG_INFO, LOG_TAG, "Flight mode");
    break;
case CONNECTION_CELLULAR_STATE_ROAMING_OFF:
    dlog_print(DLOG_INFO, LOG_TAG, "Roaming is switched off");
    break;
case CONNECTION_CELLULAR_STATE_CALL_ONLY_AVAILABLE:
    dlog_print(DLOG_INFO, LOG_TAG, "Call only");
    break;
case CONNECTION_CELLULAR_STATE_AVAILABLE:
    dlog_print(DLOG_INFO, LOG_TAG, "Available");
    break;
case CONNECTION_CELLULAR_STATE_CONNECTED:
    dlog_print(DLOG_INFO, LOG_TAG, "Connected");
    break;
default:
    dlog_print(DLOG_INFO, LOG_TAG, "error");
    break;
}

Getting Wi-Fi Connection State

The application can use the connection_get_wifi_state() function to
get the Wi-Fi connection state.

The Wi-Fi connection can be in one of the following states:

  • CONNECTION_WIFI_STATE_DEACTIVATED
  • CONNECTION_WIFI_STATE_DISCONNECTED
  • CONNECTION_WIFI_STATE_CONNECTED

The following example demonstrates how to get the Wi-Fi network state:

connection_wifi_state_e wifi_state;
connection_get_wifi_state(connection, &wifi_state);
switch (wifi_state) {
case CONNECTION_WIFI_STATE_DEACTIVATED:
    dlog_print(DLOG_INFO, LOG_TAG, "Deactivated state");
    break;
case CONNECTION_WIFI_STATE_DISCONNECTED:
    dlog_print(DLOG_INFO, LOG_TAG, "Disconnected state");
    break;
case CONNECTION_WIFI_STATE_CONNECTED:
    dlog_print(DLOG_INFO, LOG_TAG, "Connected state");
    break;
default:
    dlog_print(DLOG_INFO, LOG_TAG, "error");
    break;
}

Collecting Connection Statistics

The Connection Statistics API (in
mobile
and
wearable
applications) provides functions for getting statistical information,
such as the amount of sent or received data. The API also provides
functions for getting the cumulative size of packets sent or received
since the last reset based on the operation mode, such as packet
switching (PS).

Connection statistics include the amount of total sent and received data
and the last sent and received data. The parameters of the
connection_get_statistics() function determine which connection type
and which statistics are gathered:

  • The connection_type_e enumerator (in
    mobile
    and
    wearable applications)
    defines the connection types: CONNECTION_TYPE_WIFI is Wi-Fi and
    CONNECTION_TYPE_CELLULAR is the mobile network. Only Wi-Fi and
    mobile network connections are supported in the statistics.
  • The connection_statistics_type_e enumerator (in
    mobile
    and
    wearable applications)
    defines the statistics type.

The following example demonstrates how to get received data and sent
data for mobile connections:

long long total_received_size;

/* Gets statistics of total received data through the mobile network connection */
error_code = connection_get_statistics(connection, CONNECTION_TYPE_CELLULAR,
                                       CONNECTION_STATISTICS_TYPE_TOTAL_RECEIVED_DATA,
                                       &total_received_size);

long long total_sent_size;

/* Gets statistics of total sent data through the mobile network connection */
error_code = connection_get_statistics(connection, CONNECTION_TYPE_CELLULAR,
                                       CONNECTION_STATISTICS_TYPE_TOTAL_SENT_DATA,
                                       &total_sent_size);