Funzione RasEnumDevicesA (ras.h)

Articolo
11/20/2024

La funzione RasEnumDevices restituisce il nome e il tipo di tutti i dispositivi con supporto RAS disponibili.

Sintassi

DWORD RasEnumDevicesA(
  [in]      LPRASDEVINFOA unnamedParam1,
  [in, out] LPDWORD       unnamedParam2,
  [out]     LPDWORD       unnamedParam3
);

Parametri

[in] unnamedParam1

Puntatore a un buffer che riceve una matrice di strutture RASDEVINFO, una per ogni dispositivo che supporta RAS. Prima di chiamare la funzione, impostare il membro dwSize del primo RASDEVINFO struttura nel buffer su sizeof(RASDEVINFO) per identificare la versione della struttura.

[in, out] unnamedParam2

Puntatore a una variabile che, in input, contiene le dimensioni, in byte, del buffer lpRasDevInfo .

Nell'output, la funzione imposta questa variabile sul numero di byte necessari per enumerare i dispositivi.

nota

Per determinare le dimensioni del buffer necessarie, chiamare RasEnumDevices con lpRasDevInfo 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 RASDEVINFO scritte nel buffer lpRasDevInfo .

Valore restituito

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

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti o un valore di Codici di errore di routing e accesso remoto o Winerror.h.

Valore	Significato
ERROR_BUFFER_TOO_SMALL	Il buffer lpRasDevInfo non è sufficiente. Il parametro lpcb è minore del membro dwSize nel parametro lpRasDevInfo che deve essere impostato prima di chiamare la funzione. La funzione restituisce la dimensione del buffer richiesta nella variabile a cui punta lpcb.
ERROR_NOT_ENOUGH_MEMORY	Indica memoria insufficiente. Il parametro lpRasDevInfo non èNULL, il parametro lpcb non ènull e un'allocazione di memoria interna non è riuscita. Ciò è probabilmente dovuto a una condizione di memoria insufficiente.
ERROR_INVALID_PARAMETER	Indica un valore di parametro non valido. Il parametro lpcb è NULL o il parametro lpcDevices è NULL.
ERROR_INVALID_USER_BUFFER	L'indirizzo o il buffer specificato da lpRasDevInfo non è valido. Il membro dwSize del parametro lpRasDevInfo non è uguale a sizeof(RASDEVINFO).

Osservazioni

Il codice di esempio seguente enumera i dispositivi nel computer corrente. Il codice chiama inizialmente RasEnumDevices con un parametro lpRasDevInfo di NULL, per ottenere le dimensioni del buffer da passare. Il codice imposta anche il membro del dwSize del primo struttura RASDEVINFO su sizeof(RASDEVINFO) per specificare la versione della struttura.

#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;
}

Nota

L'intestazione ras.h definisce RasEnumDevices 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

RASDEVINFO

Panoramica servizio di accesso remoto (RAS)

funzioni del servizio accesso remoto

Condividi tramite