Création d’une méthode WMI

  • Article

Pour créer une méthode WMI, définissez les paramètres d’entrée et de sortie de la méthode. Les paramètres d’entrée et de sortie sont représentés par une classe système WMI spéciale __PARAMETERS. Pour plus d’informations, consultez Appel d’une méthode et Écriture d’un fournisseur de méthode.

Les sections suivantes seront abordées dans cette rubrique :

Création d’une méthode de classe WMI dans MOF

Dans WMI, les méthodes de fournisseur sont généralement des actions distinctes liées à l’objet que la classe représente. Au lieu de modifier la valeur d’une propriété pour exécuter une action, une méthode doit être créée. Par exemple, vous pouvez activer ou désactiver un centre d’informations réseau (NIC) représenté par Win32_NetworkAdapter à l’aide des méthodes Activer et Désactiver. Bien que ces actions puissent être représentées sous la forme d’une propriété en lecture/écriture, la conception recommandée consiste à créer une méthode. Si vous souhaitez rendre un état ou une valeur visible pour la classe, l’approche recommandée consiste à créer une propriété en lecture/écriture plutôt qu’une méthode. Dans Win32_NetworkAdapter, la propriété NetEnabled rend l’état de l’adaptateur visible, mais les modifications entre les états sont exécutées par les méthodes Activer ou Désactiver.

Les déclarations de classe peuvent inclure la déclaration d’une ou plusieurs méthodes. Vous pouvez choisir d’hériter des méthodes d’une classe parente ou d’implémenter les vôtres. Si vous choisissez d’implémenter vos propres méthodes, vous devez déclarer la méthode et marquer la méthode avec des balises de qualificateur spécifiques.

La procédure suivante décrit comment déclarer une méthode dans une classe qui n’hérite pas d’une classe de base.

Pour déclarer une méthode

  1. Définissez le nom de votre méthode entre les accolades d’une déclaration de classe, suivies des qualificateurs éventuels.

    L’exemple de code suivant décrit la syntaxe d’une méthode.

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

  2. Lorsque vous avez terminé, insérez votre code MOF (Managed Object Format) dans le référentiel WMI avec un appel au compilateur MOF.

    Pour plus d’informations, consultez Compilation de fichiers MOF.

La liste suivante définit les éléments de la déclaration de méthode.

Fournisseur

Lie un fournisseur spécifique à la description de votre classe. La valeur du qualificateur fournisseur est le nom du fournisseur, qui indique à WMI où réside le code qui prend en charge votre méthode. Un fournisseur doit également marquer avec le qualificateur dynamique toute classe qui a des instances dynamiques. En revanche, n’utilisez pas le qualificateur dynamique pour marquer une classe qui contient une instance statique avec des méthodes implémentées.

Implémenté

Déclare que vous allez implémenter une méthode, plutôt que d’hériter de l’implémentation de méthode de la classe parente. Par défaut, WMI propage l’implémentation de la classe parente à une classe dérivée, sauf si la classe dérivée fournit une implémentation. Omettre le qualificateur Implémenté indique que la méthode n’a aucune implémentation dans cette classe. Si vous redéclarez une méthode sans le qualificateur Implémenté , WMI suppose toujours que vous n’allez pas implémenter cette méthode et appelle l’implémentation de la méthode de classe parente lorsqu’elle est appelée. Par conséquent, la nouvelle déclaration d’une méthode dans une classe dérivée sans attacher le qualificateur Implémenté n’est utile que lorsque vous ajoutez ou supprimez un qualificateur à la méthode ou à partir de celle-ci.

ReturnType

Décrit la valeur retournée par la méthode. La valeur de retour d’une méthode doit être un objet booléen, numérique, CHAR, STRING, DATETIME ou schéma. Vous pouvez également déclarer le type de retour comme VOID, ce qui indique que la méthode ne retourne rien. Toutefois, vous ne pouvez pas déclarer un tableau en tant que type de valeur de retour.

MethodName

Nom de la méthode. Chaque méthode doit avoir un nom unique. WMI n’autorise pas l’existence de deux méthodes portant le même nom et des signatures différentes dans une classe ou au sein d’une hiérarchie de classes. Par conséquent, vous ne pouvez pas surcharger une méthode.

ParameterDirection

Contient des qualificateurs qui décrivent si un paramètre est un paramètre d’entrée, un paramètre de sortie ou les deux. N’utilisez pas le même nom de paramètre plusieurs fois comme paramètre d’entrée ou plusieurs fois comme paramètre de sortie. Si le même nom de paramètre apparaît avec les qualificateurs In et Out , la fonctionnalité est conceptuellement identique à l’utilisation des qualificateurs In, Out sur un seul paramètre. Toutefois, lors de l’utilisation de déclarations distinctes, les paramètres d’entrée et de sortie doivent être exactement les mêmes à tous les autres égards, y compris le nombre et le type de qualificateurs d’ID , et le qualificateur doit être le même et explicitement déclaré pour les deux. Il est vivement recommandé d’utiliser les qualificateurs In, Out au sein d’une déclaration de paramètre unique.

