RasGetSubEntryHandle function

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

Syntax


DWORD RasGetSubEntryHandle(
  _In_  HRASCONN   hRasConn,
  _In_  DWORD      dwSubEntry,
  _Out_ LPHRASCONN lphRasConn
);

Parameters

hRasConn [in]

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

dwSubEntry [in]

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

lphRasConn [out]

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.

ValueMeaning
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 RasGetProjectionInfo 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.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Ras.h

Library

Rasapi32.lib

DLL

Rasapi32.dll

Unicode and ANSI names

RasGetSubEntryHandleW (Unicode) and RasGetSubEntryHandleA (ANSI)

See also

Remote Access Service (RAS) Overview
Remote Access Service Functions
RasDial
RasGetConnectStatus
RasGetProjectionInfo
RasHangUp

 

 

Community Additions

ADD
Show: