RasHangUpA function (ras.h)

Article
02/09/2023

The RasHangUp function terminates a remote access connection. The connection is specified with a RAS connection handle. The function releases all RASAPI32.DLL resources associated with the handle.

Syntax

DWORD RasHangUpA(
  [in] HRASCONN unnamedParam1
);

Parameters

[in] unnamedParam1

Specifies the remote access connection to terminate. This is a handle returned from a previous call to RasDial or RasEnumConnections.

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 handle specified in hrasconn is invalid.

Remarks

The connection is terminated even if the RasDial call has not yet been completed.

After this call, the hrasconn handle can no longer be used.

An application should not call RasHangUp and then immediately exit. The connection state machine needs time to properly terminate. If the system prematurely terminates the state machine, the state machine can fail to properly close a port, leaving the port in an inconsistent state. Also, an immediate attempt to use the same connection may fail leaving the connection unusable. A simple way to avoid these problems is to call Sleep(3000) after returning from RasHangUp; after that pause, the application can exit. A more responsive way to avoid these problems is, after returning from RasHangUp, to call RasGetConnectStatus(hrasconn) and Sleep(0) in a loop until RasGetConnectStatus returns ERROR_INVALID_HANDLE.

You can call RasHangUp on the handle returned by RasGetSubEntryHandle to terminate a single link in a multi-link connection. However, in this case, 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 RasHangUp 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