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

Функция RasEnumConnections выводит список всех активных подключений RAS. Он возвращает дескриптор каждого подключения и имя записи телефонной книги.

Синтаксис

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

Параметры

[in, out] unnamedParam1

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

На входных данных приложение должно задать для члена dwSize первой структуры RASCONN в буфере значение sizeof(RASCONN), чтобы определить версию передаваемой структуры.

[in, out] unnamedParam2

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

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

Примечание  

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

 

[out] unnamedParam3

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

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

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

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

Код возврата	Описание
ERROR_BUFFER_TOO_SMALL	Буфер lprasconn недостаточно велик. Параметр lpcb меньше, чем член dwSize в параметре lprasconn , который должен быть задан перед вызовом функции. Функция возвращает требуемый размер буфера в переменной, на которую указывает lpcb.

Комментарии

Если подключение было выполнено без указания имени записи в телефонной книге, сведения, возвращаемые для этого подключения, предоставляют номер телефона подключения, перед которым следует ".".

В следующем примере кода используется 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 перечисляет соединение как активное сразу после начала набора номера.

Самый надежный способ перечисления и проверка активного подключения — вызвать RasEnumConnections или RasDial, чтобы получить дескриптор подключения, а затем вызвать RasGetConnectStatus, чтобы определить фактическое состояние подключения.

Примечание

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

Требования

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

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

RASCONN

RasEnumEntries

RasGetConnectStatus

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

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