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.
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 |
|---|---|
|
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 |