RasEnumDevicesA-Funktion (ras.h)

Artikel
11/20/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 den dwSize Member des 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 eingabe die Größe des lpRasDevInfo- Puffers in Byte enthält.

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

Um die erforderliche Puffergröße zu ermitteln, rufen Sie RasEnumDevices auf, wobei lpRasDevInfo auf NULL-festgelegt ist. Die Variable, auf die durch lpcb verweist, sollte auf Null festgelegt werden. Die Funktion gibt die erforderliche Puffergröße in lpcb- und einen Fehlercode von ERROR_BUFFER_TOO_SMALLzurück.

[out] unnamedParam3

Zeiger auf eine Variable, die die Anzahl der RASDEVINFO- Strukturen empfängt, die in den lpRasDevInfo Puffer 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 Remotezugriffsfehlercodes oder Winerror.h.

Wert	Bedeutung
ERROR_BUFFER_TOO_SMALL	Der lpRasDevInfo Puffer ist nicht groß genug. Der parameter lpcb ist kleiner als der dwSize Member im lpRasDevInfo Parameter, der vor dem Aufrufen der Funktion festgelegt werden soll. Die Funktion gibt die erforderliche Puffergröße in der Variablen zurück, auf die durch lpcbverwiesen wird.
ERROR_NOT_ENOUGH_MEMORY	Gibt nicht genügend Arbeitsspeicher an. Der parameter lpRasDevInfo ist nichtNULL, der lpcb Parameter ist nichtNULL- und eine interne Speicherzuweisung fehlgeschlagen. Dies ist möglicherweise auf einen Zustand mit geringem Arbeitsspeicher zurückzuführen.
ERROR_INVALID_PARAMETER	Gibt einen ungültigen Parameterwert an. Der parameter lpcb ist NULL oder der parameter lpcDevices ist NULL.
ERROR_INVALID_USER_BUFFER	Die durch lpRasDevInfo angegebene Adresse oder der Puffer ist ungültig. Das dwSize Member des lpRasDevInfo Parameter entspricht nicht der Größe(RASDEVINFO).

Bemerkungen

Im folgenden Beispielcode werden die Geräte auf dem aktuellen Computer aufgelistet. Der Code ruft zunächst RasEnumDevices mit einem lpRasDevInfo Parameter von NULL-auf, um die Größe des Puffers abzurufen, der übergeben werden soll. Der Code legt außerdem das dwSize Member des ersten RASDEVINFO Struktur auf größe(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;
}

Anmerkung

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 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
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	ras.h
Library	Rasapi32.lib
DLL-	Rasapi32.dll

Siehe auch

RASDEVINFO

übersicht über Ras(Remote Access Service)

Remotezugriffsdienstfunktionen

Freigeben über