Função RasEnumEntriesA (ras.h)
A função RasEnumEntries lista todos os nomes de entrada em uma lista telefônica de acesso remoto.
Sintaxe
DWORD RasEnumEntriesA(
[in] LPCSTR unnamedParam1,
[in] LPCSTR unnamedParam2,
[in, out] LPRASENTRYNAMEA unnamedParam3,
[in, out] LPDWORD unnamedParam4,
[out] LPDWORD unnamedParam5
);
Parâmetros
[in] unnamedParam1
Reservados; deve ser NULL.
[in] unnamedParam2
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o caminho completo e o nome do arquivo de um arquivo de catálogo telefônico (PBK). Se esse parâmetro for NULL, a função usará o arquivo de catálogo telefônico padrão atual. O arquivo de agendamento telefônico padrão é aquele selecionado pelo usuário na folha de propriedades Preferências do Usuário da caixa de diálogo Rede Discada .
Se esse parâmetro for NULL, as entradas serão enumeradas de todos os arquivos de catálogo telefônico de acesso remoto no perfil AllUsers e no perfil do usuário.
[in, out] unnamedParam3
Ponteiro para um buffer que, na saída, recebe uma matriz de estruturas RASENTRYNAME , uma para cada entrada de catálogo telefônico.
Na entrada, um aplicativo deve definir o membro dwSize da primeira estrutura RASENTRYNAME no buffer como sizeof(RASENTRYNAME) para identificar a versão da estrutura que está sendo passada.
[in, out] unnamedParam4
Ponteiro para uma variável que, na entrada, contém o tamanho, em bytes, do buffer especificado por lprasentryname.
Ponteiro para uma variável que, na saída, contém o tamanho, em bytes, da matriz de estruturas RASENTRYNAME necessárias para as entradas do catálogo telefônico.
Windows Vista ou posterior: Para determinar o tamanho do buffer necessário, chame RasEnumEntries com lprasentryname 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] unnamedParam5
Ponteiro para uma variável que recebe o número de entradas de livro telefônico gravadas no buffer especificado por lprasentryname.
Retornar valor
Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS.
Se a função falhar, o valor retornado será um dos seguintes códigos de erro ou um valor de Códigos de Erro de Roteamento e Acesso Remoto ou Winerror.h.
| Valor | Significado |
|---|---|
|
O buffer lprasentryname não é grande o suficiente. O parâmetro lpcb é menor que o membro dwSize no parâmetro lprasentryname 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.
Windows Vista ou posterior: O buffer lprasentryname pode ser definido como NULL e a variável apontada por lpcb pode ser definida como zero. A função retornará o tamanho do buffer necessário na variável apontada por lpcb. |
|
O valor de dwSize na estrutura RASENTRYNAME apontada por lprasentryname especifica uma versão da estrutura que não tem suporte na plataforma atual. Por exemplo, no Windows 95, RasEnumEntries retornará esse erro se dwSize indicar que RASENTRYNAME inclui os membros dwFlags e szPhonebookPath , já que esses membros não têm suporte no Windows 95 (eles têm suporte apenas no Windows 2000 e posterior). |
|
A função não pôde alocar memória suficiente para concluir a operação. |
Comentários
O código de exemplo a seguir enumera as entradas de catálogo telefônico ras no Windows Vista e versões posteriores do Windows. Inicialmente, o código chama RasEnumEntries para obter o tamanho do buffer a ser transmitido. Em seguida, o código chama RasEnumEntries novamente para enumerar as entradas. Observe que, para a segunda chamada, o código define o membro dwSize da primeira estrutura RASENTRYNAME no buffer como sizeof (RASENTRYNAME) para especificar a versão da estrutura.
#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 dwEntries = 0;
LPRASENTRYNAME lpRasEntryName = NULL;
// Call RasEnumEntries with lpRasEntryName = NULL. dwCb is returned with the required buffer size and
// a return code of ERROR_BUFFER_TOO_SMALL
dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);
if (dwRet == ERROR_BUFFER_TOO_SMALL){
// Allocate the memory needed for the array of RAS entry names.
lpRasEntryName = (LPRASENTRYNAME) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
if (lpRasEntryName == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The first RASENTRYNAME structure in the array must contain the structure size
lpRasEntryName[0].dwSize = sizeof(RASENTRYNAME);
// Call RasEnumEntries to enumerate all RAS entry names
dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);
// If successful, print the RAS entry names
if (ERROR_SUCCESS == dwRet){
wprintf(L"The following RAS entry names were found:\n");
for (DWORD i = 0; i < dwEntries; i++){
wprintf(L"%s\n", lpRasEntryName[i].szEntryName);
}
}
//Deallocate memory for the connection buffer
HeapFree(GetProcessHeap(), 0, lpRasEntryName);
lpRasEntryName = NULL;
return 0;
}
// There was either a problem with RAS or there are RAS entry names to enumerate
if(dwEntries >= 1){
wprintf(L"The operation failed to acquire the buffer size.\n");
}else{
wprintf(L"There were no RAS entry names found:.\n");
}
return 0;
}
Observação
O cabeçalho ras.h define RasEnumEntries 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 |