Como criar um método WMI

  • Artigo

Para criar um método WMI, defina os parâmetros de entrada e saída para o método. Os parâmetros de entrada e saída são representados por uma classe do sistema de WMI especial __PARAMETERS. Para obter mais informações, consulte Como chamar um método e Como escrever um provedor de método.

As seguintes seções são abordadas neste tópico:

Como criar um método de classe WMI no MOF

No WMI, os métodos de provedor geralmente são ações distintas relacionadas ao objeto que a classe representa. Em vez de alterar o valor de uma propriedade para executar uma ação, um método deve ser criado. Por exemplo, você pode habilitar ou desabilitar uma NIC (central de informações de rede) representada por Win32_NetworkAdapter usando os métodos Enable e Disable. Embora essas ações possam ser representadas como uma propriedade de leitura/gravação, o design recomendado é a criação de um método. Como alternativa, se você quiser tornar um estado ou valor visível para a classe, a abordagem recomendada será a criação de uma propriedade de leitura/gravação em vez de um método. Em Win32_NetworkAdapter, a propriedade NetEnabled torna o estado do adaptador visível, mas as alterações entre estados são executadas pelos métodos Enable ou Disable.

As declarações de classe podem incluir a declaração de um ou mais métodos. Você pode optar por herdar os métodos de uma classe pai ou implementar os seus próprios. Se você optar por implementar seus próprios métodos, deverá declarar o método e marcá-lo com marcas específicas de qualificador.

O procedimento a seguir descreve como declarar um método em uma classe que não herda de uma classe base.

Para declarar um método

  1. Defina o nome do método entre as chaves de uma declaração de classe, seguido por quaisquer qualificadores.

    O exemplo de código a seguir descreve a sintaxe de um método.

    [Dynamic, Provider ("ProviderName")]
class ClassName
{
    [Implemented] <ReturnType> <MethodName>
        ([ParameterDirection, IDQualifier] 
        <ParameterType> <ParameterName>);
};

  2. Quando terminar, insira o código MOF (Managed Object Format) no repositório do WMI com uma chamada ao compilador do MOF.

    Para obter mais informações, consulte Compilar arquivos MOF.

A lista a seguir define os elementos da declaração de método.

Provider

Vincula um provedor específico à descrição da classe. O valor do qualificador Provider é o nome do provedor, que informa ao WMI onde reside o código que dá suporte ao método. Um provedor também deve marcar com o qualificador Dynamic qualquer classe que tenha instâncias dinâmicas. Por outro lado, não use o qualificador Dynamic para marcar uma classe que contém uma instância estática com métodos Implemented.

Implemented

Declara que você implementará um método, em vez de herdar a implementação do método da classe pai. Por padrão, o WMI propaga a implementação da classe pai para uma classe derivada, a menos que a classe derivada forneça uma implementação. A omissão do qualificador Implemented indica que o método não tem nenhuma implementação nessa classe. Se você redeclarar um método sem o qualificador Implemented, o WMI ainda pressupõe que você não implementará esse método e invocará a implementação do método de classe pai quando chamado. Dessa forma, a redeclaração de um método em uma classe derivada sem anexar o qualificador Implemented é útil somente quando você adiciona ou remove um qualificador de ou para o método.

ReturnType

Descreve o valor retornado pelo método. O valor retornado de um método deve ser um objeto booliano, numérico, CHAR, STRING, DATETIME ou esquema. Você também pode declarar o tipo de retorno como VOID, indicando que o método não retorna nada. No entanto, você não pode declarar uma matriz como um tipo de valor retornado.

MethodName

Define o nome do método. Todos os métodos precisam ter um nome exclusivo. O WMI não permite que dois métodos com o mesmo nome e assinaturas diferentes existam em uma classe ou hierarquia de classe. Dessa forma, você também não pode sobrecarregar um método.

ParameterDirection

Contém qualificadores que descrevem se um parâmetro é um parâmetro de entrada, um parâmetro de saída ou ambos. Não use o mesmo nome de parâmetro mais de uma vez como um parâmetro de entrada ou mais de uma vez como um parâmetro de saída. Se o mesmo nome de parâmetro aparecer com os qualificadores In e Out, a funcionalidade será conceitualmente igual ao uso dos qualificadores In, Out em um único parâmetro. No entanto, ao usar declarações separadas, os parâmetros de entrada e saída devem ser exatamente iguais em todos os outros aspectos, incluindo o número e o tipo de qualificadores ID, e o qualificador deve ser o mesmo e explicitamente declarado para ambos. É altamente recomendável usar os qualificadores In, Out em uma única declaração de parâmetro.

IDQualifier

Contém o qualificador ID que identifica exclusivamente a posição de cada parâmetro dentro da sequência de parâmetros no método. Por padrão, o compilador MOF marca automaticamente parâmetros com um qualificador ID. O compilador marca o primeiro parâmetro com um valor de 0 (zero), o segundo parâmetro com um valor de 1 (um) e assim por diante. Se necessário, você pode declarar explicitamente a sequência de ID em seu código MOF.

