Funzione RasEnumEntriesA (ras.h)

La funzione RasEnumEntries elenca tutti i nomi di voce in una rubrica telefonica di accesso remoto.

Sintassi

DWORD RasEnumEntriesA(
  [in]      LPCSTR          unnamedParam1,
  [in]      LPCSTR          unnamedParam2,
  [in, out] LPRASENTRYNAMEA unnamedParam3,
  [in, out] LPDWORD         unnamedParam4,
  [out]     LPDWORD         unnamedParam5
);

Parametri

[in] unnamedParam1

Riservati; deve essere NULL.

[in] unnamedParam2

Puntatore a una stringa con terminazione null che specifica il percorso completo e il nome file di un file PBK (Phone Book). Se questo parametro è NULL, la funzione usa il file di rubrica telefonico predefinito corrente. Il file di rubrica telefonico predefinito è quello selezionato dall'utente nella finestra di proprietà Preferenze utente della finestra di dialogo Rete remota .

Se questo parametro è NULL, le voci vengono enumerate da tutti i file di telefono di accesso remoto nel profilo AllUsers e dal profilo dell'utente.

[in, out] unnamedParam3

Puntatore a un buffer che, nell'output, riceve una matrice di strutture RASENTRYNAME , una per ogni voce di rubrica telefonica.

In input, un'applicazione deve impostare il membro dwSize della prima struttura RASENTRYNAME nel buffer su sizeof(RASENTRYNAME) per identificare la versione della struttura passata.

[in, out] unnamedParam4

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

Puntatore a una variabile che, nell'output, contiene le dimensioni, in byte, della matrice di strutture RASENTRYNAME necessarie per le voci della rubrica telefonica.

Windows Vista o versioni successive: Per determinare le dimensioni del buffer necessarie, chiamare RasEnumEntries con lprasentryname impostato su NULL. La variabile a cui punta per 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] unnamedParam5

Puntatore a una variabile che riceve al numero di voci della rubrica telefonica scritte nel buffer specificato da lprasentryname.

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 da Routing e codici di errore di accesso remoto o Winerror.h.

Commenti

Il codice di esempio seguente enumera le voci del telefono RAS in Windows Vista e versioni successive di Windows. Il codice chiama inizialmente RasEnumEntries per ottenere le dimensioni del buffer da passare. Il codice chiama quindi di nuovo RasEnumEntries per enumerare le voci. Si noti che per la seconda chiamata, il codice imposta il membro dwSize della prima struttura RASENTRYNAME nel buffer su sizeof(RASENTRYNAME) 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 dwEntries = 0;
    LPRASENTRYNAME lpRasEntryName = NULL;
    
    // Call RasEnumEntries with lpRasEntryName = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS entry names.
        lpRasEntryName = (LPRASENTRYNAME) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasEntryName == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASENTRYNAME structure in the array must contain the structure size
        lpRasEntryName[0].dwSize = sizeof(RASENTRYNAME);
        
        // Call RasEnumEntries to enumerate all RAS entry names
        dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

        // If successful, print the RAS entry names 
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS entry names were found:\n");
            for (DWORD i = 0; i < dwEntries; i++){
                wprintf(L"%s\n", lpRasEntryName[i].szEntryName);
            }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasEntryName);
        lpRasEntryName = NULL;
        return 0;
    }

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

    return 0;
}

Requisiti

Vedi anche

RASENTRYNAME

RasEnumConnections

Panoramica del servizio di accesso remoto (RAS)

Funzioni del Servizio di accesso remoto