Establishing and Maintaining Connections

Now that you have the proper network identifier to use for the network location from which you are requesting a resource, you can go ahead and tell Connection Manager to make the connection.

The Connection Manager API currently supports two different functions for establishing a connection to the network:

• Synchronous Mode: To create a connection request that will not return until the connection either is established or returns an error, you can use the ConnMgrEstablishConnectionSync() function.

• Asynchronous Mode: To create a connection request that returns immediately, you can use the ConnMgrEstablishConnection() function. You need to poll the request handle that you are returned in order to find out the current status of the connection.

Regardless of which method you use to establish your network connection, you need to properly fill out a CONNMGR_CONNECTIONINFO structure, which contains the parameters that describe the request. The structure is defined as follows:

typedef struct _CONNMGR_CONNECTIONINFO {
   DWORD cbSize;
   DWORD dwParams;
   DWORD dwFlags;
   DWORD dwPriority;
   BOOL bExclusive;
   BOOL bDisabled;
   GUID guidDestNet;
   HWND hWnd;
   UINT uMsg;
   LPARAM lParam;
   ULONG ulMaxCost;
   ULONG ulMinRcvBw;
   ULONG ulMaxConnLatency;
} CONNMGR_CONNECTIONINFO;

The cbSize member should be set to the size of the CONNMGR_CONNECTIONINFO structure.

The dwParams member contains a list of optional member fields that are set in the structure, and can be a combination of the values shown in Table 7.1.

The dwFlags member defines the list of flags that specify any special properties for establishing the network connection. If no flags are set, the Connection Manager will use a direct IP connection. The dwFlags member should be set to one of the values shown in Table 7.2.

The dwPriority member specifies the priority level of the connection you are requesting. Remember that the Connection Manager needs to delegate various simultaneous network requests among multiple applications. It gives precedence to those that specify a higher priority value. Table 7.3 describes the priority levels that can be used.

The bExclusive member specifies whether the connection can be shared among multiple applications. If you set this value to FALSE, then other programs will be notified when the connection is available. If you set it to TRUE, then you place the connection in a state in which it cannot be shared. Other applications that request to establish a similar connection will fight for the same resource, with the outcome depending on each connection request's priority.

The bDisabled member prevents the connection request from actually establishing a remote connection if set to TRUE. This can be used to test the availability of a network connection.

The guidDestNet member should contain the GUID for the network identifier that will be used to connect to the network. This is the same identifier returned using the ConnMgrMapURL() or ConnMgrEnumDestinations() functions. A remote connection cannot be established without this identifier.

To have the Connection Manager send any changes in the connection status to a window handle, you can use the next three members to set that up. The hWnd member is the window handle that you want to receive messages, uMsg should contain the WM_USER message ID that you want to have sent with the status change, and lParam is a DWORD value that will be placed in the lParam parameter of your message. You can set all three of these members to zero if you don't want the Connection Manager to post any messages to your window.

The ulMaxCost member should specify the maximum cost of the connection.

The ulMinRcvBw member specifies the minimum amount of bandwidth that you need in order to accept the connection.

Finally, the ulMaxConnLatency member should specify the maximum acceptable connection latency, in milliseconds, before a connection fails. An acceptable value for the maximum latency would be around 4 seconds, or 4,000 milliseconds.

Establishing Connections

To create a synchronous connection, you can call the following function:

HRESULT WINAPI ConnMgrEstablishConnectionSync(
   CONNMGR_CONNECTIONINFO *pConnInfo, HANDLE *phConnection,
   DWORD dwTimeout, DWORD *pdwStatus);

The pConnInfo parameter should point to a CONNMGR_CONNECTIONINFO structure that contains the instructions for establishing the connection. This is followed by phConnection, a pointer to the connection handle that you are returned from the function. The dwTimeout parameter should be used to set a timeout value, in milliseconds, which the function will return if a connection cannot be established. Finally, the pdwStatus parameter will point to the final status of the connection.

Don't forget that you need to call the ConnMgrReleaseConnection() function once you are finished using the connection in order to properly free the connection handle.

The following code establishes a synchronous connection:

// Establish a synchronous connection
HANDLE hConnection = NULL;
DWORD dwStatus = 0;
DWORD dwTimeout = 5000;

// Get the network information where we want to establish a
// connection
TCHAR tchRemoteUrl[256] = TEXT("\0");
wsprintf(tchRemoteUrl,
  TEXT("http://www.furrygoat.com/index.html"));
GUID guidNetworkObject;
DWORD dwIndex = 0;