IDQualifier

Contient le qualificateur d’ID qui identifie de manière unique la position de chaque paramètre dans la séquence de paramètres de la méthode. Par défaut, le compilateur MOF marque automatiquement les paramètres avec un qualificateur d’ID . Le compilateur marque le premier paramètre avec la valeur 0 (zéro), le deuxième paramètre la valeur 1 (un), et ainsi de suite. Si nécessaire, vous pouvez indiquer explicitement la séquence d’ID dans votre code MOF.

ParameterType

Décrit le type de données que la méthode peut accepter. Vous pouvez définir un type de paramètre comme n’importe quelle valeur de données MOF, y compris un tableau, un objet de schéma ou une référence. Lorsque vous utilisez un tableau en tant que paramètre, utilisez le tableau comme non lié ou avec une taille explicite.

ParameterName

Contient le nom du paramètre. Vous pouvez également choisir de définir la valeur par défaut du paramètre à ce stade. Les paramètres qui n’ont pas de valeurs initiales ne sont pas attribués.

L’exemple de code suivant décrit la liste des paramètres et les qualificateurs.

[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);
};

L’exemple de code suivant décrit comment utiliser un tableau dans un paramètre 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]);
};

L’exemple de code suivant décrit l’utilisation d’un objet de schéma comme paramètre et comme valeur de retour.

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

L’exemple de code suivant explique comment inclure deux références : l’une à un instance de la classe Win32_LogicalDisk et l’autre à un instance d’un type d’objet inconnu.

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

Création d’une méthode de classe WMI en C++

La procédure suivante décrit comment créer une méthode de classe WMI par programme.

Pour créer une méthode de classe WMI par programmation

  1. Créez la classe à laquelle la méthode appartiendra.

    Vous devez d’abord disposer d’une classe dans laquelle placer la méthode avant de créer la méthode.

  2. Récupérez deux classes enfants de la classe système __PARAMETERS en utilisant IWbemServices::GetObject ou GetObjectAsync.

    Utilisez la première classe enfant pour décrire les paramètres entrants et la seconde pour décrire les paramètres de sortie. Si nécessaire, vous pouvez effectuer une récupération unique suivie d’un appel à la méthode IWbemClassObject::Clone .

  3. Écrivez les in-parameters dans la première classe et les out-parameters dans la deuxième classe, à l’aide d’un ou plusieurs appels à IWbemClassObject::P ut.

    Lorsque vous décrivez des paramètres à une méthode, observez les règles et restrictions suivantes :

    • Traitez les paramètres [in, out] comme des entrées distinctes, l’une dans l’objet qui contient les in-parameters et l’autre dans l’objet qui contient les out-parameters.

    • En dehors des qualificateurs [in, out], les qualificateurs restants doivent être exactement les mêmes.

    • Spécifiez les qualificateurs d’ID , à partir de 0 (zéro), un pour chaque paramètre.

      L’ordre des paramètres d’entrée ou de sortie est établi par la valeur du qualificateur d’ID sur chaque paramètre. Tous les arguments d’entrée doivent précéder tous les arguments de sortie. La modification de l’ordre des paramètres d’entrée et de sortie de méthode lors de la mise à jour d’un fournisseur de méthode existant peut entraîner l’échec des applications qui appellent la méthode. Ajoutez de nouveaux paramètres d’entrée à la fin des paramètres existants au lieu de les insérer dans la séquence déjà établie.

      Veillez à ne laisser aucune lacune dans la séquence de qualificateurs d’ID.

    • Placez la valeur de retour dans la classe out-parameters en tant que propriété nommée ReturnValue.

      Cela identifie la propriété comme valeur de retour de la méthode. Le type CIM de cette propriété est le type de retour de la méthode. Si la méthode a un type de retour void, il n’y a pas de propriété ReturnValue du tout. En outre, la propriété ReturnValue ne peut pas avoir de qualificateur d’ID comme les arguments de la méthode. L’affectation d’un qualificateur d’ID à la propriété ReturnValue génère une erreur WMI.

    • Exprimez toutes les valeurs de paramètre par défaut pour la propriété dans la classe .

  4. Placez les deux objets __PARAMETERS dans la classe parente avec un appel à IWbemClassObject::PutMethod.

    Un seul appel à PutMethod peut placer les deux objets __PARAMETERS dans la classe.

Création d’une classe