The Connection Manager API consists of about 11 functions, but you only need five of these functions for the tasks of establishing and releasing a network connection. In many cases, your application may require as few as two of these functions. Table 1 shows these five functions.

Table 1. Connection Manager functions used to establish and release a network connection

Function	Description
ConnMgrMapURL	Retrieves the network identifier (Internet or Work) for the specified URL.
ConnMgrEstablishConnection	Selects and establishes the appropriate connection for the specified network identifier. This method returns without waiting for the connection attempt to complete; use ConnMgrConnectionStatus to determine the connection status.
ConnMgrEstablishConnectionSync	Selects and establishes the appropriate connection for the specified network identifier. This method does not return until the connection attempt completes.
ConnMgrReleaseConnection	Releases the specified connection, which may also close the connection.
ConnMgrConnectionStatus	Retrieves the status of the specified connection.

To access these five functions from your .NET Compact Framework application, you will need to include the p/invoke declarations shown in the following code.

When you use the Connection Manager to establish a connection, you must specify the characteristics of the desired connection. In native code you specify these characteristics using a native structure, CONNMGR_CONNECTIONINFO, and several groups of #definemacros. To make the structure more consistent with other features of .NET, you might implement the native structure as a managed class and name the managed class something like ConnMgrConnectionInfo. Rather than representing the macros as constants in .NET, you can create more explicit groupings of the macros by defining each group of related macros as a set of enumeration values.

Several of the structure members rely on the macros, so the first thing to do is define the enumerations that correspond to the macros.

The first enumeration corresponds to the CONNMGR_PARAM_* family of macros. These values identify which of the criteria fields in the structure are valid. The criteria-related fields in the structure specify the desired characteristics of the requested connection. A connection request can specify multiple criteria therefore the enumeration declaration includes the Flagsattribute as shown in the following code. By marking the enumeration with the Flagsattribute, you can bitwise-or the members together.

Each of the enumeration members have the same name as the structure field to which they correspond. The upcoming discussion of the structure definition will address the meanings of each of the fields.

The next enumeration corresponds to the CONNMGR_FLAG_PROXY_* macros. These values specify the types of proxy servers that Connection Manager can use to establish the connection. Like the ConnMgrParamenumeration, this declaration includes the Flagsattribute as shown in the following code.

The next thing to consider when requesting a connection is the priority of the request. The Connection Manager is responsible for all connections on the device and tries to service as many of the requests for those connections as possible. To assist the Connection Manager in determining the order and importance of each request, each request must specify its priority. The Connection Manager supports several different priority levels; however, applications commonly use only a few of these values. The following code shows the enumeration declaration with the commonly used priority values.

Table 2 provides a description of each of these priorities.

Table 2. Common Connection priorities

Priority	Description
UserInteractive	A user-initiated action has requested the connection and the user interface is waiting for the connection. This priority supersedes most other priorities.
HighPriorityBackground	The connection request is of high priority, but the application is in the background and therefore not affecting the user interface.
LowPriorityBackground	The connection request only connects if another higher priority application is already using the requested path. Using this priority, an application may share an existing connection but will not establish a new one.

Connection Manager supports a number of priority values beyond those in the enumeration declaration. The CONNMGR_PRIORITY_* macros in the connmgr.h header file provide the complete list. For a description of the priority values not listed in Table 2, check out Connection Manager Priority Constants .

The last enumeration is for the connection status values. For the most part, the names of each status value are self-explanatory. For a description of each status value, see Connection Manager Status Constants or look at the CONNMGR_STATUS_* macros in the connmgr.h header file. The following code shows the status value enumeration.

With all of the enumerations defined, the next thing to do is understand the connection request structure. As you are likely aware, you can represent a native structure as either a managed structure or a managed class. In general, classes are a little more flexible than structures because classes allow you to provide a default constructor and use member initializers. As mentioned earlier in this article, the ConnMgrConnectionInfomanaged class represents to the CONNMGR_CONNECTIONINFOnative structure. The following code shows the ConnMgrConnectionInfoclass definition.

The description of each of the structure fields is in Table 3.

Table 3. ConnMgrConnectionInfo class members

