CmAcquireConnection (Compact 2013)

Article
11/04/2015

3/26/2014

This function acquires a connection to use.

Syntax

CM_RESULT CmAcquireConnection(
__in CM_CONNECTION_HANDLE hConnection
);

Parameters

hSession
[in] A pointer to a CM_SESSION_HANDLE.

Return Value

The following table shows possible return values.

Value	Description
CMRE_SUCCESS	The operation completed successfully.
CMRE_INVALID_CONNECTION	The name of the connection is not valid.
CMRE_CONNECTION_ALREADY_ACQUIRED	A connection has already been established in the context of this session.
CMRE_UNEXPECTED	An unexpected failure occurred.

Remarks

Only one connection can be acquired in the context of a single session.

Selected Windows Sockets (Winsock) and Windows Internet (WinINet) APIs can automatically connect a SOCKET or HINTERNET handle to the requested destination host.

Avoiding Synchronization Problems when Establishing a Connection

After you call CmAddConnectionConfig to add a connection, the connection will be in CMCS_DISCONNECTED_UNAVAILABLE state for a short period of time. If during this time CmAcquireConnection is called, it would fail with a general error code. To avoid this problem, wait until the connection is in CMCS_DISCONNECTED state, and then call CmAcquireConnection.

Set Priorities Explicitly when Switching Connections

When you have a CMCB_ALWAYS_CONNECTED connection that is using a unique resource, such as the only Wi-Fi card in the device, and you want to switch to another connection that needs the same resource, you must make sure that your client session has a higher priority than the CMCB_ALWAYS_CONNECTED connection.

A CMCB_ALWAYS_CONNECTED connection has a priority of CM_PRIORITY_BACKGROUND_LOWEST. The default priority of the new connection is lower than that. This means that when you create your session you must explicitly call CmSetPriority with a higher priority than CM_PRIORITY_BACKGROUND_LOWEST.

Requirements

Header	cmnet.h
Library	cmnet.lib