CellularDataInterface

Since: BlackBerry 10.2.0

#include <bb/device/CellularDataInterface>

To link against this class, add the following line to your .pro file: LIBS += -lbbdevice

Represents a logical network connection for a cellular data service.

A carrier may route traffic for different cellular data services over different network interfaces. Furthermore, different carriers may route traffic for the same service over different network interfaces. CellularDataInterface maps the logical name of a cellular data service to its carrier-dependent network interface, provides information about the service's network connection, and allows the activation/de-activation of on-demand connections.

Use allNames() to discover the set of cellular data services configured for this device. Possible logical names include:

  • a_gps - Connection for Assisted Global Positioning (A-GPS)

  • bip - Connection for Bearer Independent Protocol (BIP) - see 3gpp TS 31.111 and 3gpp TS 27.007

  • bip_2 - Alternate connection for BIP

  • bip_3 - Alternate connection for BIP

  • bip_4 - Alternate connection for BIP

  • bip_5 - Alternate connection for BIP

  • blackberry - Connection for BlackBerry services

  • carrier_800 - Connection for carrier applications

  • carrier_admin - Connection for carrier administrative applications

  • carrier_apps - Connection for carrier applications

  • ims - Connection for IP Multimedia Subsystem (IMS)

  • internet - Connection for cellular Internet access

  • mms - Connection for Multimedia Messaging Service (MMS)

  • plan_admin - Connection for adminstration of user's cellular service plan

  • rim_admin - Connection for administrative BlackBerry services

  • software_update - Connection for downloading software updates

  • streaming - Connection for alternate streaming channels

  • tethering - Connection for tethering applications

  • tethering_2 - Alternate connection for tethering applications

  • tethering_entitlement - Connection for tethering entitlement check

  • tethering_user - Connection for tethering applications with user supplied configuration

  • vvm - Connection for Visual Voicemail (VVM)

  • wap - Connection for Wireless Application Protocol (WAP)

The following cellular data services support activation/de-activation of on-demand connections via requestConnect() and requestDisconnect():

  • carrier_800 - Requires cds_carrier_800 permission

  • carrier_admin - Requires cds_carrier_admin permission

  • carrier_apps - Requires cds_carrier_apps permission

  • plan_admin - Requires cds_plan_admin permission

Most applications that need to send/receive data over a network connection should not bind to a specific network interface. Instead, these applications should accept the default route for their traffic. Even binding to the network interface for internet is not recommended as this is a cellular-only connection and does not account for the availability of a WiFi connection.

Applications that have a specific need to send/receive data using a particular cellular data service can do so using the following steps:

  1. Create an instance of CellularDataInterface using the logical name of your service.

  2. Call isValid() to verify the logical name is correct and supported.

  3. Call requestConnect() and check the return value for an error.

  4. Wait for the connectionState property to become CellularConnectionState::Connected.

  5. Query the networkInterfaceName property to get the service's network interface.

  6. Set the SOCK_SO_BINDTODEVICE environment variable to the service's network interface; all subsequently created sockets will be bound to this network interface.

  7. Send/receive data.

  8. Call requestDisconnect().

It is important to always call requestConnect() and requestDisconnect() regardless of the current connection state. The OS determines when to activate/de-activate an on-demand connection for a cellular data service based on the calls to requestConnect() and requestDisconnect(). When multiple applications use the same service, the OS keeps the connection active until the last application calls requestDisconnect(). Using a service without first calling requestConnect() means there is no guarantee the connection will remain active while you're using it.

Furthermore, you must keep the CellularDataInterface object alive until you're done sending/receiving data. The destructor for CellularDataInterface implicitly calls requestDisconnect().


Overview

Properties Index

Public Functions Index

CellularDataInterface (QObject *parent=0)
CellularDataInterface (const QString &name, QObject *parent=0)
virtual ~CellularDataInterface ()
QStringaccessPointName () const
bb::device::CellularConnectionState::TypeconnectionState () const
boolisAccessControlled () const
boolisAlwaysOn () const
boolisValid () const
QStringname () const
QStringnetworkInterfaceName () const
Q_SLOT intrequestConnect ()
Q_SLOT intrequestDisconnect ()
voidsetName (const QString &name)

Static Public Functions Index

Q_INVOKABLE QStringListallNames ()

Signals Index

voidaccessControlledChanged (bool accessControlled)
voidaccessPointNameChanged (const QString &accessPointName)
voidalwaysOnChanged (bool alwaysOn)
voidconnectionStateChanged (bb::device::CellularConnectionState::Type connectionState)
voidnameChanged (const QString &name)
voidnetworkInterfaceNameChanged (const QString &networkInterfaceName)
voidvalidChanged (bool valid)

Properties

bool accessControlled[read-only]

Flag indicating if only authorized processes can control and/or send traffic over this interface.

Since:

BlackBerry 10.2.0

QString accessPointName[read-only]

Name of the access point (APN) used by this cellular data service.

Since:

BlackBerry 10.2.0

bool alwaysOn[read-only]

Flag indicating if this interface is automatically connected when data services are enabled.

Since:

BlackBerry 10.2.0

bb::device::CellularConnectionState::Type connectionState[read-only]

State of this cellular data services's network connection.

See CellularConnectionState for details.

Since:

BlackBerry 10.2.0

QString name

Logical name of the cellular data service this object represents.

Since:

BlackBerry 10.2.0

QString networkInterfaceName[read-only]

Name of the network interface that handles traffic for this cellular data service.

Since:

BlackBerry 10.2.0

