通过

RasEnumDevicesA 函数 (ras.h)

  • 项目

RasEnumDevices 函数返回所有支持 RAS 的可用设备的名称和类型。

语法

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

参数

[in] unnamedParam1

指向接收 RASDEVINFO 结构数组的缓冲区的指针，每个支持 RAS 的设备对应一个。 在调用函数之前，请将缓冲区中第一个 RASDEVINFO 结构的 dwSize 成员设置为 size of (RASDEVINFO) ，以标识结构的版本。

[in, out] unnamedParam2

指向变量的指针，该变量在输入时包含 lpRasDevInfo 缓冲区的大小（以字节为单位）。

在输出时， 函数将此变量设置为枚举设备所需的字节数。

注意  

若要确定所需的缓冲区大小，请在将 lpRasDevInfo 设置为 NULL 的情况下调用 RasEnumDevices。 l 指向的变量应设置为零。 该函数将返回所需的缓冲区大小（以 l ERROR_BUFFER_TOO_SMALL为单位）和错误代码。

 

[out] unnamedParam3

指向一个变量的指针，该变量接收写入 lpRasDevInfo 缓冲区的 RASDEVINFO 结构的数量。

返回值

如果函数成功，则返回值 ERROR_SUCCESS。

如果函数失败，则返回值为以下错误代码之一或 路由和远程访问错误代码 或 Winerror.h 中的值。

值 含义
ERROR_BUFFER_TOO_SMALL
 lpRasDevInfo 缓冲区不够大。 l 参数小于 lpRasDevInfo 参数中的 dwSize 成员，应在调用函数之前设置该成员。 该函数在 ls 指向的变量中返回所需的缓冲区大小。
ERROR_NOT_ENOUGH_MEMORY
 指示内存不足。 lpRasDevInfo 参数为非 NULL，l 参数为非 NULL，内部内存分配失败。 这可能是由于内存不足。
ERROR_INVALID_PARAMETER
 指示无效的参数值。 lpcDevices 参数为 NULL 或 lpcDevices 参数为 NULL。
ERROR_INVALID_USER_BUFFER
 lpRasDevInfo 指定的地址或缓冲区无效。 lpRasDevInfo 参数的 dwSize 成员的大小不等于 (RASDEVINFO) 。

注解

以下示例代码枚举当前计算机上的设备。 代码最初使用 lpRasDevInfo 参数 NULL 调用 RasEnumDevices，以获取应传入的缓冲区的大小。 该代码还将第一个 RASDEVINFO 结构的 dwSize 成员设置为 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 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 ras.h
Library Rasapi32.lib
DLL Rasapi32.dll

另请参阅

RASDEVINFO

远程访问服务 (RAS) 概述

远程访问服务功能