Using Qualifiers

[This is preliminary documentation and subject to change.]

Qualifiers are modifiers that can be used to describe a class, an instance, a property, a method, or a parameter. Creators of classes and instances can attach qualifiers to their class and instance declarations to provide the user of those declarations, typically management applications, with more detail. Similar to properties, qualifiers have a name, a type, and a value. Unlike properties, the value of a qualifier rarely changes. Also unlike properties, a qualifier can be associated with a flag known as a flavor. Qualifier flavors indicate how a qualifier is used. For example, the qualifier flavor NotOverrideable indicates that when a qualifier is propagated from a base class to a derived class or from a class to an instance, its value cannot be changed. All inherited versions of the qualifier have the original value.

Some examples of qualifiers are:

Some of the qualifiers that are commonly used in MOF syntax are defined by WBEM and are known as standard qualifiers. The Dynamic and Read qualifiers are examples of standard qualifiers. Other qualifiers are included in the Desktop Management Task Force (DMTF) CIM specification, available from http:// www.dmtf.org. Still other qualifiers are defined by the creators of new classes, typically providers. The Units qualifier is an example of a non-standard, provider-specific qualifier.

WBEM enforces virtually no rules regarding the the naming of qualifiers or their use. The only restriction is that neither the standard CIMOM qualifiers or those included in the CIM specification can be redefined. To avoid potential conflict, WBEM recommends that providers prefix their new qualifiers with the name or their schema.

In MOF syntax, a qualifier is placed before the keyword or identifier that it is describing:

[QualifierName1 ("QualifierValue1")]

The following syntax shows the placement of class qualifiers, property qualifiers, method qualifiers, and parameter qualifiers:

[qualifiers...]
class MyClass
{
    [qualifiers...]  uint32 dwNumber;
    [qualifiers...]  sint32 ValueMethod ();
    sint32 MyMethod ([qualifiers...] sint32 Param);
};
 

All qualifier names are case-insensitive. Their type is inferred from the declaration syntax as is described in the following table:

Homogeneous arrays of any of these types are supported. The other Automation types such as VT_I2 and VT_NULL are not supported.

The following class definition is an example of a derived class that has class qualifiers. The class qualifiers, Dynamic and Provider, are standard qualifiers defined by WBEM. Dynamic is a boolean qualifier that when set indicates that instances of the class are dynamically provided. Provider is a string qualifier supplying the name of the provider associated with the class.

[Dynamic, Provider ("ProviderX")] 
class MyDerivedClass : MyClass
{
    [Implemented] uint32 dwNumber ;
    [Implemented] sint32 ValueMethod();
    [Implemented] sint32 MyMethod ([in] sint32 Param)
} ;

The next definition shows how to use qualifiers with instances. The two instances of the MyClass class are differentiated using the Description qualifier:

[Description ("This instance is the first")] 
instance of MyClass
{
    dwNumber = 1;
} ;

  [Description ("This instance is the second")] 
instance of MyClass
{
    dwNumber = 2;
} ;

One of the most common uses of property qualifiers is to associate access permissions with a property. For example, this class has three properties, two that are read-only and one that is read/write. The read/write property is also marked with the Key qualifier, identifying it as the unique identifier for the class. Although keys are optional like all other qualifiers, most classes include one. Classes that are intended solely as abstract base classes do not necessarily include a key as a property.

class MyClass3 
{
    [read, write, KEY] STRING  MyKey;
    [read] real32 MyProp1;
    [read] real64 MyProp2;
};

WBEM defines two qualifiers that are commonly used with methods: Implemented and Static. The Implemented qualifier indicates whether a method has an implementation available for a particular class or instance. Because the data type of this qualifier is boolean, its absence indicates the absence of an implementation. The Static qualifier marks a method as able to run against an object path that refers to a class definition. These qualilfiers are used as follows:

[Dynamic, Provider ("ProviderY")]
class MyMethodClass 
{
    [read, write, KEY] STRING  MyKey;
    [implemented] sint32 MyMethod1 ();;
    [static] sint32 MyMethod2();
};

Parameters to methods can have standard qualifiers that describe whether a parameter is an input parameter, an output parameter, or an input parameter and an output parameter. Other qualifiers can also be attached to method parameters.

[Dynamic, Provider ("ProviderZ")]
class MyMethodClass 
{
    [read, write, KEY] STRING  MyKey;
    [implemented] sint32 MyMethod1 ([in] uint32 Param1);
    [static] sint32 MyMethod2 ([out] uint32 Param2);
    sint32 MyMethod3 ([in] uint32 Param1, [in, out] string Param3);
};