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

  • Статья

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

Требования

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

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

RASENTRYNAME

RasEnumConnections

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

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