Freigeben über


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
ERROR_BUFFER_TOO_SMALL
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.

ERROR_INVALID_SIZE
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).
ERROR_NOT_ENOUGH_MEMORY
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

Weitere Informationen

RASENTRYNAME

RasEnumConnections

Übersicht über ras (Remote Access Service, RAS)

Funktionen des RAS-Diensts