Поделиться через

Функция RasEnumDevicesA (ras.h)

  • Статья

Функция RasEnumDevices возвращает имя и тип всех доступных устройств с поддержкой RAS.

Синтаксис

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

Параметры

[in] unnamedParam1

Указатель на буфер, который получает массив структур RASDEVINFO , по одному для каждого устройства с поддержкой RAS. Перед вызовом функции задайте для члена dwSize первой структуры RASDEVINFO в буфере значение sizeof(RASDEVINFO), чтобы определить версию структуры.

[in, out] unnamedParam2

Указатель на переменную, которая при входных данных содержит размер буфера lpRasDevInfo в байтах.

На выходе функция задает для этой переменной число байтов, необходимое для перечисления устройств.

Примечание  

Чтобы определить требуемый размер буфера, вызовите RasEnumDevices с параметром lpRasDevInfo со значением NULL. Переменная, на которую указывает lpcb , должна иметь нулевое значение. Функция возвращает требуемый размер буфера в lpcb и код ошибки ERROR_BUFFER_TOO_SMALL.

 

[out] unnamedParam3

Указатель на переменную, которая получает количество структур RASDEVINFO , записанных в буфер lpRasDevInfo .

Возвращаемое значение

Если функция завершается успешно, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается ошибкой, возвращается один из следующих кодов ошибок или значение из кода ошибок маршрутизации и удаленного доступа или Winerror.h.

Значение Значение
ERROR_BUFFER_TOO_SMALL
 Буфер lpRasDevInfo недостаточно велик. Параметр lpcb меньше, чем член dwSize в параметре lpRasDevInfo , который следует задать перед вызовом функции. Функция возвращает требуемый размер буфера в переменной, на которую указывает lpcb.
ERROR_NOT_ENOUGH_MEMORY
 Указывает на нехватку памяти. Параметр lpRasDevInfo имеет значение, отличное от NULL, параметр lpcb — не NULL , и произошел сбой выделения внутренней памяти. Возможно, это связано с нехваткой памяти.
ERROR_INVALID_PARAMETER
 Указывает недопустимое значение параметра. Параметр lpcb имеет значение NULL или параметр lpcDevices имеет значение NULL.
ERROR_INVALID_USER_BUFFER
 Недопустимый адрес или буфер, указанный в lpRasDevInfo . Член dwSize параметра lpRasDevInfo не равен sizeof(RASDEVINFO).

Комментарии

В следующем примере кода перечисляются устройства на текущем компьютере. Код изначально вызывает RasEnumDevices с параметром lpRasDevInfo со значением NULL, чтобы получить размер буфера, который должен быть передан. Код также задает члену dwSize первой структуры RASDEVINFO значение sizeof(RASDEVINFO), чтобы указать версию структуры.

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

Примечание

Заголовок ras.h определяет RasEnumDevices в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header ras.h
Библиотека Rasapi32.lib
DLL Rasapi32.dll

См. также раздел

RASDEVINFO

Общие сведения о службе удаленного доступа (RAS)

Функции службы удаленного доступа