RasGetSubEntryHandleW function (ras.h)

Article
02/22/2024

The RasGetSubEntryHandle function retrieves a connection handle for a specified subentry of a multilink connection.

Syntax

DWORD RasGetSubEntryHandleW(
  [in]  HRASCONN   unnamedParam1,
  [in]  DWORD      unnamedParam2,
  [out] LPHRASCONN unnamedParam3
);

Parameters

[in] unnamedParam1

Specifies the HRASCONN connection handle returned by the RasDial function for a multilink phone-book entry.

[in] unnamedParam2

Specifies a valid subentry index for the phone-book entry.

[out] unnamedParam3

Pointer to the HRASCONN variable that receives a connection handle that represents the subentry connection.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes or a value from Routing and Remote Access Error Codes or Winerror.h.

Value	Meaning
ERROR_INVALID_HANDLE	The hRasConn connection handle does not represent a connected phone-book entry.
ERROR_PORT_NOT_OPEN	The hRasConn and dwSubEntry parameters are valid, but the specified subentry is not connected.
ERROR_NO_MORE_ITEMS	The value specified by dwSubEntry exceeds the maximum number of subentries for the phone-book entry.

Remarks

The connection handle specified in the hRasConn parameter refers to the entire multilink connection, but the connection handle returned in the *lphRasConn parameter refers only to the subentry connection. Use the subentry connection handle in any function that accepts an hRasConn parameter, including the RasHangUp, RasGetConnectStatus, and RasGetProjectionInfoEx functions. The projection information returned by RasGetProjectionInfo for a multilink entry is the same for the each of the subentry connection handles as it is for the main connection handle.

You can call RasHangUp on the handle returned by RasGetSubEntryHandle to terminate a single link in a multi-link connection. However, you cannot use RasGetConnectStatus to determine if the link terminated; RasGetConnectStatus may not return ERROR_INVALID_HANDLE even though the link terminated successfully.

Note

The ras.h header defines RasGetSubEntryHandle as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	ras.h
Library	Rasapi32.lib
DLL	Rasapi32.dll