RasGetSubEntryHandleA function (ras.h)

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


DWORD RasGetSubEntryHandleA(
  [in]  HRASCONN   unnamedParam1,
  [in]  DWORD      unnamedParam2,
  [out] LPHRASCONN unnamedParam3


[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
The hRasConn connection handle does not represent a connected phone-book entry.
The hRasConn and dwSubEntry parameters are valid, but the specified subentry is not connected.
The value specified by dwSubEntry exceeds the maximum number of subentries for the phone-book entry.


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.


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.


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

See also





Remote Access Service (RAS) Overview

Remote Access Service Functions