Функция 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.

При входе приложение должно задать 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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	ras.h
библиотеки	Rasapi32.lib
DLL	Rasapi32.dll

См. также

RASCONN

RasEnumEntries

RasGetConnectStatus

Обзор службы удаленного доступа (RAS)

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

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