CmGetFirstCandidateConnection (Compact 7)

  • Article

3/12/2014

This function gets the first candidate connection that can be used by an application to try to connect to a destination host.

Syntax

CM_RESULT CmGetFirstCandidateConnection(
__in CM_SESSION_HANDLE hSession,
__in const WCHAR* pszHost,
__in CM_CONNECTION_SELECTION_OPTION Option,
__out CM_CONNECTION_HANDLE* phConnection
);

Parameters

  • pszHost
    [in] A pointer to a string value specifying the destination host name or IP address.

    Delimit a name with quotes. For example: "www.microsoft.com". A "*" in the leftmost label of the name will match all FQDN names in the domain. For example: "*.microsoft.com" matches "www.microsoft.com" and "msdn.microsoft.com".

    Delimit an IP address with quotes and square brackets. For example: "[207.46.19.254]". A "/" and a prefix length is used to define a CIDR block of addresses. For example: "[207.46.19.0/24]" or "[2001:0db8:1234::/48]".

  • phConnection
    [in] A pointer to a storage area to place the output.

    [out] A pointer to a CM_SESSION_HANDLE of the first candidate connection.

Return Value

Value Description

CMRE_SUCCESS

The operation completed successfully.

CMRE_INVALID_SESSION

The hSession is not valid.

CMRE_INVALID_PARAMETER

A parameter other than hSession is invalid.

CMRE_OUT_OF_MEMORY

Memory can not be allocated to complete the operation.

CMRE_NO_CONNECTIONS

There are no configured connections that meet the requirements and policies of the caller.

CMRE_UNEXPECTED

An unexpected failure occurred.

Remarks

After the application gets the first candidate connection, the application may then use CmGetNextCandidateConnection to iterate through all connections that meet the requirements and policies of the application.

Selected Winsock and WinInet APIs can automatically connect a SOCKET or HINTERNET handle to the requested destination host.

Requirements

Header

cmnet.h

Library

cmnet.lib

See Also

Reference

Connection Manager Connectivity Functions
CM_CONNECTION_SELECTION_OPTION
CM_SESSION_HANDLE
CmGetNextCandidateConnection