RasEnumConnectionsW function (ras.h)

Article
02/09/2023

The RasEnumConnections function lists all active RAS connections. It returns each connection's handle and phone-book entry name.

Syntax

DWORD RasEnumConnectionsW(
  [in, out] LPRASCONNW unnamedParam1,
  [in, out] LPDWORD    unnamedParam2,
  [out]     LPDWORD    unnamedParam3
);

Parameters

[in, out] unnamedParam1

Pointer to a buffer that receives, on output, an array of RASCONN structures, one for each RAS connection.

On input, an application must set the dwSize member of the first RASCONN structure in the buffer to sizeof(RASCONN) in order to identify the version of the structure being passed.

[in, out] unnamedParam2

Pointer to a variable that, on input, contains the size, in bytes, of the buffer specified by lprasconn.

On output, the function sets this variable to the number of bytes required to enumerate the RAS connections.

Note

To determine the required buffer size, call RasEnumConnections with lprasconn set to NULL. The variable pointed to by lpcb should be set to zero. The function will return the required buffer size in lpcb and an error code of ERROR_BUFFER_TOO_SMALL.

[out] unnamedParam3

Pointer to a variable that receives the number of RASCONN structures written to the buffer specified by lprasconn.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is from Routing and Remote Access Error Codes or Winerror.h.

Return code	Description
ERROR_BUFFER_TOO_SMALL	The lprasconn buffer is not large enough. The lpcb parameter is less than the dwSize member in the lprasconn parameter which is should be set prior to calling the function. The function returns the required buffer size in the variable pointed to by lpcb.

Remarks

If a connection was made without specifying a phone-book entry name, the information returned for that connection gives the connection phone number preceded by ".".

The following code sample code uses RasEnumConnections to enumerates the active RAS connections.

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "raserror.h"
#pragma comment(lib, "rasapi32.lib")

DWORD __cdecl wmain(){

    DWORD dwCb = 0;
    DWORD dwRet = ERROR_SUCCESS;
    DWORD dwConnections = 0;
    LPRASCONN lpRasConn = NULL;
    
    // Call RasEnumConnections with lpRasConn = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumConnections(lpRasConn, &dwCb, &dwConnections);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS structure(s).
        lpRasConn = (LPRASCONN) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasConn == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASCONN structure in the array must contain the RASCONN structure size
        lpRasConn[0].dwSize = sizeof(RASCONN);
        
        // Call RasEnumConnections to enumerate active connections
        dwRet = RasEnumConnections(lpRasConn, &dwCb, &dwConnections);

        // If successful, print the names of the active connections.
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS connections are currently active:\n");
            for (DWORD i = 0; i < dwConnections; i++){
                         wprintf(L"%s\n", lpRasConn[i].szEntryName);
                  }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasConn);
        lpRasConn = NULL;
        return 0;
    }

    // There was either a problem with RAS or there are no connections to enumerate    
    if(dwConnections >= 1){
        wprintf(L"The operation failed to acquire the buffer size.\n");
    }else{
        wprintf(L"There are no active RAS connections.\n");
    }

    return 0;
}

RasEnumConnections cannot enumerate a connection as Active until RAS has successfully connected.

Windows Me/98/95: RasEnumConnections enumerates a connection as Active as soon as it starts dialing.

The most reliable way to enumerate and check for an active connection is to call RasEnumConnections or RasDial to get a connection handle, then call RasGetConnectStatus to determine the actual connection state.

Note

The ras.h header defines RasEnumConnections 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