Field	Description
cbSize	The size of the class in bytes.
dwParams	The list of class criteria fields to consider when selecting the connection. To specify multiple criteria fields, use a bitwise-or to combine multiple ConnMgrParamenumeration values.
dwFlags	The connection request's proxy requirements.
dwPriority	The connection request's priority.
bExclusive	The connection request's exclusivity; a non-zero value indicates that connection cannot be shared with other applications.
bDisabled	The connection request's indicator whether the Connection Manager should establish the connection; a non-zero value indicates that the Connection Manager should determine if the connection is possible but not actually perform the connection. When the Connection Manager reaches the point where it would normally establish the connection, the Connection Manager sets the connections status to ConnMgrStatus.ConnectionDisabled.
guidDestNet	The connection request's destination expressed as a GUID; if this field is valid the dwParamsfield must contain ConnMgrParam.GuidDestNet.
hWnd	The handle of the window to send status change messages; this will normally be the handle of a MessageWindow-derived class.
uMsg	The message to send to the window identified by the hWndfield when sending status change messages; this field is only valid if the hWndfield is set to a valid window handle.
lParam	A value to include in the status change message sent to the window identified by the hWndfield; this field is only valid if the hWndfield is set to a valid window handle. Use this field to include application-specific data in the status change message.
ulMaxCost	The maximum acceptable cost of the connection; if this field is valid the dwParamsfield must contain ConnMgrParam.MaxCost(most applications can ignore this field).
ulMinRcvBw	The minimum acceptable reception bandwidth of the connection; if this field is valid the dwParamsfield must contain ConnMgrParam.MinRcvBw(most applications can ignore this field).
ulMaxConnLatency	The maximum acceptable connection latency expressed in milliseconds; if this field is valid the dwParamsfield must contain ConnMgrParam.MaxConnLatency(most applications can ignore this field).

To simplify working with the ConnMgrConnectionInfoclass, the class definition includes a couple of constructors that take care of some common situations. First is the default constructor, which is shown in the following code example.

Before passing the ConnMgrConnectionInfoclass to any of the Connection Manager functions, the size of the class must be stored in the cbSizemember so this constructor automatically stores the class size in cbSizeas part of the class construction.

Although the ConnMgrConnectionInfoclass has several members, applications often need to set only the destination, the priority, and if needed, the proxy; to include the destination in the connection request criteria the dwParamsmember is set to ConnMgrParam.GuidDestNet. The constructor shown in the following code handles this situation.

For convenience, the class contains two other constructors that represent common situations. The first accepts the destination and priority, and sets the connection criteria to indicate that no proxy is necessary. The second accepts the destination and sets the connection request priority to ConnMgrPriority.UserInteractive, which is the priority of a connection for which the application user interface is waiting.

The first step to establishing a connection is to identify whether your application needs to connect to the Internet or your Work network. Each network destination has a specific GUID. The GUID for the Internet is 436EF144-B4FB-4863-A041-8F905A62C572. The GUID for your Work network is A1182988-0D73-439e-87AD-2A5B369F808B.

Although the GUIDs for each of the network destinations are well known, most applications do not use the GUIDs directly. Instead you can use the ConnMgrMapURLfunction to determine the appropriate network GUID.

The Connection Manager encapsulates the logic to determine which network a specific URL requires. So rather than hard-code a specific network GUID in your application, you simply pass the destination URL to the ConnMgrMapURLfunction and the function returns the appropriate GUID.

The following code shows an example of using the ConnMgrMapURLfunction to determine the destination GUIDs for different URLs.

In the sample, there are two URLs. The first URL points to a location on Microsoft's MSDN® Web site, which is of course on the Internet. The other URL points to one of the computers on the internal network and therefore is located on the Work network. Figure 1 shows the information that appears in the Visual Studio Output window when you run this code. As you can see, the Microsoft URL returns the Internet GUID (436EF144-B4FB-4863-A041-8F905A62C572) whereas the URL pointing the internal network returns the Work GUID (A1182988-0D73-439e-87AD-2A5B369F808B).

Figure 1. The destination network identifiers for an Internet URL and a Work URL

Thanks to the ConnMgrMapURLfunction, this may be the last time you ever have to see those GUIDs. In the future, you can just let the ConnMgrMapURLfunction figure out the GUIDs for you.

From this point, making the connection simply requires you to create an instance of the ConnMgrConnectionInfoclass with the appropriate connection criteria, and call the appropriate Connection Manager function.

When you make the connection request you can use either the ConnMgrEstablishConnectionSyncfunction, which blocks until the connection process completes or you can use the ConnMgrEstablishConnectionfunction, which returns immediately and establishes the connection without requiring the calling thread to wait for the connection process to complete. If your application is running in the background or if you are establishing the connection on a background thread, the ConnMgrEstablishConnectionSyncfunction is easy to work with because you know as soon as the function returns whether you have successfully established a connection. The following code sample demonstrates using the ConnMgrEstablishConnectionSyncfunction to establish a connection.

Notice that the preceding code passes a timeout value to the ConnMgrEstablishConnectionSyncfunction. You should provide a substantial value for the timeout because establishing connections, especially in places with poor network coverage, can sometimes take many tens of seconds. If the function returns because the timeout expires, as opposed to because of a connection error, the status value is ConnMgrStatus.WaitingConnection. When you receive the ConnMgrStatus.WaitingConnectionstatus value, chances are that the connection could have succeeded given enough time; therefore, you should try to make the connection using a longer timeout value.