if(ConnMgrMapURL(tchRemoteUrl, &guidNetworkObject, &dwIndex)
      == E_FAIL) {
      OutputDebugString(TEXT("Could not map the request to a
         network identifier"));
return FALSE;
}

// Now that we've got the network address, set up the
// connection structure
CONNMGR_CONNECTIONINFO ccInfo;

memset(&ccInfo, 0, sizeof(CONNMGR_CONNECTIONINFO));
ccInfo.cbSize = sizeof(CONNMGR_CONNECTIONINFO);
ccInfo.dwParams = CONNMGR_PARAM_GUIDDESTNET;
ccInfo.dwFlags = CONNMGR_FLAG_PROXY_HTTP;
ccInfo.dwPriority = CONNMGR_PRIORITY_USERINTERACTIVE;
ccInfo.guidDestNet = guidNetworkObject;

// Make the connection request (timeout in 5 seconds)
if(ConnMgrEstablishConnectionSync(&ccInfo, &hConnection,
      dwTimeout, &dwStatus) == E_FAIL) {
      return FALSE;
}

// Connection has been made, continue on...

Creating an asynchronous connection is a bit more involved. To make the connection request, you can use the ConnMgrEstablishConnection() function, which is defined as follows:

HRESULT WINAPI ConnMgrEstablishConnection(
   CONNMGR_CONNECTIONINFO *pConnInfo, HANDLE *phConnection);

The first parameter, pConnInfo, is a pointer to a CONNMGR_CONNECTIONINFO structure that describes the connection. When the function returns, phConnection will point to a connection handle for the request.

When you are finished using the connection, you must properly free the handle by calling the ConnMgrReleaseConnection() function, as described in the section "Disconnecting from an Active Connection," later in this chapter.

The following code polls the request handle for status changes:

  // Establish an asynchronous connection
  HANDLE hConnection = NULL;
  DWORD dwStatus = 0;

  // Get the network information where we want to establish a
  // connection
  TCHAR tchRemoteUrl[256] = TEXT("\0");
  wsprintf(tchRemoteUrl, TEXT("http://www.furrygoat.com/index.html"));
  GUID guidNetworkObject;
  DWORD dwIndex = 0;

  if(ConnMgrMapURL(tchRemoteUrl, &guidNetworkObject, &dwIndex)
        == E_FAIL) {
     OutputDebugString(TEXT("Could not map the request to a
        network identifier"));
     return FALSE;
  }

  // Now that we've got the network address, set up the
  // connection structure
  CONNMGR_CONNECTIONINFO ccInfo;

  memset(&ccInfo, 0, sizeof(CONNMGR_CONNECTIONINFO));
  ccInfo.cbSize = sizeof(CONNMGR_CONNECTIONINFO);
  ccInfo.dwParams = CONNMGR_PARAM_GUIDDESTNET;
  ccInfo.dwPriority = CONNMGR_PRIORITY_USERINTERACTIVE;
  ccInfo.guidDestNet = guidNetworkObject;

  // Make the connection request
  if(ConnMgrEstablishConnection(&ccInfo, &hConnection) ==
        E_FAIL)
     return FALSE;

  // Poll to see if the connection has been established
  BOOL fLoop = TRUE;
  BOOL fConnected = FALSE;

  while(fLoop) {
     dwStatus = 0;
     if(FAILED(ConnMgrConnectionStatus(hConnection,
          &dwStatus))) {
        // Do some error processing here
     fLoop = FALSE;
     break;
  }

  // Got the status, do something with it:
  if(dwStatus & CONNMGR_STATUS_CONNECTED) {
     OutputDebugString(TEXT("Connected!"));
     fLoop = FALSE;
     fConnected = TRUE;
     break;
  }

  if(dwStatus & CONNMGR_STATUS_WAITINGCONNECTION)
     OutputDebugString(TEXT("Establishing a
          connection...."));

  if(dwStatus & CONNMGR_STATUS_DISCONNECTED) {
     OutputDebugString(TEXT("Disconnected from the
          network...."));
     fLoop = FALSE;
   }
}

// Release the handle gracefully
if(!fConnected && hConnection) {
   if(ConnMgrReleaseConnection(hConnection, FALSE) == S_OK)
      hConnection = NULL;
   return FALSE;
}

// Connection has been made, continue on...

Getting the Connection Status

To get the status of a Connection Manager connection, you can use the ConnMgrConnectionStatus() function:

HRESULT WINAPI ConnMgrConnectionStatus(HANDLE hConnection,
   DWORD *pdwStatus);

The function needs only the handle to a current connection, and will return the status code for it in the pointer specified by the pdwStatus parameter.

Table 7.4 shows the possible status values that the Connection Manager can return.

Connection Priorities

One of the Connection Manager's most useful features is its ability to juggle multiple requests, i.e., from more than one application at the same time. When making a connection request for your application, you are required to set its priority level (the dwPriority member of the CONNMGR_CONNECTIONINFO structure). This enables the Connection Manager to effectively schedule the order in which each request is processed?connection requests that have a higher priority are handled before those with a lower one.

Once a connection has been established, you can manually change its priority at any time by calling the ConnMgrSetConnectionPriority() function:

HRESULT WINAPI ConnMgrSetConnectionPriority(HANDLE
   hConnection, DWORD dwPriority);

The first parameter is the request handle you were returned from either the ConnMgrEstablishConnection() or ConnMgrEstablishConnectionSync() function. This is followed by the new priority level you want to set for the request. The list of possible values is the same as the list for the dwPriority member of the CONNMGR_CONNECTIONINFO structure.

A well-behaved application will change its connection priority based on what the user is currently doing on the device. For example, if an application is downloading a Web page, you would want to set the connection to a high-priority level such as CONNMGR_PRIORITY_USERINTERACTIVE. This provides users with a better experience, because they expect an immediate response and high-priority requests are favored by the Connection Manager. However, if a user switches to a different application or is idle for an extended period of time, you will want to switch the level to CONNMGR_PRIORITY_USER_IDLE. A lower priority level enables other processes to more effectively share the connection.

The following code sample shows how to manually change the priority for a connection:

if(FAILED(ConnMgrSetConnectionPriority(hConnection,
   CONNMGR_PRIORITY_USERIDLE))) {
      OutputDebugString(TEXT("Could not change connection
           priority.."));
      return FALSE;
}

Disconnecting from an Active Connection

To close a connection request, you can simply call the following function:

HRESULT WINAPI ConnMgrReleaseConnection(HANDLE hConnection,
  BOOL bCache);

The hConnection parameter should be set to the current connection you want to release. If this is the last request handle that the Connection Manager has for the network type with which you are connected, it will drop the connection; otherwise, it will be left open for any other active requests. The bCache parameter should be set to TRUE if you want the Connection Manager to remember the connection in its cache; otherwise, you should set this to FALSE.