CmGetFirstCandidateConnection (Compact 2013)

3/26/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

• hSession
  [in] A pointer to a CM_SESSION_HANDLE.

• 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]".

• Option
  [in] A CM_CONNECTION_SELECTION_OPTION enumeration value.

• 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

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

See Also

Reference

Connection Manager Connectivity Functions
CM_CONNECTION_SELECTION_OPTION
CM_SESSION_HANDLE
CmGetNextCandidateConnection