ConnMgrMapConRef (Windows Embedded CE 6.0)

1/6/2010

This function maps a connection reference to its corresponding GUID.

Syntax

HRESULT WINAPI ConnMgrMapConRef(
  ConnMgrConRefTypeEnum e,
  LPCTSTR               szConRef, 
  GUID                  *pGUID
);

Parameters

• e
  [in] Type of connection reference as defined in the ConnMgrConRefTypeEnum enumeration.

• szConRef
  [in] Connection reference to map. Here are some example connection references:

  • A PPP connection, such as a CSD connection on a GSM or CDMA network
  • A GPRS connection
  • A RAS connection
  • A 1xRTT connection
  • A Desktop Pass-through (DTPT) connection
  • A proxy object
  • A modem connection

• pGUID
  [out] Returned reference GUID for the connection.

Return Values

Returns S_OK if successful or an error code if the function call failed.

Remarks

This function enables you to bypass Connection Planner by explicitly providing a GUID that will map to the connection.

When you use ConnMgrMapConRef, you cannot specify metanetworks such as "Work" or "The Internet" when establishing a connection request. Instead, you must supply the name of the connection (for example, "My GPRS Connection") and use the returned GUID to establish the connection. Connection Manager then uses the connection supplied by the GUID, and not the connection path calculated by Connection Planner.

To use this function, call ConnMgrMapConRef with the szConRef parameter set to the name of the connection reference that you want to map (for example, "My GPRS Connection"). ConnMgrMapConRef returns the GUID of the connection reference using the pGUID parameter. Establish the connection by calling ConnMgrEstablishConnection or ConnMgrEstablishConnectionSync. The pConnInfo parameter of both functions is a pointer to a CONNMGR_CONNECTIONINFO structure. Set the guidDestNet member of the structure pointed to by pConnInfo to the GUID pointed to by pGUID.

When you call ConnMgrEstablishConnection or ConnMgrEstablishConnectionSync with a connection GUID instead of the metanetwork GUID, Connection Planner will use that connection, and only that connection, to satisfy the connection request. Because the connection path calculated by Connection Planner is not used, the connection selection may be less than optimal.

Requirements

See Also

Reference

Connection Manager Functions
ConnMgrConRefTypeEnum
ConnMgrEstablishConnection
ConnMgrEstablishConnectionSync

Other Resources