RasEnumConnectionsA-Funktion (ras.h)

Artikel
11/20/2024

Die RasEnumConnections Funktion listet alle aktiven RAS-Verbindungen auf. Es gibt den Handle- und Telefonbucheintragsnamen der einzelnen Verbindungen 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 RASCONN- Strukturen empfängt, eine für jede RAS-Verbindung.

Bei eingaben 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

Zeigen Sie auf eine Variable, die bei der Eingabe die Größe des durch lprasconnangegebenen Puffers in Byte enthält.

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

Um die erforderliche Puffergröße zu ermitteln, rufen Sie RasEnumConnections- auf, wobei lprasconn 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 RASCONN- Strukturen empfängt, die in den durch lprasconnangegebenen 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 aus Routing- und Remotezugriffsfehlercodes oder Winerror.h.

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

Bemerkungen

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

Der folgende Codebeispielcode verwendet RasEnumConnections- zum Aufzählen der aktiven RAS-Verbindungen.

#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 keine Verbindung als Active aufzählen, bis RAS erfolgreich verbunden ist.

Windows Me/98/95: RasEnumConnections eine Verbindung aufzählt, sobald Active gestartet wird.

Die zuverlässigste Methode zum Aufzählen und Überprüfen einer aktiven Verbindung besteht darin, RasEnumConnections oder RasDial- aufzurufen, um ein Verbindungshandle abzurufen. Rufen Sie dann RasGetConnectStatus- auf, um den tatsächlichen Verbindungszustand zu ermitteln.

Anmerkung

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

RASCONN-

RasEnumEntries

RasGetConnectStatus-

übersicht über Ras(Remote Access Service)

Remotezugriffsdienstfunktionen

Freigeben über