Función RasEnumConnectionsA (ras.h)

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 de RASCONN, una para cada conexión RAS.

En la entrada, una aplicación debe establecer el dwSize miembro de la primera estructura RASCONN en el 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 de RASCONN escritas en el búfer especificado por lprasconn.

Valor devuelto

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

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

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

Observaciones

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 Active hasta que RAS se haya conectado correctamente.

Windows Me/98/95: RasEnumConnections enumera una conexión como Active tan pronto como 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	ras.h
biblioteca de	Rasapi32.lib
DLL de	Rasapi32.dll

Consulte también

RASCONN

RasEnumEntries

RasGetConnectStatus

información general del servicio de acceso remoto (RAS)

funciones del servicio de acceso remoto