Funzione RasEnumEntriesA (ras.h)

La funzione RasEnumEntries elenca tutti i nomi di voce in una rubrica 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

Riservato; deve essere null.

[in] unnamedParam2

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

Se questo parametro è NULL, le voci vengono enumerate da tutti i file della rubrica 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 della rubrica telefonica.

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

[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 RASENTRYNAME strutture necessarie per le voci della rubrica telefonica.

Windows Vista o versione successiva: Per determinare le dimensioni del buffer necessarie, chiamare RasEnumEntries con lprasentryname 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] unnamedParam5

Puntatore a una variabile che riceve il numero di voci della rubrica scritta 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 di Codici di errore di routing e accesso remoto o Winerror.h.

Osservazioni

Il codice di esempio seguente enumera le voci della rubrica telefonica 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 del primo RASENTRYNAME struttura 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;
}

Fabbisogno

Vedere anche

RASENTRYNAME

RasEnumConnections

Panoramica servizio di accesso remoto (RAS)

funzioni del servizio accesso remoto