Função RasEnumConnectionsA (ras.h)

A função RasEnumConnections lista todas as conexões RAS ativas. Ele retorna o identificador de cada conexão e o nome da entrada do catálogo telefônico.

Sintaxe

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

Parâmetros

[in, out] unnamedParam1

Ponteiro para um buffer que recebe, na saída, uma matriz de estruturas RASCONN , uma para cada conexão RAS.

Na entrada, um aplicativo deve definir o membro dwSize da primeira estrutura RASCONN no buffer como sizeof(RASCONN) para identificar a versão da estrutura que está sendo passada.

[in, out] unnamedParam2

Ponteiro para uma variável que, na entrada, contém o tamanho, em bytes, do buffer especificado por lprasconn.

Na saída, a função define essa variável como o número de bytes necessários para enumerar as conexões RAS.

Observação  

Para determinar o tamanho do buffer necessário, chame RasEnumConnections com lprasconn definido como NULL. A variável apontada por lpcb deve ser definida como zero. A função retornará o tamanho do buffer necessário em lpcb e um código de erro de ERROR_BUFFER_TOO_SMALL.

 

[out] unnamedParam3

Ponteiro para uma variável que recebe o número de estruturas RASCONN gravadas no buffer especificado por lprasconn.

Retornar valor

Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será de Códigos de Erro de Roteamento e Acesso Remoto ou Winerror.h.

Código de retorno	Descrição
ERROR_BUFFER_TOO_SMALL	O buffer lprasconn não é grande o suficiente. O parâmetro lpcb é menor que o membro dwSize no parâmetro lprasconn que deve ser definido antes de chamar a função. A função retorna o tamanho do buffer necessário na variável apontada por lpcb.

Comentários

Se uma conexão tiver sido feita sem especificar um nome de entrada de catálogo telefônico, as informações retornadas para essa conexão fornecerão o número de telefone de conexão precedido por "".

O código de exemplo de código a seguir usa RasEnumConnections para enumerar as conexões RAS ativas.

#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 não pode enumerar uma conexão como Ativa até que o RAS tenha se conectado com êxito.

Windows Me/98/95: RasEnumConnections enumera uma conexão assim que ela começa a discar.

A maneira mais confiável de enumerar e marcar para uma conexão ativa é chamar RasEnumConnections ou RasDial para obter um identificador de conexão e, em seguida, chamar RasGetConnectStatus para determinar o estado de conexão real.

Observação

O cabeçalho ras.h define RasEnumConnections como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ras.h
Biblioteca	Rasapi32.lib
DLL	Rasapi32.dll

Confira também

RASCONN

Rasenumentries

Rasgetconnectstatus

Visão geral do RAS (Serviço de Acesso Remoto)

Funções do serviço de acesso remoto