Función RasEnumEntriesA (ras.h)

La función RasEnumEntries enumera todos los nombres de entrada de una libreta de teléfonos de acceso remoto.

Sintaxis

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

Parámetros

[in] unnamedParam1

Reservados; debe ser NULL.

[in] unnamedParam2

Puntero a una cadena terminada en null que especifica la ruta de acceso completa y el nombre de archivo de un archivo de libreta telefónica (PBK). Si este parámetro es NULL, la función usa el archivo de libreta telefónica predeterminado actual. El archivo de libreta telefónica predeterminado es el seleccionado por el usuario en la hoja de propiedades Preferencias de usuario del cuadro de diálogo Redes de acceso telefónico .

Si este parámetro es NULL, las entradas se enumeran de todos los archivos de libreta telefónica de acceso remoto en el perfil AllUsers y el perfil del usuario.

[in, out] unnamedParam3

Puntero a un búfer que, en la salida, recibe una matriz de estructuras RASENTRYNAME , una para cada entrada de la libreta de teléfonos.

En la entrada, una aplicación debe establecer el miembro dwSize de la primera estructura RASENTRYNAME del búfer en sizeof(RASENTRYNAME) para identificar la versión de la estructura que se pasa.

[in, out] unnamedParam4

Puntero a una variable que, en la entrada, contiene el tamaño, en bytes, del búfer especificado por lprasentryname.

Puntero a una variable que, en la salida, contiene el tamaño, en bytes, de la matriz de estructuras RASENTRYNAME necesarias para las entradas de la libreta telefónica.

Windows Vista o posterior: Para determinar el tamaño de búfer necesario, llame a RasEnumEntries con lprasentryname establecido en NULL. La variable a la que apunta lpcb debe establecerse en cero. La función devolverá el tamaño de búfer necesario en lpcb y un código de error de ERROR_BUFFER_TOO_SMALL.

[out] unnamedParam5

Puntero a una variable que recibe al número de entradas de la libreta de teléfono escritas en el búfer especificado por lprasentryname.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto se ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error o un valor de Códigos de error de enrutamiento y acceso remoto o Winerror.h.

Valor	Significado
ERROR_BUFFER_TOO_SMALL	El búfer lprasentryname no es lo suficientemente grande. El parámetro lpcb es menor que el miembro dwSize del parámetro lprasentryname que se debe establecer antes de llamar a la función. La función devuelve el tamaño de búfer necesario en la variable a la que apunta lpcb. Windows Vista o posterior: El búfer lprasentryname puede establecerse en NULL y la variable a la que apunta lpcb se puede establecer en cero. La función devolverá el tamaño de búfer necesario en la variable a la que apunta lpcb.
ERROR_INVALID_SIZE	El valor de dwSize en la estructura RASENTRYNAME a la que apunta lprasentryname especifica una versión de la estructura que no se admite en la plataforma actual. Por ejemplo, en Windows 95, RasEnumEntries devuelve este error si dwSize indica que RASENTRYNAME incluye los miembros dwFlags y szPhonebookPath , ya que estos miembros no se admiten en Windows 95 (solo se admiten en Windows 2000 y versiones posteriores).
ERROR_NOT_ENOUGH_MEMORY	La función no pudo asignar suficiente memoria para completar la operación.

Comentarios

En el código de ejemplo siguiente se enumeran las entradas de la libreta de teléfono ras en Windows Vista y versiones posteriores de Windows. El código llama inicialmente a RasEnumEntries para obtener el tamaño del búfer que se va a pasar. A continuación, el código llama a RasEnumEntries de nuevo para enumerar las entradas. Tenga en cuenta que, para la segunda llamada, el código establece el miembro dwSize de la primera estructura RASENTRYNAME del búfer en sizeof(RASENTRYNAME) para especificar la versión de la estructura.

#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

El encabezado ras.h define RasEnumEntries como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ras.h
Library	Rasapi32.lib
Archivo DLL	Rasapi32.dll

Consulte también

RASENTRYNAME

RasEnumConnections

Información general sobre el servicio de acceso remoto (RAS)

Funciones del Servicio de acceso remoto