CmAcquireConnection (Compact 7)

3/12/2014

This function acquires a connection to use.

Syntax

CM_RESULT CmAcquireConnection(
__in CM_CONNECTION_HANDLE hConnection
);

Parameters

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

See Also

Reference

Connection Manager Connectivity Functions
CM_CONNECTION_STATE
CM_CONNECTION_CONNECT_BEHAVIOR
CM_PRIORITY
CmSetPriority