nf-ras-rasenumdevicesw.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:ras.RasEnumDevicesW	RasEnumDevicesW function (ras.h)	The RasEnumDevices function returns the name and type of all available RAS-capable devices. (Unicode)	RasEnumDevices RasEnumDevices function [RAS] RasEnumDevicesW _ras_rasenumdevices ras/RasEnumDevices ras/RasEnumDevicesW rras.rasenumdevices	rras\rasenumdevices.htm	RRAS	819f069f-15e7-41b6-9153-4d602be4245d	12/05/2018	RasEnumDevices, RasEnumDevices function [RAS], RasEnumDevicesA, RasEnumDevicesW, _ras_rasenumdevices, ras/RasEnumDevices, ras/RasEnumDevicesA, ras/RasEnumDevicesW, rras.rasenumdevices	ras.h		Windows	Windows 2000 Professional [desktop apps only]	Windows 2000 Server [desktop apps only]				RasEnumDevicesW (Unicode) and RasEnumDevicesA (ANSI)						Rasapi32.lib	Rasapi32.dll		Windows			19H1	RasEnumDevicesW ras/RasEnumDevicesW	c++	APIRef kbSyntax	DllExport	Rasapi32.dll	RasEnumDevices RasEnumDevicesA RasEnumDevicesW

RasEnumDevicesW function

-description

The RasEnumDevices function returns the name and type of all available RAS-capable devices.

-parameters

-param unnamedParam1 [in]

Pointer to a buffer that receives an array of RASDEVINFO structures, one for each RAS-capable device. Before calling the function, set the dwSize member of the first RASDEVINFO structure in the buffer to sizeof(RASDEVINFO) to identify the version of the structure.

-param unnamedParam2 [in, out]

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

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

Note  

To determine the required buffer size, call RasEnumDevices with lpRasDevInfo 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.

 

-param unnamedParam3 [out]

Pointer to a variable that receives the number of RASDEVINFO structures written to the lpRasDevInfo buffer.

-returns

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_BUFFER_TOO_SMALL	The lpRasDevInfo buffer is not large enough. The lpcb parameter is less than the dwSize member in the lpRasDevInfo parameter which should be set prior to calling the function. The function returns the required buffer size in the variable pointed to by lpcb.
ERROR_NOT_ENOUGH_MEMORY	Indicates insufficient memory. The lpRasDevInfo parameter is non-NULL, the lpcb parameter is non-NULL and an internal memory allocation failed. This is possibly due to a low-memory condition.
ERROR_INVALID_PARAMETER	Indicates an invalid parameter value. The lpcb parameter is NULL or the lpcDevices parameter is NULL.
ERROR_INVALID_USER_BUFFER	The address or buffer specified by lpRasDevInfo is invalid. The dwSize member of the lpRasDevInfo parameter does not equal sizeof(RASDEVINFO).

-remarks

The following sample code enumerates the devices on the current machine. The code initially calls RasEnumDevices with a lpRasDevInfo parameter of NULL, to obtain the size of the buffer that should be passed in. The code also sets the dwSize member of the first RASDEVINFO structure to sizeof(RASDEVINFO) to specify the version of the structure.

#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 dwDevices = 0;
    LPRASDEVINFO lpRasDevInfo = NULL;
    
    // Call RasEnumDevices with lpRasDevInfo = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumDevices(lpRasDevInfo, &dwCb, &dwDevices);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS structure(s).
        lpRasDevInfo = (LPRASDEVINFO) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasDevInfo == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASDEVINFO structure in the array must contain the structure size
        lpRasDevInfo[0].dwSize = sizeof(RASDEVINFO);
        
        // Call RasEnumDevices to enumerate RAS devices
        dwRet = RasEnumDevices(lpRasDevInfo, &dwCb, &dwDevices);

        // If successful, print the names of the RAS devices
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS devices were found:\n");
            for (DWORD i = 0; i < dwDevices; i++){
                         wprintf(L"%s\n", lpRasDevInfo[i].szDeviceName);
                  }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasDevInfo);
        lpRasDevInfo = NULL;
        return 0;
    }

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

    return 0;
}

Note

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

-see-also

RASDEVINFO

Remote Access Service (RAS) Overview

Remote Access Service Functions