bool valid[read-only]

Flag indicating whether this object represents a valid interface.

Since:

BlackBerry 10.2.0

Public Functions

CellularDataInterface (

Creates a CellularDataInterface object which defaults to an invalid state - no name.

Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.2.0

CellularDataInterface (

Creates a CellularDataInterface object for the specified interface.

Parameters
name

Logical name of the cellular data service this object represents.

parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.2.0

virtual~CellularDataInterface ()

Destructor.

If requestConnect() was previously called, implicitly calls requestDisconnect().

Since:

BlackBerry 10.2.0

QString accessPointName ()

Retrieves the name of the access point (APN) used by this cellular data service.

Return:

Name of the access point (APN) used by this cellular data service.

Since:

BlackBerry 10.2.0

bb::device::CellularConnectionState::Type connectionState ()

Retrieves the state of this celluar data service's network connection.

Return:

State of this cellular data service's network connection. See CellularConnectionState for details.

Since:

BlackBerry 10.2.0

bool isAccessControlled ()

Indicates whether only authorized processes can control and/or send traffic over this interface.

Return:

Flag indicating if only authorized processes can control and/or send traffic over this interface.

Since:

BlackBerry 10.2.0

bool isAlwaysOn ()

Indicates whether this interface is automatically connected when data services are enabled.

Return:

Flag indicating if this interface is automatically connected when data services are enabled.

Since:

BlackBerry 10.2.0

bool isValid ()

Indicates whether this object represents a valid interface.

Return:

Flag indicating whether this object represents a valid interface.

Since:

BlackBerry 10.2.0

QString name ()

Retrieves the logical name of the cellular data service this object represents.

Return:

The logical name of the cellular data service this object represents.

Since:

BlackBerry 10.2.0

QString networkInterfaceName ()

Retrieves the name of the network interface that handles traffic for this cellular data service.

Return:

Name of the network interface that handles traffic for this cellular data service.

Since:

BlackBerry 10.2.0

Q_SLOT int requestConnect ()

Attempt to activate the network connection for this cellular data service.

This is an asynchronous operation. If CellularConnectionRequestResult::Requested is returned, monitor connectionState to determine when a connection has finally been established. Note that CellularConnectionRequestResult::Requested does not guarantee that a connection will ultimately be established, only that no immediate failure was detected.

All clients that need to send traffic over the interface should call requestConnect() and requestDisconnect() when they start and stop using the interface regardless of the current value of connectionState. This ensures that on-demand interfaces remain active until the last client disconnects.

Return:

Result of this request. See CellularConnectionRequestResult for details.

Since:

BlackBerry 10.2.0

Q_SLOT int requestDisconnect ()

Attempt to de-activate the network connection for this cellular data service.

This is an asynchronous operation. If CellularConnectionRequestResult::Requested is returned, monitor connectionState to determine when a connection has finally been shut down. Note that CellularConnectionRequestResult::Requested does not guarantee that a connection will ultimately be shut down. The connection may be always-on or another application may still be using the on-demand connection.

All clients that need to send traffic over the interface should call requestConnect() and requestDisconnect() when they start and stop using the interface regardless of the current value of connectionState. This ensures that on-demand interfaces remain active until the last client disconnects.

Return:

Result of this request. See CellularConnectionRequestResult for details.

Since:

BlackBerry 10.2.0

void setName (

Changes the cellular data service this object represents.

If requestConnect() was previously called, implicitly calls requestDisconnect() prior to switching to the new cellular data service.

Parameters
name

Logical name of the new cellular data service this object represents.

Since:

BlackBerry 10.2.0

Static Public Functions

Q_INVOKABLE QStringList allNames ()

Retrieves the logical names of each cellular data services configured for this device.

Return:

List of logical names of each cellular data services configured for this device.

Since:

BlackBerry 10.2.0

Signals

void accessControlledChanged (
  • boolaccessControlled)

Emitted when this interface changes whether only authorized processes can control and/or send traffic over this interface.

Parameters
accessControlled

Flag indicating if only authorized processes can control and/or send traffic over this interface.

Since:

BlackBerry 10.2.0

void accessPointNameChanged (

Emitted when the name of the access point (APN) used by this interface changes.

Parameters
accessPointName

Name of the access point (APN) used by this cellular data service.

Since:

BlackBerry 10.2.0

void alwaysOnChanged (
  • boolalwaysOn)

Emitted when this interface changes from an on-demand connection to an always-on connection or vice versa.

Parameters
alwaysOn

Flag indicating if this interface is automatically connected when data services are enabled.

Since:

BlackBerry 10.2.0

void connectionStateChanged (

Emitted when the state of this interface's network connection changes.

Parameters
connectionState

State of this celluar data services's network connection. See CellularConnectionState for details.

Since:

BlackBerry 10.2.0

void nameChanged (

Emitted when the name of the logical interface this object represents changes.

Parameters
name

The logical name of the cellular data service this object represents.

Since:

BlackBerry 10.2.0

void networkInterfaceNameChanged (
  • const QString &networkInterfaceName)

Emitted when the name of the network interface that maps to this logical interface changes.

Parameters
networkInterfaceName

Name of the network interface that handles traffic for this cellular data service.

Since:

BlackBerry 10.2.0

void validChanged (
  • boolvalid)

Emitted when this object changes from representing an invalid interface to a valid interface or vice versa.

Parameters
valid

Flag indicating whether this object represents a valid interface.

Since:

BlackBerry 10.2.0

Last modified: 2014-03-13

comments powered by Disqus