To test the preceding connection code, use the Windows Mobile 6 Professional Device Emulator and Cellular Emulator. The Cellular Emulator acts as a virtual cellular radio for the Device Emulator providing the Device Emulator with General Radio Packet Service (GPRS) connectivity. To get started, you must first connect the Device Emulator to the Cellular Emulator by following the instructions in the Cellular Emulator section of the Developer's Guide to the Arm Emulator .

You also need to define GPRS connections for the emulator. This is the same process you follow to define a GPRS connection on a physical device to connect to your service provider's network. Follow these steps to define the GPRS Internet connection.

1. Within the Device Emulator select Start, and then select Settings.
   
   
2. On the Settingsscreen, select the Connectionstab.
   
   
3. Select the Connectionsicon.
   
   
4. On the Connectionsscreen, select Add a new modem connectionimmediately below the heading My ISP.
   
   
5. Name the connection GPRS Internet. The name has no affect on the connection behavior.
   
   
6. Select Cellular (GPRS)from the Select a modemdrop-down list.
   
   
7. Select Next.
   
   
8. Leave the Access point namefield blank and select Next.
   
   
9. Leave all of the fields blank (User name, Password, Domain) and select Finish.
   
   

You now have a GPRS connection defined for the Internet. To define a GPRS connection for your Work network, follow these same steps except this time in step 4 select Add a new modem connectionimmediately under My Work Network, and in step 5 name the connection GPRS Work.

When you run the preceding code, you should notice that after a few seconds the Cellular Emulator shows activity on one of the Network Channels as shown in Figure 2.

Figure 2. The Cellular Emulator with an active GPRS connection

A few seconds after the Cellular Emulator shows activity, the ConnMgrEstablishConnectionSyncfunction should return. You always want to check the returned status value to verify that the connection is successful. A successful connection returns a status of ConnMgrStatus.Connected.

Because the ConnMgrEstablishConnectionSyncfunction blocks until the connection process is complete, it is not appropriate for connections that your application initiates on the main thread of a user-oriented application. Using the ConnMgrEstablishConnectionSyncfunction in this way will cause your application user interface to freeze until the connection request completes. To avoid freezing the application user interface, use the ConnMgrEstablishConnectionfunction. The ConnMgrEstablishConnectionfunction does not wait for the connection process to complete but rather initiates the connection request then returns immediately. As the following code shows, calling the ConnMgrEstablishConnectionfunction is very much like calling the ConnMgrEstablishConnectionSyncfunction.

The call to the ConnMgrEstablishConnectionfunction in the preceding code initiates the connection process but returns before the Connection Manager actually establishes the connection. To determine when the connection completes, you can use the SystemStateclass in conjunction with the ConnMgrConnectionStatusfunction.

The following code shows how to set up the SystemStateclass to notify your application when the number of active connections changes.

In the preceding code, the program constructs the _connectionsCountinstance and associates it with the ConnectionsCountstate value. By then associating the ConnectionsCount_Changedmethod with the _connectionsCount.Changedevent, the _connectionsCountinstance will call the ConnectionsCount_Changedmethod anytime the number of active connections changes.

Once you know that the number of active connections has changed, you need to determine if the change is caused by the connection you requested. The following code demonstrates using the ConnMgrConnectionStatusfunction to determine if that change is caused by successfully establishing the connection you requested in your earlier call to the ConnMgrEstablishConnectionfunction.

As you can see in the preceding code, if the connection status is ConnMgrStatus.Connected, you know your connection is ready and you can begin using it. One thing to keep in mind is that the system calls the ConnectionsCount_Changedmethod on the main application thread; therefore, you do not want to perform any long-running tasks from within this method. Instead you should perform the task either on a background thread or by using an asynchronous method such as the SqlCeReplicationclass' BeginSynchronizemethod.

You can test this code using the Device Emulator and Cellular Emulator just as you did earlier when testing the ConnMgrEstablishConnectionSyncfunction.

The process of releasing a connection is pretty straightforward. For the most part, you simply the call the ConnMgrReleaseConnectionfunction passing the connection handle returned from either the ConnMgrEstablishConnectionSyncfunction or the ConnMgrEstablishConnectionfunction. The ConnMgrReleaseConnectionfunction signals the Connection Manager that your application is done with the connection but the function does not necessarily close it. To understand when connections are actually closed, you need to understand the affect of the ConnMgrReleaseConnectionfunction's cacheparameter and how the Connection Manager manages connection caching.

Caching the Connection

As you know, establishing a connection can be time consuming. To avoid the overhead of re-establishing the same connection repeatedly, the Connection Manager may maintain a connection even after the last application has released the connection. This is known as connection caching. Applications can influence the length of time the Connection Manager caches a connection through the cacheparameter of the ConnMgrReleaseConnectionfunction but the Connection Manager has ultimate authority. Table 4 shows the list of possible cacheparameter values and their meaning.

