Operating System

Windows Management Instrumentation
Provider Programming

White Paper

Abstract

This paper presents an overview of the Microsoft® Windows® Management Instrumentation (WMI) Providers API. The Windows Management Instrumentation is an implementation of the Distributed Management Task Force (DMTF) Web-Based Enterprise Management (WBEM) initiative that provides standards for accessing and sharing management information in an enterprise environment.

© 1999 Microsoft Corporation. All rights reserved.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.

Microsoft, Active Directory, ActiveX, IntelliMirror, Jscript,Visual Basic, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation.

Other product or company names mentioned herein may be the trademarks of their respective owners.

Microsoft Corporation • One Microsoft Way • Redmond, WA 98052-6399 • USA

12/99

Contents

Introduction

Windows Management Instrumentation Technology

WMI Architecture Overview

Programming Basics for WMI Providers

Provider Primary Interfaces

Registering a Provider

Initializing a Provider

Making Calls to WMI

Unloading a Provider

Abrupt Termination of Providers

Client Impersonation by Providers

Registering Providers

High-Performance API Providers

Provider Framework

Provider Code Generator

Compiling a Framework Provider

Error Handling for Framework Providers

Upgrading Framework Providers

Conclusion

For More Information

Introduction

The Windows® Management Instrumentation (WMI) technology is the Microsoft® implementation of the Distributed Management Task Force (DMTF) Web-Based Enterprise Management (WBEM) initiative that extends the Common Information Model (CIM) to represent management objects in Windows-based management environments. The Common Information Model, also a DMTF standard, is an extensible data model for logically organizing management objects in a consistent, unified manner in a managed environment.

Based on the Common Information Model, WBEM is a DMTF initiative and technology that establishes management infrastructure standards and provides a standardized way to access information from various hardware and software management systems in an enterprise environment. Using WBEM standards, developers can create tools and technologies that reduce the complexity and costs of enterprise management. By providing such standards, WBEM contributes to industry-wide efforts to lower total cost of ownership (TCO). TCO refers to the administrative costs associated with computer hardware and software purchases, deployment and configuration, hardware and software updates, training, maintenance, and technical support.

WBEM provides a point of integration through which data from management sources can be accessed, and it complements and extends existing management protocols and instrumentation such as Simple Network Management Protocol (SNMP), Desktop Management Interface (DMI), and Common Management Information Protocol (CMIP).

The WBEM initiative results from the cooperative efforts of Microsoft, BMC Software, Cisco Systems, Compaq Computer, and Intel, as well as many other member companies active in the DMTF.

This paper presents a brief overview of WMI (the Microsoft implementation of the WBEM standard) and its architecture and goes on to provide detailed information about the WMI provider interfaces and aspects of programming WMI providers.

Windows Management Instrumentation Technology

The Windows Management Instrumentation (WMI) technology is a management infrastructure that supports the syntax of CIM, the Managed Object Format (MOF), and a common programming interface. The MOF syntax defines the structure and contents of the CIM schema in human and machine-readable form. Windows Management Instrumentation offers a powerful set of services, including query-based information retrieval and event notification. These services and the management data are accessed through a Component Object Model (COM) programming interface. The WMI scripting interface also provides scripting support.

The WMI technology provides:

  • Access to monitor, command, and control any managed object through a common, unifying set of interfaces, regardless of the underlying instrumentation mechanism. WMI is an access mechanism.
  • A consistent model of Windows 2000 operating system operation, configuration, and status.
  • A COM Application Programming Interface (API) that supplies a single point of access for all management information.
  • Interoperability with other Windows 2000 management services. This approach can simplify the process of creating integrated, well-architected management solutions.
  • A flexible, extensible architecture. Developers can extend the information model to cover new devices, applications, and so on, by writing code modules called WMI providers, described later in this document.
  • Extensions to the Windows Driver Model (WDM) to capture instrumentation data and events from device drivers and kernel-side components.
  • A powerful event architecture. This allows management information changes to be identified, aggregated, compared, and associated with other management information. These changes can also be forwarded to local or remote management applications.
  • A rich query language that enables detailed queries of the information model.
  • A scriptable API which developers can use to create management applications. The scripting API supports several languages, including Microsoft Visual Basic®; Visual Basic for Applications; Visual Basic, Scripting Edition (VBSript); Microsoft JScript® development software. Besides VBScript and JScript, developers can use any scripting language implementation that supports Microsoft ActiveX® scripting technologies with this API (for example, a Perl scripting engine). Additionally, you can use the Windows Script Host or Microsoft Internet Explorer to write scripts using this interface. Windows Script Host, like Internet Explorer, serves as a controller engine of ActiveX scripting engines. Windows Script Host supports scripts written in VBScript, and JScript.

