Función RasEnumDevicesA (ras.h)

La función RasEnumDevices devuelve el nombre y el tipo de todos los dispositivos compatibles con RAS disponibles.

Sintaxis

DWORD RasEnumDevicesA(
  [in]      LPRASDEVINFOA unnamedParam1,
  [in, out] LPDWORD       unnamedParam2,
  [out]     LPDWORD       unnamedParam3
);

Parámetros

[in] unnamedParam1

Puntero a un búfer que recibe una matriz de estructuras de RASDEVINFO, una para cada dispositivo compatible con RAS. Antes de llamar a la función, establezca el dwSize miembro del primer estructura de RASDEVINFO del búfer en sizeof(RASDEVINFO) para identificar la versión de la estructura.

[in, out] unnamedParam2

Puntero a una variable que, en la entrada, contiene el tamaño, en bytes, del búfer de lpRasDevInfo.

En la salida, la función establece esta variable en el número de bytes necesarios para enumerar los dispositivos.

nota  

Para determinar el tamaño de búfer necesario, llame a RasEnumDevices con lpRasDevInfo establecido en NULL. La variable a la que apunta lpcb debe establecerse en cero. La función devolverá el tamaño de búfer necesario en lpcb y un código de error de ERROR_BUFFER_TOO_SMALL.

 

[out] unnamedParam3

Puntero a una variable que recibe el número de estructuras de RASDEVINFO escritas en el búfer de lpRasDevInfo de .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error o un valor de Códigos de error de enrutamiento y acceso remoto o Winerror.h.

Valor	Significado
ERROR_BUFFER_TOO_SMALL	El búfer lpRasDevInfo no es lo suficientemente grande. El parámetro lpcb es menor que el miembro dwSize en el parámetro lpRasDevInfo que se debe establecer antes de llamar a la función. La función devuelve el tamaño de búfer necesario en la variable a la que apunta lpcb.
ERROR_NOT_ENOUGH_MEMORY	Indica memoria insuficiente. El parámetro lpRasDevInfo no esNULL, el parámetro lpcb no esnull y se produjo un error en la asignación de memoria interna. Esto es posiblemente debido a una condición de memoria baja.
ERROR_INVALID_PARAMETER	Indica un valor de parámetro no válido. El parámetro lpcb es NULL o el parámetro lpcDevices es NULL.
ERROR_INVALID_USER_BUFFER	La dirección o el búfer especificados por lpRasDevInfo no es válido. El miembro dwSize del parámetro lpRasDevInfo no es igual a sizeof(RASDEVINFO).

Observaciones

En el código de ejemplo siguiente se enumeran los dispositivos de la máquina actual. El código llama inicialmente a RasEnumDevices con un parámetro de lpRasDevInfo de NULL, para obtener el tamaño del búfer que se debe pasar. El código también establece el miembro dwSize del primer RASDEVINFO estructura en sizeof(RASDEVINFO) para especificar la versión de la estructura.

#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;
}

Nota

El encabezado ras.h define RasEnumDevices como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	ras.h
biblioteca de	Rasapi32.lib
DLL de	Rasapi32.dll

Consulte también

RASDEVINFO

información general del servicio de acceso remoto (RAS)

funciones del servicio de acceso remoto