Introduction to Connection Manager


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]

Comments (32)

  1. Kartik says:

    If I use ConnMgrMapConRef() to force my connection path and bypass Connection Planner, would this connection be used across applications or would this connection be local to my application?

  2. cenet says:

    Kartik:  Yes, use of ConnMgrMapConRef() affects only the CR that would be created with a subsequent call to ConnMgrEstablishConnectionSync.  Every CR is local to the application (process) that created it.  [Author: Adam Dyba]

  3. Kartik says:

    Thanks for answering my previous query, Adam. I have one more query.  Using ConnMgrMapConRef() is it possible to create a CR using a 802.11 connection?

  4. cenet says:

    Kartik:  Yes, ConnMgrMapConRef() can be used to select by name any connection available (configured) at the time of the call, including a 802.11 (WiFi) connection.  The set of configured connections can be enumerated using ConnMgrQueryDetailedStatus().  [Author:  Adam Dyba]

  5. raj_rr7 says:

    I have a GPRS connection which is connected manually. Now if i want my application to tera down it, is it possible or is there any way using Connection Manager APIs?

  6. cenet says:

    raj_rr7:  When you say that the GPRS connection was "connected manually," what do you mean?  What API was used?

    CM will disconnect a GPRS connection it has connected (as a result of application CR) when it determines the right time to do so:  i) no other CR is using the connection, ii) the cache times of all CRs that previously used the connection have expired (see cache time parameter to ConnMgrReleaseConnection()), and iii) the configuration doesn’t prevent CM from disconnecting the connection (a connection configured as Suspend/Resume capable, such as GPRS connection (by default), will be kept connected for as long as possible).  CM may also disconnect a connection as a result of resource conflict.  [Author:  Adam Dyba]

  7. Jeremy says:

    I have used the RAS APi to create a GPRS connection and dial it. This works fine until you turn my device – running WM 5.0 – off. This is a problem because I need it to keep a reliable GPRS connection – ie have no user interaction in the connection process.

    So the problem is that when a GPRS connection is up and running, and the user turns the device off for some period of time, when the device is turned back on the GPRS connection stops, but not necessarily closes. Heres what i mean.

    Now some of this is ok because I can wait a little while – about ten seconds – and the connection will close, then I can start the connection again.

    However, if the device is turned off again a second time, shortly after it has been turned off the first time, the connection will not close properly. In terms of networking, the connection closes – ie I cannot open IE and browse any web pages. But the device thinks the connection is still active, because the connection icon remains in the task bar, and if I try and restart the connection, the connection’s message box appears and tells me that it is still connected.

    So I need some way to force this to stop and be disconnected. Any ideas would be much appreciated.

  8. cenet says:

    Jeremy:  Since the connection was setup manually using RAS API, you can try to use the complementary RAS API to disconnect it.

    Note however that use of RAS APIs on Windows Mobile can lead into problems.  It is recommended that you use Connection Manager (CM) to setup network connectivity for your application.  One problem with connections that are not connected by CM is that they will not be managed by CM, which means that they may be disconnected unexpectedly, be never disconnected, or in certain cases, they may not be usable by other CM aware applications.  [Author:  Adam Dyba]

  9. mario says:

    I developed a program which can connect to WLAN manually by NDIS APIs, and I also disabled WZCSVC in WM5.0. The program can associate to AP and get IP from DHCP server. Then, the PDA phone can ping some IPs and download files from FTP server via WLAN connection. But when I run IE and try to open URLs, windows still try to make DialUp connection to browse the URL even there is already a WLAN connection. Why? Should I do something in Connection Manager (CM) after connecting to AP? Or is there anything I missed? Any idea would be much appreciated.

  10. Kapil says:

    Nice crisp information about CM. I have few queries.

    If I want a seamless connectivity for applications especially for a call, can I switch between VoWLAN and VoGSM/GPRS (CellCore) seamlessly? Can CM handle the case where it finds WiFi connection available and switches the call (which was over GSM/3G) to WiFi? Basically I want to know if CM maintains the network connections information statically or dynamically? Any pointers in this direction will be of great help.

  11. cenet says:

    mario:  It sounds like CM doesn’t know about your is not provisioned with settings for your NDIS adapter.  Typically, the task of provisioning a NDIS adapter is handled by the Shell when it sees it being initialized.  It is possible that Shell has not been notified of the adapter being initialized.  Couple things to try:  1. Can you confirm that the adapter is bound to NDISUIO?  2. Provision the adapter with CM manually using XML configuration for CM_NetEntries, ex.:

       <wap-provisioningdoc>
          <characteristic type=”CM_NetEntries”>
             <characteristic type=”My NDIS adapter”>
                <parm name=”DestId” value=”<destination_metanetwork>”/>
                <parm name=”Adapter” value=”<ndis_adapter_name>”/>
                <parm name=”Desc.Default” value=”<description>”/>
             </characteristic>
          </characteristic>
       </wap-provisioningdoc>

    Note that <destination_metanetwork> (meta-network to which the adapter connects, ex. {436EF144-B4FB-4863-A041-8F905A62C572} for “The Internet”), <ndis_adapter_name> (the adapter name as exposed to NDIS) and <description> (any string) are required fields.  [Author:  Adam Dyba]

  12. cenet says:

    Kapil:  Yes, CM dynamically tracks the state of all connections that it has been provisioned with.  As new connections become available (ex. WiFi is connected to some SSID, a GPRS APN is provisioned), CM will make these connections available to applications.  However, once an application’s connection request (CR) is connected over a certain connection, CM will not dynamically transition the CR to a better connection when it becomes available at some later point in time.  Instead, it is up to the application to recognize that a new connection is available, close its existing CR, and recreate it.  CM will ensure that the new CR is connected over the best connection available at the given point in time.  Application can use ConnMgrRegisterForStatusChangeNotification and ConnMgrQueryDetailedStatus APIs to be notified of status changes and query the status of connections, respectively.  [Author:  Adam Dyba]

  13. alexei says:

    Why does Connection Manager terminates other NDIS adapters once RNDIS interface is up? How can this behavior be disabled?

  14. cenet says:

    alexei:  Beginning with WM 5, CM will disconnect all connections when the Desktop Pass-through (DTPT) connection has been connected, including unbind and power-down NDIS adapters.  This is done as a security precaution to prevent multi-homing while device is connected to a secure network accessible using the DTPT connection.  Beginning with WM 6, ActiveSync on the desktop exposes an option to disable or enable multi-homing support with DTPT.  This behavior is controlled with "Allow wireless connection on device when connected to the desktop" checkbox in ActiveSync’s Connection Settings.  [Author:  Adam Dyba]

  15. vinay_b says:

    How can 3rd party VPN clients interact with Connection manager…? If I am developing a VPN solution, is it possible for me to setup a VPN entry in CM so that my VPN client would get invoked…?

    Thanks,

    Vinay

  16. cenet says:

    vinay:  Yes.  Implement your VPN solution using NDIS WAN miniport driver and use RASDT_Vpn as the device type for the line(s) supported by the miniport.  See more information on implementing the miniport according to the NDIS WAN interface @ http://msdn2.microsoft.com/en-us/library/aa912467.aspx/.  [Author:  Adam Dyba]

  17. Julien says:

    Is it possible to configure a meta-network with 2 different GPRS connections ?

    Will it be able to switch from one to another if necessary ?

    Thanks,

    Julien

  18. mahesh says:

    Plz tell me how to communicate between PDA to PDA using GPRS ?Where can I find APIs for GPRS communication ?

  19. cenet says:

    Julien:  Yes, it is possible to configure more than one GPRS connection leading to the same destination meta-network.  However, CM in choosing use of connections of the same type leading to the same destination network will prefer an already connected connection over a disconnected one, but other than this the choice will be arbitrary.  It is also possible to adjust connection preferences using CM_Planner Configuration Service Provider (CSP), see MSDN for details.

    The switch from use of one connection to another will not be done by CM — such action requires application’s action to deal with disruption of connectivity, including reconnecting sockets.  The switch can be done by the application, for example, by selecting the connection it needs, see ConnMgrMapConRef API.  [Author:  Adam Dyba]

  20. cenet says:

    mahesh:  If both PDAs are connected to the same network, ex. The Internet, then they should be able to reach and communicate with each other.  A complication arises when the two peers are behind a NAT (cellular data connections are typically NATed), in which case they will not be able to reach each other directly.  In this case, they will need to use a server that has a global IP that they can both reach and use to talk with each other across it.  Unfortunately, I’m now aware of a service that exposes this in a simple API set.  [Author:  Adam Dyba]

  21. Bruce says:

    Currently WinMo behavior for PDP context activation is to keep it at always-on, even if all applications have released their connections through Connection Manager.  Is there a way for me to monitor when all connections through the specific APN have been released, then disconnect the data connection manually through the RIL layer?  I tried this with the SuspendResume registry setting, but that would just disconnect my data connection when a phone call came in.  Thanks.

  22. gokros says:

    I have an NDIS miniport driver and a client application. The driver defines a special IP range for other applications running in the OS and is configured to have one adapter. The application has to connect to some servers on the Internet via NOT my miniport driver (adapter), but another possible connection whatever is present (WLAN, GPRS, etc…).

    When the application initializes the miniport driver a Network Entry (CM_NetEntries) is created for the network adapter. My adapter has a very low cost.

    My problem is that when my application requests a connection from CM it gets a connection which is through my network adapter.

    I defined my own Network and Network Entry for my adapter.

    Is it possible to supress the automatic registration of Network Entry for my network adapter?

    How can I increase the cost of my netvork adapter to CM?

    I could use the ConnMgrMapConRef API in my application, but this case I should implement a similar role that Connection Planner does.

  23. disha says:

    can we set a WiFi connection name or GPRS connection name in CM_Planner preferred connection options to choose among WIFI and GPRS (when both are available and connected)

  24. Nick says:

    Cenet: I have been working on a proxy server running locally on a WM6 device in which the connection used varies on the type of content being requested.  For example, when both WiFi and GPRS connections are available, the proxy will use WiFi for mp3 requests and GPRS for html requests.  Is this something I can accomplish with the ConnMgrMapConRef() function and other functions in the ConnectionManager API?  I am developing in C# on .NET Compact Framework.  Also, do you have any example functions of how to determine which connections there are as well as a function that picks one.  Your help is greatly greatly appreciated.  Its taken me three months to find this blog which seems perfect!. Thanks in advance,

    Nick.

  25. cenet says:

    Bruce:  Yes, a connection configured as Suspend/Resume capable will remain connected even after all Connection Requests (CRs) that used it have been released.  This is done for the purpose of avoiding reconnection delays that would be incurred if the connection was disconnected.

    There is no simple means, outside of CM, of detecting that a connection is no longer used by any CR.

    gokros:  Unfortunately, it is not possible to suppress the default configuration of CM_NetEntries entry for your adapter.  However, once it has been configured, it is possible to delete it/replace it using CM_NetEntries configuration service provider.

    disha:  Connected connections are automatically preferred.  In cases where more than one suitable connection exists and is already connected, the selection is based on other properties, ex. if GPRS and WiFi expose connectivity to the same destination meta-network, CM will use WiFi to satisfy CRs, because WiFi typically provides more bandwidth.

    Note that the PreferredConnection parm in CM_Planner configuration service provider exposes means of preferring connections before they are connected.

    Nick:  If I understand your question correctly, it is possible to accomplish what you intend, but it requires some ingenuity.  Consider two options: i) change URL-to-destination-meta-network mappings (CM_Mappings) or ii) reconfigure GPRS (CM_GPRSEntries) and WiFi (CM_NetEntries) connections.  With the latter approach, you could reconfigure both GPRS and WiFi connections to lead to the "Work" meta-network.  Then, configure your proxy as leading from "Work" to "The Internet".  With this configuration, CM would satisfy CRs to "The Internet" over WiFi + proxy, or GPRS + proxy.  Take a look at my more recent blog (“Associating an application with a connection in Connection Manager”) for further hints.

    Thanks all for your many questions, and sorry for taking so long to reply.  [Author:  Adam Dyba]

  26. Nick says:

    Hi Adam.  There seems to be two types of “meta-networks”; the ones you cannot add or delete like “Work” and “The Internet” and then ones you can add in which you can change the settings.  I’ve configured my GPRS and WiFi connections to lead to a network I’ve created called Proxy.  I think I understand everything up to here (besides the fact that I can’t actually connect them directly to ‘Work’).  But when you say configure your proxy as leading from “Work” to “The Internet”, I’m not quite sure how to do this – in my application I do a connect to “The Internet”?  I can see how this may work. but its quite a strange configuration and I’m not totally clear.

    P.S. I bind sockets using the WiFi endpoint IP and GPRS endpoint IP.  In your more recent blog mentioned above I quote you

    “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.”

    I don’t want CM to choose the best connection, I want to tell it which connection to use.  Can I accomplish this?

  27. Bruce says:

    Thanks for answering my question.  I was wondering about this part of your response:

    “There is no simple means, outside of CM, of detecting that a connection is no longer used by any CR.”

    So is there a way within Connection Manager for me to do this?  Some sort of query or notification?  

  28. cenet says:

    Nick:  To answer your questions, one by one:

    > There seems to be two types of “meta-networks”; the ones you cannot add or delete like “Work” and “The Internet” and then ones you can add in which you can change the settings.

    You can add/delete any meta-network, however doing so to the predefined networks (“Work”, “My Work”, “The Internet”, “My ISP”) may have side-effects on UI behavior.

    > But when you say configure your proxy as leading from “Work” to “The Internet”, I’m not quite sure how to do this – in my application I do a connect to “The Internet”?  

    CM_ProxyEntries, configuration service provider that allows provisioning of proxy connection, exposes two parms, “SrcId” and “DestId”, that describe proxy’s source and destination meta-networks (by meta-network GUID), respectively.  In this way, a proxy can be used to “bridge” the two networks.  So what?  Well, if you have a base connection (a connection that doesn’t have a source meta-network, i.e., connects directly from device, such as WiFi) that has a proxy associated with it, then you can model this in CM configuration as follows: Base Connection (ex. WiFi): {“DestId”=Network_1}, Proxy: {“SrcId”=Network_1, “DestId”=Network_2}.  So, if an application asks to connect to Network_2 and the base connection is chosen by CM, then the application will be told to use the proxy.  If you have a set of connections that need to use the same proxy, then you can configure those connections to lead to the same network, Network_1.  The connectivity UI supports this configuration by using “Work” for Network_1, and “The Internet” for Network_2.  Hopefully this explains why I suggested how to configure the connections to achieve your desired result in my previous response.

    >I don’t want CM to choose the best connection, I want to tell it which connection to use.  Can I accomplish this?

    Use ConnMgrMapConRef, but note its limitations.

    Bruce:  No, whether a connection is used or not is CM’s private knowledge.  [Author:  Adam Dyba]

  29. selva says:

    How can i reterive and change the current NEtwork setting. For ex.  I have three settings ?My work, Internet, My VPN”.

    I want to programatically reterive the current active connection. and change the connection to My VPN if others.

    So, how can i reterive them.  I can able to get the Values of connections using the “CM_NetEntries” xml query.

     

    <<Rajesh>> Unfortunately, RTC does not give you that kind of control. On Windows Mobile, something can be done using connection manager.