Функция 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.
| Значение | Значение |
|---|---|
|
Буфер lprasentryname недостаточно велик. Параметр lpcb меньше, чем член dwSize в параметре lprasentryname , который следует задать перед вызовом функции. Функция возвращает требуемый размер буфера в переменной, на которую указывает lpcb.
Windows Vista или более поздней версии: Буферу lprasentryname может быть присвоено значение NULL, а переменной, на которую указывает lpcb, — нулевое значение. Функция возвращает требуемый размер буфера в переменной, на которую указывает lpcb. |
|
Значение dwSize в структуре RASENTRYNAME , на которую указывает lprasentryname, указывает версию структуры, которая не поддерживается на текущей платформе. Например, в Windows 95 RasEnumEntries возвращает эту ошибку , если dwSize указывает, что RASENTRYNAME включает элементы dwFlags и szPhonebookPath , так как эти элементы не поддерживаются в Windows 95 (они поддерживаются только в Windows 2000 и более поздних версиях). |
|
Функции не удалось выделить достаточный объем памяти для завершения операции. |
Комментарии
В следующем примере кода перечисляются записи телефонных книг 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 |