Windows CE Networking Team WebLog : Author: Adam Dyba

Associating an application with a connection in Connection Manager

cenet — Tue, 20 Feb 2007 00:05:00 GMT

Consider a scenario where a connection exposes some service to be used by a service-specific application, or collection of such applications. For example, consider some set of “Premium Services” that are used by an application allowing user to interact with these services. In Connection Manager (CM), there are two options in associating an application with a connection:

1. Association by connection name. If the name of the connection is known, the application can ask for it explicitly using ConnMgrMapConRef(). The application can obtain the connection name by having the name configured in application.

2. Association by meta-network. If the meta-network that the connection leads to is known, the application can ask for the meta-network by its GUID. The application can obtain the GUID by:

a. GUID configured in the application.

b. Name of meta-network, such as “Premium Services Network”, configured in application, and mapping the name of the meta-network to GUID using ConnMgrEnumDestinations().

The above approaches require that the service-specific connection is provisioned to lead to a custom destination meta-network that is unlikely to be requested by other applications. Custom networks can be created using CM_Networks configuration service provider. If a service-specific connection points to a well known network is, such as “The Internet” or “Work”, then CM may connect applications such as Mobile Internet Explorer (IE) over the connection even in the presence of other more appropriate connections. If the service-specific connection is not able to honor Mobile IE’s HTTP requests then this misconfiguration will lead to failures in many applications and a bad user experience.

Option 1 is simple to implement, but has limitations. First, since the application is specifically asking for the one connection, CM will be forced to use that connection by itself without any proxies that may be required to access the service. In this case, the application will need to be also configured with the proxy information. Second, if the service is accessible using more than one connection, then CM will not be able to select the best connection for the given moment, and the application will need to know about the different options and implement the selection logic.

The preferred option in associating an application to a connection is option 2, association by meta-network. Although this option requires more configuration, it is flexible and doesn’t have the limitations associated with the first option. For example, consider a Premium Service available as a custom network “Premium Service Network” and exposed by:

· A WiFi connection: PREMIUM à “Premium Services Network”

· Across a HTTP proxy over any connection connecting to the Internet: “The Internet” à Premium Services HTTP Proxy à “Premium Service Network”

With this configuration, an application wanting to access the Premium Service Network could find it in list of ConnMgrEnumDestinations and have CM choose the best connection for the application to connect. The XML configuration that supports this example follows.

<wap-provisioningdoc>

</characteristic>

</characteristic>

</characteristic>

</wap-provisioningdoc>

References:

· Meta-networks Configuration Service Provider @ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mobilesdk5/html/wce51grfcm_proxyentriescsp.asp

· WiFi Configuration Service Provider @ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mobilesdk5/html/wce51grfcm_proxyentriescsp.asp

· Proxy Configuration Service Provider @ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mobilesdk5/html/wce51grfcm_proxyentriescsp.asp

[Author: Adam Dyba]

Connection Request Status Transitions

cenet — Thu, 08 Jun 2006 01:51:00 GMT

Creation of CR initiates the process during which attempts at connecting, or satisfying, that CR will be made, and may result in eventual success or failure in establishing the required connection(s) leading to the requested meta-network. During the connection process, the CR owner will be notified of, potentially, many state transitions, each of which needs to be properly handled by the application.

In particular, a CR can be in two states,

i) Transient state – Being in this state, the status of the CR will change at some point to another status, ex. the connected state having status CONNMGR_STATUS_CONNECTED is transient.

ii) Non-transient state – When a CR is in this state, its status will never change. For example, a disconnected CR in non-transient state will continue to be disconnected (and have the same status) forever. If an application finds its CR in this state, and a connection to desired meta-network is still required, the application needs to release and recreate the CR.

The figure attached to this blog entry maps out possible status transitions, clearly defines the transient and non-transient states and is meant to be used as a guide in implementations handling status updates. The meaning of each of the statuses is summarized in the table below.

Note that the CONNMGR_STATUS_ status prefix has been omitted in status names to aid in readability. Also note that since the status of CR can always change to CONNECTIONCANCELED, all states are in fact transient (of course, except for the state having the canceled status). However, the canceled state is a special case, and can be handled as such.

Figure: Client status transitions.

