Funzione RasEnumConnectionsA (ras.h)

Articolo
11/20/2024

La funzione RasEnumConnections elenca tutte le connessioni RAS attive. Restituisce l'handle di ogni connessione e il nome della voce della rubrica telefonica.

Sintassi

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

Parametri

[in, out] unnamedParam1

Puntatore a un buffer che riceve, nell'output, una matrice di strutture RASCONN, una per ogni connessione RAS.

In caso di input, un'applicazione deve impostare il membro dwSize del primo struttura RASCONN nel buffer su sizeof(RASCONN) per identificare la versione della struttura passata.

[in, out] unnamedParam2

Puntatore a una variabile che, in input, contiene le dimensioni, in byte, del buffer specificato da lprasconn.

Nell'output, la funzione imposta questa variabile sul numero di byte necessari per enumerare le connessioni RAS.

nota

Per determinare le dimensioni del buffer necessarie, chiamare RasEnumConnections con lprasconn impostato su NULL. La variabile a cui punta lpcb deve essere impostata su zero. La funzione restituirà le dimensioni del buffer necessarie in lpcb e un codice di errore di ERROR_BUFFER_TOO_SMALL.

[out] unnamedParam3

Puntatore a una variabile che riceve il numero di strutture RASCONN scritte nel buffer specificato da lprasconn.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito proviene da codici di errore di routing e accesso remoto o Winerror.h.

Codice restituito	Descrizione
ERROR_BUFFER_TOO_SMALL	Il buffer lprasconn non è sufficientemente grande. Il parametro lpcb è minore del membro dwSize nel parametro lprasconn che deve essere impostato prima di chiamare la funzione. La funzione restituisce la dimensione del buffer richiesta nella variabile a cui punta lpcb.

Osservazioni

Se è stata stabilita una connessione senza specificare un nome di immissione della rubrica telefonica, le informazioni restituite per tale connessione assegnano il numero di telefono di connessione preceduto da ".".

Il codice di esempio seguente usa RasEnumConnections per enumerare le connessioni RAS attive.

#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 non è possibile enumerare una connessione come active fino a quando RAS non è stato connesso correttamente.

Windows Me/98/95: RasEnumConnections enumera una connessione come Active non appena inizia la composizione.

Il modo più affidabile per enumerare e verificare la presenza di una connessione attiva consiste nel chiamare RasEnumConnections o RasDial per ottenere un handle di connessione, quindi chiamare RasGetConnectStatus per determinare lo stato di connessione effettivo.

Nota

L'intestazione ras.h definisce RasEnumConnections come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	ras.h
libreria	Rasapi32.lib
dll	Rasapi32.dll

Vedere anche

RASCONN

RasEnumEntries

RasGetConnectStatus

Panoramica servizio di accesso remoto (RAS)

funzioni del servizio accesso remoto

Condividi tramite