The WMI technology architecture consists of the following:

  • A management infrastructure. This includes the CIM Object Manager, which provides applications with uniform access to management data and a central storage area for management data called the CIM Object Manager repository.
  • WMI Providers. These function as intermediaries between the CIM Object Manager and managed objects. Using the WMI APIs, providers supply the CIM Object Manager with data from managed objects, handle requests on behalf of management applications, and generate event notifications.

The management infrastructure consists of CIM Object Manager and the CIM Object Managerrepository. Applications depend on the Object Manager to handle the interface between management applications and data providers. WMI facilitates these communications by providing a common programming interface to Windows management services using COM. This COM API supplies event notification and query processing services, and can be used in several programming language environments such as C and C++. The CIM Object Manager repository holds the CIM and extension schemas, and data information or data source details. CIM Object Manager uses the schema data in this repository when servicing requests from management applications for managed objects.

Managed objects are either physical or logical enterprise components that are modeled using CIM. For example, a managed object can be hardware such as a cable, or software such as a database application. Management applications can access managed objects through CIM Object Manager.

Management applications are applications or Windows 2000 services that use or process information originating from managed objects. Management applications can access managed object information by making a request to CIM Object Manager through one of the methods in the WMI API.

WMI providers are standard COM and Distributed Component Object Model (DCOM) servers that function as mediators between managed objects and the CIM Object Manager. If the CIM Object Manager receives a request from a management application for data that is not available from the CIM Object Manager repository or for event notifications that are not supported by the CIM Object Manager, it forwards the request to a WMI provider. Providers supply data and event notifications for managed objects that are specific to their particular domain. Figure 1 illustrates the three layer model WMI uses, which consists of providers, the CIM Object Manager, and consumers of WMI information.

Figure 1. Model that WMI uses

To implement a provider, you should use one of the following supported server types:

  • Microsoft Windows 2000 services, local or remote.
  • Standard executables (.exe files), local or remote.
  • In-process dynamic-link libraries (DLLs).

Note that local or remote Windows 2000 services and standard executables are recommended server types.

WMI ships with built-in providers (or standard providers) that supply data from sources such as the system registry. The built-in providers include:

  • Active Directory Provider—Acts as a gateway to all the information stored in the Active Directory™ service. Allows information from both WMI and Active Directory to be accessed using a single API.
  • Windows Installer Provider—Allows complete control of Windows Installer and installation of software through WMI. Also supplies information about any application installed with Windows Installer.
  • Performance CounterProvider—Exposes the raw performance counter information used to compute the performance values shown in the System Monitor tool. Any performance counters installed on a system will automatically be visible through this provider. Supported by Windows 2000.
  • Registry Provider—Allows Registry keys to be created, read, and written. WMI events can be generated when specified Registry keys are modified
  • SNMP Provider—Acts as a gateway to systems and devices that use the Simple Network Management Protocol (SNMP) for management. SNMP MIB object variables can be read and written. SNMP traps can be automatically mapped to WMI events.
  • Event Log Provider—provides access to data and event notifications from the Windows 2000 Event Log.
  • Win32 Provider—Provides information about the operating system, computer system, peripheral devices, file systems and security information.
  • WDM Provider—Supplies low level Windows Driver Model driver information for user input devices, storage devices, network interfaces, and communications ports.
  • View Provider—Allows new aggregated classes to be built up from existing classes. Source classes can be filtered for only the information of interest, information from multiple classes can be combined into a single class and data from multiple machines can be aggregated into a single view.

The WMI technology also provides support for third party custom providers. Custom providers can be used to service requests related to managed objects that are environment-specific. Providers typically use the MOF language to define and create classes. Providers use the WMI API to access the CIM Object Manager repository, and to respond to CIM Object Manager requests made initially by applications.

Additional technical papers on WMI are available on the MicrosoftWeb site.

The next sections present an overview of the WMI provider interfaces and programming guidelines.

Programming Basics for WMI Providers

WMI providers are categorized according to the types of requests that they service. The most common providers are instance providers. Instance providers supply instances of a given class and support one or more of the following asynchronous operations:

  • Instance retrieval
  • Enumeration
  • Modification
  • Deletion
  • Query processing

Class providers can support the same asynchronous operations as instance operations. However, class providers supply class definitions rather than instances of a class. Because the operations supported by class providers can negatively impact system performance, they should only be implemented when absolutely required.

Class providers can be implemented as pull or push providers; instance providers can only be implemented as pull providers. Pull providers maintain their own data, generating it dynamically when necessary. Push providers rely on WMI to maintain their data in the Common Information Model (CIM) repository.

Property providers can support the retrieval and modification of individual property values.

Method providers implement the methods of one or more classes. Having a single provider support both methods and instances can be convenient.

Event providers deliver event notifications to WMI from a data source, such as the system registry or a Simple Network Management Protocol (SNMP) device. Then, WMI forwards the events to the appropriate consumers.

Event consumer providers are used by permanent event consumers to supply the appropriate physical destination for particular events.