Client status	Reason
CONNECTED	The connection path leading to the requested network is now fully connected. After receiving this status notification, all sockets opened by the process-owner of this CR will use the selected connection path for sending data.
SUSPENDED	One of the connections used by this CR* is suspended as a result of an incoming or outgoing voice call. In this state, all active sockets of the process-owner of the CR will not be able to send or receive data until the connection is resumed (is CONNECTED). Note that if CR persists in this state for long enough, data sessions may timeout and they may need to be restarted.
DISCONNECTED	This is the initial client status of all CRs. This status indicates that CR has not been evaluated. This status will also be signaled if CR is not S/R-aware (didn’t have CONNMGR_FLAG_SUSPEND_AWARE set), but one of the connections used by this CR* is suspended as a result of an incoming or outgoing voice call. See SUSPENDED status for more information.
CONNECTIONFAILED	One of the connections used by this CR* failed to be connected or was prematurely terminated as a result of resource conflict with the same or higher priority CR, system entering secure mode, or some other error.
CONNECTIONCANCELED	The CR was cancelled.
CONNECTIONDISABLED	This CR is disabled and will not be connected. The CR is disabled if the bDisabled member of the CONNMGR_CONNECTIONINFO structure initially passed in call to ConnMgrEstablishConnection() is TRUE.
NOPATHTODESTINATION	Connection planner could not find a suitable connection path that can satisfy the requirements of the CR including the specified cost, bandwidth, latency and the requested destination network.
WAITINGFORPATH	VPN is connected, but the selected path to the requested destination network does not use the VPN connection.
WAITINGFORPHONE	Resources required by the selected path to the requested destination network cannot be reserved because the phone is in use.
PHONEOFF	The selected path to the requested destination network requires one of radio connections, but the radio is off (i.e. in flight-mode).
EXCLUSIVECONFLICT	The system is in secure mode, that is, a secure connection, such as DTPT is connected. The selected path to the requested destination network cannot be connected because it doesn’t use the connected secure connection (or a more secure connection).
NORESOURCES	Reserved for internal use.
CONNECTIONLINKFAILED	One of the connections used by this CR* failed to be connected or was prematurely terminated, typically by a remote disconnection, ex. PPP server terminated connection with client.
AUTHENTICATIONFAILED	One of the connections used by this CR* and requiring credentials failed to be connected because of authentication failure.
NOPATHWITHPROPERTY	CR asked for Wake-On-Incoming support (set CONNMGR_FLAG_WAKE_ON_INCOMING), but such path to requested destination network doesn’t exist.
WAITINGCONNECTION	A connection path for this CR was selected, required resources were successfully allocated, and now connections on the path are being connected. Indication with CONNECTED or disconnected (failed) status should follow.
WAITINGFORRESOURCE	A connection path for this CR was selected, but not all of the required resources could be reserved. This typically means that the resources are occupied by same or higher priority CR. If former, then the CR is now being disconnected, and this CR should transition to WAITINGCONNECTION within short amount of time; if latter, then this CR may remain in this state until the higher priority CR is disconnected or a new path becomes available.
WAITINGFORNETWORK	This status indicates one of two things, (i) if the priority of this CR has LOWBKGND priority, then the CR cannot be connected because the path selected is not already connected by another higher priority CR, or (ii) if the priority of this CR is not LOWBKGND, but the CR has flag CONNMGR_FLAG_REGISTERED_HOME is set, then the connection path used by the CR contains a radio connection, and radio is not registered home, i.e. it is roaming.
WAITINGDISCONNECTION	This CR is being disconnected because, (i) the CR was canceled, or (ii) the CR has LOWBKGND priority, but the connection path used by this CR is not used by another higher priority CR, or (iii) this CR lost resources required to maintain its CONNECTED status to another same or higher priority CR.
WAITINGCONNECTIONABORT	This CR was in the process of being connected, but is now aborted for one of the reasons listed in WAITINGDISCONNECTION, above.
*) A connection that is used by a CR is one that appears on the connection path used by the CR.

Table: Meanings of client statues.

[Author: Adam Dyba]

Introduction to Connection Manager

cenet — Wed, 07 Jun 2006 09:44:00 GMT

