RasEnumConnections

DWORD RasEnumConnections(
  _Inout_ LPRASCONN lprasconn,
  _Inout_ LPDWORD   lpcb,
  _Out_   LPDWORD   lpcConnections
);

说明

该函数列出所有活动的RAS连接，包含连接句柄和电话簿条目名称。

参数

lprasconn [in, out]

指向一个RASCONN结构数组，用于接收所有活动连接的信息，每个数组成员代表一个连接。

输入该参数时，必须设置第一个结构的dwSize成员值为sizeof(RASCONN)。

lpcb [in, out]

作为输入参数，指示lprasconn参数指向的缓冲大小字节数。
作为输出参数，该函数设置参数值为实际需要的缓冲字节数。

注意 设置参数lprasconn=NULL用于计算枚举连接需要的缓冲字节数，调用函数前应把lpcb指向的变量设置为0。函数返回时将设置lpcb指向的变量为实际需要的缓冲字节数，同时返回错误代码ERROR_BUFFER_TOO_SMALL。

lpcConnections [out]

指向一个变量用于接收枚举到的连接数量。

返回值

成功时返回ERROR_SUCCESS。
失败时返回下列表格中的错误码之一或是来自Routing and Remote Access Error Codes或Winerror.h中定义的错误码。

值	含义
ERROR_BUFFER_TOO_SMALL	lprasconn指向的缓冲长度不足

注意事项

如果某个连接不是通过电话簿条目创建的，那么返回的信息中电话号码是一个"."字符。
以下代码示例使用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函数不会枚举此连接。
Windows Me/98/95:连接一旦开始拨号就会被RasEnumConnections函数枚举。

枚举和检查一个活动连接的最可靠办法是，通过RasEnumConnections或RasDial函数获取连接句柄，然后调用RasGetConnectStatus检查连接的状态。

系统支持

客户端最小支持	Windows 2000专业版
服务端最小支持	Windows 2000 Server
Header	Ras.h
Library	Rasapi32.lib
DLL	Rasapi32.dll
Unicode和ANSI名称	RasEnumConnections(Unicode)和RasEnumConnectionsA(ANSI)