Compartilhar via

Função DhcpRequestParams (dhcpcsdk.h)

  • Artigo

A função DhcpRequestParams permite que os chamadores obtenham dados DHCP de forma síncrona ou síncrona e persistente de um servidor DHCP.

Sintaxe

DWORD DhcpRequestParams(
  [in]      DWORD                 Flags,
  [in]      LPVOID                Reserved,
  [in]      LPWSTR                AdapterName,
  [in]      LPDHCPCAPI_CLASSID    ClassId,
  [in]      DHCPCAPI_PARAMS_ARRAY SendParams,
  [in, out] DHCPCAPI_PARAMS_ARRAY RecdParams,
  [in]      LPBYTE                Buffer,
  [in, out] LPDWORD               pSize,
  [in]      LPWSTR                RequestIdStr
);

Parâmetros

[in] Flags

Sinalizadores que especificam os dados que estão sendo solicitados. Esse parâmetro é opcional. Os seguintes valores possíveis têm suporte e não são mutuamente exclusivos:

Valor Significado
DHCPCAPI_REQUEST_PERSISTENT
 A solicitação é persistente, mas nenhuma opção é buscada.
DHCPCAPI_REQUEST_SYNCHRONOUS
 As opções serão buscadas do servidor.

[in] Reserved

Reservado para uso futuro. Deve ser definido como NULL.

[in] AdapterName

GUID do adaptador no qual os dados solicitados estão sendo feitos. Deve ter menos de 256 caracteres.

[in] ClassId

ID (identificador de classe) que deve ser usado se as mensagens DHCP INFORM estiverem sendo transmitidas para a rede. Esse parâmetro é opcional.

[in] SendParams

Dados opcionais a serem solicitados, além dos dados solicitados na matriz RecdParams . O parâmetro SendParams não pode conter nenhuma das opções padrão que o cliente DHCP envia por padrão.

[in, out] RecdParams

Matriz de dados DHCP que o chamador está interessado em receber. Essa matriz deve estar vazia antes da chamada da função DhcpRequestParams .

[in] Buffer

Buffer usado para armazenar os dados associados a solicitações feitas em RecdParams.

[in, out] pSize

Tamanho do Buffer.

O tamanho necessário do buffer, se ele não for dimensionado suficientemente para armazenar os dados, caso contrário, indicará o tamanho do buffer que foi preenchido com êxito.

[in] RequestIdStr

ID (identificador de aplicativo) usado para facilitar uma solicitação persistente. Deve ser uma cadeia de caracteres imprimível sem caracteres especiais (vírgulas, barras invertidas, dois-pontos ou outros caracteres ilegais não podem ser usados). A ID (identificador de aplicativo) especificada é usada em uma chamada de função DhcpUndoRequestParams subsequente para limpar a solicitação persistente, conforme necessário.

Valor retornado

Retorna ERROR_SUCCESS após a conclusão bem-sucedida.

Após o retorno, RecdParams é preenchido com ponteiros para dados solicitados, com os dados correspondentes colocados em Buffer. Se pSize indicar que Buffer não tem espaço suficiente para armazenar dados retornados, a função DhcpRequestParams retornará ERROR_MORE_DATA e retornará o tamanho do buffer necessário no pSize. Observe que o tamanho necessário do Buffer pode aumentar durante o tempo decorrido entre o retorno da chamada de função inicial e uma chamada subsequente; portanto, o tamanho necessário do Buffer (indicado no pSize) fornece uma indicação do tamanho aproximado necessário do Buffer, em vez de garantir que as chamadas subsequentes retornarão com êxito se Buffer for definido como o tamanho indicado no pSize.

Outros erros retornam códigos de erro apropriados do Windows.

Código de retorno Descrição
ERROR_INVALID_PARAMETER
 Retornado se o parâmetro AdapterName tiver mais de 256 caracteres.
ERROR_BUFFER_OVERFLOW
 Retornado se o parâmetro AdapterName tiver mais de 256 caracteres.

Comentários

Os clientes DHCP armazenam dados obtidos de um servidor DHCP em seu cache local. Se o cache do cliente DHCP contiver todos os dados solicitados na matriz RecdParams de uma chamada de função DhcpRequestParams , o cliente retornará dados de seu cache. Se os dados solicitados não estiverem disponíveis no cache do cliente, o cliente processará a chamada da função DhcpRequestParams enviando uma mensagem DHCP-INFORM para o servidor DHCP.

Quando o cliente envia uma mensagem DHCP-INFORM para o servidor DHCP, ele inclui todas as solicitações fornecidas no parâmetro opcional SendParams e fornece o identificador de classe (ID) especificado no parâmetro ClassId , se fornecido.

Os clientes também podem especificar que os dados DHCP sejam recuperados do servidor DHCP sempre que o cliente DHCP for inicializado, o que é considerado uma solicitação persistente. Para habilitar solicitações persistentes, o chamador deve especificar o parâmetro RequestIdStr e também especificar o sinalizador de DHCPAPI_REQUEST_PERSISTENT adicional no parâmetro dwFlags . Essa funcionalidade de solicitação persistente é especialmente útil quando os clientes precisam solicitar automaticamente informações críticas ao aplicativo em cada inicialização. Para desabilitar uma solicitação persistente, os clientes devem chamar a função .

Nota Os chamadores dessa API não devem fazer chamadas de bloqueio para essa API, pois pode levar até um máximo de 2 minutos para retornar um código ou status. Os comportamentos da interface do usuário, em particular, não devem bloquear no retorno dessa chamada, pois ela pode introduzir um atraso significativo no tempo de resposta da interface do usuário.
 
Para obter mais informações sobre mensagens DHCP INFORM e outras informações baseadas em padrões sobre DHCP, consulte Padrões DHCP.

Para ver a função DhcpRequestParams em uso, confira Exemplos de DHCP.

Requisitos

   
Cliente mínimo com suporte Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho dhcpcsdk.h
Biblioteca Dhcpcsvc.lib
DLL Dhcpcsvc.dll

Confira também

Funções DHCP

DHCPCAPI_PARAMS_ARRAY

DhcpCApiInitialize

DhcpUndoRequestParams