Função RasEnumDevicesA (ras.h)

Artigo
11/20/2024

A função RasEnumDevices retorna o nome e o tipo de todos os dispositivos compatíveis com RAS disponíveis.

Sintaxe

DWORD RasEnumDevicesA(
  [in]      LPRASDEVINFOA unnamedParam1,
  [in, out] LPDWORD       unnamedParam2,
  [out]     LPDWORD       unnamedParam3
);

Parâmetros

[in] unnamedParam1

Ponteiro para um buffer que recebe uma matriz de estruturas de RASDEVINFO , uma para cada dispositivo compatível com RAS. Antes de chamar a função, defina o dwSize membro da primeira estrutura de RASDEVINFO do no buffer como sizeof(RASDEVINFO) para identificar a versão da estrutura.

[in, out] unnamedParam2

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

Na saída, a função define essa variável como o número de bytes necessários para enumerar os dispositivos.

de Observação

Para determinar o tamanho do buffer necessário, chame RasEnumDevices com lpRasDevInfo 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 RASDEVINFO gravadas no buffer lpRasDevInfo.

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á 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
ERROR_BUFFER_TOO_SMALL	O buffer lpRasDevIn fo não é grande o suficiente. O parâmetro lpcb é menor que o dwSize membro no parâmetro lpRasDevInfo 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.
ERROR_NOT_ENOUGH_MEMORY	Indica memória insuficiente. O parâmetro lpRasDevInfo não éNULL, o parâmetro lpcb não é NULL e uma alocação de memória interna falhou. Isso é possivelmente devido a uma condição de memória baixa.
ERROR_INVALID_PARAMETER	Indica um valor de parâmetro inválido. O parâmetro lpcb é NULL ou o parâmetro lpcDevices é NULL.
ERROR_INVALID_USER_BUFFER	O endereço ou buffer especificado por lpRasDevInfo é inválido. O dwSize membro do parâmetro lpRasDevInfo não é igual a sizeof(RASDEVINFO).

Observações

O código de exemplo a seguir enumera os dispositivos no computador atual. O código inicialmente chama RasEnumDevices com um parâmetro lpRasDevInfo de NULL, para obter o tamanho do buffer que deve ser passado. O código também define o dwSize membro da primeira estrutura de RASDEVINFO como sizeof(RASDEVINFO) 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 dwDevices = 0;
    LPRASDEVINFO lpRasDevInfo = NULL;
    
    // Call RasEnumDevices with lpRasDevInfo = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumDevices(lpRasDevInfo, &dwCb, &dwDevices);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS structure(s).
        lpRasDevInfo = (LPRASDEVINFO) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasDevInfo == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASDEVINFO structure in the array must contain the structure size
        lpRasDevInfo[0].dwSize = sizeof(RASDEVINFO);
        
        // Call RasEnumDevices to enumerate RAS devices
        dwRet = RasEnumDevices(lpRasDevInfo, &dwCb, &dwDevices);

        // If successful, print the names of the RAS devices
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS devices were found:\n");
            for (DWORD i = 0; i < dwDevices; i++){
                         wprintf(L"%s\n", lpRasDevInfo[i].szDeviceName);
                  }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasDevInfo);
        lpRasDevInfo = NULL;
        return 0;
    }

    // There was either a problem with RAS or there are no RAS devices to enumerate    
    if(dwDevices >= 1){
        wprintf(L"The operation failed to acquire the buffer size.\n");
    }else{
        wprintf(L"There were no RAS devices found.\n");
    }

    return 0;
}

Nota

O cabeçalho ras.h define RasEnumDevices como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do 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

RASDEVINFO

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

Funções do Serviço de Acesso Remoto

Compartilhar via