Função RasEnumConnectionsA (ras.h)

Artigo
11/20/2024

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

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 de RASCONN , uma para cada conexão RAS.

Na entrada, um aplicativo deve definir o dwSize membro da primeira estrutura de 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.

de 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 de RASCONN gravadas no buffer especificado por lprasconn.

Valor de retorno

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.

Observações

Se uma conexão foi feita sem especificar um nome de entrada de lista telefônica, as informações retornadas para essa conexão dã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 podem enumerar uma conexão como Active até que o RAS tenha se conectado com êxito.

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

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

Nota

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. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	ras.h
biblioteca	Rasapi32.lib
de DLL	Rasapi32.dll

Consulte também

RASCONN

RasEnumEntries

rasGetConnectStatus

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

Funções do Serviço de Acesso Remoto

Compartilhar via