Connection Manager (CM) is a networking component available on Microsoft Pocket PC and Windows Mobile (WM) OS. CM provides two key services to applications and the OS,

1. Abstracts network resources to applications. It exposes access to all network resources for applications without applications having to refer to any of the resources explicitly. Simply stated, the applications can be completely oblivious to how the connection to their network of choice is established, and at the same time, be confident that the “right” connection path is chosen. CM computes the “best” path for each of the Connection Requests (CRs), connects all connections on it to satisfy the requests, and provides a continuous feed of status notifications to the owner application informing them when status of their CR changes.

2. Resource arbitration. CM manages all network resources, including CSD, GPRS, 1xRTT, Ethernet, VPN, and even voice connections, as they are leased to applications’ CRs to provide access to different destination networks. Use of resources is restricted to different CRs based on their priority and resources’ security properties.

In CM, the Connection Planner is responsible for choosing one or a set of connections (a connection path), that will satisfy CR. During the computation of a connection path, all Connection Service Providers (CSPs) are queried for available connections. A connection contains two important fields used in connection path evaluation,

Source meta-network. The meta-network such as “Work” or “The Internet,” specified as a GUID, from which the connection connects. If the source meta-network is NULL, the connection connects directly from device.
Destination meta-network. The meta-network, specified as a GUID, from which the connection connects.

Connection Planner uses these fields to form a path to the requested destination network. As an example, consider CR to “Work,” and a set of available connections:

My Connection. GPRS connection to “The Internet” (source meta-network is NULL).
My VPN. VPN connection from “The Internet” to “Work.”
ACMECORP. WiFi connection to “Work.”

Having this choice of connections, the connection planner has a couple choices in paths that will satisfy the CR,

My Connection à “The Internet” à My VPN à “Work”
ACMECORP à “Work”

By default, the planner will choose the connection path that is likely to have the highest bandwidth. In this example, that is the latter path since WiFi typically has higher bandwidth than GPRS plus VPN.

An application uses the fields in CONNMGR_CONNECTIONINFO structure to influence path that is chosen to satisfy its CR. These fields include the destination meta-network or specific connection to use (guidDestNet), flags (dwFlags), and others.

When an application opens a CR, CM will begin evaluating it, a process that involves determination of a path, allocation of resources required to connect, and the actual connecting of connections. During the life of a CR, CM will indicate updates to the CR application owner that reflect connection status of the CR. Subsequent blog entries will talk more about meanings of different statues and their handling.

Notes:

Compatibility. Connection Manger was available in the first version of Pocket PC. CM available on the newest WM platforms is a result of many upgrades, however its main purpose has remained the same: abstract network resources to applications and resource arbitration. New APIs have been added, but the functionality provided by first APIs has not changed. Applications using CM APIs and written for the old version of the OS, should compile and run in much the same way on the newer versions of the OS. Unless otherwise stated, this and subsequent blogs are based on functionality supported by WM 5.0 and above.
Configuration. CSPs are configured with connections using Configuration Service Providers via CM_xxx XML entries (ex. CM_GPRSEntries). Configuration Service Providers are described in, http://msdn.microsoft.com/library/default.asp?url=/library/en-us/DevGuideSP/html/sp_wce51conconfigurationserviceproviderscspsozup.asp.
Fixed connection path for CRs. Beginning with WM 5.0, an application can specify precisely the connection that CM will use to satisfy its CR. This is done by selecting the connection by name using ConnMgrMapConRef() and passing the returned GUID as guidDestNet field of the CONNMGR_CONNECTIONINFO structure when calling ConnMgrEstablishConnection[Sync](). The disadvantage of this is that the resultant connection path will contain only one connection (ex. no proxies), and the choice of connection may not be optimal (ex. there may be a faster connection available).

[Author: Adam Dyba]

About Adam…

cenet — Wed, 07 Jun 2006 09:43:00 GMT

My name is Adam Dyba. I’ve been working on Windows CE core networking technologies since 2001. Currently, my main focus is on Connection Manager. Some of the technologies that I dealt with in the past include IPv6 core protocol, Mobile IPv6, IP NAT, Firewall, IP Helper API.

[Author: Adam Dyba]