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.

Valore	Significato
ERROR_BUFFER_TOO_SMALL	Il buffer lprasentryname non è abbastanza grande. Il parametro lpcb è minore del membro dwSize nel parametro lprasentryname che deve essere impostato prima di chiamare la funzione. La funzione restituisce le dimensioni del buffer necessarie nella variabile a cui punta lpcb. Windows Vista o versioni successive: Il buffer lprasentryname può essere impostato su NULL e la variabile puntata da lpcb può essere impostata su zero. La funzione restituirà le dimensioni del buffer necessarie nella variabile a cui punta lpcb.
ERROR_INVALID_SIZE	Il valore di dwSize nella struttura RASENTRYNAME a cui punta il nome lprasentryname specifica una versione della struttura non supportata nella piattaforma corrente. Ad esempio, in Windows 95, RasEnumEntries restituisce questo errore se dwSize indica che RASENTRYNAME include i membri dwFlags e szPhonebookPath , poiché questi membri non sono supportati in Windows 95 (sono supportati solo in Windows 2000 e versioni successive).
ERROR_NOT_ENOUGH_MEMORY	La funzione non ha potuto allocare memoria sufficiente per completare l'operazione.

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

Nota

L'intestazione ras.h definisce RasEnumEntries come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ras.h
Libreria	Rasapi32.lib
DLL	Rasapi32.dll

Vedi anche

RASENTRYNAME

RasEnumConnections

Panoramica del servizio di accesso remoto (RAS)

Funzioni del Servizio di accesso remoto