RasEnumEntriesA-Funktion (ras.h)
Die RasEnumEntries-Funktion listet alle Eintragsnamen in einem Telefonbuch für den Remotezugriff auf.
Syntax
DWORD RasEnumEntriesA(
[in] LPCSTR unnamedParam1,
[in] LPCSTR unnamedParam2,
[in, out] LPRASENTRYNAMEA unnamedParam3,
[in, out] LPDWORD unnamedParam4,
[out] LPDWORD unnamedParam5
);
Parameter
[in] unnamedParam1
Reserviert; muss NULL sein.
[in] unnamedParam2
Zeiger auf eine NULL-endende Zeichenfolge, die den vollständigen Pfad und Dateinamen einer Telefonbuchdatei (PBK) angibt. Wenn dieser Parameter NULL ist, verwendet die Funktion die aktuelle Standardtelefonbuchdatei. Die Standardmäßige Telefonbuchdatei wird vom Benutzer im Eigenschaftenblatt Benutzereinstellungen des DialogfeldsDFÜ-Netzwerk ausgewählt.
Wenn dieser Parameter NULL ist, werden die Einträge aus allen Remotezugriffs-Telefonbuchdateien im AllUsers-Profil und im Profil des Benutzers aufgelistet.
[in, out] unnamedParam3
Zeiger auf einen Puffer, der bei der Ausgabe ein Array von RASENTRYNAME-Strukturen empfängt, eine für jeden Telefonbucheintrag.
Bei der Eingabe muss eine Anwendung den dwSize-Member der ersten RASENTRYNAME-Struktur im Puffer auf sizeof(RASENTRYNAME) festlegen, um die Version der übergebenen Struktur zu identifizieren.
[in, out] unnamedParam4
Zeiger auf eine Variable, die bei der Eingabe die Größe des durch lprasentryname angegebenen Puffers in Bytes enthält.
Zeiger auf eine Variable, die bei der Ausgabe die Größe des Arrays der RASENTRYNAME-Strukturen in Bytes enthält, die für die Telefonbucheinträge erforderlich sind.
Windows Vista oder höher: Um die erforderliche Puffergröße zu bestimmen, rufen Sie RasEnumEntries auf, wobei lprasentryname auf NULL festgelegt ist. Die Variable, auf die von lpcb verwiesen wird, sollte auf 0 (null) festgelegt werden. Die Funktion gibt die erforderliche Puffergröße in lpcb und den Fehlercode ERROR_BUFFER_TOO_SMALL zurück.
[out] unnamedParam5
Zeiger auf eine Variable, die die Anzahl von Telefonbucheinträgen empfängt, die in den durch lprasentryname angegebenen Puffer geschrieben werden.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes oder ein Wert aus Routing- und RAS-Fehlercodes oder Winerror.h.
| Wert | Bedeutung |
|---|---|
|
Der Puffer lprasentryname ist nicht groß genug. Der lpcb-Parameter ist kleiner als der dwSize-Member im lprasentryname-Parameter , der vor dem Aufrufen der Funktion festgelegt werden sollte. Die Funktion gibt die erforderliche Puffergröße in der Variablen zurück, auf die lpcb verweist.
Windows Vista oder höher: Der Puffer lprasentryname kann auf NULL und die Variable, auf die von lpcb verwiesen wird, auf Null festgelegt werden. Die Funktion gibt die erforderliche Puffergröße in der Variablen zurück, auf die lpcb verweist. |
|
Der Wert von dwSize in der RASENTRYNAME-Struktur , auf die von lprasentryname verwiesen wird, gibt eine Version der Struktur an, die auf der aktuellen Plattform nicht unterstützt wird. Unter Windows 95 gibt RasEnumEntries diesen Fehler beispielsweise zurück, wenn dwSize angibt, dass RASENTRYNAME die Member dwFlags und szPhonebookPath enthält, da diese Member unter Windows 95 nicht unterstützt werden (sie werden nur unter Windows 2000 und höher unterstützt). |
|
Die Funktion konnte nicht genügend Arbeitsspeicher zuweisen, um den Vorgang abzuschließen. |
Hinweise
Der folgende Beispielcode listet die RAS-Telefonbucheinträge unter Windows Vista und höheren Versionen von Windows auf. Der Code ruft zunächst RasEnumEntries auf, um die Größe des zu übergebenden Puffers abzurufen. Der Code ruft dann erneut RasEnumEntries auf, um die Einträge aufzulisten. Beachten Sie, dass der Code für den zweiten Aufruf den dwSize-Member der ersten RASENTRYNAME-Struktur im Puffer auf sizeof(RASENTRYNAME) festlegt, um die Strukturversion anzugeben.
#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;
}
Hinweis
Der ras.h-Header definiert RasEnumEntries als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | ras.h |
| Bibliothek | Rasapi32.lib |
| DLL | Rasapi32.dll |