Método Provider::ExecQuery (provider.h)

  • Artigo

[A classe Provider faz parte do WMI Provider Framework que agora é considerado em estado final e nenhum desenvolvimento, melhoria ou atualização adicional estará disponível para problemas não relacionados à segurança que afetarem essas bibliotecas. As APIs de MI devem ser usadas para todos os novos desenvolvimentos.]

O método ExecQuery é chamado pelo WMI para processar uma consulta WQL (WMI Query Language).

Sintaxe

HRESULT ExecQuery(
        MethodContext     *pMethodContext,
  [ref] CFrameworkQuery & cQuery,
        long              lFlags
);

Parâmetros

pMethodContext

Ponteiro para o objeto de contexto dessa chamada. Esse valor contém todas as propriedades IWbemContext especificadas pelo cliente. Além disso, esse ponteiro deve ser usado como um parâmetro para todas as chamadas de volta para o WMI.

[ref] cQuery

Ponteiro para uma consulta que já foi analisada pela estrutura do provedor.

lFlags

Máscara de bits de sinalizadores com informações sobre a operação de execução de consulta. Esse é o valor especificado pelo cliente no método IWbemServices::ExecQuery .

Os seguintes sinalizadores são manipulados por (e filtrados) pelo WMI:

  • WBEM_FLAG_ENSURE_LOCATABLE
  • WBEM_FLAG_FORWARD_ONLY
  • WBEM_FLAG_BIDIRECTIONAL
  • WBEM_FLAG_USE_AMENDED_QUALIFIERS
  • WBEM_FLAG_RETURN_IMMEDIATELY
  • WBEM_FLAG_PROTOTYPE

Valor retornado

A implementação do provedor de estrutura padrão desse método retorna WBEM_E_PROVIDER_NOT_CAPABLE ao método de chamada. O método IWbemServices::ExecQuery lista os valores retornados comuns, embora você possa optar por retornar qualquer código de retorno COM.

Comentários

O WMI geralmente chama ExecQuery em resposta a uma chamada de cliente para IWbemServices::ExecQuery, em que o cliente passa uma lista de propriedades selecionadas ou uma cláusula WHERE. O WMI também poderá chamar ExecQuery se a consulta de cliente contiver uma instrução "ASSOCIATORS OF" ou "REFERENCES OF" que descreve sua classe. Se a implementação do ExecQuery retornar WBEM_E_NOT_SUPPORTED, o cliente dependerá do WMI para manipular a consulta.

O WMI manipula uma consulta chamando sua implementação de CreateInstanceEnum para fornecer todas as instâncias. Em seguida, o WMI filtra as instâncias resultantes antes de retornar as instâncias para o cliente. Portanto, qualquer implementação do ExecQuery que você criar deve ser mais eficiente do que CreateInstanceEnum.

O seguinte descreve uma implementação comum do ExecQuery:

  1. Crie uma instância vazia da classe usando Provider::CreateNewInstance.
  2. Determine o subconjunto de instâncias que você deve criar.

    Você pode usar métodos como IsPropertyRequired para ver quais propriedades são necessárias e GetValuesForProp para ver quais instâncias o WMI requer. Outros métodos que lidam com as propriedades solicitadas incluem CFrameworkQuery::GetRequiredProperties, CFrameworkQuery::AllPropertiesAreRequired e CFrameworkQuery::KeysOnly.

  3. Preencha as propriedades da instância vazia usando os métodos Set da classe CInstance , como CInstance::SetByte ou CInstance::SetStringArray.
  4. Envie a instância de volta para o cliente usando CInstance::Commit.
  5. Retornar os valores de retorno apropriados.

    A implementação padrão do provedor de estrutura execQuery retorna WBEM_E_PROVIDER_NOT_CAPABLE. Se você implementar o ExecQuery, deverá usar os valores retornados comuns listados em IWbemServices::ExecQuery. No entanto, se necessário, você pode retornar qualquer código de retorno COM.

O WMI não envia consultas "ASSOCIATORS OF" ou "REFERENCES OF" por meio de provedores de estrutura. Em vez disso, o WMI usa o esquema para determinar quais classes estão relacionadas à classe em questão e gera uma consulta WQL apropriada para recuperar os resultados. Portanto, você não precisa codificar nenhum suporte adicional de consultas "ASSOCIATORS OF" e "REFERENCES OF".

No entanto, você deve ter o seguinte em mente ao escrever seu provedor de estrutura:

  • Certifique-se de dar suporte a consultas padrão em sua classe de associação, especialmente consultas em que as propriedades de referência são usadas em uma cláusula WHERE. Para obter mais informações, consulte CFrameworkQuery::GetValuesForProp.
  • No suporte à classe de associação, quando você marcar para ver se os pontos de extremidade existem, use os métodos CWbemProviderGlue::GetInstanceKeysByPath ou CWbemProviderGlue::GetInstancePropertiesByPath.

    Esses métodos permitem que os pontos de extremidade ignorem o preenchimento de propriedades com uso intensivo de recursos ou desnecessárias.

  • Verifique se todas as classes de ponto de extremidade de associação dão suporte a métodos Get por propriedade. Para obter mais informações, consulte Suporte a operações de Partial-Instance. Para obter mais informações sobre o parâmetro de consulta, consulte CFrameworkQuery.

Requisitos

   
Cliente mínimo com suporte Windows Vista
Servidor mínimo com suporte Windows Server 2008
Plataforma de Destino Windows
Cabeçalho provider.h (inclua FwCommon.h)
Biblioteca FrameDyn.lib
DLL FrameDynOS.dll; FrameDyn.dll