Table 4. ConnMgrReleaseConnection cache parameter values

Parameter Value	Description
0	Do not cache the connection
1	Cache the connection for the default amount of time
Greater than 1	Cache the connection for this number of seconds

As shown in Table 4, you can request that the Connection Manager close the connection immediately by passing a cacheparameter value of 0. To request that the Connection Manager cache the connection for the default period of time, pass a cacheparameter value of 1 as shown in the following code sample.

	Copy Code
// Release the connection and cache it for the default time period. ConnMgrReleaseConnection(_connectionHandle, 1);

The default connection cache times are defined as named values in the registry under the HKEY_LOCAL_MACHINE\Comm\ConnMgr\Planner\Settingsregistry key. The default cache time for a connection depends on whether the connection is created as an exclusive connection. The CacheTimenamed registry value defines the default cache time for non-exclusive connections. The CacheTimenamed registry value is set to 600 seconds (10 minutes) on most devices. For exclusive connections, the VPNCacheTimenamed registry value defines the cache time, which is 60 seconds (1 minute) on most devices.

Note:
An exclusive connection is a connection that cannot be used by any application other than the application that creates the connection. You create an exclusive connection by setting the ConnMgrConnectionInfo.bExclusivefield to a non-zero value. In most cases, you can make most efficient use of device resources by allowing connections to be shared (that is, non-exclusive).

Prior to Windows Mobile 5.0, an application could only specify whether or not a connection was cached. With Windows Mobile 5.0 and continuing with Windows Mobile 6, you can specify the amount of time you would like the Connection Manager to cache the connection. You do this by simply passing the desired number of seconds to cache the connection rather than passing a 0 or a 1 to the cacheparameter. For example, the following code shows how to release the connection and request that the Connection Manager cache the connection for 5 minutes (300 seconds).

	Copy Code
// Release the connection and cache it for 5 minutes. ConnMgrReleaseConnection(_connectionHandle, 300);

You should always remember that the value that your application passes to the ConnMgrReleaseConnectionfunction's cacheparameter is simply a request. The Connection Manager may choose to ignore that request. Most commonly when the Connection Manager overrides your caching request, the Connection Manager keeps the connection cached longer than requested. One case where this happens is when the device has a constant connection, such as when connected to the network via Ethernet cable or when the device is cradled and is using desktop pass-through networking through ActiveSync. In these types of connections, the actual network connection is established physically through a network cable or by a cradled device; they remain connected until physically disconnected. The Connection Manager manages these connections but does not actually open or close them.

Another case where the Connection Manager may cache the connection longer than your application requests is when there is no cost to maintaining the connection. The most common example is a GPRS connection. GPRS radios do not consume power except when actually transferring data, and in most cases mobile operators bill GPRS connections based on data transfer volume not the amount of time connected.

You can see the Connection Manager's caching behavior of GPRS connections with the Cellular Emulator. To do so, verify that the Device Emulator and Cellular Emulator are still properly connected. If the Cellular Emulator still has an active connection, close the connection by clicking Disconnect GPRSon the Cellular Emulator's Networktab. Now run the following code.

Copy Code

Guid networkGuid = Guid.Empty; ConnMgrStatus status = ConnMgrStatus.Unknown; ConnMgrMapURL(url, ref networkGuid, 0); ConnMgrConnectionInfo info = new ConnMgrConnectionInfo(networkGuid, ConnMgrPriority.HighPriorityBackground); Debug.WriteLine ("Attempting Sync Connect"); ConnMgrEstablishConnectionSync(info, ref _connectionHandle, _syncConnectTimeOut, ref status); if (status == ConnMgrStatus.Connected) ConnMgrReleaseConnection(_connectionHandle, 0); else Debug.WriteLine("Connection failed: " + status.ToString());

The preceding code is the code from the earlier ConnMgrEstablishConnectionSyncfunction example code with a call to the ConnMgrReleaseConnectionfunction added at the end. Notice that the call to the ConnMgrReleaseConnectionfunction passes 0 to the cacheparameter requesting that the Connection Manager immediately close the connection.

When you run the code, you will notice that the Cellular Emulator shows that the connection becomes active just as it did previously. Notice though that the connection never terminates; the value in the Time(s)column keeps incrementing. The connection remains established but it is not transferring any data, and on a real device it does not consume any power in this state. The Connection Manager is overriding the request to not cache the connection but doing so does not consume any significant resources.

This type of connection is sometimes called a suspend/resume connection indicating that when not in use, the connection can remain connected but go into an efficient suspended state. This GPRS connection may remain connected indefinitely but will not be active until the Connection Manager returns the connection to an application and the application uses it.