RasEnumConnectionsA-Funktion (ras.h)

Artikel
08/25/2023

Die RasEnumConnections-Funktion listet alle aktiven RAS-Verbindungen auf. Es gibt den Handle- und Telefonbucheintragsnamen jeder Verbindung zurück.

Syntax

DWORD RasEnumConnectionsA(
  [in, out] LPRASCONNA unnamedParam1,
  [in, out] LPDWORD    unnamedParam2,
  [out]     LPDWORD    unnamedParam3
);

Parameter

[in, out] unnamedParam1

Zeiger auf einen Puffer, der bei der Ausgabe ein Array von RASCONN-Strukturen empfängt, eines für jede RAS-Verbindung.

Bei der Eingabe muss eine Anwendung das dwSize-Member der ersten RASCONN-Struktur im Puffer auf sizeof(RASCONN) festlegen, um die Version der übergebenen Struktur zu identifizieren.

[in, out] unnamedParam2

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

Bei der Ausgabe legt die Funktion diese Variable auf die Anzahl der Bytes fest, die zum Auflisten der RAS-Verbindungen erforderlich sind.

Hinweis

Um die erforderliche Puffergröße zu bestimmen, rufen Sie RasEnumConnections auf, wobei lprasconn 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 RASCONN-Strukturen empfängt, die in den von lprasconn angegebenen Puffer geschrieben wurden.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, stammt der Rückgabewert von Routing- und RAS-Fehlercodes oder Winerror.h.

Rückgabecode	Beschreibung
ERROR_BUFFER_TOO_SMALL	Der Puffer lprasconn ist nicht groß genug. Der lpcb-Parameter ist kleiner als der dwSize-Member im lprasconn-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.

Hinweise

Wenn eine Verbindung hergestellt wurde, ohne den Namen eines Telefonbucheintrags anzugeben, geben die für diese Verbindung zurückgegebenen Informationen die Verbindungstelefonnummer vor "." an.

Der folgende Codebeispielcode verwendet RasEnumConnections , um die aktiven RAS-Verbindungen aufzulisten.

#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 dwConnections = 0;
    LPRASCONN lpRasConn = NULL;
    
    // Call RasEnumConnections with lpRasConn = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumConnections(lpRasConn, &dwCb, &dwConnections);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS structure(s).
        lpRasConn = (LPRASCONN) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasConn == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASCONN structure in the array must contain the RASCONN structure size
        lpRasConn[0].dwSize = sizeof(RASCONN);
        
        // Call RasEnumConnections to enumerate active connections
        dwRet = RasEnumConnections(lpRasConn, &dwCb, &dwConnections);

        // If successful, print the names of the active connections.
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS connections are currently active:\n");
            for (DWORD i = 0; i < dwConnections; i++){
                         wprintf(L"%s\n", lpRasConn[i].szEntryName);
                  }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasConn);
        lpRasConn = NULL;
        return 0;
    }

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

    return 0;
}

RasEnumConnections kann eine Verbindung nicht als Aktiv aufzählen , bis RAS eine Verbindung erfolgreich hergestellt hat.

Windows Me/98/95: RasEnumConnections listet eine Verbindung als aktiv auf, sobald sie mit dem Wählen beginnt.

Die zuverlässigste Methode zum Auflisten und Überprüfen auf eine aktive Verbindung besteht darin , RasEnumConnections oder RasDial aufzurufen, um ein Verbindungshandle zu erhalten, und dann RasGetConnectStatus aufrufen, um den tatsächlichen Verbindungsstatus zu bestimmen.

Hinweis

Der ras.h-Header definiert RasEnumConnections 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