Función RasEnumConnectionsA (ras.h)

Artículo
08/25/2023

La función RasEnumConnections enumera todas las conexiones RAS activas. Devuelve el identificador de cada conexión y el nombre de entrada de la libreta de teléfonos.

Sintaxis

DWORD RasEnumConnectionsA(
  [in, out] LPRASCONNA unnamedParam1,
  [in, out] LPDWORD    unnamedParam2,
  [out]     LPDWORD    unnamedParam3
);

Parámetros

[in, out] unnamedParam1

Puntero a un búfer que recibe, en la salida, una matriz de estructuras RASCONN , una para cada conexión RAS.

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

[in, out] unnamedParam2

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

En la salida, la función establece esta variable en el número de bytes necesarios para enumerar las conexiones RAS.

Nota

Para determinar el tamaño de búfer necesario, llame a RasEnumConnections con lprasconn 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] unnamedParam3

Puntero a una variable que recibe el número de estructuras RASCONN escritas en el búfer especificado por lprasconn.

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 procede de Los códigos de error de enrutamiento y acceso remoto o Winerror.h.

Código devuelto	Descripción
ERROR_BUFFER_TOO_SMALL	El búfer lprasconn no es lo suficientemente grande. El parámetro lpcb es menor que el miembro dwSize del parámetro lprasconn 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.

Comentarios

Si se realizó una conexión sin especificar un nombre de entrada de la libreta de teléfonos, la información devuelta para esa conexión proporciona el número de teléfono de conexión precedido por ".".

El código de ejemplo de código siguiente usa RasEnumConnections para enumerar las conexiones RAS activas.

#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 dwConnections = 0;
    LPRASCONN lpRasConn = NULL;
    
    // Call RasEnumConnections with lpRasConn = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumConnections(lpRasConn, &dwCb, &dwConnections);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS structure(s).
        lpRasConn = (LPRASCONN) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasConn == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASCONN structure in the array must contain the RASCONN structure size
        lpRasConn[0].dwSize = sizeof(RASCONN);
        
        // Call RasEnumConnections to enumerate active connections
        dwRet = RasEnumConnections(lpRasConn, &dwCb, &dwConnections);

        // If successful, print the names of the active connections.
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS connections are currently active:\n");
            for (DWORD i = 0; i < dwConnections; i++){
                         wprintf(L"%s\n", lpRasConn[i].szEntryName);
                  }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasConn);
        lpRasConn = NULL;
        return 0;
    }

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

    return 0;
}

RasEnumConnections no puede enumerar una conexión como Activa hasta que RAS se haya conectado correctamente.

Windows Me/98/95: RasEnumConnections enumera una conexión como Activa en cuanto se inicia la marcación.

La manera más confiable de enumerar y comprobar una conexión activa es llamar a RasEnumConnections o RasDial para obtener un identificador de conexión y, a continuación, llamar a RasGetConnectStatus para determinar el estado de conexión real.

Nota

El encabezado ras.h define RasEnumConnections 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