Inside the WMI Object Model
The DMTF’s Common
Information Model (CIM) is the basis for the WMI object model. CIM
defines a core model that provides the basic semantics for representing
managed objects, and describes several common models representing
specific areas of management, such as systems, networks, and
applications. Third parties develop extended models, which
are platform-specific implementations of common classes. You can
categorize the class definitions used to represent managed objects as
follows:
Core classes
represent general constructs that are applicable to all areas of
management. The Managed Element class is the most basic and general
class and is at the root of the CIM class hierarchy. Other examples of
core classes include
Component
Collection
Statistical Information
Core classes are part of the core model and are the basic building blocks from which other classes are developed.
Common classes
represent specific types of managed objects. Common classes are
generalized representations of a category of objects, such as a computer
system or an application. These classes are not tied to a particular
implementation or technology.
Extended classes are technology-specific extensions of common classes, such as a Win32 computer system or Configuration Manager.
WMI classes support
inheritance, meaning you can derive a new class from an existing class.
The derived class is often referred to as a child or subclass
of the original class. The child class has a set of attributes
available to it from its parent class. Inheritance saves developers the
effort of needing to create definitions for all class attributes from
scratch. Developers of a child class can optionally override the
definition of an inherited attribute with a different definition better
suited to that class. A child class can also have additional attributes
not inherited from the parent.
Typically, core and common classes are not used directly to represent managed objects. Rather, they are used as base classes from which other classes are derived.
A special type of WMI class is the system class.
WMI uses system classes internally to support its operations. They
represent providers, WMI events, inheritance metadata about WMI classes,
and more.
WMI classes support three types of attributes:
Properties
are the characteristics of the managed objects, such as the name of a
computer system or the current value of a performance counter.
Methods
are actions that a managed object can perform on your behalf. As an
example, an object representing a Windows service may provide methods to
start, stop, or restart the service.
Associations
are actually links to a special type of WMI class, an association
class, which represents a relationship between other objects. The “Looking Inside the CIMV2 Namespace”
section examines the associations that link a file share security
descriptor to the share and to the security principals specified in its
access control lists.
You can also modify WMI classes, properties, and methods by the use of qualifiers.
A qualifier on a class may designate it as abstract, meaning the class
is used only to derive other classes and no objects of that class will
be instantiated. Two important qualifiers designate data as static or
dynamic:
The CIM
specification also includes a language for exchanging management
information. The Managed Object Format (MOF) provides a way to describe
classes, instances, and other CIM constructs in textual form. In WMI,
MOF files are included with providers to register the classes,
properties, objects, and events they support with WMI. The information
in the MOF files is compiled and stored in the WMI repository.
Namespaces organize WMI classes and other elements. A namespace
is a container, much like a folder in a file system. Developers can add
objects to existing namespaces or create new namespaces. As already
seen in the “Managing WMI” section, the Root namespace defines a hierarchy organizing the namespaces on a system. The “Managing WMI”
section also mentions that the WMI Control tool allows you to specify
the default namespace for connections to WMI. Generally, the default
namespace will be Root\CIMV2. This is the namespace defining most of the
major classes for Windows management. The next section looks at several
of the classes in that namespace. Because Configuration Manager is all
about Windows Management, it is not surprising that ConfigMgr uses this
namespace extensively. ConfigMgr also defines its own namespaces,
discussed in the section “Looking Inside Configuration Manager with WMI.”
This
section covers the major concepts of WMI and the CIM model, which will
be used to look inside ConfigMgr WMI activity. If you are interested in
learning about other aspects of CIM, a good place to start is the
tutorial at http://www.wbemsolutions.com/tutorials/CIM/index.html. The full CIM specification can by found at http://www.dmtf.org/standards/cim/cim_spec_v22. Documentation for WMI is available at http://msdn.microsoft.com/en-us/library/aa394582.aspx.
Looking Inside the CIMV2 Namespace
Windows provides a
basic tool called WBEMTest that allows you to connect to a WMI namespace
and execute WMI operations. There are also a number of tools from
Microsoft and third parties with more intuitive graphical interfaces for
displaying and navigating WMI namespaces. This section uses the
Microsoft WMI Administrative Tools to look into the Root\CIMV2
namespace. These tools include the WMI CIM Studio and the WMI Object
Browser. You can download the WMI Administrative Tools from http://www.microsoft.com/downloads/details.aspx?FamilyID=6430f853-1120-48db-8cc5-f2abdc3ed314&DisplayLang=en or search for WMITools at www.microsoft.com/downloads. After downloading, you will need to run the WMITools.exe executable file to install the tools.
You can use CIM Studio
to explore the classes in a namespace and view the properties, methods,
and associations of each class. Perform the following steps to launch
CIM Studio and connect to the CIMV2 namespace:
1. | Select Start -> All Programs -> WMI Tools -> WMI CIM Studio.
|
2. | CIM Studio will open a web browser and attempt to run an ActiveX control.
If your browser blocks the control, select the option Allow Blocked Content.
|
3. | Verify
that root\CIMV2 displays in the Connect to namespace dialog box and
then click OK. Notice that you can also browse to other namespaces on
the local computer of a remote computer.
|
4. | Click OK to accept the default logon settings.
|
When you open CIM
Studio and connect to a namespace, the Class Explorer in the left pane
contains a tree structure that displays the base classes in the selected
namespace. Figure 8 displays the left pane with some of the root classes of the CIMV2 namespace.
Notice that most of the class names in Figure 3.15 begin with CIM or Win32. Class names starting with CIM
indicate that the class is one of the core or common classes defined in
the DMTF CIM schema. Extended classes are those classes with names
beginning with Win32, which are part of the Win32 schema defined by Microsoft for managing the Win32 environment.
The Win32_LogicalShareSecuritySetting class
This section uses the
Win32_LogicalShareSecuritySetting class to illustrate how you can use
CIM Studio to understand a class of managed objects. Figure 9
shows the Win32_LogicalShareSecuritySetting class displayed in CIM
Studio. This class represents the security settings on a Windows file
share. The expanded tree shows the root class, CIM_Setting, and the
classes derived from each successive subclass.
Looking at the tree
structure, you can see that Win32_LogicalShareSecuritySetting is derived
from Win32_SecuritySetting, which in turn is derived from CIM_Setting.
The Class View in the right pane displays the properties of the
Win32_LogicalShareSecuritySetting class. To the left of each property
name you will see one of the following icons:
A yellow downward-pointing arrow indicates the property is inherited from the parent class.
A property page indicates the property is defined within the class.
A
computer system indicates that the property is a system class. You can
also recognize system classes by their names, which always start with a
double underscore (__).
As an example, each WMI
class has certain System properties, such as __PATH, __DYNASTY,
__SUPERCLASS, and __DERIVATION. Here are some points to keep in mind:
The __PATH
property shows the location of the class in the namespace hierarchy.
Management applications and scripts use the __PATH property to connect
to the class.
__DYNASTY,
__SUPERCLASS, and __DERIVATION are all related to class inheritance and
represent the root class from which the class is derived, its immediate
parent, and the entire family tree of the class, respectively.
Clicking
the Array button next to __DERIVATION displays the array of parent
classes from which the class is derived. The array is essentially the
inheritance information already observed by traversing the tree, as
shown in Figure 10.
The remaining properties
of Win32_LogicalShareSecuritySetting are the ones that actually
represent characteristics describing instances of Windows file share
security settings. You can see that except for the name, all of these
properties are inherited. An object that has nothing unique about it
except its name would not be very interesting, but there is more to the
Win32_LogicalShareSecuritySetting class than just the class properties.
The most interesting attributes of Win32_LogicalShareSecuritySetting are
on the remaining tabs of the CIM Studio Class View pane.
Clicking
the Methods tab displays the two methods of the
Win32_LogicalShareSecuritySetting class (GetSecurityDescriptor and
SetSecurityDescriptor), as shown in Figure 11.
Getting Additional Information
These methods let
you work with the permissions on the actual file share. Clicking the
Help button on the toolbar in the upper-right corner of Class View in Figure 3.18 provides additional information about the class.
|
The help entry for Win32_LogicalShareSecuritySetting returns the following information:
security settings for a logical file
Caption
A short textual description (one-line string) of the CIM_Setting object.
ControlFlags
Inheritance-related flags. See SECURITY_DESCRIPTOR_CONTROL
Description
A textual description of the CIM_Setting object.
Name
The name of the share
SettingID
The identifier by which the CIM_Setting object is known.
uint32 GetSecurityDescriptor(
[out] object:Win32_SecurityDescriptor Descriptor
);
Retrieves a structural representation of the object's security descriptor.
The method returns an integer value that can be interpreted as follows:
0 - Successful completion.
2 - The user does not have access to the requested information.
8 - Unknown failure.
9 - The user does not have adequate privileges.
21 - The specified parameter is invalid.
Other - For integer values other than those listed above,
refer to Win32 error code documentation.
Descriptor
<description missing>
uint32 SetSecurityDescriptor(
[in] object:Win32_SecurityDescriptor Descriptor
);
Sets security descriptor to the specified structure.
The method returns an integer value that can be interpreted as follows:
0 - Successful completion.
2 - The user does not have access to the requested information.
8 - Unknown failure.
9 - The user does not have adequate privileges.
21 - The specified parameter is invalid.
Other - For integer values other than those listed above,
refer to Win32 error code documentation.
Descriptor
<description missing>
|
Putting It All Together
The Win32_LogicalShareSecuritySetting example in the “A Sample Help Entry”
sidebar shows that the GetSecurityDescriptor method returns the current
security descriptor of the file share as an object of type
Win32_SecurityDescriptor. The SetSecurityDescriptor method accepts a
Win32_SecurityDescriptor object as input and replaces the security
descriptor on the share with information supplied in the security
descriptor object. The example also lists the status codes returned by
these methods.
The information on the Class View Associations tab, shown in Figure 12, provides the key to understanding the implementation of Win32_LogicalShareSecuritySetting.
The Win32_LogicalShareSecuritySetting Associations tab shown in Figure 12
displays an association with the Win32_Share class as well as
associations with the two instances of the Win32_SID class. Class icons
marked with a diagonal arrow represent the association classes linking
other classes together. If you hover your mouse cursor over the Class
icons for each of the association classes linking
Win32_LogicalShareSecuritySetting to Win32_SID class instances, you can
see that one is a Win32_LogicalShareAccess class instance and the other
is a Win32_LogicalShareAuditing class instance.
Instances of the
Win32_LogicalShareAccess association represent access control entries
(ACEs) in the DACL (that is, share permissions).
The
Win32_LogicalShareAuditing instances represent ACEs in the SACL (audit
settings) on the share. You can double-click any of the classes shown on
this tab to navigate to it in Class View.
Because
objects of the Win32_LogicalShareSecuritySetting class allow you to
work with live data on the system, you would expect this to be a dynamic
class. You can verify this by returning to the Properties or Methods
tab, right-clicking any attribute, and selecting Object Qualifiers. The
Win32_LogicalShareSecuritySetting object qualifiers are shown in Figure 13, including the Dynamic qualifier, which is of type Boolean with a value of True.
From the Class View you
can also use the Instances button to display all instances of the class,
and you can open the properties of an instance by double-clicking it.
The section “Hardware Inventory Through WMI”
discusses how to use another of the WMI administrative tools, the WMI
Object Browser, to view class instances. Just above the toolbar are
icons that launch the MOF generator and MOF compiler wizards.
To launch the MOF compiler, you must check the Class icon next to the
class and double-click the Wizard icon. The MOF language defining the
Win32_LogicalShareSecuritySetting class is as follows:
#pragma namespace("\\\\.\\ROOT\\CIMV2")
//**************************************************************************
//* Class: Win32_LogicalShareSecuritySetting
//* Derived from: Win32_SecuritySetting
//**************************************************************************
[dynamic: ToInstance, provider("SECRCW32"): ToInstance, Locale(1033): ToInstance,
UUID("{8502C591-5FBB-11D2-AAC1-006008C78BC7}"): ToInstance]
class Win32_LogicalShareSecuritySetting : Win32_SecuritySetting
{
[key, read: ToSubClass] string Name;
[Privileges{"SeSecurityPrivilege", "SeRestorePrivilege"}: ToSubClass,
implemented, ValueMap{"0", "2", "8", "9", "21", ".."}]
uint32 GetSecurityDescriptor([OUT] Win32_SecurityDescriptor Descriptor);
[Privileges{"SeSecurityPrivilege", "SeRestorePrivilege"}: ToSubClass,
implemented, ValueMap{"0", "2", "8", "9", "21", ".."}]
uint32 SetSecurityDescriptor([IN] Win32_SecurityDescriptor Descriptor);
};
The first line of the MOF entry, #pragma namespace ("\\\\.\\ROOT\\CIMV2"),
is a preprocessor command instructing the MOF compiler to load the MOF
definitions into the Root\CIMV2 namespace. A comment block follows,
which indicates the class name Class: Win32_LogicalShareSecuritySetting and the class derivation Derived from: Win32_SecuritySetting. Next, a bracketed list of object qualifiers (refer to Figure 13 for a GUI representation of the object qualifiers):
The dynamic qualifier indicates that the class is dynamic and will be instantiated at runtime.
The provider qualifier specifies that the instance provider is “SECRCW32.”
The locale qualifier indicates the locale of the class, 1033 (U.S. English).
The UUID qualifier is a Universally Unique Identifier for the class.
Each of these qualifiers propagates to class instances, as indicated by the toinstance keyword.
The next section contains the class declaration Win32_LogicalShareSecuritySetting : Win32_SecuritySetting.
This declaration derives the Win32_LogicalShareSecuritySetting class
from the Win32_SecuritySetting base class. The body of the class
declaration declares locally defined class properties and methods. The
Name property (the name of the share) is declared to be of type String
and designated as a key value, indicating that it uniquely identifies an
instance of the class. The GetSecurityDescriptor and
SetSecurityDescriptor methods are both of type uint32, indicating that
each method return an unsigned 32-bit integer. GetSecurityDescriptor has
an output parameter of type Win32_SecurityDescriptor, whereas
SetSecurityDescriptor has a corresponding input parameter of the same
type. Immediately preceding each of these method definitions you will
see the following method qualifiers specified:
Privileges requests the access privileges required to manipulate Win32 security descriptors.
Implemented is a Boolean value indicating the method is implemented in the class.
Valuemap specifies the method’s return values. The “A Sample Help Entry” sidebar lists the meaning of each of these values.
In addition to the
locally implemented properties and qualifiers, the
Win32_LogicalShareSecuritySetting class inherits properties and
qualifiers defined as part of its parent class, Win32_SecuritySetting.
Before continuing, you may want to explore several other classes in the Root\CIMV2 namespace:
Work your way up
the inheritance tree from the Win32_LogicalShareSecuritySetting class
and see where each of the inherited properties of the class originates.
In addition, notice that if you bring up the object qualifiers on the
parent classes, you can see these are qualified as abstract classes.
The
immediate sibling of the Win32_LogicalShareSecuritySetting class is the
Win32_LogicalFileSecuritySetting class. Notice the differences in the
properties and associations for this class. Share security and file
security have many characteristics in common but a few important
differences. Seeing how they are both derived from the
Win32_SecuritySetting class demonstrates the power and flexibility of
class inheritance.
Expand
the CIM_StatisticalInformation root class and then the Win32_Perf
class. The two branches of Win32_Perf show how a variety of performance
counters are implemented as managed objects.
This section looked
at several of the default classes in the Root\CIMV2 namespace and
discussed how to use CIM Studio to explore a WMI namespace. The “Hardware Inventory Through WMI” section looks at how ConfigMgr uses the classes in Root\CIMV2 and adds some of its own classes.
