ConnMgrEstablishConnectionSync

Article
08/28/2006

The ConnMgrEstablishConnectionSync function creates a connection request but returns information only after the connection has been established or has failed.

Syntax

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

Parameters

pConnInfo
Pointer to the CONNMGR_CONNECTIONINFO structure, which contains the parameters that describe the requested connection.
phConnection
Pointer to the returned connection handle.
dwTimeout
The time-out value in milliseconds.

pdwStatus
Pointer to the final status value of the connection. The following table lists the possible values of this parameter.

Value	Description
CONNMGR_STATUS_UNKNOWN	The status is unknown.
CONNMGR_STATUS_CONNECTED	The connection is up.
CONNMGR_STATUS_DISCONNECTED	The connection has been disconnected.
CONNMGR_STATUS_WAITINGFORPATH	A path to the destination exists but is not presently available (for example, the device is out of radio range or is not plugged into its cradle).
CONNMGR_STATUS_WAITINGFORRESOURCE	Another client is using resources that this connection requires.
CONNMGR_STATUS_WAITINGFORPHONE	An in-progress voice call is using resources that this connection requires.
CONNMGR_STATUS_WAITINGFORNETWORK	The device is waiting for a task with a higher priority to connect to the network before connecting to the same network. This status value is returned only to clients that specify a priority of CONNMGR_PRIORITY_LOWBKGND when requesting a connection.
CONNMGR_STATUS_NOPATHTODESTINATION	No path to the destination could be found.
CONNMGR_STATUS_CONNECTIONFAILED	The connection failed and cannot be reestablished.
CONNMGR_STATUS_CONNECTIONCANCELED	The user aborted the connection.
CONNMGR_STATUS_CONNECTIONDISABLED	The connection can be made, although the connection is disabled. This value is returned only to clients that set the bDisabled value in the CONNMGR_CONNECTIONINFO structure.
CONNMGR_STATUS_WAITINGCONNECTION	The device is attempting to connect.
CONNMGR_STATUS_WAITINGCONNECTIONABORT	The device is aborting the connection attempt.
CONNMGR_STATUS_WAITINGDISCONNECTION	The connection is being brought down.

Return Values

None of the following values are returned until the connection either has been established or has failed.

S_OK
The connection was successfully requested.
Error code
The connection could not be requested.

Remarks

This function uses ConnMgrEstablishConnection and ConnMgrConnectionStatus internally to attempt to fully establish a connection before returning to the caller. The ConnMgrEstablishConnectionSync function does not provide an internal message pump; therefore, the message queues of any user interface threads that call into this function are blocked until the function returns.

Requirements

Pocket PC: Windows Mobile 2000 and later
OS Versions: Windows CE 3.0 and later
Header: connmgr.h
Library: cellcore.lib