RasEnumConnectionsA-Funktion (ras.h)
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.
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 |
|---|---|
|
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 |