ParameterType

Descreve qual tipo de dados o método pode aceitar. Você pode definir um tipo de parâmetro como qualquer valor de dados MOF, incluindo uma matriz, um objeto de esquema ou uma referência. Ao usar uma matriz como parâmetro, use a matriz como não associada ou com um tamanho explícito.

ParameterName

Contém o nome do parâmetro. Você também pode definir o valor padrão do parâmetro neste ponto. Parâmetros sem valores iniciais permanecem não atribuídos.

O exemplo de código a seguir descreve a listagem de parâmetros e qualificadores.

[Dynamic, Provider ("ProviderX")]
class MyClass
{
    [Implemented] 
    sint32 MyMethod1 ([in, id(0)] sint32 InParam);
    [Implemented] 
    void MyMethod2 ([in, id(0)] sint32 InParam, 
       [out, id(1)] sint32 OutParam);
    [Implemented] 
    sint32 MyMethod3 ([in, out, id(0)] sint32 InOutParam);
};

O exemplo de código a seguir descreve como usar uma matriz em um parâmetro MOF.

[Dynamic, Provider ("ProviderX")]
class MyClass
{
    [Implemented] 
    sint32 MyMethod1 ([in, id(0)] Win32_LogicalDisk DiskParam[]);
    [Implemented] 
    sint32 MyMethod2 ([in, id(0)] Win32_LogicalDisk DiskParam[32]);
};

O exemplo de código a seguir descreve o uso de um objeto de esquema como um parâmetro e um valor retornado.

[Dynamic, Provider ("ProviderX")]
class MyClass
{
    [Implemented] sint32 MyMethod1 ([in, id(0)] Win32_LogicalDisk 
        DiskParam);
    [Implemented] 
    Win32_LogicalDisk MyMethod2 ([in, id(0)] string DiskVolLabel);
};

O exemplo de código a seguir descreve como incluir duas referências: uma para uma instância da classe Win32_LogicalDisk e a outra para uma instância de um tipo de objeto desconhecido.

[Dynamic, Provider("ProviderX")]
class MyClass
{
    [Implemented] 
    sint32 MyMethod1 ([in, id(0)] Win32_LogicalDisk ref DiskRef);
    [Implemented] 
    sint32 MyMethod2 ([in, id(0)] object ref AnyObject);
};

Como criar um método de classe WMI no C++

O procedimento a seguir descreve como criar um método de classe WMI programaticamente.

Para criar um método de classe WMI programaticamente

  1. Crie a classe à qual o método pertencerá.

    Primeiro, você deve ter uma classe para posicionar o método antes de criá-lo.

  2. Recupere duas classes filho da classe __PARAMETERS do sistema usando IWbemServices::GetObject ou GetObjectAsync.

    Use a primeira classe filho para descrever os parâmetros in e a segunda para descrever os parâmetros externos. Se necessário, você pode executar uma única recuperação seguida por uma chamada para o método IWbemClassObject::Clone.

  3. Escreva os parâmetros de entrada na primeira classe e os parâmetros de saída na segunda classe, usando uma ou mais chamadas para IWbemClassObject::Put.

    Ao descrever os parâmetros para um método, observe as seguintes regras e restrições:

    • Trate os parâmetros [in, out] como entradas separadas, uma no objeto que contém os parâmetros de entrada e outra no objeto que contém os parâmetros de saída.

    • Além dos qualificadores [in, out], os qualificadores restantes devem ser exatamente os mesmos.

    • Especifique os qualificadores ID, começando em 0 (zero), um para cada parâmetro.

      A ordem dos parâmetros de entrada ou saída é estabelecida pelo valor do qualificador ID em cada parâmetro. Todos os argumentos de entrada devem preceder os argumentos de saída. Alterar a ordem dos parâmetros de entrada e saída do método ao atualizar um provedor de método existente pode fazer com que os aplicativos que chamam o método falhem. Adicione novos parâmetros de entrada no final dos parâmetros existentes em vez de inseri-los na sequência já estabelecida.

      Não deixe lacunas na sequência do qualificador ID.

    • Coloque o valor retornado na classe out-parameters como uma propriedade chamada ReturnValue.

      Isso identifica a propriedade como o valor retornado do método. O tipo CIM dessa propriedade é o tipo de retorno do método. Se o método tiver um tipo de retorno nulo, não tenha uma propriedade ReturnValue. Além disso, a propriedade ReturnValue não pode ter um qualificador ID como os argumentos do método. A atribuição de um qualificador ID à propriedade ReturnValue produz um erro WMI.

    • Expresse quaisquer valores de parâmetro padrão para a propriedade na classe.

  4. Coloque ambos objetos __PARAMETERS na classe pai com uma chamada para IWbemClassObject::PutMethod.

    Uma única chamada para PutMethod pode posicionar ambos objetos __PARAMETERS na classe.

Criar uma classe