RasEnumDevicesA-Funktion (ras.h)

Artikel
03/04/2024

Die RasEnumDevices-Funktion gibt den Namen und Typ aller verfügbaren RAS-fähigen Geräte zurück.

Syntax

DWORD RasEnumDevicesA(
  [in]      LPRASDEVINFOA unnamedParam1,
  [in, out] LPDWORD       unnamedParam2,
  [out]     LPDWORD       unnamedParam3
);

Parameter

[in] unnamedParam1

Zeiger auf einen Puffer, der ein Array von RASDEVINFO-Strukturen empfängt, eines für jedes RAS-fähige Gerät. Legen Sie vor dem Aufrufen der Funktion das dwSize-Member der ersten RASDEVINFO-Struktur im Puffer auf sizeof(RASDEVINFO) fest, um die Version der Struktur zu identifizieren.

[in, out] unnamedParam2

Zeiger auf eine Variable, die bei der Eingabe die Größe des Puffers lpRasDevInfo in Bytes enthält.

Bei der Ausgabe legt die Funktion diese Variable auf die Anzahl der Bytes fest, die zum Auflisten der Geräte erforderlich sind.

Hinweis

Um die erforderliche Puffergröße zu ermitteln, rufen Sie RasEnumDevices auf , wobei lpRasDevInfo auf NULL festgelegt ist. Die Variable, auf die von lpcb verwiesen wird, sollte auf 0 festgelegt werden. Die Funktion gibt die erforderliche Puffergröße in lpcb und einen Fehlercode von ERROR_BUFFER_TOO_SMALL zurück.

[out] unnamedParam3

Zeiger auf eine Variable, die die Anzahl der RASDEVINFO-Strukturen empfängt, die in den Puffer lpRasDevInfo geschrieben wurden.

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 lpRasDevInfo ist nicht groß genug. Der lpcb-Parameter ist kleiner als der dwSize-Member im lpRasDevInfo-Parameter , der vor dem Aufrufen der Funktion festgelegt werden sollte. Die Funktion gibt die erforderliche Puffergröße in der Variablen zurück, auf die von lpcb verwiesen wird.
ERROR_NOT_ENOUGH_MEMORY	Gibt nicht genügend Arbeitsspeicher an. Der lpRasDevInfo-Parameter ist nicht NULL, der lpcb-Parameter ist nicht NULL , und eine interne Speicherzuordnung ist fehlgeschlagen. Dies ist möglicherweise auf eine unzureichende Arbeitsspeicherbedingung zurückzuführen.
ERROR_INVALID_PARAMETER	Gibt einen ungültigen Parameterwert an. Der lpcb-Parameter ist NULL oder der Parameter lpcDevices ist NULL.
ERROR_INVALID_USER_BUFFER	Die von lpRasDevInfo angegebene Adresse oder der Puffer ist ungültig. Das dwSize-Element des lpRasDevInfo-Parameters ist nicht gleich sizeof(RASDEVINFO).

Hinweise

Der folgende Beispielcode listet die Geräte auf dem aktuellen Computer auf. Der Code ruft zunächst RasEnumDevices mit dem lpRasDevInfo-ParameterNULL auf, um die Größe des Puffers abzurufen, der übergeben werden soll. Der Code legt auch das dwSize-Member der ersten RASDEVINFO-Struktur auf sizeof(RASDEVINFO) fest, um die Version der Struktur 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 dwDevices = 0;
    LPRASDEVINFO lpRasDevInfo = NULL;
    
    // Call RasEnumDevices with lpRasDevInfo = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumDevices(lpRasDevInfo, &dwCb, &dwDevices);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS structure(s).
        lpRasDevInfo = (LPRASDEVINFO) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasDevInfo == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASDEVINFO structure in the array must contain the structure size
        lpRasDevInfo[0].dwSize = sizeof(RASDEVINFO);
        
        // Call RasEnumDevices to enumerate RAS devices
        dwRet = RasEnumDevices(lpRasDevInfo, &dwCb, &dwDevices);

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

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

    return 0;
}

Hinweis

Der ras.h-Header definiert RasEnumDevices 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 nicht codierungsneutralem Code 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

RASDEVINFO

Ras-Dienst (Ras) – Übersicht

Funktionen des RAS-Diensts

Share via