RasEnumConnectionsA 函数（ras.h）

项目
11/20/2024

RasEnumConnections 函数列出了所有活动的 RAS 连接。它返回每个连接的句柄和电话簿条目名称。

语法

DWORD RasEnumConnectionsA(
  [in, out] LPRASCONNA unnamedParam1,
  [in, out] LPDWORD    unnamedParam2,
  [out]     LPDWORD    unnamedParam3
);

参数

[in, out] unnamedParam1

指向在输出上接收 RASCONN 结构的缓冲区的指针，每个 RAS 连接都有一个。

在输入时，应用程序必须将缓冲区中第一个 RASCONN 结构的 dwSize 成员设置为 sizeof（RASCONN），以便标识要传递的结构的版本。

[in, out] unnamedParam2

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

在输出中，该函数将此变量设置为枚举 RAS 连接所需的字节数。

注释

若要确定所需的缓冲区大小，请调用 RasEnumConnections，并将 lprasconn 设置为 NULL。 l 指向的变量应设置为零。该函数将返回 l 中所需的缓冲区大小，并返回 ERROR_BUFFER_TOO_SMALL的错误代码。

[out] unnamedParam3

指向一个变量的指针，该变量接收写入 lprasconn指定的缓冲区 RASCONN 结构的数目。

返回值

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

如果函数失败，则返回值来自路由和远程访问错误代码或 Winerror.h。

返回代码	描述
ERROR_BUFFER_TOO_SMALL	lprasconn 缓冲区不够大。 l 参数小于 lprasconn 参数中 dwSize 成员，该参数应在调用函数之前设置。该函数返回 l指向的变量中所需的缓冲区大小。

言论

如果在未指定电话簿条目名称的情况下建立连接，则为该连接返回的信息会提供前面有“.”的连接电话号码。

下面的代码示例代码使用 RasEnumConnections 枚举活动 RAS 连接。

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

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS structure(s).
        lpRasConn = (LPRASCONN) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasConn == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASCONN structure in the array must contain the RASCONN structure size
        lpRasConn[0].dwSize = sizeof(RASCONN);
        
        // Call RasEnumConnections to enumerate active connections
        dwRet = RasEnumConnections(lpRasConn, &dwCb, &dwConnections);

        // If successful, print the names of the active connections.
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS connections are currently active:\n");
            for (DWORD i = 0; i < dwConnections; i++){
                         wprintf(L"%s\n", lpRasConn[i].szEntryName);
                  }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasConn);
        lpRasConn = NULL;
        return 0;
    }

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

    return 0;
}

RasEnumConnections 在 RAS 成功连接之前，无法将连接枚举为活动。

Windows Me/98/95：RasEnumConnections 在开始拨号时将连接枚举为 Active。

枚举和检查活动连接的最可靠方法是调用 RasEnumConnections 或 RasDial 以获取连接句柄，然后调用 RasGetConnectStatus 来确定实际连接状态。

注意

ras.h 标头将 RasEnumConnections 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。

要求

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