Pei Zheng's Mobile Computing Blog : Connection Manager

ConnectivityManager in Android SDK: Compared with Connection Manager in Windows Mobile

zhengpei — Wed, 23 Sep 2009 08:03:00 GMT

Anyone who has ever used Windows Mobile (actually WinCE) Connection Manager will probably share mix feelings: on one side, the ConnMgr APIs provide a nice abstraction for applications to request and use a connection without knowing and controlling the physical connectivity; on the other side, it has been a pain in the neck to override or bypass Connection Manager's connection selection logic if the application should use a specific physical connection (for example, GPRS rather than WiFi). And the concept of metanetworks, Internet, Work, WAP network, Secured WAP, is indeed very confusing and difficult to manipulate.

So how does Android manage connections?

In Android SDK 1.5 (code named cupcake), the android.net.ConnectivityManager class (this is Java, not C++) provides connection state management and notification functionality. Specifically, it can be used to:

Obtain broadcast intents when network connectivity changes by checking ConnectivityManager.CONNECTIVITY_ACTION and ConnectivityManager.EXTRA_NETWORK_INFO in a class extended from BroadcastReceiver. (For a brief introduction to Android application fundamentals, read this document. An example of network connectivity listener can be found here.
Query the coarse-grained or fine-grained state of the available networks using ConnectivityManager.GetActiveNetworkInfo() or ConnectivityManager.GetNetworkInfo(int networkType).

This is same-old same-old as in Windows Mobile, which provides similar APIs like ConnMgrRegisterStatusNotification(), ConnMgrConnectionStatus, and ConnMgrQueryDetailedStatus() (examples of these APIs can be found in WM SDK cmhelper).

However, the ConnectivityManager class does offer an interesting method called requestRouteToHost():

public boolean requestRouteToHost (int networkType, int hostAddress)

Since: API Level 1

Ensure that a network route exists to deliver traffic to the specified host via the specified network interface. An attempt to add a route that already exists is ignored, but treated as successful.

Parameters

networkType the type of the network over which traffic to the specified host is to be routed

hostAddress the IP address of the host to which the route is desired

Returns

true on success, false on failure

networkType	the type of the network over which traffic to the specified host is to be routed
hostAddress	the IP address of the host to which the route is desired

This method is very useful--it allows your application to ensure that a desired physical connectivity (represented by the networkType) is available to reach a specific destination. If a route to the destination IP address from the desired network type is in place (in the routing table), then it simply returns success. Otherwise, it will try to make that happen--this is not mentioned in the above description but can be traced to ConnectivityService class:

In ConnectivityManager class where mService is a ConnectivityService object:

/**
     * Ensure that a network route exists to deliver traffic to the specified
     * host via the specified network interface.
     * @param networkType the type of the network over which traffic to the specified
     * host is to be routed
     * @param hostAddress the IP address of the host to which the route is desired
     * @return {@code true} on success, {@code false} on failure
     */
    public boolean requestRouteToHost(int networkType, int hostAddress) {
        enforceChangePermission();
        if (!ConnectivityManager.isNetworkTypeValid(networkType)) {
            return false;
        }
        NetworkStateTracker tracker = mNetTrackers[networkType];
        /*
         * If there's only one connected network, and it's the one requested,
         * then we don't have to do anything - the requested route already
         * exists. If it's not the requested network, then it's not possible
         * to establish the requested route. Finally, if there is more than
         * one connected network, then we must insert an entry in the routing
         * table.
         */
        if (getNumConnectedNetworks() > 1) {
            return tracker.requestRouteToHost(hostAddress);
        } else {
            return tracker.getNetworkInfo().getType() == networkType;
        }
    }

The mNetTrackers array contains NetworkStateTracker objects for different network types (mobile data and WiFi).

In MobileDataStateTracker class, which extends from NetworkStateTracker:

/**
     * Ensure that a network route exists to deliver traffic to the specified
     * host via the mobile data network.
     * @param hostAddress the IP address of the host to which the route is desired,
     * in network byte order.
     * @return {@code true} on success, {@code false} on failure
     */
    @Override
    public boolean requestRouteToHost(int hostAddress) {
        if (mInterfaceName != null && hostAddress != -1) {
            if (DBG) {
                Log.d(TAG, "Requested host route to " + Integer.toHexString(hostAddress));
            }
            return NetworkUtils.addHostRoute(mInterfaceName, hostAddress) == 0;
        } else {
            return false;
        }
    }

Notice the NetworkUtils.addHostRoute() call. This will add a host route into the system's routing table for the specified destination address via the mobile WWAN interface. This enables the scenario where you want your MMS go through a specific APN for MMS while other traffic on another APN. As of Android SDK 1.5, only MobileDataStateTracker class will actually does this--the WiFiStateTracker class does not do anything yet at this point.

Connection Manager: What's in CONNMGR_CONNECTION_DETAILED_STATUS?

zhengpei — Thu, 01 Nov 2007 11:12:00 GMT

The CONNMGR_CONNECTION_DETAILED_STATUS struct tells the detailes information of all connections that connection manager can use to build connection path to satisfy a connection request at that point of time. It can be otabined by calling ConnMgrQueryDetailedStatus.

typedef struct _CONNMGR_CONNECTION_DETAILED_STATUS{

struct _CONNMGR_CONNECTION_DETAILED_STATUS* pNext;

DWORD dwVer;

DWORD dwParams;

DWORD dwType;

DWORD dwSubtype;

DWORD dwFlags;

DWORD dwSecure;

GUID guidDestNet;

GUID guidSourceNet;

TCHAR* szDescription;

TCHAR* szAdapterName;

DWORD dwConnectionStatus;

SYSTEMTIME LastConnectTime;

DWORD dwSignalQuality;

CONNMGR_CONNECTION_IPADDR* pIPAddr;

} CONNMGR_CONNECTION_DETAILED_STATUS;

Two interesting fields of this struct are szAdapterName and szDescription. Here is the output from a HTC PPC with GPRS and WiFi active:

szAdapterName: szDescription

Cellular Line: T-Mobile USA

(NULL): SOCKS-{18AD9FBD-F716-ACB6-FD8A-1965DB95B814}

(NULL): HTTP-{18AD9FBD-F716-ACB6-FD8A-1965DB95B814}

(NULL): T-Mobile USA Proxy Internet

(NULL): null-corp-{18AD9FBD-F716-ACB6-FD8A-1965DB95B814}

(NULL): HTTP-{ADB0B001-10B5-3F39-27C6-9742E785FCD4}

TIACXWLN1: MCT

Observations:

1. The connected APN name (for example, ‘T-Mobile USA’) is in the szDescription field, with ‘Cellular Line’ as its adapter name. You can verify these two values by dumping CM_GPRSEntries using rapiconfig. The adapter name ‘Cellular Line’ is the DeviceName parameter in a GPRS entry provisioned to the device.

2. Wireless LAN adapter name varies on devices. Here the adapter name is ‘TIACXWLN1’. The connected SSID is MCT, as in the szDescription field.

3. All proxies, including null proxies are listed as connections. Their adapter name is ‘NULL’.

Update: the dwType field can be used to identify connection types:

dwType Value	Description
CM_CONNTYPE_UNKNOWN	Unknown connection.
CM_CONNTYPE_CELLULAR	Cellular connection.
CM_CONNTYPE_NIC	Network interface card (NIC) connection.
CM_CONNTYPE_BLUETOOTH	Bluetooth connection.
CM_CONNTYPE_UNIMODEM	Unimodem connection.
CM_CONNTYPE_VPN	Virtual private network (VPN) connection.
CM_CONNTYPE_PROXY	Proxy connection. For more proxy constants, see Connection Manager Proxy Flag Constants.
CM_CONNTYPE_PC	PC connection.

Connection Manager: Null Proxy

zhengpei — Thu, 01 Nov 2007 03:20:00 GMT

Null Proxy

In CM_ProxyEntries CSP, a proxy entry has a “Type” characteristic:

· 0 for null proxies

· 1 for HTTP proxies

· 2 for WAP proxies

· 4 for SOCKS4 proxies

· 5 for SOCKS5 proxies

Notice Type 0 is for Null Proxy. What is a Null Proxy? A Null Proxy basically identifies two networks—the srcID and destID--that are essentially the same. For example, on a PPC phone emulator, you can see the following proxy entry:

<parm name="SrcId" value="{ADB0B001-10B5-3F39-27C6-9742E785FCD4}"/>

<parm name="DestId" value="{436EF144-B4FB-4863-A041-8F905A62C572}"/>

<parm name="Type" value="0"/>

</characteristic>

This is a Null Proxy, who specifies a ‘hidden link’ between “My ISP” ({ADB0B001-10B5-3F39-27C6-9742E785FCD4}) and the “Internet” GUID. This is to say everything to “My ISP” is destined to “Internet”. This is the default Null Proxy on PPC Phone.

Another entry:

<parm name="SrcId" value="{18AD9FBD-F716-ACB6-FD8A-1965DB95B814}"/>

<parm name="DestId" value="{A1182988-0D73-439E-87AD-2A5B369F808B}"/>

<parm name="Type" value="0"/>

</characteristic>

This is a Null Proxy between “My Work Network” and the “Work” network.

On PPC Phone, a user will not see “Internet” and “Work” meta networks. Instead, UI will show “My ISP” and “My Work Network”. By default, Internally, Null Proxies are created to link “My ISP” to “Internet” and “My Work Network” to “Work”. PPC Phone UI allows user to configure which network (could be one of the two, or a new one created by the user or OEM) is going to connect to the Internet and which is to work (How confusing is that!). Once user changes the setting, the default Null Proxies will be updated automatically to link that selected network to either “Internet” or “Work”. All these settings are actually used to establish relationships between *networks* that can be those provisioned by default or by OEM.

For example, OEM can add a new network called “TMOBILE Network”, and Null-Proxy it to “Internet”. Then, OEM can add a GPRS connection that connects to “TMOBILE Network”. Thus, when an app is asking Connection Manager for a connection to “Internet”, this path—using GPRS to TMOBILE then to “Internet”—will be considered against other options such as WiFi or PPP, if any. There is a similar example in OEM doc “Add a Null Proxy connection example”.

On Smartphone, there is no “My ISP” or “My Work Network”. A user can directly specify *connections* that destine to “Internet” or “Work”.