Windows Mobile 6.5 Connection Manager APIs

In Windows Mobile 6.5, network connectivity was centrally orchestrated by the Connection Manager, an operating system subsystem designed to broker and automate network connections such as cellular data, dial-up, and Virtual Private Networks (VPNs). Rather than manually manipulating modems or Point-to-Point Protocol (PPP) interfaces directly, developers used the Connection Manager API set (connmgr.h) to programmatically initiate, manage, and tear down dial-up and corporate VPN tunnels. This article outlines the key APIs, configuration structures, and workflow required to automate these connections.

Core Connection Functions

The Connection Manager abstracted physical networking layers into logical destination networks (such as the Internet or a Corporate Work Network). To automate connection establishment, developers primarily relied on two functions:

  • ConnMgrEstablishConnection(): An asynchronous function that posts a connection request to the Connection Manager service. It accepts a pointer to a CONNMGR_CONNECTIONINFO structure and returns immediately with a handle (HANDLE phConnection). The operating system handles dialing the phone number or negotiating the PPTP/L2TP VPN handshake in the background, reporting progress via a Windows messaging event or notification handle.
  • ConnMgrEstablishConnectionSync(): A synchronous variant of the establishment API. It blocks the calling thread until the dial-up sequence or VPN tunnel is fully negotiated, timed out, or encountered a failure code (such as CONNMGR_STATUS_CONNECTED or CONNMGR_STATUS_DISCONNECTED).

The CONNMGR_CONNECTIONINFO Structure

Automating specific connection paths required properly populating the CONNMGR_CONNECTIONINFO structure before passing it to the establishment APIs. Key fields include:

  • cbSize: The size of the structure in bytes.
  • dwParams: Bit flags indicating valid parameters (e.g., CONNMGR_PARAM_GUIDDESTNET).
  • dwPriority: The priority of the request (e.g., CONNMGR_PRIORITY_USERINTERACTIVE, CONNMGR_PRIORITY_HIPRIV, or CONNMGR_PRIORITY_VOICE). Priority settings allowed automated tasks to defer to user-facing applications or demand immediate access.
  • guidDestNet: The globally unique identifier representing the destination network. For dial-up to corporate networks or initiating secure VPN connections, developers targeted IID_DestNetCorp (Corporate Network), signaling the OS to evaluate configured VPN and dial-up profiles.

Connection Monitoring and Teardown

Managing automated links required monitoring connection lifecycle states and releasing resources once data transfers concluded:

  • ConnMgrReleaseConnection(): Closes the connection handle. When the final reference to a connection is released, Connection Manager automatically drops the VPN tunnel or hangs up the dial-up call according to OS idle-timeout rules.
  • ConnMgrQueryDetailedStatus(): Returns detailed diagnostic and state information for all active connections, mapping to structures like CONNMGR_CONNECTION_DETAILED_STATUS to expose connection types (such as CM_CONNTYPE_CELLULAR or CM_CONNTYPE_VPN).

Scheduled and Automated Connections

For background tasks requiring periodic syncs without active application execution, the API provided scheduling capabilities:

  • ConnMgrRegisterScheduledConnection(): Configures the operating system to automatically establish a specified dial-up or VPN connection at predefined intervals or upon wake conditions, subsequently launching an application once the path is active.
  • ConnMgrUnregisterScheduledConnection(): Removes automated, scheduled connection triggers from the system registry.

Programmatic Configuration via Configuration Service Providers

While the runtime APIs handled link negotiation, the underlying dial-up numbers, VPN gateways, authentication protocols (PAP, CHAP, MS-CHAPv2), and IPSec credentials were configured via Configuration Service Providers (CSPs). Developers automated this provisioning step using the DMProcessConfigXML() API targeting the CM_PPPEntries and CM_VPNEntries CSPs, ensuring the target endpoints were properly installed in the device registry before calling the runtime ConnMgrEstablishConnection functions.