Providers typically perform the following tasks:

  • Register with WMI. All types of providers are required to complete the registration process.
  • Implement the IWbemProviderInit interface to perform initialization. All types of providers are required to support initialization.
  • Implement a primary interface. Most providers are required to implement a primary interface to support the features that are specific to the type of provider. Only push providers are exempt from having to implement a primary interface.
  • Support a request from WMI to unload. All pure providers (providers that operate only as providers) are required to unload when asked to do so by WMI. Non-pure providers (providers that can also operate as clients) do not have to respond to an unload request. However, such providers place an additional load on WMI by performing private operations not related to their role as providers. This should only be done if strictly necessary. Providers specify whether they are pure or non-pure in the registration process.

Provider Primary Interfaces

Providers implement a primary interface that supports the type of functionality specific to their role. The following table lists primary interfaces by provider type.

Provider / Primary interface
Class provider / IwbemServices (asynchronous methods only)
Instance provider / IWbemServices (asynchronous methods only)
Property provider / IWbemPropertyProvider
Method provider / IWbemServices (ExecMethodAsync only)
Event provider / IWbemEventProvider
Event consumer provider / IWbemEventConsumerProvider

As an option, event providers can also implement IWbemEventProviderQuerySink. This interface is most useful for providers that supply events of multiple types and that need to perform as many internal optimizations as possible.

Because IWbemServices is also used by applications and providers to request services of WMI, it contains many methods that are irrelevant to certain types of providers. Class, instance, and method providers are typically concerned with fewer than six IWbemServices methods. These providers can supply a stub implementation that returns WBEM_E_PROVIDER_NOT_CAPABLE for all of the other methods that do not support their feature set. This is illustrated in the following code sample.

HRESULT STDMETHODCALLTYPE PutClassAsync(

IWbemClassObject __RPC_FAR *pObject,

long lFlags,

IWbemContext __RPC_FAR *pCtx,

IWbemObjectSink __RPC_FAR *pResponseHandler)

{return WBEM_E_PROVIDER_NOT_CAPABLE;};

Class and instance providers can support zero or more of the following features by supplying a complete implementation of the corresponding IWbemServices method.

Feature / Class Provider Method / Instance Provider Method
Data retrieval / GetObjectAsync / GetObjectAsync
Data modification / PutClassAsync / PutInstanceAsync
Data deletion / DeleteClassAsync / DeleteInstanceAsync
Data enumeration / CreateClassEnumAsync / CreateInstanceEnumAsync
Query processing / ExecQueryAsync / ExecQueryAsync

Note that both provider types implement only the asynchronous variety of methods. There is no support in the Windows 2000 operating system for providers that implement the synchronous methods of IWbemServices.

The target data for a class provider is a class definition; the data for an instance provider is an instance of a class. Class and instance providers inform WMI of their feature set as part of the registration process.

Method providers fully implement a set of methods for a Common Information Management (CIM) object in their primary interface, ExecMethodAsync. All of the other methods return WBEM_E_NOT_IMPLEMENTED.

A single provider can act simultaneously as a class, instance, and method provider by proper registration and implementation of all relevant methods.

Property, event, and event consumer providers implement all of the methods in their primary interface.

NoteClass providers that are designed as simple push providers only implement IWbemProviderInit; they do not implement a primary interface. This is because push providers use WMI to support their operations.

Registering a Provider

Providers register with WMI to publish information about the data and operations that they support and their physical implementation. WMI uses this information to load and initialize the provider and to determine the right provider for a particular client request. All types of providers follow the same procedure for registration. Neither WMI nor the provider needs to be running during the registration process. To register with WMI, a provider must execute the following steps.

  1. Register with the Component Object Model (COM) by creating registry entries if necessary. This process applies to all COM servers and is unrelated to WMI.
  2. Create a Managed Object Format (MOF) file that contains the following two instances:
  • An instance of the __Win32Provider class to describe the physical implementation of the provider.
  • An instance of a class derived either directly or indirectly from __ProviderRegistration to describe the logical implementation of the provider. For more information on provider registration see the corresponding section for a particular type of provider.
  1. Place the .mof file into a permanent directory, typically the provider's installation directory.
  2. Locate the following registry key: HKLM\SOFTWARE\Microsoft\WBEM. This key contains a REG_SZ value named "MOF Self-Install Directory."
  3. Copy the .mof file into the directory named by the registry key value. Placing the .mof file into this directory ensures that it is compiled either right away (if WMI is currently running) or the next time that WMI is started. When WMI compiles the .mof file, it will move the file to the good or bad subdirectories depending on whether the .mof file was compiled with or without errors. Refer to the mofcomp.log file in the %systemroot%\system32\wbem\logs for related messages.
  4. Locate the following registry key:HKLM\SOFTWARE\Microsoft\WBEM\CIMOM. This key contains a REG_MULTI_SZ value named "Autorecover MOFs (recovered)" that contains a list of paths to various .mof files.

Add the full path to the permanent location of the .mof file to the end of this list. This ensures that the .mof file will be recompiled if a problem occurs.