Método IWbemServices::ExecNotificationQuery (wbemcli.h)

Artigo
08/27/2023

O método IWbemServices::ExecNotificationQuery executa uma consulta para receber eventos. A chamada retorna imediatamente e o usuário pode sondar o enumerador retornado para eventos à medida que eles chegam. A liberação do enumerador retornado cancela a consulta.

Sintaxe

HRESULT ExecNotificationQuery(
  [in]  const BSTR           strQueryLanguage,
  [in]  const BSTR           strQuery,
  [in]  long                 lFlags,
  [in]  IWbemContext         *pCtx,
  [out] IEnumWbemClassObject **ppEnum
);

Parâmetros

[in] strQueryLanguage

BSTR válido que contém um dos idiomas de consulta compatíveis com o Gerenciamento do Windows. Isso não pode ser NULL. Atualmente, há suporte apenas para a WQL ( Linguagem de Consulta WMI ).

[in] strQuery

BSTR válido que contém o texto da consulta relacionada ao evento. Isso não pode ser NULL. Para obter mais informações sobre como criar cadeias de caracteres de consulta do WMI, veja Como consultar com WQL e a referência da WQL.

[in] lFlags

Esse parâmetro deve ser definido como WBEM_FLAG_RETURN_IMMEDIATELY e WBEM_FLAG_FORWARD_ONLY ou a chamada falhará.

WBEM_FLAG_FORWARD_ONLY

Esse sinalizador faz com que um enumerador somente de encaminhamento seja retornado. Os enumeradores somente de encaminhamento geralmente são muito mais rápidos e usam menos memória do que os enumeradores convencionais, mas não permitem chamadas para Clonar ou Redefinir.

WBEM_FLAG_RETURN_IMMEDIATELY

O usuário deve especificar esse sinalizador ou a chamada falhará. Isso ocorre porque os eventos são recebidos continuamente, o que significa que o usuário deve sondar o enumerador retornado. Bloquear essa chamada indefinidamente enquanto aguarda um possível evento bloqueia o thread por um período indefinido. Para obter mais informações, confira Como chamar um método.

[in] pCtx

Normalmente NULL. Caso contrário, esse é um ponteiro para um objeto IWbemContext que pode ser usado pelo provedor que fornece os eventos solicitados. Os valores no objeto de contexto devem ser especificados na documentação do provedor em questão. Para obter mais informações sobre esse parâmetro, consulte Fazendo chamadas para WMI.

[out] ppEnum

Se nenhum erro ocorrer, esse parâmetro receberá o enumerador que permite ao chamador recuperar as instâncias no conjunto de resultados da consulta. O chamador chama periodicamente IEnumWbemClassObject::Next para ver se algum evento está disponível. Observe que, nesse uso, Redefinir não move o enumerador de volta para o início da sequência de eventos; não tem efeito. O parâmetro pode continuar a receber eventos até que Release seja chamado no enumerador retornado.

Retornar valor

Esse método retorna um HRESULT que indica o status da chamada de método. A lista a seguir lista o valor contido em um HRESULT.

Em caso de falha, você pode obter todas as informações disponíveis da função COM GetErrorInfo.

Códigos de erro específicos do COM também poderão ser retornados se problemas de rede fizerem com que você perca a conexão remota com o Gerenciamento do Windows.

Comentários

Existem limites para o número das palavras-chave AND e OR que podem ser usadas nas consultas WQL. Um grande número de palavras-chave WQL usadas em uma consulta complexa pode fazer com que o WMI retorne o código de erro WBEM_E_QUOTA_VIOLATION como um valor HRESULT. O limite de palavras-chave WQL depende da complexidade da consulta.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	wbemcli.h (include Wbemidl.h)
Biblioteca	Wbemuuid.lib
DLL	Fastprox.dll; Esscli.dll; FrameDyn.dll; FrameDynOS.dll; Ntevt.dll; Stdprov.dll; Viewprov.dll; Wbemcomn.dll; Wbemcore.dll; Wbemess.dll; Wbemsvc.dll; Wmipicmp.dll; Wmidcprv.dll; Wmipjobj.dll; Wmiprvsd.dll