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

Статья
11/20/2024

Функция RasEnumEntries содержит все имена записей в телефонной книге удаленного доступа.

Синтаксис

DWORD RasEnumEntriesA(
  [in]      LPCSTR          unnamedParam1,
  [in]      LPCSTR          unnamedParam2,
  [in, out] LPRASENTRYNAMEA unnamedParam3,
  [in, out] LPDWORD         unnamedParam4,
  [out]     LPDWORD         unnamedParam5
);

Параметры

[in] unnamedParam1

Скрытный; должен быть null.

[in] unnamedParam2

Указатель на строку, завершающуюся значением NULL, которая указывает полный путь и имя файла телефонной книги (PBK). Если этот параметр NULL, функция использует текущий файл телефонной книги по умолчанию. Файл телефонной книги по умолчанию — это файл, выбранный пользователем в разделе настройки пользователя свойств диалогового окна "Подключение к сети".

Если этот параметр null, записи перечисляются из всех файлов телефонной книги удаленного доступа в профиле AllUsers и профиле пользователя.

[in, out] unnamedParam3

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

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

[in, out] unnamedParam4

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

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

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

[out] unnamedParam5

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

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

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

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

Ценность	Значение
ERROR_BUFFER_TOO_SMALL	Буфер lprasentryname недостаточно велик. Параметр lpcb меньше элемента dwSize в параметре lprasentryname, который необходимо задать перед вызовом функции. Функция возвращает требуемый размер буфера в переменной, на которую указывает lpcb. Windows Vista или более поздней версии: буфер lprasentryname может иметь значение NULL, а переменная, указываемая на lpcb, может быть равно нулю. Функция вернет требуемый размер буфера в переменной, на которую указывает lpcb.
ERROR_INVALID_SIZE	Значение dwSize в структуре RASENTRYNAME, на которую указывает lprasentryname, указывает версию структуры, которая не поддерживается на текущей платформе. Например, в Windows 95 RasEnumEntries возвращает эту ошибку, если dwSize указывает, что RASENTRYNAME включает dwFlags и szPhonebookPath членов, так как эти члены не поддерживаются в Windows 95 (они поддерживаются только в Windows 2000 и более поздних версиях).
ERROR_NOT_ENOUGH_MEMORY	Функция не могла выделить достаточно памяти для завершения операции.

Замечания

В следующем примере кода перечисляются записи телефонной книги RAS в Windows Vista и более поздних версиях Windows. Код изначально вызывает RasEnumEntries, чтобы получить размер буфера для передачи. Затем код вызывает RasEnumEntries еще раз, чтобы перечислить записи. Обратите внимание, что для второго вызова код задает dwSize член первой RASENTRYNAME в буфере для sizeof(RASENTRYNAME) для указания версии структуры.

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

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS entry names.
        lpRasEntryName = (LPRASENTRYNAME) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasEntryName == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASENTRYNAME structure in the array must contain the structure size
        lpRasEntryName[0].dwSize = sizeof(RASENTRYNAME);
        
        // Call RasEnumEntries to enumerate all RAS entry names
        dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

        // If successful, print the RAS entry names 
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS entry names were found:\n");
            for (DWORD i = 0; i < dwEntries; i++){
                wprintf(L"%s\n", lpRasEntryName[i].szEntryName);
            }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasEntryName);
        lpRasEntryName = NULL;
        return 0;
    }

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

    return 0;
}

Заметка

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

Требования

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

См. также

RASENTRYNAME

RasEnumConnections

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

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

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