【转】Using Windows Mobile Connection Manager APIs

Connection Manager is a Windows Mobile component that manages and monitors different types of network connections such as PPP, RAS, GPRS, etc… Connection Manager provides a set of native code APIs which can be used to establish voice and data connections. When an application requests a connection, the connection manager determines which is the optimal connection type and establishes the connection. The Connection Manager also tracks which connections are active and disconnect connections which are idle for a given period of time.

The Connection Manager supports two types of destination networks, Internet Network and Work Network. Internet Network is used to connect to the wider internet and Work Network is used to connect to the corporate network directly or through VPN connection. Before using the Connection Manager you have to configure these two network settings.

Following are some of the main parts of Connection Manager:

Connection Manager Application (ConnMgr.exe): When an application request a connection, the Connection Manager application determines the path to the target network. Once the Connection Manager found all the paths it requests the Connection Manager to determine the best connection to the target network. Connection Planner (ConnPlann.dll): Connection Planner is responsible for determine the best path to the target network. Connection Planner uses Connection Manager Configuration Service Providers to find out the cost, bandwidth, etc… before deciding the best connection path. Connection Planner is also responsible for determining the priority of the connection. When a higher priority connection is made and if there is a lower priority connection is active, then Connection Planner disconnects the lower priority connection. Connection Service Providers: These are dynamic link libraries (DLLs) that provide the connection information such as route and cost to the Connection Manager application and store this information. There are different connection service providers such as CSPNet, CSPProxy, CSPRas, CSPVoice, etc…

Connection Manager provides a set of native code APIs for the applications to request and manage network connection. An application can use these APIs to request a connection, register for status notification, etc… Following are some of the important Connection Manager APIs:

 

ConnMgrConnectionStatus	This function retrieves the status of the current connection.
ConnMgrEnumDestinations	This function enumerates available networks.
ConnMgrEstablishConnection	This function creates a connection request.
ConnMgrEstablishConnectionSync	This function creates a connection request.
ConnMgrMapConRef	This function maps a connection reference to its corresponding GUID.
ConnMgrMapURL	This function maps a URL to the GUID of a destination network.
ConnMgrRegisterScheduledConnection	This function registers a scheduled connection.
ConnMgrReleaseConnection	This function deletes a specified connection request, potentially dropping the physical connection.
ConnMgrUnregisterScheduledConnection	This function unregisters a scheduled connection.
ConnMgrRegisterForStatusNotification	Registers a window handle for connection status notifications.

 

For a complete list of Connection Manager APIs refer to the Connection Manager Function documentation

To enumerate the available network details ConnMgrEnumDestinations API is used. The syntax is defined as:

HRESULT WINAPI ConnMgrEnumDestinations(int Index,CONNMGR_DESTINATION_INFO *pDestInfo);

To enumerate all the available networks, an application calls this API with index 0 and increment until the API returns an error.

To establish a connection we can use the API ConnMgrEstablishConnection or ConnMgrEstablishConnectionSync. The syntax of the functions are:

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

The pConnInfo parameter is a pointer to the structure CONNMGR_CONNECTIONINFO and provides the information about the request. ThephConnection parameter receives the handle of the connection when the connection is established. The dwTimeout specifies the timeout in millisecond for the connection establishment. The pdwStatus parameter specifies the status of the connection upon exit.

ConnMgrEstablishConnection is asynchronous in nature. It will request a connection and return immediately. The Connection Manager will post a message to the window handle specified by the hWnd member of the CONNMGR_CONNECTIONINFO structure . The uMsg member specifies what message should be used to send the status change notification. The wParam of the message will be the status of the connection. There are different status values defined in connmgr.h header file which describes the current status of the connection.

ConnMgrEstablishConnectionSync is synchronous in nature. It will request a connection and wait for specified time and return. Upon exit thepdwStatus will have the connection status.

The sample application provided here lists all available networks in a combo box. When connection is requested the selected network is used to establish the connection. The status of the connection will be displayed in a static text box. Hope this gives you an introduction to the Connection Manager APIs.