Función RasEnumDevicesA (ras.h)

  • Artículo

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 RASDEVINFO , una para cada dispositivo compatible con RAS. Antes de llamar a la función, establezca el miembro dwSize de la primera estructura 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 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 RASDEVINFO escritas en el búfer lpRasDevInfo .

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 Enrutamiento y códigos de error de 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 del 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 es NULL, el parámetro lpcb no es NULL 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 son válidos. El miembro dwSize del parámetro lpRasDevInfo no es igual a sizeof(RASDEVINFO).

Comentarios

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 lpRasDevInfo de NULL, para obtener el tamaño del búfer que se debe pasar. El código también establece el miembro dwSize de la primera estructura RASDEVINFO 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado ras.h
Library Rasapi32.lib
Archivo DLL Rasapi32.dll

Consulte también

RASDEVINFO

Información general sobre el servicio de acceso remoto (RAS)

Funciones del Servicio de acceso remoto