License Agreement

This is a legal agreement ("Agreement") between you (either an individual or an entity), the end user, and Microsoft Corporation. By installing, copying, or otherwise using the Product (as defined below), you agree to be bound by the terms of this Agreement. If you do not agree to the terms of this Agreement, do not install, copy, or use the Product, and promptly return the disks and any accompanying items (including written materials and binders or other containers, if any) to Microsoft Corporation.

MICROSOFT LICENSE AGREEMENT

for a Pre-Release Copy of

Microsoft Web-Based Enterprise Management
Software Development Kit (SDK)

© 1997 Microsoft Corporation. All rights reserved.

  1. GRANT OF LICENSE.

    (a) Microsoft grants you ("Recipient") a limited, nonexclusive, nontransferrable, royalty-free license to make and use an unlimited number of copies of the software accompanying this agreement ("Product") to be installed on an unlimited number of CPUs residing on Recipient's premises, solely for Recipient's internal testing and development. The total number of individual users with access to the Product shall be unlimited. All other rights are reserved to Microsoft. Recipient shall not rent, lease, sell, sublicense, assign, or otherwise transfer the Product or any accompanying printed materials ("Documentation"). Recipient may not reverse engineer, decompile the Product, except to the extent that the foregoing restriction is expressly prohibited by local law. Microsoft and its suppliers shall retain title and all ownership rights to the product, and this Agreement shall not be construed in any manner as transferring any rights of ownership or license to the Product or to the features or information therein, except as specifically stated herein.

    (b) Recipient agrees to provide reasonable feedback to Microsoft, including but not limited to usability, bug reports, and test results, with respect to the Product testing and development use. Recipient will use reasonable efforts to review and comment on all documentation supplied. All bug reports, test results, and other feedback made by Recipient shall be the property of Microsoft and may be used by Microsoft for any purpose it sees fit. Due to the nature of the development work, Microsoft is not certain as to when errors or discrepancies in the Products may be corrected.

    (c) Recipient may disclose the Product only to its employees who have a need to know and have access to the Product in order to assist in Recipient's testing and development use of the Product, provided that (1) such employee's use of the Product takes place solely at Recipient's site and (2) Recipient has executed appropriate written agreements with such employees sufficient to enable it to comply with the terms of this Agreement. Upon Microsoft's request, Recipient shall provide to Microsoft a list of all employees granted access to the Product hereunder.

  2. TERM OF AGREEMENT. The term of this Agreement shall commence on the date you accept this Agreement and shall continue unless terminated by Microsoft in writing at any time, with or without cause. This Agreement will terminate without notice upon the commercial release of the Product. Upon the termination of this Agreement, Recipient shall promptly return to Microsoft, or certify destruction of, all full or partial copies of such product and related materials provided by Microsoft.
  3. COST OF TESTING. There is no charge to Recipient for testing and development use of the Product. Microsoft shall bear all transportation expenses relating to the shipment of the Product to Recipient's place of business. If the Product is returned by Recipient, Recipient will pay the return transportation expense.
  4. PRODUCT MAINTENANCE. Microsoft is not obligated to provide maintenance or updates to Recipient for Product licensed under this Agreement. In no event shall Microsoft be obligated to provide Recipient, free of charge, a copy of the commercial release version of the Product in connection with Recipient's participation in the testing and development program.
  5. DISCLAIMER OF WARRANTY. Product is deemed accepted by Recipient. The Product constitutes prerelease code and may be changed substantially before the first commercial release. The PRODUCT is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, MICROSOFT FURTHER DISCLAIMS ALL WARRANTIES, INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. THE ENTIRE RISK ARISING OUT OF THE USE OR PERFORMANCE OF THE PRODUCT AND DOCUMENTATION REMAINS WITH RECIPIENT.

    TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL MICROSOFT OR ITS SUPPLIERS BE LIABLE FOR ANY CONSEQUENTIAL, INCIDENTAL, DIRECT, INDIRECT, SPECIAL, PUNITIVE, OR OTHER DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE PRODUCT OR DOCUMENTATION, EVEN IF MICROSOFT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES/JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO RECIPIENT.

  6. GOVERNING LAW; ATTORNEYS FEES. This Agreement shall be governed by the laws of the State of Washington and Recipient further consents to jurisdiction by the state and federal courts sitting in the State of Washington. If either Microsoft or Recipient employs attorneys to enforce any rights arising out of or relating to this Agreement, the prevailing party shall be entitled to recover reasonable attorneys' fees.
  7. U.S. GOVERNMENT RESTRICTED RIGHTS. The Product and Documentation are provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause of DFARS 252.227-7013 or subparagraphs (c)(i) and (2) of the Commercial Computer Software -- Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is Microsoft Corporation, One Microsoft Way, Redmond, WA 98052-6399.
  8. EXPORT RESTRICTIONS. Recipient acknowledges that the Product and Documentation acquired hereunder are subject to the export control laws and regulations of the U.S.A., and any amendments thereof. Recipient confirms that with respect to these Product and Documentation, it will not export or re-export them, directly or indirectly, either to (i) any countries that are subject to U.S.A export restrictions (currently including, but not necessarily limited to, Cuba, Iran, Iraq, Libya, North Korea, Syria, and Sudan); (ii) any end user who Recipient knows or has reason to know will utilize them in the design, development or production of nuclear, chemical or biological weapons; or (iii) any end user who has been prohibited from participating in the U.S.A. export transactions by any federal agency of the U.S.A. government. Recipient further acknowledges that the Product may include technical data subject to export and re-export restrictions imposed by U.S.A. law.

Should you have any questions concerning this Agreement, or if you desire to contact Microsoft for any reason, please write: Microsoft Corporation, Attn: Stephen Todd, Program Manager, Systems Management Server Group, One Microsoft Way, Redmond, WA 98052-6399.


Overview

Web-Based Enterprise Management (WBEM) is a standard approach to the management of multivendor and multiplatform systems and networks. Information from a managed environment is supplied by object providers through an object manager to management applications. The WBEM SDK contains the programming interfaces and tools that applications and object providers use to participate in a managed environment.

The Overview to the WBEM SDK documentation includes:

  • Architectural Overview, a high level description of the WBEM initiative and the components that are part of Microsoft's WBEM technology.
  • Terms and Concepts, a description of the main terms and concepts that are central to WBEM.
  • Using the WBEM SDK, a collection of topics that apply to getting started as a developer of a management application, an object provider, or with the WBEM SDK.
  • Managed Object Format (MOF) Language, a guide to creating classes and instances using this compiled language.


Architectural Overview

Web-Based Enterprise Management (WBEM) is an initiative undertaken by the Desktop Management Task Force to provide enterprise system managers with a standard low-cost solution for their management needs. The WBEM initiative encompasses a multitude of tasks, ranging from simple workstation configuration to full-scale enterprise management across multiple platforms. Central to the initiative is the Common Information Model (CIM), an extensible data model for representing objects that exist in typical management environments, and the Managed Object Format (MOF) language for defining and storing modelled data.

The WBEM technology is an implementation of the WBEM initiative for Microsoft® Windows® platforms. By extending the CIM to represent objects that exist in Windows management environments and implementing a management infrastructure to support both the MOF language and a common programming interface, the WBEM technology enables diverse applications to transparently manage a variety of enterprise components.

WBEM's management infrastructure consists the following components:

  • The CIM Object Manager (CIMOM), a component that provides applications with uniform access to management data.
  • The CIMOM repository, a central storage area for management data.


WBEM Architecture

[This is preliminary documentation and subject to change.]

The architecture of the Web-Based Enterprise Management (WBEM) technology consists of the following components:

  • Management applications
  • Managed objects
  • Providers
  • Management infrastructure, consisting of the CIM Object Manager (CIMOM) and the CIMOM repository

Management applications are Windows applications or Microsoft® Windows NT® services that process or display data from managed objects. A management application can perform a variety of tasks such as measuring performance, reporting outages, and correlating data.

Managed objects are logical or physical enterprise components. Managed objects are modelled using the CIM and accessed by management applications through CIMOM. A managed object can be any enterprise component, from a small piece of hardware such as a cable to a large software application such as a database system.

Providers use the CIMOM API to supply CIMOM with data from managed objects, to handle requests on behalf of management applications, and to generate notifications of events. The WBEM SDK supplies several standard providers, such as a Registry Provider for accessing information from the system registry, and a Microsoft Windows NT Event Log Provider for receiving notifications of Windows NT events and access to the information stored in the Windows NT event log. Third-party vendors can create custom providers to interact with managed objects specific to their environment.

The management infrastructure consists of CIMOM for handling the communication between management applications and providers and the CIMOM repository for storing static data. Applications and providers communicate through CIMOM using a common programming interface (CIMOM API) which supplies such services as event notification and query processing. The CIMOM API is available in several programming languages, such as C, C++, Microsoft® Visual Basic®, and Java™.

The CIMOM repository holds static management data. Static data is data that does not regularly change. WBEM also supports dynamic data, or data that must be generated on demand because it is frequently changing. Data can be placed in the CIMOM repository by by CIMOM, network administrators, or third-party developers using either the Managed Object Format (MOF) language and its compiler or the CIMOM API.

The following diagram shows the relationship between the components in the WBEM technology. At the top of the diagram are examples of management applications. Some of these applications access the CIMOM API directly to interact with CIMOM and the CIMOM Repository; some use a variety of access methods. The applications in the diagram use Open Database Connectivity (ODBC), the Hypertext Markup Language (HTML), and the Active Directory Services Interface (ADSI) to make management requests.

At the bottom of the diagram are examples of managed objects and their corresponding providers. Again there is a variety of access methods used for communication.

The protocol used for communication between local and remote components is Distributed COM (DCOM).


Management Applications

A management application is an application or Microsoft® Windows NT® service that uses information originating from one or more managed objects. To access the information, a management application makes a request to CIMOM through one of the methods in the CIMOM API.

The WBEM technology enables management applications to implement a wide range of features such as producing reports of network inventory, displaying system information, responding to events, starting or stopping system services, and sending an "eject" command to a disk drive with replaceable media. Although some of the features can also be implemented without WBEM, much additional work is necessary.

WBEM supports a number of different strategies to implement management applications. Applications can access CIMOM directly through the CIMOM API or indirectly with one of the following access methods:

  • Web browsers can use a set of Microsoft® ActiveX® controls to control the appearance, relationships, and behavior of data relating to managed objects. The controls are customizable and can be included in a standard schema definition.
  • Web browsers can also use the Hypertext Markup Language (HTML, the standard HTML page and hyperlink paradigm. HTML is supported through an Internet Server API (ISAPI) layer that interacts with CIMOM.
  • Database applications can use the Microsoft® Open Database Connectivity (ODBC) driver to merge the database capabilities of ODBC with the management capabilities of WBEM. With the ODBC driver, an application can use a wide range of ODBC-based reporting packages and tools such as Microsoft® Visual Basic®, Microsoft Excel, and Microsoft Access.
  • The CIMOM API is available to both C/C++ programmers and to programmers writing in an Automation-compatible programming language. Therefore, applications written in C or C++ can use the primary version of the CIMOM API and applications written in Java or a scripting language such as Visual Basic can use the Automation-compatible version.

The following figure shows management applications of various types communicating with CIMOM. Two of the applications use one of the access strategies; one communicates directly to CIMOM.


WBEM Providers

Web-Based Enterprise Management (WBEM) providers act as intermediaries between CIMOM and one or more managed objects. When CIMOM receives a request from a management application for data that is not available from the CIMOM repository or for notifications of events that CIMOM does not support, it forwards the request to a provider. Providers supply data and event notifications for managed objects that are specific to their particular domain.

Providers are standard COM/DCOM servers that can be implemented using the full range of supported server types:

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

The WBEM SDK includes several built-in providers. The built-in providers, also referred to as standard providers, supply data from well-known sources such as the system registry and the Win32 subsystem.

The WBEM technology also supports the creation of custom providers by third-party developers. These providers service requests relating to managed objects that are environment-specific. Providers typically use the MOF language to define and create classes. They use the CIMOM API to access the CIMOM repository and to respond to CIMOM requests made initially by applications.

The following diagram illustrates the architecture of providers. The PerfMon Provider, Registry Provider, and WMI Provider are examples of standard providers. Provider X, Provider Y, and Provider Z are examples of custom providers. Both the standard and custom providers can access data from the CIMOM repository through the CIMOM API.

The WBEM technology categorizes providers by the different features that they support. Every provider can support one or more feature set. For each feature, a different method is implemented. There are basically two types of providers: those that support data retrieval and modification and those that support event notification. Providers can be categorized further as follows:

Provider type | Description
Class | Retrieves, modifies, deletes, and/or enumerates a provider-specific class. Can also support query processing.
Event | Generate notifications of events.
Event consumer | Supports event notification by mapping a physical consumer with a logical consumer.
Instance | Retrieves, modifies, deletes, and/or enumerates the instances of system and/or provider-specific classes. Can also support query processing.
Method | Invokes methods for a provider-specific class.
Property | Retrieves and/or modifies individual property values.

Each of the features listed for the property, instance, and class providers are optional. These providers can choose to support one or more of the possible features. Providers indicate which features they support through the registration process and through their implementation of the corresponding method in the CIMOM API. A provider that does not support a particular feature returns WBEM_E_NOT_SUPPORTED from the corresponding method.

However, to avoid making unnecessary calls, CIMOM always checks a provider's registration first to determine if it can handle a request. If CIMOM detects that the provider can not handle the request because it does not support a feature, CIMOM never makes the request.


Common Information Model (CIM)

The Common Information Model (CIM) presents a consistent and unified view of all types of logical and physical objects in a managed environment. Managed objects are represented using object-oriented constructs such as classes that include properties to describe data and methods to describe behavior. Designed by the Desktop Management Task Force (DMTF) as part of the WBEM initiative, the CIM is not tied to any particular platform. The WBEM technology includes an extension of the CIM for Windows platforms.

The CIM defines three levels of classes:

  • Classes representing managed objects that apply to all areas of management. These classes provide a basic vocabulary for analyzing and describing managed systems and are part of what is called the core model.
  • Classes representing managed objects that apply to specific management areas but are independent of a particular implementation or technology. These classes are part of what is called the common model, an extension of the core model.
  • Classes representing managed objects that are technology-specific additions to the common model. These classes typically apply to specific platforms such as unix or the Microsoft Win32 environment.

All classes can be related by inheritance, where a child class includes data and methods from its parent class. Inheritance relationships typically are not visible to the management application using them. These applications are not required to know the inheritance hierarchy. Class hierarchies can be obtained using applications that are included in the WBEM SDK; see WBEM SDK Applications for more information.

CIMOM also supports association classes. Association classes link two other classes to model a user-defined relationship. Association relationships are visible to management applications. CIMOM defines association classes to support system classes; third-party developers can also define association classes for their management environment.

The CIM supports with documentation what is referred to as a metamodel. A metamodel is a description of the entities and relationships that are used to represent the managed objects. For example, classes, instances, and associations are included in the metamodel. The metamodel is fixed and is not supported programmatically.

WBEM supports the concept of schemas to group the classes and instances that are used within a particular management environment. The WBEM SDK includes two schemas: the CIM schema and the Microsoft® Win32® schema. The CIM schema contains the class definitions for the first two levels of the CIM. These classes represent managed objects that are part of every management environment regardless of platform. The Microsoft® Win32® schema contains class definitions for managed objects that are part of a typical Win32 environment.

Third-party developers can create their own custom schemas to describe vendor-specific environments. Because schemas are meant to be infinitely extensible, developers can always add new classes to represent new managed objects in an existing environment. Custom schemas are extensions of the CIM or Win32 schema.


CIM Object Manager (CIMOM)

The Common Information Model Object Manager (CIMOM) is the primary component in the management infrastructure of the Web-Based Enterprise Management (WBEM) technology. CIMOM runs as a standard executable that is started when the first management application makes a call to connect. CIMOM runs continuously as long as management applications are actively seeking its services. When the last management application shuts down, CIMOM eventually does the same.

CIMOM supports a single programming interface known as the CIMOM API that is used by management applications, providers, and schema extensions. The CIMOM API enables these components to interact with CIMOM using C, C++, Java™, or Microsoft® Visual Basic® and is based on the Component Object Model (COM).

When an application makes a request by calling one of the methods in the CIMOM API, CIMOM determines whether or not the request involves static data stored in the CIMOM repository or dynamic data supplied by a provider. Static data can be handled by CIMOM whereas dynamic data always involves a provider. Providers register their location and support for particular operations such as data retrieval, modification, deletion, enumeration or query processing. CIMOM uses this registration information to match application requests with appropriate providers and to find and load the providers when necessary. When a provider has finished processing a request, it returns the results back to CIMOM, which it turns forwards the result to the application.

CIMOM ensures that all of the operations specified in the CIMOM API are supported. When an application makes a complex request that a provider cannot handle, CIMOM supplies the implementation by making an equivalent series of much simpler calls to the provider. CIMOM is always available to handle a request if a registered provider is unable to do so.

In addition to implementing each of the operations associated with application requests, CIMOM also supplies:

  • Support for event notification
  • Query language support
  • Security support
  • Localization support
  • Support for local and remote access

For a complete description of the interfaces in the CIMOM API, see Interfaces


Support for Event Notification

CIMOM supports the registration for and distribution of event notifications. Event consumers register to receive particular types of notifications. Event providers register to supply particular types of notifications. To enable event consumers to operate independently from event providers, CIMOM acts as the intermediary, matching registered consumers with corresponding providers and forwarding appropriate events.

CIMOM produces two types of events: timer events and intrinsic events. Timer events occur either periodically, according to a specified time interval, or once at a specified time. Intrinsic events correspond to changes in data stored in the CIMOM repository.

Event providers can support a third type of event called an extrinsic event in addition to timer events and intrinsic events. Although WBEM prefers that providers use intrinsic events whenever possible, it is sometimes necessary to create new event types to represent changes to provider-specific managed objects. Events pertaining to provider-specific events are called extrinsic events.

CIMOM forwards the notifications of all types of events to applications that have registered to receive them. For a detailed description of the event services architecture, see Event Notification.


Query Language Support

CIMOM currently supports the WBEM Query Language (WQL) to handle query processing. WQL is a subset of the ANSI standard Structured Query Language (SQL) with WBEM-specific extensions. Some extensions support event registration and notification, while others support relationships between classes and instances. WQL is a read-only query language in that it cannot be used to update, insert, or delete data. WQL can only be used to retrieve information.

For more information about WQL, see WBEM Query Language (WQL)


Security Support

CIMOM's security support differs depending on the platform. On Windows NT platforms, CIMOM supports a limited form of security whereby DCOM positively identifies each user before allowing the user to attempt to connect to CIMOM. Once identified, CIMOM verifies that the user has the appropriate access level.

An administrator can change the access level for users. Some users can perform read-only operations while others can make modifications.

Users have access to either all or none of the classes supported by CIMOM and providers. CIMOM does not enforce security on particular classes. That is, a user cannot be able to access class A but not class B.

Security support differs on Windows 95 and 98 platforms where all local users are assumed to be authentic. Because these operating systems are not secure, no check is made to validate the user names or passwords of local users. For remote access, CIMOM supports security through Microsoft® LAN Manager.

For more information about security and authentication in WBEM, see Security and Authentication.


Localization Support

CIMOM supports services that enable developers to localize classes created for the Microsoft® Windows NT®, Microsoft® Windows® 95, and Windows 98 platforms. Localization support exists for the following elements of a class:

  • Class name
  • Property name
  • Property value
  • Descriptive help text
  • Qualifier name
  • Qualifier value

Existing classes and instances can be localized after they have been introduced and remain unaffected. Localization services are provided entirely through WBEM classes specified with Unicode MOF files; the CIMOM API is not involved.

For a detailled description of CIMOM's localization support, see Localization Services.


Support for Local and Remote Access

When an application attempts to connect to CIMOM, the normal COM/DCOM proxy is loaded to make the connection. On the server side (CIMOM), COM loads the interface stub, performs user-level authentication, and completes the connection.

A user can call the DCOM function DCOMCNFG.EXE for DCOM-related access to CIMOM. However, because changes made to permissions can affect access to CIMOM, it is not recommended that users make changes with this application.

Because DCOM is not supported on Windows NT 3.51 platforms, remote access on these platforms is not available. Local access on Windows NT 3.51 platforms is granted with a custom proxy and stub pair that is implemented with anonymous pipes.


Terms and Concepts

The terms and concepts used to support the Web-Based Enterprise Management (WBEM) technology originate from many sources. Many were conceived by the Desktop Management Task Force (DMTF) to describe managed objects. Others are standard Component Object Model (COM) terms and concepts. Still others are specific to the WBEM SDK.

For additional information about WBEM architecture, see Architectural Overview.


WBEM Classes

Web-Based Enterprise Management (WBEM) classes define the basic units of management. Each class is a template for a type of managed object; all instances of the type use the template. For example, the __Win32LogicalDisk class is a model for all disks that can exist on a Windows machine. For each physical disk that exists, there is an instance of the __Win32LogicalDisk class. Classes can contain properties, which describe the data of the class, and methods, which describe the behavior of the class.

The WBEM technology incorporates classes defined by the Common Information Model (CIM), classes defined by the CIM Object Manager (CIMOM), and classes defined by third-party developers.

The CIM classes describe objects that exist in:

  • Every managed environment
  • Managed environments of a specific type.
  • Technology-specific managed environments

CIM classes describe components that are independent of a particular implementation or technology.

The classes defined by CIMOM are called system classes and are not part of the CIM. System classes are specific to Microsoft's WBEM technology, its implementation for Windows platforms. System classes support CIMOM's core features, such as event notification, security, and localization. For a complete description of the system classes, see the System Class Reference.

Third-party developers can define custom classes to support managed objects that are specific to their managed environment. For example, a custom class can be defined to represent a specific database or type of tape drive. Developers can use the CIMOM API to define new classes or the Managed Object Format (MOF) language.

The system classes all begin with a double-leading underscore. Custom classes must be named according to the following convention:

SchemaName_ClassName

The SchemaName portion specifies the name of the schema to which the class belongs. Schema names cannot contain underscore characters and must be unique. Including the schema name as a prefix to the class name allows users of the class to strip off the schema name when it is implied by the context.

The ClassName portion specifies the name of the class. Class names should be descriptive and can include underscore characters to delimit parts of a compound name. For example, Logical_Disk is a valid WBEM class name. Class names must be unique; they cannot conflict with another class in the system.

WBEM classes support inheritance, the technique of classification that enables a child class to implicitly inherit, or contain, all of the properties and methods of a parent class. A child class can either accept the parent's property values and method implementations or override them by assigning new values and creating new implementations, depending on the rules established by the parent.

The term base class refers to the class at the root of a class hierarchy. The term superclass indicates a parent class; the terms can be used interchangeably. The terms derived class or subclass can be used to indicate a child class. Each parent class can have multiple child classes. However, each child class can only have one parent. Superclasses must already exist before new classes that derive from them can be created.

WBEM classes can participate in a relationship known as an association. An association relates two classes or instances of classes by referring to them in the properties of another class, a special association class.

WBEM classes can be static or dynamic. A static class has a definition that is persistent; the definition is stored in the CIMOM repository until it is explicitly deleted. CIMOM can provide definitions of static classes without the help of a provider.

A dynamic class has its definition supplied by a provider at runtime as needed. Dynamic classes are not stored permanently. Whenever a dynamic class is requested, CIMOM makes a call to the appropriate provider to request it.

Because of the shared and distributed nature of classes within WBEM, changing a class definition has the potential to impact any WBEM managed entities that are currently deployed. Classes should be carefully designed to not require modification. However, if modifications must be made, it is recommended that the class be removed and then recreated. Adding qualifiers is the only way that changes should be made to an existing class.

WBEM uses the concept of a namespace to logically differentiate between managed environments. Every managed environment is represented by a schema which contains the class definitions for the managed objects in the environment. Every schema exists within a different namespace.

Class definitions need to be unique and consistent across all namespaces; it is recommended that a given class name and its methods and properties not conflict with a class of the same name in another namespace. In this way, client software expecting to deal with a particular class in a particular way will always succeed, regardless of the namespace.


Classes and Properties

Web-Based Enterprise Management (WBEM) classes can include one or more properties, or name/value pairs that describe the data of the class. Properties are assigned names that cannot begin with a digit or a double underscore and cannot contain white space. Property values must belong to one of the types described in Managed Object Format (MOF) Data Types.

When a subclass contains a property with the same name as a property in its superclass, the subclass always overrides the inherited property.

Properties can also be modified by descriptors known as qualifiers. Qualifiers provide additional information about the use of a property, such as whether it acts as a key or can contain NULL values. Users can define their own qualifiers if one of the standard qualifiers does not suit their purpose. In addition to properties, qualifiers can be attached to classes, instances, methods, and parameters.


Classes and Methods

Web-Based Enterprise Management (WBEM) classes can include zero or more methods, or functions that describe the behavior of the class. Including a method in a class does not guarantee an implementation of the method. The Implemented qualifier is attached to the method to indicate that an implementation is available for the class.

A derived class inherits a method implementation by default, but it can override that implementation. When CIMOM is attempting to invoke a method for a particular instance of a class, CIMOM starts at the lowest subclass in the class hierarchy and works toward the base class searching for the Implemented qualifier. If no implementation is present before the base class is reached, CIMOM invokes the implementation of the base class. Providers of derived classes need to implement a method only if they want to override the implementation of the base class.


Class and Instances

A Web-Based Enterprise Management (WBEM) class defines a template for describing a type of managed object. An instance of a WBEM class represents a specific managed object of the type described by the class. Where the class generally models the real-world device or component in the general sense, each instance represents a specific occurrence of the device or component. For example, while there might be a general class called FloppyDisk, the instances on a particular host machine might represent drives "A" and "B".

Some WBEM classes permit the creation of instances; others do not. Abstract base classes are used solely as templates for derived classes. The __Event system class, for example, is an abstract class. Real world events are modelled using classes that are derived from the __Event class. Instances are created from the __Event subclasses. Another type of class supports only a single instance; such classes are known as singleton classes.

All instances of a class exist within the namespace to which the class belongs. Within a namespace,instances can be either static or dynamic. Static instances are persistently stored and remain valid until explicitly deleted, even across system reboots. Static instances are manually placed in the CIMOM repository using IWbemServices::PutInstance or IWbemServices::PutInstanceAsync or through a MOF definition submitted to the MOF compiler.

Dynamic instances are supplied by a provider when the need arises and are not stored in the CIMOM repository. Requests for dynamic instances are forwarded through CIMOM to the provider for the class. Supporting instances of a class dynamically allows a provider to always supply up-to-the-minute property values.

Static classes can support either static or dynamic instances. Within a static instance, either static or dynamic properties can exist. A static class that supports only static instances containing static properties is always available through CIMOM. Provider involvement is unnecessary.

Static classes with dynamic instances store only the class definition in the CIMOM repository. When instances are requested, a provider must retrieve the class definition and build the required instance or set of instances on demand.

Static classes with static instances containing both static and dynamic properties store placeholders for the dynamic properties in the CIMOM repository. When a request is made for an instance, a provider must be summoned to supply the actual data for each dynamic property.

Dynamic classes support only dynamic instances. With a dynamic class, neither the class definition nor the instances are stored in the CIMOM repository. The provider responsible for a dynamic class stores information about its location. When an application requests a dynamic class, CIMOM locates the provider and forwards the request.


Association Classes

Web-Based Enterprise Management (WBEM) association classes describe a relationship between two classes or between instances of two classes. The properties of an association class include pointers, or references, to the two instances. The references always take the form of an object path, a string that uniquely identifies the location of the instance. By storing paths rather than real objects in the association class, relationships can be added or removed without affecting the objects. All association classes are identified by the Association qualifier, one of the standard qualifiers defined by WBEM for use with classes.

All WBEM classes can be included in zero or more association classes. Association classes can be system classes defined by WBEM or custom classes defined by a third-party vendor. The Common Information Model (CIM) defines various types of associations, each type defining a different relationship. For example, the CIM_Dependency class defines a dependency association. The properties of the CIM_Dependency class include two instances that are dependent upon each other in some way. One instance cannot exist or operate without the other instance. The CIM_HostedService association class is an example of a dependency association. The reference properties of this class include an instance of the CIM_System class and an instance of the CIM_Service class.

An example of a custom association class might be the NetCardToProtocolBinding class for relating network cards to protocols. Because a network card can support multiple protocols and the same protocol runs over multiple network cards, defining an association class enables these two types of managed objects to be related without affecting their class definitions and without knowledge of the providers for the protocol and network card instances.


Qualifiers

Qualifiers contain information 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.

There are three categories of qualifiers: those defined by the Common Information Model (CIM), those defined by WBEM, and those defined by developers. The qualifiers defined by WBEM are known as the standard qualifiers. Some of the CIM and standard qualifiers are automatically assigned when a class or instance is created; others must be explicitly attached through inclusion in a MOF statement or a function call.

Qualifiers can be specified in class and instance declarations using the Managed Object Format (MOF) language and accessed programmatically through the IWbemQualifierSet interface. All qualifiers have a name and a value. Qualifier values can be explicit or implied. When a value is absent, the value TRUE is implied. Some qualifiers also include a descriptor known as a flavor

Depending on the qualifier and its intended use, it may or may not be required. For example, WBEM defines the Implemented qualifier for methods. If a provider defines a class with a method and includes an implementation of that method, the provider must attach the qualifier Implemented to the method declaration. Another required qualifier is the Key qualifier. The Key qualifier must be attached to every property in a class that serves as part of the key for that class. Optional qualifiers include provider-defined qualifiers and standard qualifiers that can be used as comments. A qualifier is considered optional when its removal does not affect the functionality of the class or instance with which it is associated.


Qualifier Flavors

Qualifier flavors describe the use of a qualifer. Flavors can be specified with predefined flags in class and instance declarations using the Managed Object Format (MOF) language and accessed with numeric constants using the IWbemQualifierSet interface. Whereas developers can define new qualifiers to support their custom classes, they cannot define new flavors. All new and existing classes must use flavors that have been defined by WBEM.

WBEM flavors describe rules that specify whether a qualifier can be propagated to derived classes and instances and whether or not a derived class or instance can override the qualifier's original value. Qualifiers can propagate from:

  • Class to subclass
  • Class to instance
  • Class property to instance property

Qualifiers that are declared on the class or instance do not propagate to properties of that class or instance. The single exception to this rule is the Key standard qualifier which is used to uniquely identify an instance.

Override permissions define whether or not a subclass can change the meaning of a qualifier defined in the superclass. Override permissions are set in conjunction with propagation rules. That is, if propagation rules are set for a qualifier, it must also have override permissions to specify how values are set for the qualifier in the derived classes or instances.

The following table describes the flags that are used to specify flavors in MOF syntax:

Flavor flag | Description
DisableOverride | Qualifier value cannot be overridden in a derived class or an instance.
EnableOverride | Qualifier value can be overridden in a derived class or an instance.
NotToInstance | Qualifier is not propagated to instances.
NotToSubclass | Qualifier is not propagated to derived classes.
Restricted | Qualifier is not propagated to instances or derived classes. This is the default behavior of the qualifier when a flavor is not specified.
ToInstance | Qualifier is propagated to instances.
ToSubclass | Qualifier is propagated to derived classes.

To assign a flavor programmatically, call IWbemQualifierSet::Put with the lFlavor parameter set to one of the following constants:

WBEM_FLAVOR_FLAG_PROPAGATE_TO_DERIVED_CLASS

WBEM_FLAVOR_FLAG_PROPAGATE_TO_INSTANCE

WBEM_FLAVOR_OVERRIDABLE

WBEM_FLAVOR_NOT_OVERRIDABLE

Setting a qualifier's flavor to WBEM_FLAVOR_FLAG_PROPAGATE_TO_DERIVED_CLASS is the same as using the ToSubclass flag. The qualifier is propagated to all classes derived from this class. The WBEM_FLAVOR_FLAG_PROPAGATE_TO_INSTANCE value is the same as the ToInstance flag and indicates that the qualifier is propagated to all instances of this class.

The WBEM_FLAVOR_OVERRIDABLE and WBEM_FLAVOR_NOT_OVERRIDABLE values are the same as the EnableOverride and DisableOverride flags. Setting a qualifier's flavor to WBEM_FLAVOR_OVERRIDABLE indicates that its value can be overridden by a derived class or an instance. Setting the flavor to WBEM_FLAVOR_NOT_OVERRIDABLE forces derived classes and instances to use the qualifier's original value. WBEM always permits qualifier values to be overridden unless WBEM_FLAVOR_NOT_OVERRIDABLE or DisableOverride is specified.


Singleton Classes

Web-Based Enterprise Management (WBEM) supports singleton classes, or classes that can have only one instance. Because there is no need to uniquely identify one instance from another, singleton classes do not designate one or more of their properties as the key.

Singleton classes can be defined programmatically using the methods of the IWbemServices interface or with Managed Object Format (MOF) syntax. In either case, the Singleton standard qualifier is attached to the class declaration and set to the Boolean value of TRUE to designate the class as a singleton class. To ensure that the qualifier is propagated from the class to the instance, a qualifier flavor must also be included. The flag ToInstance is specified when defining the class using MOF; the constant WBEM_FLAVOR_FLAG_PROPAGATE_TO_INSTANCES when defining the class programmatically.

To retrieve an instance of a singleton class, call IWbemServices::GetObject with the bstrObjectPath parameter set to SingletonClassName="@".

For more information about defining classes with the MOF syntax, see Managed Object Format (MOF) Language.

For more information about qualifiers and qualifier flavors, see Qualifiers and Qualifier Flavors.


System Classes

The Web-Based Enterprise Management (WBEM) system classes are a collection of predefined classes that are included with the WBEM SDK and are used to support the activities of the CIM Object Manager (CIMOM). They are automatically defined in every namespace. For example, there are system classes to describe providers, events, event providers, and event consumers.

System classes are identified by a leading double underscore in their name. All system classes derive from the abstract base class __SystemClass. Because the system classes are predefined by WBEM, developers cannot create their own system classes by starting a class name with a double underscore. However, they can create classes that derive from system classes.

For detailled information about each of the WBEM system classes, see the System Classes reference.


System Properties

In addition to class-specific properties, Web-Based Enterprise Management (WBEM) defines a set of system properties that are associated with all classes and instances of classes. System properties provide information that is applicable to every class, such as its name, its derivation, and its namespace.

As with system classes, system properties begin with a double underscore to differentiate them from properties created by applications or providers, which cannot start with a single or double underscore. Another way to identify a system property is by using the IWbemClassObject::Get method.

Not all system properties are available on all classes or instances at all times. For detailed information about each of the WBEM system properties and their availability, see the System Properties reference.


Identity and Location

Web-Based Enterprise Management (WBEM) classes and instances are identified and located using a formatted string known as an object path. For classes, an object path identifies the server on which the class resides, the namespace to which it is assigned, and the name of the class. A namespace is a key-scoping mechanism, a unit for grouping classes that operate in the same managed environment. The object path for instances specifies a key in addition to the server, namespace, and class.


Key Properties

Web-Based Enterprise Management (WBEM) identifies instances through the use of keys, or properties that provide a unique value. Key properties are designated by the Key qualifier, a standard qualifier defined by WBEM. Key qualifiers can be attached to more than one property in a class to create a compound key for the class. Properties chosen as key properties for a class must contain values that can uniquely identify each instance of the class.

The following MOF syntax illustrates how to define a class with a single key property:

class MyClass
{
    [key] string MyKey;
    string RegularProp;
}

When a superclass class specifies a key, all of the derived classes inherit that key. The derived classes cannot alter the inherited key or define any new key properties. However, when a subclass derives from an abstract class without a key, the subclass is permitted to introduce its own key.

A property must be one of the following types to be able to act as a key:

  • Decimal integer (VT_I4)
  • Boolean (VT_BOOL)
  • String (VT_BSTR)

All classes that define more than one instance must specify a key. Because abstract classes do not define any instances, they need not specify keys. Because singleton classes define only one instance, they cannot specify keys.


Namespaces

A namespace is a unit for grouping classes and instances and controlling their scope and visibility. Namespaces are not physical locations; they are more like logical databases containing specific classes and instances. Namespaces are represented by the __Namespace system class or a class that derives from the __Namespace class. The __Namespace class has a single property: Name. It is the Name property that distinguishes a namespace from all other namespaces.

Namespaces can be nested within each other to form an arbitrary hierarchy of classes and instances. The nesting model resembles that used for a hierarchical file system, where each namespace needs to have a unique name within the scope of its immediate parent object.

The namespace hierarchy is represented by individual namespaces delimited by a backward slash:

Namespace1\Namespace2\Namespace3........\LastNamespace

Classes are defined for use within one namespace, but associations can span namespaces. An association can contain references to instances in two different namespaces.

Typically a namespace contains a set of classes and instances that represent managed objects in a particular environment. For example, the classes and instances defined to manage objects in the Microsoft® Win32® environment are created in their own unique namespace. WBEM recommends that a given class name and its associated properties and methods not conflict with a class of the same name in another namespace.

All WBEM installations have three predefined namespaces:

  • Root
  • Root\Security
  • Root\Cimv2

The Root namespace is primarily designed to contain other namespaces. The Security namespace, created under the Root namespace, contains the classes and instances that are used for WBEM's security subsystem.

Another child namespace, the Cimv2 namespace contains the classes and instances that represent the host machine such as:

  • LogicalDisk
  • Netcard

Most operations occur against the Cimv2 namespace. However, if the WBEM installation is also acting as a proxy for a logical or network device, then the classes and instances associated with the logical or network device need to be located in a different namespace, as shown in the following illustration. Having classes and instances of both the local machine and the network device in a common list is confusing; there is no immediate way to determine which instances belong to the local machine and which are part of the network device. By separating these into separate namespaces, it becomes easier to distinguish between the classes and instances for the local machine and those for the network device.

In the following example, two namespaces are nested beneath the Root namespace: Cimv2 and UnixProxy. The Cimv2 namespace models the local machine, and the UnixProxy namespace holds two other namespaces, UnixA and UnixB. The UnixA and UnixB namespaces each model a complete Unix machine.

Namespaces can be arranged in a hierarchical format, as is shown in the preceeding example, or in a lateral format. Either way, the relationship has nothing to do with inheritance of classes or instances. That is, a child namespace does not automatically receive the classes and instances of its parent namespace.

Because namespaces are represented as instances of the __Namespace class, creating instances of the class is how new namespaces are created and deleting instances of the class is how namespaces are deleted. When a namespace is deleted, it is only marked for deletion. All clients of that namespace can continue to access it for as long as necessary. Events continue to be delivered. A namespace is not physically removed until there are no longer any users needing to access it.


Object Paths

Web-Based Enterprise Management (WBEM) object paths are used to access namespaces, classes, and instances. Each instance of a class has a unique path which identifies it locally or over the network. Object paths are conceptually similar to Universal Resource Locators (URLs). Object paths can be fully qualified or relative to a certain location, such as the local machine or a particular namespace on the local machine.

The namespace in which a class or instance resides can be specified if it is different from the current namespace. The most important part of an object path for a class is its name; the most important part for an instance is its class name and key. This use of keys to distinguish instances parallels the relational database model where key columns are used to index and distinguish rows of a table.

Object paths are used in the reference properties of association classes to identify related objects.

For information about how to create object paths, see Specifying Object Paths.


Using the WBEM SDK

The Web-Based Enterprise Management (WBEM) Software Development Kit (SDK) contains the header files and Interface Definition Language (IDL) files for creating management applications, providers, and schema extensions. There are four IDL files that are included in the WBEM SDK: Wbemcli.idl, Wbemtran.idl, Wbemprov.idl, and Wbemdisp.idl.

The WBEM SDK contains:

  • Applications for viewing and changing data in the Common Information Model Object Manager (CIMOM) repository
  • Object providers for accessing data and events
  • Open Database Connectivity (ODBC) adapter
  • Managed Object Format (MOF) language and compiler
  • Sample Component Object Model (COM) programs


WBEM SDK Applications

The Web-Based Enterprise Management (WBEM) SDK includes three applications:

WBEM Object Browser

WBEM CIM Studio

WBEM HTML Viewer

All three applications can be used to view objects in the CIMOM repository. The Object Browser and CIM Studio also allow users to change properties and qualifiers and to run selected operations. The Object Browser and CIM Studio are Microsoft® ActiveX® applications and require ActiveX capability.

The HTML Viewer does not require ActiveX capability and is designed for use by advanced system managers and developers (particularly those writing providers) who do not have access to Microsoft® Internet Explorer with ActiveX.

CIM Studio is the most extensive of the three applications. In addition to its use as an editor of properties and qualifiers, CIM Studio can also be used to edit classes and instances, to generate and compile Managed Object Format (MOF) files, and to generate framework provider code.


MOF Language and Compiler

The Managed Object Format (MOF) language is a compiled language for defining classes and instances. The MOF compiler offers a textual means of adding data to the CIMOM repository. Although classes and instances can also be added through the CIMOM API using C/C++ or Visual Basic®, MOF eliminates the need to write code. MOF provides developers and administrators with a simple and fast technique for modifying the CIMOM repository.

For information about how to invoke the MOF compiler, see MOF Compiler. For a guide to writing correct MOF syntax, see Managed Object Format (MOF) Language.


Sample Programs

Two sets of sample programs are provided with the Web-Based Enterprise Management (WBEM) SDK: Component Object Model (COM) samples and Visual Basic samples. Sample program files, including source code, are located in the Vc and Vb subdirectories of the \Wbem\Samples directory. In addition to the brief descriptions here, each sample contains a Readme.txt file describing it.

ClientSample

[This is preliminary documentation and subject to change.]

ClientSample is a dialog-based application created by the Microsoft® Visual Studio™ AppWizard and uses the Microsoft Foundation Class (MFC) Library to simplify the process. This sample application demonstrates some more important WBEM capabilities such as connecting to a namespace, listing logical disks, and adding users to a WBEM workgroup.

Customview

[This is preliminary documentation and subject to change.]

Customview provides a description of the custom views for the Common Information Model (CIM) and the corresponding Automation interface. These custom views provide alternative views for object instances contained in the CIM Object Manager (CIMOM) repository. Any number of views can be defined for each class stored in the CIMOM repository.

For more information on Customview, please see the Readme.txt file in the Samples\Customv subdirectory of the WBEM installation directory.

EventConsumer

[This is preliminary documentation and subject to change.]

EventConsumer is a tutorial demonstrating a permanent event consumer. This application demonstrates how to implement a simple IWBEMUnboundObjectSink and its class factory. You must generate your own class identifier (CLSID) when building your permanent provider.

Instprov

[This is preliminary documentation and subject to change.]

Instprov is an example of an instance provider application. This sample is a small C++ dynamic-link library (DLL) that does not use any sort of framework.

For more information on Instprov, see the Readme.txt file in the Samples\Instprov subdirectory of the WBEM installation directory.


Methods Client and Provider

The Methods Client sample demonstrates how to access CIMOM and a provider. The Methods Provider sample implements a method that the Methods Client uses by calling IWbemServices::ExecMethod and IWbemServices::ExecMethodAsync. The Methods Client uses this method to populate instances of classes that are defined in the Methods.mof file.


Propprov

Propprov is an example of a property provider DLL. This provider simply returns a property of type SINT32 or STRING. This is the easiest provider to write, and makes a good starting point for developers.

For more information on Propprov, see the Readme.txt file in the Samples\Propprov subdirectory of the WBEM installation directory.

WBEMDump

[This is preliminary documentation and subject to change.]

WBEMDump shows the entire contents of the CIMOM database in a hierarchical view. CIMOM supports a number of options to specify which information is shown. To view these options, open a command prompt window and use the cd command to move to the \Samples\WBEMDump subdirectory of the WBEM installation directory. Then enter the string shown below, followed by the ENTER key:

Wbemdump /?


Managed Object Format (MOF) Language

Managed Object Format (MOF) is a compiled language created by the Destop Management Task Force (DMTF) and based on the Interface Definition Language (IDL). MOF is used to define static or dynamic classes and instances. Classes and instances are defined using ASCII or Unicode text and placed in a file that is submitted to the MOF compiler, Mofcomp.exe. The MOF compiler parses the file and adds the classes and instances defined in the file to the CIM repository.

To submit a MOF file to the compiler, enter the name of the compiler followed by the name of the file:

mofcomp <MOF filename>

The MOF compiler supports a number of options that you can specify with command line switches. For example, the following command line invokes the compiler with a specific namespace, user name, and password:

mofcomp –N:root\special –U:Joe –P:xyz  myfile.mof

For a complete description of the command line syntax for the MOF compiler, see MOF Compiler.

To view the Backus-Naur Form definition for the MOF syntax, see the MOF BNF Syntax appendix.


Declaring Classes

The MOF language can be used to define either new base classes and classes that derive from existing classes. To declare the most basic class, use the Class keyword with the name of your new class followed by a pair of curly braces and a semi-colon:

class ClassName
{
};

Class names must start with a letter and never an underscore. WBEM only allows system classes and system properties to start with an underscore. All remaining characters must be letters, digits, or underscores. WBEM recommends that you use a two-part name joined by an underscore. Specify your vendor name as the first part and a descriptive class name for the second part. For example, Acme_LogicalDisk describes the LogicalDisk class manufactured by Acme.

Most classes include properties to describe the data of the class. To declare a property, include the property's data type, name, and an optional default value between the curly braces as follows:

class MyClass
{
    string   strProp;
    sint32   dwProp1 = 21;
    uint32       dwProp2;
}

The MyClass class has three properties: a character string, a 32-bit signed integer, and a 32-bit unsigned integer. As an option, a property can be assigned an initial value in the class declaration. Instances of a class inherit all of the properties of the class and any initial values. However, each instance can choose whether to accept these default values or override them with alternate values.

Methods are declared much like properties. The following sample illustrates how to declare a class that includes two methods: one that returns a 32-bit integer and another that has no return value. The VOID keyword can be used to indicate a method that does not have a return value.

class MyClass
{
    sint32  Method1 ();
    void    Method2 ([in] sint32 InParam);
};

Class definitions can be more complicated, including such MOF features as aliases and qualifiers. Default values can be assigned to properties and qualifiers using one of the MOF data types.


Declaring a Derived Class

Classes that derive from other classes are declared with a colon followed by the name of the superclass as the following sample declaration indicates:

class MyClass
{
    string   strProp;
    sint32   dwProp1;
    uint32       dwProp2;
}

class MyDerivedClass : MyClass
{
    string   strDerivedProp;
    sint32   dwDerivedProp;
};

By default, a derived class inherits the properties of its base class. A derived class can declare additional properties and can redeclare one or more of the inherited properties. A redeclared property is added to the list of original properties and any extra qualifiers are added to the list of original qualifiers, subject to the specified propagation rules. When a derived class redeclares a property, its type must remain the same unless it is a reference property. The property's value, if specified, overrides the value defined by the superclass.

A derived class inherits the qualifiers of its base class if those qualifiers have been assigned the value ToDerivedClass.

When the MOF compiler attempts to add a derived class to the CIM repository, its superclass must already exist. The declaration of the superclass can appear in the same MOF file as the derived class or in a different file. A run-time error is generated by the compiler if the superclass is unknown.

A derived class can only have a single superclass; WBEM does not support multiple inheritance. However, a superclass can have many derived classes.


Declaring an Association Class

An association class is a special type of class that defines a relationship between two other classes. Every association class is identified by the Association qualifier and has two or more properties that are of type ref (reference) that provide a path to an object. Association class can also have other types of properties.

The following syntax illustrates how to declare an association class. The MyAssocClass class defines a relationship between ClassX and ClassY. . The reference properties PathToClassX and PathToClassY contain the paths to the classes to be associated. The keyword ToInstance is one of several flags that are defined by WBEM to provide information about the use of a qualifier. These flags are known as qualifier flavors. ToInstance indicates that the association class is inherited by all instances of the class. In this way, the client software can determine that an instance belongs to an association class without having to retrieve the class definition to look for the Association qualifier. For more information about qualifier flavors, see Using Qualifier Flavors

[Association : ToInstance]
class MyAssocClass
{
    ClassX ref PathToClassX ;
    ClassY ref PathToClassY ;
} ;


Declaring Instances

An instance is an object that is derived from a WBEM class. To declare the most basic instance of a class, use the Instance of keyword followed by the class name, curly braces, and a semi-colon:

instance of ClassName
{

};

All properties of the class are properties of each instance derived from the class. If the class is a derived class, instances inherit all of the properties belonging to both the derived class and its base class.

Because properties are strongly typed, instances can not change the type of properties that they have inherited. The value of these properties, however, can be changed. By default, when a class assigns a default value to a property, that value is inherited along with the property. Instances can override that value by placing an assignment statement between the curly braces as follows:

instance of ClassName
{
    InheritedProp = "value";
};

Instances need not provide explicit values for properties unless the property is a key. Values for key properties must be explicitly set to enable the instance to be properly identified. System properties cannot be set in the instance declaration; they are assigned values by the CIM Object Manager when the instance is created.

Instances can also inherit optional tags known as qualifiers that are attached to the class or properties of the class. When the flag ToInstance is associated with a qualifier that is attached to a class, that qualifier is propagated to all of the instances of that class. ToInstance is one of several qualifier flags known as flavors. Flavors provide information about the use of the qualifier to which they are associated. For more information about qualifiers and qualifier flavors, see Using Qualifiers and Using Qualifier Flavors.

The following class and instance declarations show how an instance specifies data for properties defined by the class. The class defines three properties: a character string, a 32-bit signed integer, and a 32-bit unsigned integer. The instance provides data values for each of these properties.

class MyClass
{
    string   strProp;
    sint32   dwProp1;
    uint32       dwProp2;
}

instance of MyClass
{
    strProp = "hello";
    dwProp1 = -1;
    dwProp2 = 0xffffffff;
}


Declaring Methods

Class declarations can include one or more methods. A method is a function the class defines. An implementation of a method may or may not be available. Whereas the definition of methods are inherited between classes, their implementation may not be. The Implemented qualifier must be used to describe a method that has an available implementation for a given class. Omission of the Implemented qualifier indicates that the method is lacking implementation.

If a method is redeclared for a class without the Implemented qualifier, it is considered unimplemented for that class and the invoked implementation at runtime becomes the implementation of the superclass. Therefore, a derived class always inherits the implementation of its superclass unless the derived class provides its own implementation. Redeclaration of a method in a derived class is useful only when method qualifiers are changed; such as is the case when adding the Implemented qualifier.

When a provider is supplying the implementation of a method, it must mark the class with the Provider qualifier. The value of the Provider qualifier is the name of the provider.

Every method must have a unique name; WBEM does not allow two methods with the same name and different signatures to exist in one class or within a class hierarchy. Methods can not be overloaded.

The return value for a method is one of the CIM data types. Parameters are listed with both their name and type and must be marked either as input parameters, output parameters, or both input and output parameters using the In, Out, or In, Out qualifiers:

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

If the same parameter name appears with both an In and an Out qualifier, it it is conceptually the same as the In, Out qualifier on a single parameter. However, by using separate declarations, the input and output parameters can be treated differently. For example, other qualifiers can be added only to the input parameter.

Schema objects (existing CIM repository classes) can be used as either parameters or return values, as the following example illustrates:

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

Arrays can only be passed as parameters; they are not allowed as return value types. Arrays can be unbounded or have an explicit size, as is illustrated below:

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

The MOF language supports the use of object references as parameters. Object references are paths to objects. The parameter type object ref can be used to indicate a generic path to any object. Using object references reduces transport time and encoding if the object already exists in its entirety within the CIM repository. The following class definition shows how to include two object references: one to a Win32LogicalDisk object and the other to a generic object:

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


Using Aliases

An alias is a symbolic reference in either a class or instance declaration to an object located elsewhere in a MOF file. Alias names follow the same rules as instance and class names, except that they must begin with a dollar sign ($) to mark them as an alias. Underscores can appear in an alias name following the initial character. Aliases are typically used as shortcuts to lengthy object paths.

To define an alias, add the phrase "as $AliasName" to the instance or class declaration:

class MyClass as $MyClassAlias
{
}

instance of MyClass as $MyInstanceAlias
{
}

The following examples illustrate how to use an alias as a symbolic reference to an object path. Two classes are declared to describe a disk: the Disk class for the drive letter and the DiskRef class for its path. An alias is defined for the Disk class instance and is used as the value for the PathToDisk property in the DiskRef instance.

class Disk {
    [key]  string    DriveLetter;
};

class DiskRef
{
    [key]  string    MyKey;
    Disk   ref       PathToDisk;
};

instance of Disk as $DiskAlias
{
    DriveLetter = "c";
};

instance of DiskRef
{
    MyKey      =  "hello";
    PathToDisk = $DiskAlias;
}

Aliases have scope only within the MOF file in which they are declared. They are used at compile time to make it easy to establish references and are not available programmatically.

Note WBEM supports forward-referencing but not circular aliases.


Using Qualifiers

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:

Qualifier | Used with | Purpose
Dynamic | Classes | Indicates that instances of a class are supplied by a provider.
Implemented | Methods | Indicates that an implementation of a method is available.
In | Parameters | Describes a parameter as an input parameter.
Read | Properties | Describes a property's value as read-only.
Units | Properties | Describes a property value's unit of measure.

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:

Qualifier type | CIM type | Automation type
String | String | VT_BSTR
Signed or unsigned 16 bit number | Sint16, Uint16 | VT_I2
Signed or unsigned 32-bit number | Sint32, Sin32 | VT_I4
Signed or unsigned 64-bit number | Sint64, Uint64 | VT_BSTR
Floating-point | Real8 | VT-R8
Boolean | Boolean | VT_BOOL

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


Using Qualifier Flavors

A qualifier flavor is a flag that describes the usage of a qualifer. The MOF language defines several qualifier flavors that can be attached to any qualifier, regardless of its origin. That is, the same flavor can be used to describe a standard WBEM class qualifier such as Association or a property qualifier defined by a provider for a specific class. However, some flavors are not appropriate for all qualifier types. The ToSubclass flavor, for example, is only appropriate for qualifiers defined with a class. It cannot be attached to a qualifier being used to describe an instance.

Flavors appear in the MOF syntax as follows. When multiple flavors are specified for a qualifier, whitespace acts as the delimiter:

[qualifier1 : flavor1 flavor2 flavor3, qualifier2 : flavor1]

The following table describes the flavor flags:

Flavor | Description
DisableOverride | Qualifier value cannot be overridden in a derived class or an instance.
EnableOverride | Qualifier value can be overridden in a derived class or an instance.
NotToInstance | Qualifier is not propagated to instances.
NotToSubclass | Qualifier is not propagated to derived classes.
Restricted | Qualifier is not propagated to instances or derived classes.
ToInstance | Qualifier is propagated to instances.
ToSubclass | Qualifier is propagated to derived classes.

When a qualifier lacks the DisableOverride flavor, its value can be overridden by a derived class or an instance. Specifying EnableOverride is optional.


MOF Data Types

The MOF language supports many data types that can be used to assign values to properties, qualifiers, and method parameters. Some of these data types map to Automation data types. All MOF data types are case-insensitive.

When a property is lacking an initial value, it is assigned the value of NULL. When a qualifier is lacking a value, it is assigned the value of TRUE. Parameters lacking initial values remain unassigned.

The MOF language also supports the following categories of data types:

  • Boolean
  • Numeric
  • String
  • Array
  • Embedded Object
  • Ref
  • Void


MOF Boolean Data Type

The Boolean data type takes on a value of logical TRUE or logical FALSE. This type is accessed programatically using the Automation type VT_BOOL, which takes on values of VARIANT_TRUE (-1) or VARIANT_FALSE (0). Note the difference between the programmatic representations of logical TRUE in C/C++ and Automation types:

  • C/C++: TRUE (1)
  • Automation:VARIANT_TRUE (-1)

While both types are nonzero and therefore not FALSE, they have different representations for TRUE.


MOF String Data Types

The MOF language supports the following string data types:

Data type | Automation type | Description
Char16 | VT_I2 | Single 16-bit UCS-2 Unicode character
Datetime | VT_BSTR | String containing a date and time in DMTF format
String | VT_BSTR | Unicode character string

Single character constants are surrounded by single quotes or else the integer representation of the UNICODE character value can be used directly:

char16  TestChar1 = '\x41';
char16  Testchar2 = 'A';
char16  TestChar3 = 65;
char16  TestChar4 = 0x1000;

Note that characters can be specified literally or with the \x escape sequence as in ANSI-C. Since the characters are Unicode, 16-bit values can also be specified.

Character strings are surrounded by double quotes. Note that ANSI-C single character constants are surrounded by double quotes.

Successive quoted strings are concatenated with one or more white spaces placed between them as delimiters. The following example illustrates how to represent a long character string using two character strings:

"This" "becomes a long string"

Embedded quotes require the use of an escape sequence beginning with the backslash:

"This is \"embedded quote example\" "

Because character and short integer values are identical, character constants can be assigned integer values if the values are within the 16-bit range of an unsigned Unicode character. The following class and instance declarations show how to initialize several string properties and a string parameter.

class  StringDataClass
{
    [KEY]  String    Dstring;
    DateTime         DTime;
    sint16           CharVal1;
    sint16           CharVal2
    sint32 DiskMethod ([in] string Description = "Disk Number 1");
};

instance of StringDataClass
{
    Dstring = "this can go on for " " some time"
       " before we are done";
    DTime    = "19940107140332.000000-300";
    CharVal1 = '\n';
    CharVal2 = '\x32';
};


MOF Numeric Data Types

MOF supports the following types of numeric values:

Data type | Automation type | Description
Sint8 | VT_I2 | Signed 8-bit integer
Sint16 | VT_I2 | Signed 16-bit integer
Sint32 | VT_I4 | Signed 32-bit integer
Sint64 | VT_BSTR | Signed 64-bit integer in string form. Hexadecimal or decimal format according to ANSI C rules.
Real32 | VT_R4 | IEEE 4-byte floating-point
Real64 | VT_R8 | IEEE 8-byte floating-point
Uint8 | VT_UI1 | Unsigned 8-bit integer
Uint16 | VT_I4 | Unsigned 16-bit integer
Uint32 | VT_I4 | Unsigned 32-bit integer
Uint64 | VT_BSTR | Unsigned 64-bit integer in string form. Hexadecimal or decimal format according to ANSI C rules.

Note 64-bit integers must be encoded as string because Automation does not support a 64-bit integral type.

Automation types do not always correspond in bit size to MOF data types. For example, VT_I4 is used to return an Uint16 value. This is because of sign extension problems. If VT_I2 was used instead of VT_I4, 65,536 would appear to be the value -1, causing a number of type and range problems.

Since Automation does support an unsigned 8 bit type, VT_UI1, no change in representation is required. The Uint32 type is represented as VT_I4 because there is no larger integer type to contain it.

Long constants are integer values that are declared using a simple series of digits with an optional negative sign. The long constant may not exceed the size of the variable that is declared to hold it. Some examples of long constants are 1000 and -12310.

Hexadecimal, binary, and octal constants are also supported:

val = 65;                        // Decimal
val = 0x41;                    // Hex (0x prefix)
val = 0101;                    // Octal (leading zero)
val = 1000001B;                // Binary (trailing B)

Binary constants have a series of 1 and 0 digits, with a "b" or "B" suffix to indicate that the value is binary.

Floating point constants can be used to represent scientific notation as well as fractions:

3.14
-3.14
-1.2778E+02

The following class and instance declarations illustrate how to use each of the numeric data types to set properties:

class NumericDataClass
{
    uint8            Duint8;
    SInt8            Dchar;
    UInt16               Dtword;
    Sint16               Dinst16;
    UInt32               DDword;
    Sint32               Dinst1;
    Sint32               Dinst2;
    Sint32               Dinst3;
    Sint32               Dinst4;
    Sint32               Dinst5;
    Real32           Dfloat;
    Real64               Ddouble1;
    Real64               Ddouble2;
}

instance of NumericDataClass
{
    Duint8   =  122;
    Dchar    = -128;
    Dtword   =  30;
    Dinst16  = -1445;
    Ddword   =  6987777;
    Dinst1   = -455589;
    Dinst2   =  23;
    Dinst3   =  03;                // base 8
    Dinst4   =  0xFe;                // base 16
    Dinst5   =  11b;                // base 2
    Dfloat   =  3.1478;
    Ddouble1 =  99987.3654;
    Ddouble2 =  2.3e-2;
}


MOF Arrays

MOF supports many different types of arrays, such as arrays of object references and embedded objects in addition to more standard string and numeric arrays. All arrays must be one-dimensional. Array dimensions vary at run time and are implemented internally as SAFEARRAY types. Arrays are initialized by specifying values of the appropriate type in a comma-separated list.

All elements in an array must be either values of the same type or NULL values. If the elements of an array are of type object, then any object is allowed in the array. If a specific type is declared, then only objects of that class or any of its subclasses are allowed.

To specify an array in a class declaration, use brackets after the property identifer.

class ArrayDataClass
{
    string strArray1[];
    string strArray2[] = {"hello", "there"};
    sint32 dwArray1[] = {1,2,3};
    EmbedClass objArray[];
};
instance of ArrayDataClass
{
    strArray1 = { "1.2.3.4", "1.2.3.5", "1.2.3.7"};
    strArray2 = {
            "select * from RegistryKeyChangeEvent",
            "select * from RegistryValueChangeEvent",
            "select * from RegistryTreeChangeEvent"};
    dwArray  = { 1, 2, 3, 5, 6 };
    objArray = {instance of EmbedClass{PropOfClass=3},
                instance of EmbedClass(PropOfClass=4};};
}

Arrays of references are simply arrays of object path strings:

instance of ClassWithRefArray
{
    refArray = {"Disk.Name=\"C:\"", "Disk.Name=\"E:\"";};
}

Arrays can be used with methods in class declarations only as parameters; they are not allowed to function as return values that are not output parameters. Arrays can be unbounded or have an explicit size, as is illustrated below:

Class MyClass
{
    sint32 MyMethod1 ([in] Win32LogicalDisk DiskArray1[]);
    sint32 MyMethod2 ([in] Win32LogicalDisk DiskArray2[32]);
}

WBEM implements bounded and unbounded arrays as SAFEARRAYS, expanding an array's size if necessary. When an array is declared with an explicit size, this size is stored as a qualifier and treated as the suggested maximum size. The explicit size has no affect on the actual data.


MOF Embedded Objects

MOF supports the use of objects fully embedded in class or instance declarations. Objects in this context refer to instances of another class. These objects can be declared as strongly typed or weakly typed, depending on whether a class name or the keyword Object is used with the declaration. Both types map to the VT_UNKNOWN type. The following class declaration illustrates how to declare strongly and weakly typed embedded objects:

class MyClass
{
    EmbedClass    Object1;          // strong typed
    object            Object2;          // weakly typed
}

The following examples show how to declare embedded objects within a class declaration:

class Class1
{
     [key] sint32 Class1Index;
};

class Class2
{
    [key] sint32 Class2Index;
    Class1 EmbedObject1 = instance of Class1{Class1Index = 3;};
};

class Class3
{
    [key] sint32 Class3Index;
    Class2 EmbedObject2 = instance of Class2 {Class2Index = 4;};

};

An embedded object can be an alias only if that object is a reference:

Instance of MyClass as $A
{
    intval = 33;
}

Instance of AnotherClass2
{
    intval = 34;
    EmbeddedObject = $A;
}

To initialize an embedded object, use the syntax for declaring an instance:

Instance of AnotherClass
{
    intval = 33;
    EmbeddedObject = instance of MyClass { intval = 99; }
}

Arrays of embedded objects are permitted. Because arrays can be weakly typed, they can be heterogeneous:

Instance of SomeClass
{
    ObArray = { instance of MyClass {intval = 33; },
      instance of YourClass { stringval = "Hello"; } };
}

Explicit use of NULL for the default value of embedded objects and paths is allowed, both for initializers and declarations.


MOF Object References

An object reference is a path to the location of an object. It can be either a fully qualified path to a server and namespace or a relative path to another object in the same namespace. Object references can be used as properties or parameters to methods.

MOF supports the use of object references with the ref data type. Object references are implemented programmatically as strings. Using object references reduces transport time and encoding if the object already exists in its entirety within the CIM repository.

MOF supports the concept of a weakly typed reference and a strongly typed reference. Both types map to the VT_BSTR Automation type. A weakly typed reference uses the ref data type with the object keyword whereas a strongly typed reference uses ref with the class name:

class MyClass
{
    object ref RefToAnyClass;                // weakly typed
    ClassX ref RefToClassX;                    // strongly typed
}

In the preceeding example, RefToAnyClass can be legally set to point to any class or instance while RefToClassX can only be set to point to objects of the class ClassX. This includes instances of ClassX as well as instances of any class derived from Class X.

The following class definition shows how to include two object references: one to a Win32LogicalDisk object and the other to a generic object:

Class MyClass
{
    sint32 MyMethod1 ([in] Win32LogicalDisk ref DiskRef);
    sint32 MyMethod2 ([in] object ref AnyObject);
}

If the object to be referenced is located within the same MOF file, an alias can be used. For information on referencing another object in the same MOF file, see Using Aliases.


MOF Void Data Type

The Void data type is only used in the MOF syntax to indicate a method that has no return value.


Specifying Comments

The MOF compiler supports two styles of comments:

  • // to mark the start of a comment

    -- or --

  • /* to mark the start of a comment and */ to mark its end

As in the C/C++ programming languages, the // style must be used with single line comments whereas the /* and */ style can be used with either single or multiple lines.

The following code illustrates a comment using the first style:

int32 MyProp = 2; // this is also a comment until the line ends

This code uses the second style:

int32 /* this is a comment */ MyProp = 2;


Specifying a Namespace

Because MOF files are compiled in the context of a namespace, it is necessary to identify the namespace into which the classes and instances defined in the MOF file should be placed. A namespace can be specified using either the following preprocessor command or the -N switch on the MOF compiler command line. In either case, the namespace path must be a fully qualified path or a path that is relative to the current namespace. The following statements show how to specify the SMIR namespace using first a full path and then a relative path:

// Full path to the SMIR namespace
  #pragma namespace("\\\\.\\root\\smir\\SMIR")
// Relative path to the SMIR namespace
  #pragma namespace ("SMIR")


Applications Guide

The Web-Based Enterprise Management (WBEM) Software Development Kit (SDK) applications include:

  • ActiveX™ Applications:
    • WBEM Object Browser

      The Object Browser is primarily used to view objects in a WBEM Common Information Model Object Manager (CIMOM) database. You can also edit property values, edit object and property qualifiers, and run operations on objects in the Object Browser.

    • Common Information Model (CIM) Studio

      The CIM Studio is used to view classes in a CIMOM database. You can also perform editing functions on classes, properties, qualifiers, and instances, run operations on classes, generate and compile Managed Object Format (MOF) files, and generate framework provider code in the CIM Studio.

  • WBEM HTML Viewer

    The HTML Viewer is used to view classes, properties, qualifiers, and instances in a CIMOM database. This tool is designed for use by advanced system managers and developers, particularly those writing providers, who do not have access to Microsoft® Internet Explorer with ActiveX™.

  • WBEM Event Registration Viewer

    The WBEM Event Registration Viewer is a graphical interface for viewing event consumer, filter, and timer system class properties and creating instances of them, as an alternative to doing so programmatically.

  • WBEM Event Viewer

    The WBEM Event Viewer displays events for all instances of registered consumers. You can also start the WBEM Event Registration Viewer from the Event Viewer in order to register consumers for events.

  • WBEM User Manager

    The WBEM User Manager allows you to create authorized WBEM users and set their access privileges.

  • WBEM Administrator

    The WBEM Administrator allows you to configure CIMOM database backups, enable and configure logging, and to set security for the WBEM installation directories and the registry.

This document provides a brief description of these applications and how to use them.


System Requirements for the ActiveX Applications

The system requirements for running the ActiveX applications are as follows:

  • Microsoft® Windows NT® version 4.0 or higher or Windows® 95. ActiveX™ components are not supported on Windows NT® 3.51.
  • Internet Explorer version 3.01 or higher. Note that the original version of Windows 95 includes a version of Internet Explorer that is labeled 4.0, but is actually an older version. You must update Internet Explorer if you are still using this version. You can download the latest version of Internet Explorer from http://www.microsoft.com.
  • Screen resolution is no less than 800x600.
  • VBScript version 2.0 must be installed on your machine. You can download VBScript from http://www.microsoft.com/vbscript.


Opening the ActiveX Applications

To open the ActiveX applications:
  1. Click Start.
  2. Point to Programs, then click WBEM SDK.
  3. Click the application you want to open (CIM Studio or WBEM Object Browser). The WBEM Login dialog box appears.

  4. Select the authentication method you want to use:

    Current User

    This method validates against the credentials of the currently logged-in user, and does not require you to enter a user name or password. If no account has been defined in the WBEM Security database for the currently logged-in user, you will be logged on to the WBEM GUEST account.

    WBEM

    If you select WBEM, enter your WBEM User Name and Password. If no account has been defined for your user name and password in the WBEM Security database, you will be logged on to the WBEM GUEST account.

    NTLM Domain

    If you select NTLM Domain, enter the Windows® NT® domain name as well as your User Name and Password for that domain.

  5. Click OK.


WBEM Object Browser

The WBEM Object Browser is designed for use by system managers. The Object Browser displays the object tree in a CIMOM database, showing the relationships (that is, associations) between the objects. You can browse the objects in the database by traversing these relationships in either tree or graphical formats.

Using the Object Browser, you can do the following:

  • Display the object tree contained in a specified CIMOM database.
  • Reroot the object tree.
  • Display properties, methods (operations), and associations for a selected object.
  • Display custom views of object data.
  • Display instances of grouped objects.
  • Display property and object qualifiers.
  • Run operations on a selected object.

Note This feature is not implemented at this time.

  • Edit property values and object and property qualifiers.


Object Browser User Interface

The WBEM Object Browser contains an Object Explorer and an Object Viewer. In general, you select objects in the Object Explorer and their details appear in the Object Viewer. A sample WBEM Object Browser screen is shown below:


Object Explorer

The left frame in the WBEM Object Browser is the Object Explorer, which shows the object tree contained in the current namespace. By default, the root\DEFAULT namespace on the local machine appears. You can select a different local namespace or a namespace on a remote machine.

Clicking the plus and minus boxes expands and contracts the tree display. The tree shows regular objects and grouping nodes. Grouping nodes are not objects themselves, but are a way to organize objects. The icons next to the names indicate the type of object or node:

Regular object.
Node that groups objects by type.
Node that groups objects by association type and role. All objects beneath such a node are associated with the parent object through the same association type and role.

Some of these icons are also used in the Object Viewer.

Hovering over an object in the tree displays the object's path. The object path identifies the object in the namespace. You can also change the root of the object tree. For instructions, see Rerooting an Object Tree.

The Object Explorer also includes the following buttons:

Browse for Namespace button allows you to browse and select namespaces on the local machine or a remote machine. See Browsing for a Namespace for information.
Browse for Instance button allows you to browse classes for a specific instance and reroot the Object Explorer tree from that instance. See Using Browse for Instance to Reroot the Object Tree.


Object Viewer

The right frame in the WBEM Object Browser is the Object Viewer, which displays details on a selected object. Using the tabs, you can display the properties, methods, and associations for an object. For additional information on each of these views, see Object Browser Functions. Selecting a regular object in the Object Explorer automatically updates the Object Viewer to show details on that object. Selecting a grouping node updates the Object Viewer to show an instance table for that node.

The Object Viewer uses an additional icon to identify association objects ( [image]) on the Associations page.

The Object Viewer includes the following buttons:

Back/Forward buttons display previously-viewed pages.
Save button commits changed information to CIMOM.
Views button switches to custom views of object data. See Displaying Custom Views of Object Data.

The WBEM Object Browser also includes a Help button ( [image]). Double-click this button to open help on the WBEM ActiveX applications.


Object Browser Functions

This section describes the viewing and editing functions you can perform in the WBEM Object Browser.

Note If an error occurs while you are editing object properties or qualifiers (for example, if you enter a property type and value that are incompatible), a message box appears with a brief description of the problem. Click Advanced to view the error object's properties. The property display contains more details on the problem that occurred.


Displaying an Object Tree

By default, the Object Browser sets the namespace to root\DEFAULT, which is the default namespace on the local machine. You can view the object tree for any namespace in your system or on a network by specifying the namespace path in one of the following ways:

Specifying the Namespace in the Objects in Box

Selecting the Namespace from the History List

Browsing for a Namespace

Using the Go to Namespace Function

Note While the Object Browser runs with any database, a database that has no associations shows only a single object, the root selected by the user. This type of database can be viewed more effectively in the CIM Studio.


Rerooting an Object Tree

When the Object Browser opens, it searches for an instance of the System class or any class derived from System. If found, this class becomes the root of the initial object tree. If no such class is found, the Object Browser displays a dialog box asking for a class name. Type a class name in the dialog box, and click OK. The specified class becomes the root of the initial object tree.

Any regular object can be made the root of the object tree by using either of the following methods:

Using Make Root to Reroot the Object Tree

Using Browse for Instance to Reroot the Object Tree


Displaying Properties of Regular Objects

To display properties of regular objects
  1. Select the object in the Object Explorer.
  2. Click the Properties tab in the Object Viewer.

The Properties page displays the properties for a selected regular object. Properties attached to an object by the system are preceded by a double underscore (for example, __SERVER). Nonsystem properties are either defined by the user or inherited from parent classes.

The following example screen shows the properties for the Win32ProgramGroup All Users:ODBC object:

See Also

Displaying Properties of Association Objects


Displaying Custom Views of Object Data

The example screen shown in the topic Displaying Properties of Regular Objects shows the Generic view of an object's data. Developers can create custom views of data, and associate those views with specific objects. If a custom view is available for an object, the Views button becomes active when the object is selected.

To display a custom view
  1. Click the Views button. The Views window appears with a list of available views.
  2. Select the view you want from the list, then click OK.

To return to the Generic view, click the Views button, then select Generic view from the list. Then click OK.

The following custom view shows the amount of free space available on a system's disk drives. The WBEM SDK samples directory <drive>:\<Wbem-directory>\sdk\com\CustomViews contains files and instructions for creating this sample view.


Editing Object Properties

You can edit the Value field for most properties.

To edit a property value
  1. Display the Properties page for the object you want to change. For instructions, see Displaying Properties of Regular Objects or Displaying Properties of Association Objects.
  2. Click the property value you want to change.
  3. If a down arrow appears when you select the value, click the arrow, then choose a value from the list that appears.

    If no down arrow appears, type the new value in the field.

    When you start typing, the text turns blue. The Save button becomes active; this indicates that the value has not been committed yet.

    If the property type is an array, clicking the Array button in the Value field opens a dialog box in which you can enter each value in the array. When you have finished entering values, click OK to return to the Properties page.

    If the property type is an object, the Value field contains either <empty> (which represents NULL) or an Object button. To change this field, do one of the following:

    • Click the Object button to open the Embedded Object dialog box. You can edit properties and qualifiers from this box the same way as on the Object Viewer Properties page. Click OK to return to the Object Viewer.
    • Right-click the Object button, and select Set to <empty>.
    • Right-click the <empty> value, and select Create object. This opens the Embedded Object dialog box. Enter the name of the class to which the object belongs. The Properties page for that class appears. You can edit properties and qualifiers the same way as on the Object Viewer Properties page. Click OK to return to the Object Viewer.
  4. When you have finished editing, click the Save button. A confirmation message appears. Click Yes to save the changes. After the changes are saved, the text turns black.

Note Some property values are read-only and cannot be edited.


Displaying Instances

When you select a grouping node in the Object Explorer, the Object Viewer displays an instance table showing all objects in the namespace that belong to the selected group, as well as the common properties of those objects.

The following screen shows the instance table for the Win32ProgramGroup object group:


Displaying and Executing Object Methods

To display object methods
  1. Select the object in the Object Explorer.
  2. Click the Methods tab.

Execution of methods is not implemented in this release.


Displaying Object Associations

To display object associations
  1. Select the object in the Object Explorer.
  2. Click the Associations tab in the Object Viewer.

The Associations page graphically displays the objects associated with the current object.

The following screen shows all objects associated with the computer system EDKDOCS1, which is the root of the object tree in the example:

On the Associations page:

  • The left-most object icon always represents the current object, EDKDOCS1, as shown in the preceding screen sample.
  • Each branch from the current object represents an association of that object to another object.
  • The icon in the middle ( [image]) represents the association object.
  • The right-most object icons represent the objects associated with the current object.

On the Associations page, you can also do the following:

  • Hover over the association object icon to display the association type.
  • Hover over the connecting lines on each side of the association object icon to display the roles of the related objects.
  • Jump to another regular object by double-clicking its icon. For example, double-clicking the icon next to Win32Service.Name="Messenger" in the preceding screen sample changes the display to the following:

Selecting another object on the Associations page updates all displays in the Object Viewer. In this example, the Properties and Methods pages now display information about the Messenger object.

  • Jump to an association object by double-clicking its icon. In the preceding screen sample, the association object next to Win32Service.Name="LanmanWorkstation" is of the type Win32ServiceToService. Selecting this icon changes the display to the following:

This also updates the Properties and Methods pages to show information for the newly-selected association object.

  • Jump to the Properties page of an object by right-clicking the object's icon or name. Select Properties from the menu that appears.
  • Invoke the Make Root and Go to Namespace functions by right-clicking an object's icon or name and selecting the appropriate option from the menu that appears.


Displaying Properties of Association Objects

To display the properties of an association object
  1. On the Associations page, double-click the icon for the association object you want to display.
  2. Click the Properties tab. The property details for the selected association object appear.

You can also right-click an object in the Object Explorer, then select Association from the menu that appears. The Object Viewer displays the details of the association object that links the selected object to the object above it.

See Also

Displaying Properties of Regular Objects


Editing Properties of Association Objects

You can edit the property values of association objects in the same way as regular objects. For instructions, see Editing Object Properties.


Displaying Object Qualifiers

To display object qualifiers
  1. Select the object in the Object Explorer, and click the Properties tab in the Object Viewer.
  2. Right-click in the Properties page of the Object Viewer.
  3. Select Object qualifiers from the menu that appears. The Qualifiers window appears.


Displaying Property Qualifiers

Property qualifiers can only be displayed for non-system properties.

To display property qualifiers
  1. Select the object in the Object Explorer, and click the Properties tab in the Object Viewer.
  2. Double-click the property whose qualifiers you want to display.

    —or—

    Right-click the property whose qualifiers you want to display. Select Property qualifiers from the menu that appears.

    In both cases, the Qualifiers window appears. If the object has no property qualifiers, the window is blank.

To close the Qualifiers window, click the OK or Cancel button.

The following screen shows the qualifiers for the BorderWidth property of the Win32Desktop Administrator object:


Editing Object and Property Qualifiers

To edit object and property qualifiers
  1. Select the object in the Object Explorer.
  2. Display the Qualifiers (object or property) window you want to edit.
  3. Click the field you want to change.
  4. If a down arrow appears when you select the field, click the arrow and choose a value from the list that appears.

    If no down arrow appears, type the new value in the field.

    Click the I, C, and O fields to select or cancel these settings.

    The Origin field is read-only. It indicates where the qualifier originated: local (for qualifiers defined in the current object) or propagated (for qualifiers propagated from another object).

    When you start typing, the text turns blue. The Save button becomes active to indicate that the value has not been committed yet.

  5. When you have finished editing, click the OK button. This closes the Qualifiers window.
  6. In the Object Viewer, click the Save button. A confirmation message appears. Click Yes to save the changes.


Common Information Model (CIM) Studio

The CIM Studio is designed primarily for use by developers, particularly those who are writing providers, and for advanced system managers. Using the CIM Studio, you can do the following:

  • Display the class inheritance tree (schema) in a specified CIMOM database.
  • Search for a specific class.
  • Display the definition of an existing class (properties, qualifiers, and methods (operations)).
  • Display instances of an existing class (standard or custom views).
  • Extend and modify the existing schema by adding or deleting class definitions.
  • Modify a class by adding, editing, or deleting properties, qualifiers, and methods in a class definition.
  • Add or delete instances of a class.
  • Run the C++ code generator, MOF file generator, and MOF file compiler on selected classes and/or instances.


CIM Studio User Interface

The CIM Studio contains a Class Explorer and a Class Viewer. In general, when you select classes in the Class Explorer, their details appear in the Class Viewer. The CIM Studio wizards generate and compile MOF files, and generate framework provider C++ code.

A sample CIM Studio screen is shown below:


Class Explorer

The left frame in the CIM Studio is the Class Explorer. The Class Explorer shows the selected namespace (root\DEFAULT in the sample screen in the preceding topic) and the schema defined for that namespace as a class inheritance tree. Clicking the plus and minus boxes expands and contracts the tree. The shaded icons next to the class names indicate the type of objects defined by the class:

Class that defines regular objects
Class that defines association objects

Use the check boxes to select or cancel the selection of classes for the wizard operations performed in the CIM Studio. You can also select or clear all check boxes by right-clicking anywhere in the Class Explorer, and then choosing Select all or Unselect all from the menu that appears.

For non-wizard operations, select classes by clicking the class name in the Class Explorer.

The Class Explorer includes the following buttons:

Browse for Namespace button allows you to browse and select namespaces on the local machine or a remote machine. See Browsing for a Namespace.
Search for Class button allows you to search for a specific class in the namespace. See Searching for a Class.
Add class button adds a new class to the current database. See Adding Class Definitions.
Delete class button deletes a selected class from the current database. See Deleting Class Definitions.


Class Viewer

The right frame in the CIM Studio is the Class Viewer. The Class Viewer displays details on a selected class. Using the tabs, you can display the properties and methods defined for a class. For additional information on these views, see Displaying the Definition of an Existing Class. Selecting a class in the Class Explorer automatically updates the Class Viewer display.

The Class Viewer includes the following buttons:

Create instance button creates a new instance of a selected class. See Adding Instances of a Class.
Delete instance button deletes the selected instance. See Deleting Instances of a Class.
Back/Forward buttons display previously-viewed pages.
Save button commits changed information to CIMOM.
Instances button displays a table of all instances of a selected class. See Displaying an Instance Table.
Views button displays custom views of class instance data. See Creating and Using Custom Views of Instances.

The CIM Studio also includes a Help button ( [image]). For help on the WBEM ActiveX applications, double-click this button.


Wizards

The three icons above the Class Viewer invoke the following wizards:

C++ Code Generator Wizard generates framework provider C++ code for a selected class. See C++ Code Generator Wizard.
MOF Generator Wizard inserts selected class definitions and/or instances from the database into a text file in the MOF syntax. See MOF Generator Wizard.
MOF Compiler Wizard imports class definitions or instances described in a MOF file into the current database. See MOF Compiler Wizard.

When selected, each wizard opens a series of screens that guide you through the operation.


CIM Studio Functions

This section describes the functions that can be performed in the CIM Studio.

Note If an error occurs while you are editing class properties or qualifiers (for example, if you enter a property type and value that are incompatible), a message box appears with a brief description of the problem. Click the Advanced button to display the error object's properties. The property display contains more details on the problem that occurred.


Displaying a Class Inheritance Tree

By default, the CIM Studio sets the namespace to root\DEFAULT. This is the default namespace on the local machine. You can view the class inheritance tree for any namespace in your system or on a network by specifying the namespace path in one of the following ways:

Specifying the Namespace in the Classes in Box

Selecting the Namespace from the History List

Browsing for a Namespace


Searching for a Class

To search for a specific class in the namespace
  1. In the Class Explorer, click the Search for Class button. The Search for Class dialog box appears.
  2. Enter the name of the class you want to find, then click OK. If found, the class is selected in the Class Explorer and its details appear in the Class Viewer.


Displaying the Definition of an Existing Class

Within CIM Studio, you can display the properties, qualifiers, and methods of an existing class.

Displaying Class Properties

Displaying Class Qualifiers

Displaying Property Qualifiers

Displaying Class Methods


Displaying Instances of an Existing Class

Within CIM Studio, you can open a table of all instances of a class. You can also define and display custom views of instances.

Displaying an Instance Table

Creating and Using Custom Views of Instances


Adding Class Definitions

To add a class
  1. In the Class Explorer, select the class from which you want to derive a new class.
  2. Click the Add Class button. The Add Class dialog box appears.
  3. Type the name of the new class in the New Class box, and then click OK.

The Class Viewer displays the new class in the Properties page, showing all the parent class's properties that are inherited by the new class.

To add a class at the top level
  1. In the Class Explorer, click the Add Class button. The Add Class dialog box appears.
  2. Erase the parent class name in the Add Class dialog box (this box should be blank).
  3. Type the name of the new class in the New Class box, and click OK.

For more information on adding properties to a new class, see Adding Class Properties.


Deleting Class Definitions

To delete a class
  1. In the Class Explorer, select the class you want to delete.
  2. Click the Delete Class button. The Delete Class Query box appears.
  3. Click Yes to delete the class.

When you delete a class, all of its child classes are deleted.


Modifying Class Definitions

You can modify a class by adding, editing, or deleting properties, qualifiers, and methods in a class definition.

Adding Class Properties

Deleting Class Properties

Editing Class Properties

Adding Class or Property Qualifiers

Deleting Class or Property Qualifiers

Editing Class or Property Qualifiers

Modifying Class Methods


Editing Class or Property Qualifiers

To edit class or property qualifiers
  1. Open the Qualifiers (class or property) window you want to edit. For instructions, see Displaying Class Qualifiers or Displaying Property Qualifiers.
  2. Click the field you want to change.
  3. If a down arrow appears when you select the field, click the arrow and choose a value from the list that appears.

    If no down arrow appears, type the new value in the field.

    Click the I, C, and O fields to select or cancel these settings.

    The Origin field is read-only. It indicates where the qualifier originated: local (for qualifiers defined in the current object) or propagated (for qualifiers propagated from another object).

    When you start typing, the text turns blue. This indicates that the value has not been committed yet.

  4. When you have finished editing, click the OK button to close the Qualifiers window.
  5. In the Class Viewer, click the Save button. A confirmation message appears. Click Yes to save your changes.


Adding Instances of a Class

To add an instance of a class
  1. In the Class Explorer, select the class for which you want to create an instance.
  2. Click the Create instance button in the Class Viewer. The viewer displays data for the new instance, and the Save button becomes active.
  3. Enter values for the key property fields. For information on editing properties, see Editing Class Properties.
  4. When you have finished editing the key fields, click the Save button.

Note You cannot add instances of the following classes:

  • Classes that do not have key fields (abstract classes)
  • Classes that have dynamic instance providers


Deleting Instances of a Class

To delete an instance of a class
  1. Open the instance table for the desired class. For instructions, see Displaying an Instance Table.
  2. Click the blank box to the left of the instance you want to delete. This selects the entire instance entry.
  3. Click the Delete instance button in the Class Viewer. A confirmation message appears. Click OK to delete the instance. The instance is deleted from the table.


MOF Generator Wizard

The MOF Generator Wizard generates a MOF file for class definitions and/or instances from an existing database. Typically, you run this wizard when you have created a new class, or when you want to port existing database information to another machine.

To run the MOF Generator Wizard
  1. In the Class Explorer, click the check boxes to select the classes you want to insert in the MOF file.
  2. Double-click the MOF Generator Wizard icon. A welcome screen appears.
  3. Click Next. The following screen appears:

This screen shows each class you selected in step 1. For each class, do the following:

  1. Select the class name from the list under Classes to generate code for. The instances of that class, if any, appear in the right pane.
  2. Select whether you want the class definition in the MOF file by clicking the check box next to Include class definition.
  3. Click the check boxes to select the instances to be included in the MOF file.
  4. Click Next. The following screen appears:

Enter the MOF File Name and the directory where you want it to reside, or use the Browse button to select a directory.

  5. Click Finish. A message box appears notifying you that the MOF file has been generated. Click OK to dismiss the message and close the wizard.


MOF Compiler Wizard

The MOF Compiler Wizard compiles the MOF file into a database, importing any class definitions or instances from the MOF file into the current database. You can also use this wizard to check the syntax of a MOF file.

Compiling a MOF File

Checking the Syntax of a MOF File


C++ Code Generator Wizard

The C++ Code Generator Wizard generates framework provider code for classes defined in the database. Producing this code is an initial step in the process of writing a provider that provides dynamic instances for a particular class of objects.

To run the C++ Code Generator Wizard
  1. In the Class Explorer, click the check boxes to select the classes for which you want to generate code.
  2. Double-click the Provider C++ Wizard icon. A welcome screen appears.
  3. Click Next. The following screen appears:

This screen shows each class you selected in step 1. For each class, do the following:

  1. Select the class name from the list under Classes to generate code for.
  2. Enter a Base File Name, C++ Class Name, and Description for the class.
  3. Select whether you want to override any inherited properties for the class. If you select Override Inherited Properties, a list of properties appears. Click the check boxes to select the properties to override.

    If you are writing a provider for a class that is derived from an abstract class or if the parent class does not have a provider, you typically need to provide all the class properties. In this case, select Override Inherited Properties, then select all the properties that appear.

    If your class is derived from a class that already has a provider, you only need to provide the properties the derived class defines. You do not need to override inherited properties in this case.

  4. Click Next. The following screen appears:

Enter the Provider Name, Provider Description, and the directory where the generated files will reside. You can use the Browse button to select the directory.

  5. Click Finish. A message box appears notifying you that the files have been generated. Click OK to dismiss the message box and close the wizard.

The wizard generates the following files: .CPP and .H files for each class created, .DEF and .ODL files for the provider, and Olesrvr.cpp. For instructions on turning these files into a functioning provider, see Creating a Provider with CIM Studio.


WBEM HTML Viewer

The HTML Viewer is designed for use by advanced system managers and developers, particularly those who are writing providers, and who do not have access to Microsoft® Internet Explorer with ActiveX™.It provides HTML-based browser views of a CIM Object Manager (CIMOM) schema. The HTML Viewer is automatically installed during a complete installation of the WBEM SDK.

This interface requires Microsoft® Internet Information Server (IIS) and an Internet browser. Because the HTML Viewer uses HTML frames, it is recommended that you use only Internet browsers supporting frames, such as Microsoft® Internet Explorer 3.0 and newer versions and Netscape® Navigator 2.0 and newer versions).

Note If you have Microsoft® Internet Explorer with ActiveX™, use the WBEM Object Browser.

Using the HTML Viewer, you can do the following:

  • Display the class inheritance tree (schema) in a specified CIMOM database.
  • Search for a specific class.
  • Display the definition of an existing class (properties, qualifiers, and methods (operations)).
  • Display instances of an existing class (standard or graphic views).


HTML Viewer Environment

The HTML Viewer allows you to view schema class definitions on a particular machine in a network, and to view objects of those classes on that machine. The HTML Viewer displays objects from a CIM Object Manager (CIMOM) database. You can browse the objects by selecting the classes by using the graphical or default views.

Each time you use the HTML Viewer you are asked for the machine name to browse. Before you can view the classes on a particular machine, CIMOM must create a database on that machine.

Note CIMOM must be installed and a database of classes must be created on the target machine prior to using the HTML Viewer. One of the methods for creating a database of classes is to compile a MOF file in the directory where the SDK was installed (typically c:\Wbem). To compile the MOF file, type the following at the command-line prompt: mofcomp <filename.mof>. For more information, see MOF Compiler.

The examples in the following topics use the Cimwin32.mof file that is provided in the SDK. This MOF file compiles into a database of Win32® schema classes that can be viewed by using the HTML Viewer.

The HTML Viewer uses a pure HTML output to present the following information:

  • Classes
  • Properties
  • Instances
  • Values

This information is presented in an HTML view derived from the CIMOM database.


Viewing Namespaces

In CIMOM, namespace objects are used to control the scope and visibility of instances of a particular class. A namespace is a logical data set consisting of classes and all instances that belong to those classes, thus forming the logical database.

Every machine that has CIMOM installed has a root namespace, \\<machinename>\Root, and potentially more namespaces defined under the root namespace in a tree hierarchy. For example, the Win32 schema and objects are located in the default namespace under the root namespace (\\<machinename>\root\DEFAULT). For a more complete discussion see Namespaces in the CIMOM Reference.

To open the HTML Viewer:
  1. Click Start.
  2. Select Programs, then select WBEM SDK.
  3. Double-click the WBEM HTML Viewer icon.

When you are prompted to enter the name of the machine you wish to browse, type in the target machine name (\\machine) and select Go. The HTML Viewer presents a list of all namespaces available on the target machine. There is one link for each available namespace. The root\DEFAULT namespace is a special case, since it is more frequently used. It has an additional link to a graphical view of the most interesting classes in this namespace.

Note After selecting the Go button, Netscape can fail to display a list of the namespaces initially. To try again, select the reload button.


Standard View

The standard view provides a flat list of classes in the namespace. Each class is identified by a unique name. For example, there can only be one class in a particular namespace with the name LogicalDisk. Select a class to view its properties. The following screen shows the standard view for the root\default namespace on the \\Sapper7 machine.


Graphic View

The graphic view is available only for the root\default namespace, also known as the Win32 schema namespace. This view displays the classes available in the selected namespace. The following screen shows the Win32 classes available on that namespace.

Note Not all of the Win32 schema classes are available on this view. Only the more interesting classes are presented.


Viewing Class Definitions and Instances

By default, the HTML Viewer sets the namespace to root\default, which is the default namespace on the local machine. You can view the class inheritance tree for any namespace in your system or on a network by specifying the namespace path.

For example, specifying \\Sapper7\root\default displays the class inheritance tree for the default namespace on the machine Sapper7. If no machine is specified, the default is the local machine. You can specify a chain of namespaces, separating each with a backslash:

\\<machine>\root\<namespace>\<namespace>\<namespace>

The HTML Viewer can also display a table of all instances of a class. You can also define and display custom views of instances.

Class Information Pages

To View a Class Definition

To View Instances


Class Information Pages

The HTML pages representing class information are provided in three different views:

  • Short view—This page provides information immediate to the class plus any associations that involve the class. The superclass, if any, appears as a link that references the short page for the superclass. The subclasses, if any, appear as links that reference the short page for the subclasses.
  • Flat view—This page provides information about the class and all of its superclasses up to the root class.
  • Verbose view—The verbose view resembles the short view except that all qualifiers for the class and its properties are shown on the one page.

The developer or system administrator selects the view that best suits the current task. For example, if information about the inheritance chain and the properties inherited at each stage is needed, look at the class definitions in the flat view. However, if a brief description of the local properties is needed, look at the short view.


To View a Class Definition

Select a class from the standard or graphic views to display the properties of that class. The following screen shows the class definition for the ComputerSystem class.

The Parent <class> represents the class from which this class is derived. In this case, it is the "System" class. Selecting this link takes you to an HTML page that provides a description of the parent class.

Select the link to the namespace that you are currently browsing. In this example, \\<MachineName>\root\default allows you to jump back to the standard view for this namespace.


To View Instances

Deriving from a class definition, you can define specific managed objects by using instances of that class. Where the class models the real-world device or component in the general sense, each instance represents a specific occurrence of the class.

To see instances of a class, select Instances from the property page. From this view you can see all instances of the class and the values for all properties listed.


WBEM Event Registration Viewer

The WBEM Event Registration Viewer is designed for developers and system managers. It provides a graphical interface for what may also be done programmatically. The Event Registration Viewer allows you to display and modify the event consumers, filters, and timers for a given namespace and any bindings between filters and consumers.

Using the Event Registration Viewer, you can do the following:

  • View properties of the defined consumer, filter, and timer system classes and instances.
  • Add or delete event consumer instances.
  • Add or delete event filter instances.
  • Add or delete event timer instances.
  • Edit instance properties.
  • Register consumers for events by binding consumer and filters.

See Also

Timer Events

Event Consumers


WBEM Event Registration Viewer Interface

The left pane of the WBEM Event Registration Viewer displays the consumer, filter, or timer inheritance tree. The right pane displays any bindings you have defined between consumers and filters. An example Event Registration Viewer screen is shown below:

The left pane of the Event Registration Viewer shows the inheritance tree of consumers, filters, or timers contained in the current namespace. By default, the local machine displays the root\DEFAULT namespace. You can select a different local namespace or a namespace on a remote machine.

Clicking the plus and minus boxes expands and contracts the tree display. The tree shows system classes and instances of those classes.

The left pane of the Event Registration Viewer includes the following buttons and icons:

Browse for Namespace button allows you to browse and select namespaces on the local machine or a remote machine.
New Instance button allows you to define another instance of the selected consumer, filter, or timer.
Edit Instance Properties button allows you to view and modify some properties of the selected instance.
Delete Instance button deletes the selected instance.
An icon that denotes a class.
An icon that denotes an instance.
Help button. Double-click this button to display help.

The right pane of the Event Registration Viewer shows the bindings you have defined between consumers and filters. If you select consumers in the left pane, filters appear in the right pane. Likewise, if you select filters in the left pane, consumers appear in the right pane.

The right pane of the Event Registration Viewer includes the following buttons:

Register button registers the selected filter-consumer combination.
View Instance Properties button allows you to view some properties of the selected instance.

In the columns of the right pane, you can:

  • Reorder the columns by selecting and dragging a column over another column.
  • Adjust the column size.
  • Sort information according to the column heading by clicking the heading.


WBEM Event Registration Viewer Functions

This section describes the functions you can perform in the WBEM Event Registration Viewer.

Note You must install CIMOM and create a database of classes on the target machine before you can use the Event Registration Viewer. One of the methods for creating a database of classes is to compile a MOF file in the directory where the SDK was installed (typically c:\Wbem). To compile the MOF file, type the following command: mofcomp <filename.mof>. For more information, see MOF Compiler.

The examples in the following topics use the Cimwin32.mof file found in the SDK. This MOF file compiles into a database of Win32® schema classes that can be viewed in the Event Registration Viewer.

To open the Event Registration Viewer
  1. Click Start.
  2. Point to Programs, then click WBEM SDK.
  3. Click WBEM Event Registration. The WBEM Login dialog box appears.

  1. 4.Click OK.

Viewing Class Properties

Creating an Event Consumer Instance

Creating an Event Filter Instance

Creating an Event Timer Instance

Registering a Consumer for an Event


Viewing Class Properties

While you cannot modify any properties of a system class, you can view its properties.

To view class properties
  1. In the left pane of the Event Registration Viewer, click the class, and then click the View Class Properties button.

    —or—

  2. In the left pane of the Event Registration Viewer, right-click the class, and then select View Class Properties from the pop-up menu.

    The View Class Properties dialog box appears.

Creating an Event Consumer Instance

Creating an Event Filter Instance

Creating an Event Timer Instance

Registering a Consumer for an Event


Creating an Event Consumer Instance

You create event consumers as instances of a given class. This version of WBEM contains a predefined EventViewerConsumer class, which is a subclass of the __EventConsumer system class.

The first procedure describes how to create an event consumer instance. The second and third procedures are intended to work along with the example filters and timers.

To create an event consumer instance
  1. From the drop-down list box, choose Consumers.
  2. Click the class you want to create an instance, and click the New Instance button.

    —or—

  3. Right-click on the class you want to create an instance, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.

  4. In the Edit new instance properties dialog box, type strings in the Description and Name fields, and type a value in the Severity field.
  5. Click OK to create the instance.
To create the ServiceStopped event consumer instance

This example defines an instance that, in conjunction with the ServiceStoppedEvent filter, triggers an event notification and displays it in the Event Viewer when a system service is stopped.

  1. From the drop-down list box, choose Consumers.
  2. Click the EventViewerConsumer class, and click the New Instance button.

    —or—

  3. Right-click on the EventViewerConsumer class, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.
  4. In the Edit new instance properties dialog box, type the following:
    1. In the Description field, type Service was stopped.
    2. In the Name field, type ServiceStopped.
    3. In the Severity field, type 1.
  5. Click OK to create the instance.
To create the TimerEvent event consumer instance

This example defines a consumer that works with IntervalTimerFilter or AbsTimerFilter This triggers an event notification and displays it in the Event Viewer at regular intervals, or at a particular date and time.

  1. From the drop-down list box, choose Consumers.
  2. Click the EventViewerConsumer class, and click the New Instance button.

    —or—

  3. Right-click on the EventViewerConsumer class, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.
  4. In the Edit new instance properties dialog box, type the following:
    1. In the Description field, type TimerEventReceived.
    2. In the Name field, type TimerEvent.
    3. In the Severity field, type 2.
  5. Click OK to create the instance.

Viewing Class Properties

Creating an Event Filter Instance

Creating an Event Timer Instance

Registering a Consumer for an Event

See Also

Event Consumers

__EventConsumer


Creating an Event Filter Instance

Event filters define criteria for receiving event notifications.

You create event filters as instances of a given class. This version of WBEM contains the predefined __EventFilter system class.

The first procedure describes how to create an event consumer instance. The other procedures are examples intended to work along with the example consumers and timers.

To create an event filter instance
  1. From the drop-down list box, choose Filters.
  2. Click the class you want to create an instance, and click the New Instance button.

    —or—

  3. Right-click on the class you want to create an instance, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.

  4. In the Edit new instance properties dialog box, type the following:
    1. In the Name field, type a name for the filter.
    2. In the Query field, type a WQL SELECT statement that specifies the event criteria.
    3. In the Query Language field, type WQL.
  5. Click OK to create the instance.
To create the ServiceStoppedEvent filter

This example defines a filter that works with the ServiceStopped consumer to display an event notification in the Event Viewer when a system service is stopped.

  1. From the drop-down list box, choose Filters.
  2. Click the __EventFilter class, and click the New Instance button.

    —or—

  3. Right-click on the __EventFilter class, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.

  4. In the Edit new instance properties dialog box, type the following:
    1. In the Name field, type ServiceStoppedEvent.
    2. In the Query field, type the following WQL SELECT statement to specify the event criteria:
      select * from __InstanceModificationEvent within 5 where TargetInstance isa "Win32_Service" and TargetInstance.State="Stopped"
    3. In the Query Language field, type WQL.
  5. Click OK to create the instance.
To create IntervalTimerFilter

This example defines a filter that works with the TimerEvent consumer and IntervalTimer to display an event notification in the Event Viewer every 5 seconds.

  1. From the drop-down list box, choose Filters.
  2. Click the __EventFilter class, and click the New Instance button.

    —or—

  3. Right-click on the __EventFilter class, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.

  4. In the Edit new instance properties dialog box, type the following:
    1. In the Name field, type IntervalTimerFilter.
    2. In the Query field, type the following WQL SELECT statement to specify the event criteria:
      select * from __TimerEvent
    3. In the Query Language field, type WQL.
  5. Click OK to create the instance.
To create the AbsTimerFilter

This example defines a filter that works with the TimerEvent consumer and AbsTimer to display an event notification in the Event Viewer at a specified date and time.

  1. From the drop-down list box, choose Filters.
  2. Click the __EventFilter class, and click the New Instance button.

    —or—

  3. Right-click on the __EventFilter class, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.

  4. In the Edit new instance properties dialog box, type the following:
    1. In the Name field, type AbsTimerFilter.
    2. In the Query field, type the following WQL SELECT statement to specify the event criteria:
      select * from __TimerEvent where TimerId="AbsTimer"
    3. In the Query Language field, type WQL.
  5. Click OK to create the instance.

Viewing Class Properties

Creating an Event Consumer Instance

Creating an Event Timer Instance

Registering a Consumer for an Event

See Also

__EventFilter

Creating an Event Filter

Event Queries

WBEM Query Language


Creating an Event Timer Instance

Timer events may be of the absolute or interval type. Absolute timer events occur at a particular date and time, while interval timer events occur at regular intervals.

You create event timers as instances of a given class. This version of the WBEM Event Registration Viewer provides the two subclasses of __TimerInstruction, __AbsoluteTimerInstruction and __IntervalTimerInstruction. You can create an instance with either or both of these.

The first two procedures generally describe the creation of the two kinds of event timer instances. The other two procedures are examples intended to work along with the example consumers and filters.

To create an absolute event timer instance
  1. From the drop-down list box, choose Timers.
  2. Expand the tree to expose the subclasses.
  3. Click __AbsoluteTimerInstruction, and click the New Instance button.

    —or—

  4. Right-click on __AbsoluteTimerInstruction, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.

  5. Click the Value field of the EventDateTime row. The Time dialog box appears.

  6. In the Time dialog box, set the date, time, and time zone.
  7. Click OK.
  8. In the TimerId field of the Edit new instance properties dialog box, type a name for the timer.
  9. Click OK to create the instance.
To create an interval event timer instance
  1. From the drop-down list box, choose Timers.
  2. Expand the tree to expose the subclasses.
  3. Click __IntervalTimerInstruction, and click the New Instance button.

    —or—

  4. Right-click on __IntervalTimerInstruction, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.

  5. In the IntervalBetweenEvents field, type a value in milliseconds.
  6. In the TimerId field, type a name for the timer.
  7. Click OK to create the instance.
To create AbsTimer

This example creates an absolute timer instruction that works with the TimerEvent consumer and AbsTimerFilter to display an event notification in the Event Viewer at a particular date and time.

  1. From the drop-down list box, choose Timers.
  2. Expand the tree to expose the subclasses.
  3. Click __AbsoluteTimerInstruction, and click the New Instance button.

    —or—

  4. Right-click on __AbsoluteTimerInstruction, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.

  5. Click the Value field of the EventDateTime row. The Time dialog box appears.

  6. In the Time dialog box, set the date, time, and time zone appropriately.
  7. Click OK.
  8. In the TimerId field of the Edit new instance properties dialog box, type AbsTimer.
  9. Click OK to create the instance.
To create IntervalTimer

This example creates an interval timer that works with the TimerEvent consumer and AbsTimerFilter to display an event notification in the Event Viewer at regular intervals.

  1. From the drop-down list box, choose Timers.
  2. Expand the tree to expose the subclasses.
  3. Click __IntervalTimerInstruction, and click the New Instance button.

    —or—

  4. Right-click on __IntervalTimerInstruction, and choose New Instance from the pop-up menu. The Edit new instance properties dialog box appears.

  5. In the IntervalBetweenEvents field, type 5000. This means that the event notification will occur every 5000 milliseconds, which is every 5 seconds.
  6. In the TimerId field, type IntervalTimer.
  7. Click OK to create the instance.

Viewing Class Properties

Creating an Event Consumer Instance

Creating an Event Filter Instance

Registering a Consumer for an Event

See Also

Timer Events

__TimerInstruction

__AbsoluteTimerInstruction

__IntervalTimerInstruction


Registering a Consumer for an Event

If you followed the previously described examples, you created permanent consumers. To register to receive an event notification, permanent consumers must create at least one of each of the following instances:

  • Event consumer instance.
  • Event filter instance.
  • Binding between the consumer and filter.

The examples create the first two of these, as well as timers that will demonstrate that functionality. This section describes the third item, which is binding particular consumers and filters together.

To display the example consumers and filters
  1. Select Consumers in the drop-down list box.
  2. Expand the whole inheritance tree.
  3. Click on one of the example consumer instances.

The Event Registration screen now looks like this:

To register the ServiceStopped consumer for an event
  1. In the left pane, click on the ServiceStopped consumer.
  2. In the right pane, click on the ServiceStoppedEvent filter.
  3. Click the Register button.

The Event Registration screen now looks like this:

Note The name of the Register button now changes to Unregister. Click it to unregister the selected consumer and filter.

To test the ServiceStopped consumer-filter binding
  1. In Control Panel, open the Services program.
  2. Find a running service that can be safely stopped.

    —or—

  3. Find an unstarted service and start it.
  4. Stop the service.

    The Event Viewer appears, notifying you of the event:

As shown in the Event Viewer, this event is an instance of __InstanceModificationEvent.

The query in the ServiceStoppedEvent filter uses no timers. The two other example filters do.

To register the TimerEvent consumer for an absolute event

Absolute events occur only once, at a particular date and time.

  1. From the drop-down list box, choose Timers.
  2. Expand the inheritance tree under __AbsoluteTimerInstruction, then click AbsTimer to open the Edit Instance Properties dialog box.
  3. Click on the Value field of the EventDateTime property to open the Time dialog box.
  4. Set the time to a minute or two in the future, and click OK.
  5. From the drop-down list box, choose Consumers.
  6. In the left pane, expand the consumer inheritance tree and click on the TimerEvent consumer.
  7. In the right pane, click on AbsTimerFilter.
  8. Click the Register button.

    When you reach the set time, the Event Viewer appears, showing the timer event generated at the set time:

To register the TimerEvent consumer for an interval event

Interval events occur at regularly occurring intervals.

  1. From the drop-down list box, choose Consumers.
  2. In the left pane, expand the consumer inheritance tree, and click on the TimerEvent consumer.
  3. In the right pane, click on IntervalTimerFilter.
  4. Click the Register button.

    The Event Viewer appears, showing the timer event generated every five seconds:

Viewing Class Properties

Creating an Event Consumer Instance

Creating an Event Filter Instance

Creating an Event Timer Instance

See Also

__FilterToConsumerBinding

Binding a Logical Consumer to an Event Filter


WBEM Event Viewer

As CIMOM generates events, the event objects are sent automatically to consumers registered for the object type. The WBEM Event Viewer displays the events for all instances of registered consumers.

With the WBEM Event Viewer, you can do the following:

  • View CIMOM-generated events and event information, such as the event's date and time, class, point of origin, and a description.
  • View event instance properties.
  • Start the WBEM Event Registration Viewer.
  • Clear the display.


WBEM Event Viewer Interface

The Event Viewer screen looks like this:

Note You must install CIMOM and create a database of classes on the target machine before you use the Event Viewer. One of the methods for creating a database of classes is to compile a MOF file in the directory where the SDK was installed (typically c:\Wbem). To compile the MOF file, type the following command: mofcomp <filename.mof>. For more information, see MOF Compiler.

The examples in the following topics use the Cimwin32.mof file provided in the SDK. This MOF file compiles into a database of Win32® schema classes that you can view in the Event Viewer.

To open the Event Registration Viewer
  1. Click Start.
  2. Point to Programs, then click WBEM SDK.
  3. Click WBEM Event Registration. The WBEM Login dialog box appears.

  4. Click OK.

The Event Viewer includes the following buttons:

Register for events button starts WBEM Event Registration Viewer.
View properties button allows you to view the property page of any event shown in the window.
Clear Viewer button clears the display.

The Event Viewer includes the following columns of event information:

Column | Event Information
P | Event priority, set for the consumer instance in the event registration control.
Time | When the consumer received the event. The time is attached by the consumer, and controlled through the event registration control.
Event Class | The standard property of the event.
Server | The server where the event occurred.
Description | A message unique for each consumer instance, set by the event registration control.

With the Event Viewer columns, you can:

  • Reorder the columns by selecting and dragging a column over another column.
  • Adjust the column size.
  • Sort information according to the column heading by clicking the heading.


WBEM User Manager

The WBEM User Manager allows you to create authorized WBEM users, and to set their access privileges. Use this application to manage user authentication and access to CIM objects for WBEM. (On Windows NT systems, use the WBEM Administrator tool to control access to WBEM installation directories and the registry.)

The following topics describe how to use the WBEM User Manager:

Managing WBEM Security on Windows NT

Adding Users

Editing Users

Deleting Users

Adding Groups

Editing Groups

Deleting Groups


Managing WBEM Security on Windows NT

The WBEM User Manager can be used in conjunction with the Windows NT User Manager to create user accounts and groups that provide the following security:

  • User authentication for both local and remote logins
  • Permissions for both local and remote access to CIM objects

Windows NT systems include two built-in groups that can be used to manage WBEM security:

  • The local NT Administrators group

    All users who belong to this group have full local and remote access to the CIM Object Manager (CIMOM). Full access means read/write/delete access to all CIM objects in all namespaces (including ROOT\SECURITY). Users with access to ROOT\SECURITY can change security information.

  • A local WBEM Users group

    This group is created immediately after installing WBEM, when CIMOM starts. By default, this group contains no members and provides read-only access to all namespaces except ROOT\SECURITY.

You can manage most access to CIMOM by controlling the membership of these two groups using the Windows NT User Manager.

You can use the WBEM User Manager to create groups with combinations of permissions different from those provided by the built-in groups. You can also create individual users, if needed.


Adding Users

To add a user
  1. Click the Add User button.

    —or—

    Select Add New User from the User menu. The User Properties dialog box appears:

  2. Type the User Name and the Domain name where the user's account resides. User names must be unique and cannot be shared with group names. If you do not specify a domain name, the current domain is the default name.
  3. Under Attributes, select all applicable access privileges for the user:

    Enabled

    Accounts are enabled by default. When this option is not selected, the account is disabled. A login is not permitted against a disabled account.

    Execute Methods

    Allows the user to execute object methods exported from the CIM Object Manager.

    Schema Access Level

    Select one of the following access levels:

    Read Only

    Allows read-only access to CIM schema objects. Users with this privilege can execute queries or retrieve instances and classes, but cannot create, delete, or modify CIM objects.

    Write Instance

    Allows full read/write/delete access to instances. Users with this privilege have read-only access to classes.

    Write Class

    Allows full read/write/delete access to all CIM objects, classes, and instances.

  4. Under Security, select Edit Security if you want to give the user read/write access to the ROOT\SECURITY namespace. Users with this privilege can edit security information. Users without this privilege have no access to ROOT\SECURITY.
  5. Click OK. This returns you to the WBEM User Manager window. The new user appears in the list of users in the top portion of the window.
  6. Select Save changes from the User menu to save the changes and remain in the WBEM User Manager.

    —or—

    Select Exit with changes from the User menu to save the changes and close the WBEM User Manager.

    To close the WBEM User Manager without saving the changes, select Exit without changes from the User menu.


Editing Users

To edit a user's properties
  1. Double-click the user you want to edit.

    —or—

    Select the user you want to edit, then choose Edit User Properties from the User menu.

  2. In the User Properties dialog box, make the desired changes. You can edit all properties except the user name.
  3. Click OK to return to the WBEM User Manager window.
  4. Select Save changes from the User menu to save the changes and remain in the WBEM User Manager.

    —or—

    Select Exit with changes from the User menu to save the changes and close the WBEM User Manager.

    To close the WBEM User Manager without saving the changes, select Exit without changes from the User menu.


Deleting Users

To delete a user
  1. Select the user you want to delete.
  2. Click the Delete User button or select Delete User from the User menu.
  3. Select Save changes from the User menu to save the changes and remain in the WBEM User Manager.

    —or—

    Select Exit with changes from the User menu to save the changes and close the WBEM User Manager.

    To close the WBEM User Manager without saving the changes, select Exit without changes from the User menu.


Adding Groups

On Windows NT systems, WBEM users can be combined into groups. Groups have access privileges that are granted to all users who are members of the group. For example, if a user has read-only permissions, and belongs to a group with read-write permissions, then the user has read-write permissions.

Note Groups can only be created on Windows NT systems.

To add a group
  1. Click the Add Group button or select Add New Group from the User menu. The Group Properties dialog box appears:

  2. In the Group Properties dialog box, type the Group Name. Group names must be unique and cannot be shared with user names.
  3. Under Attributes, select the access privileges for the group. See Adding Users for a description of these privileges.
  4. Under Security, select Edit Security if you want to give the group read/write access to the ROOT\SECURITY namespace. Groups with this privilege can edit security information. Groups without this privilege have no access to ROOT\SECURITY.
  5. Select one of the following group types:

    NTLM Local

    Creates a local NT group (a group that can be used only in its own workstation or domain).

    NTLM Global

    Create a domain global group (a group that can be used in its own domain, member servers and workstations of the domain, and trusting domains). You must also specify the domain name.

  6. Click OK to return to the WBEM User Manager window.
  7. Select Save changes from the User menu to save the changes and remain in the WBEM User Manager.

    —or—

    Select Exit with changes from the User menu to save the changes and close the WBEM User Manager.

    To close the WBEM User Manager without saving the changes, select Exit without changes from the User menu.

You can add members to the newly-created group by using the Windows NT User Manager.


Editing Groups

To edit a group's properties
  1. Double-click the group you want to edit.

    —or—

    Select the group you want to edit, then choose Edit Group Properties from the User menu.

  2. In the Group Properties dialog box, make the desired changes. You can edit all properties except the group name.
  3. Click OK to return to the WBEM User Manager.
  4. Select Save changes from the User menu to save the changes and remain in the WBEM User Manager.

    —or—

    Select Exit with changes from the User menu to save the changes and close the WBEM User Manager.

    To close the WBEM User Manager without saving the changes, select Exit without changes from the User menu.


Deleting Groups

To delete a group
  1. Select the group you want to delete.
  2. Click the Delete Group button or select Delete Group from the User menu.
  3. Select Save changes from the User menu to save the changes and remain in the WBEM User Manager.

    —or—

    Select Exit with changes from the User menu to save the changes and close the WBEM User Manager.

    To close the WBEM User Manager without saving the changes, select Exit without changes from the User menu.


WBEM Administrator

The WBEM Administrator allows you to:

  • Configure CIMOM backup and logging
  • Set security for the WBEM installation directories and the registry (Windows NT only)

To open the WBEM Administrator, select the WBEM icon in Control Panel.


CIMOM Backup and Logging

Use the CIMOM Backup and Logging tab to set CIMOM repository backup intervals, and to enable and configure logging. An example of this tab is shown below:


Repository Backups

To set CIMOM repository backup intervals
  1. In the Idle time before attempting repository backup field, enter the amount of time (in minutes) that you want CIMOM to wait between accesses to the repository before considering doing a backup. If this check fails (that is, if the repository is constantly being accessed), no backup occurs.
  2. In the Maximum backup interval (minutes) field, enter the amount of time between repository backups. This setting is checked only if the idle time check succeeds.
  3. Click Apply to save changed information and remain in the WBEM Administrator.

    —or—

    Click OK to save changed information and close the WBEM Administrator.

Changes to backup settings take effect immediately.


Logging

To configure logging
  1. Select one of the following options:

    Disable logging - turns off logging.

    Error logging - sends only error messages to the log files.

    Verbose logging - sends general tracing messages as well as error messages to the log files.

  2. In the Maximum log file size (bytes) field, enter the maximum size of the log files.
  3. In the Logging directory field, enter the directory where the log files reside. The default is the \Logs subdirectory of the WBEM installation directory.
  4. Click Apply to save changed information and remain in the WBEM Administrator.

    —or—

    Click OK to save changed information and close the WBEM Administrator.

Changes to the logging settings take effect within one minute of the change.


WBEM Security for Windows NT

On Windows NT systems, use the WBEM Security for Windows NT tab to set security for the WBEM installation directories and the registry.

The WBEM Security for Windows NT tab shows the directory where WBEM is installed and the file system used on the drive where WBEM is installed. This tab also lists the currently defined users, the group to which they belong, and their permissions to access WBEM files and the registry. For example:

Note Directories must reside on an NTFS drive in order to be secured. Installations with file allocation table (FAT) file systems cannot be secured.

The following topics describe how to set security for Windows NT:

Adding Users or Groups

Changing Permissions for Users or Groups

Removing Users or Groups


Adding Users or Groups

To add a user or group
  1. Click the Add button. The WBEM User File and Registry Permissions dialog box appears:

  2. Under Target User or Group, type the Name of user or group you want to add.
  3. Select one of the WBEM File and Registry Permissions options:

    Use

    Allows the user/group read and execute access to all WBEM components.

    Modify

    Allows the user/group full access (read/write/execute) to all files, directories, and the registry.

    No Access

    Denies the user/group access to all WBEM components.

  4. Select the Submit Self-Installing MOFs option if you want the user/group to have this privilege.
  5. Click OK to return to the WBEM Security for Windows NT dialog box.
  6. Click Apply to save the new data and remain in the WBEM Administrator.

    —or—

    Click OK to save the new data and close the WBEM Administrator.


Changing Permissions for Users or Groups

To change permissions for a user or group
  1. Double-click the user/group you want to change.

    —or—

    Select the user/group you want to change, then click the Edit button.

    The WBEM User File and Registry Permissions dialog box appears.

  2. Make the desired changes to the WBEM File and Registry Permissions, then click OK to return to the WBEM Security for Windows NT dialog box.
  3. Click Apply to save the new data and remain in the WBEM Administrator.

    —or—

    Click OK to save the new data and close the WBEM Administrator.


Removing Users or Groups

To remove a user/group
  1. Select the user/group you want to remove.
  2. Click the Remove button.
  3. Click Apply to save the new data and remain in the WBEM Administrator.

    —or—

    Click OK to save the new data and close the WBEM Administrator.


Providers and Drivers

The Web-Based Enterprise Management (WBEM) SDK contains several built-in object providers and application drivers. The built-in object providers enable management applications to access data and event notifications from a variety of sources such as the system registry and an SNMP device. The drivers enable applications written with various programming interfaces to access the CIMOM repository without having to be rewritten.

The Providers and Drivers section of the WBEM SDK documentation contains:

  • SDK Providers, a description of the providers that ship with the WBEM SDK.
  • WBEM ODBC Driver, a description of the technology that allows ODBC applications to access database information through WBEM.
  • DMI Support, an object provider that supplies information to applications from Desktop Management Interface (DMI) objects.
  • SNMP Support, an object provider that supplies information to applications from Simple Network Management Protocol (SNMP) devices.


SDK Providers

Web-Based Enterprise Management (WBEM) defines two types of providers:

  • Application-specific providers, also known as custom providers
  • Built-in providers

Application-specific providers are developed by third-party vendors to communicate information from objects in their domain to the CIM Object Manager (CIMOM).

Built-in providers are developed by WBEM and are included with the WBEM SDK. These providers supply CIMOM with information from various logical and physical sources such as the system registry, the Microsoft® Win32® subsystem, and Simple Network Management Protocol (SNMP) devices. There are two varieties of built-in providers: those that provide data and those that provide events.

The built-in providers are briefly described in the following table:

Provider | Description
PerfMon Provider | Provides access to data from the Windows NT® PerfMon application.
Registry Event Provider | Sends an event whenever a change occurs to a key, a value, or an entire tree in the system registry.
Registry Provider | Provides access to data from the system registry.
SNMP Provider | Provides access to data and events from SNMP devices.
Windows NT Event Log Provider | Provides access to data and notifications of events from the Windows NT Event Log.
Win32 Provider | Provides access to data from the Win32 subsystem.
WMI Provider | Provides access to data and events from device drivers that conform to the Windows Management Instrumentation (WMI) interface.

To use one of the built-in WBEM providers, compile the appropriate Managed Object Format (MOF) file that installs the provider.

None of the built-in providers that serve as instance providers perform query processing; they let CIMOM handle it.


PerfMon Provider

The PerfMon Provider returns performance-related information to management applications. Because PerfMon is a Microsoft® Windows NT®. tool, only management applications running on Windows NT platforms can use this provider.

The PerfMon Provider can be used as an instance provider to supply performance information relating to instances of WBEM classes; it can also function as a property provider to modify the data for a specific instance.

Because the PerfMon Provider is not automatically registered with CIMOM when WBEM installs, management applications wanting to use it must complete the registration process. To register the PerfMon Provider as either an instance provider or as a property provider, applications create a new MOF file that includes an instance of the __Win32Provider system class as the following code fragment demonstrates:

instance of __Win32Provider as $P
{
    Name    = "PerfProv" ;
    ClsId   = "{f00b4404-f8f1-11ce-a5b6-00aa00680c3f}" ;
};

An instance of a class derived from __ObjectProviderRegistration must also be created. If the PerfMon Provider is being registered as an instance provider, the application must create an __InstanceProviderRegistration instance. If the PerfMon Provider is being registered as a property provider, the application must create a __PropertyProviderRegistration instance. Examples of these two instances follow:

instance of __InstanceProviderRegistration
{
    Provider = $P;
    SupportsPut = FALSE;
    SupportsGet = TRUE;
    SupportsDelete = FALSE;
    SupportsEnumeration = TRUE;
};

instance of __PropertyProviderRegistration
{
    Provider = $P;
    SupportsPut = TRUE;
    SupportsGet = TRUE;

The MOF file containing these two instances can either be compiled as a standalone file or included at the top of an application-specific MOF file. The application-specific MOF file typically contains classes and instances that are meant to store the performance data. The following class provides an example. The Provider qualifier specifies the PerfMon Provider as the dynamic provider responsible for managing the data for the class. The ClassContext qualifier specifies information needed by the PerfMon Provider to access the data. The PropertyContext qualifiers identify the PerfMon values to be stored in each property.

[dynamic, provider("PerfProv"), ClassContext("local|Process")]
class NTProcesses
{
    [key]
       String Process;
    [PropertyContext("ID Process")]
         uint32 ID;
    [PropertyContext("Elapsed Time")]
         real32 Time;
    [PropertyContext("Handle Count")]
         uint32 Handles;
    [PropertyContext("Working Set")]
         uint32 WorkingSet;
    [PropertyContext("Working Set Peak")]
         uint32 WorkingSetPeak;
    [PropertyContext("Virtual Bytes")]
         uint32 VirtualBytes;
    [PropertyContext("Virtual Bytes Peak")]
         uint32 VirtualBytesPeak;
    [PropertyContext("Thread Count")]
         uint32 Threads;
    [PropertyContext("Priority Base")]
         uint32 Base;
};

Some of the counter types available from the PerfMon Provider cannot be returned as instances. To use these counters in an application, create a singleton class by attaching the Singleton standard qualifier to the class as is shown below. Note the lack of a key property.

[Singleton, Dynamic, Provider("PerfProv"),
ClassContext("local|Memory")]
class memory
{
    [PropertyContext("Available Bytes")]
         uint32 Avail;
    [PropertyContext("Cache Bytes")]
         uint32 Cache;
};


Windows NT Event Log Provider

The Windows NT Event Log Provider functions as both an instance provider and an event provider. As an instance provider, the Event Log Provider returns data that describes events that have been logged to the Windows NT Event Log service and stored as formatted records in a log file. Typically, three log files reside on every machine: application, system, and security; Windows NT 5.0 has a fourth for directory events. The format for events is defined in the Win32 EVENTLOGRECORD data structure. The Event Log Provider maps each field in the EVENTLOGRECORD to a property in an instance of the Win32_NTLogEvent class. The Event Log Provider supports the Win32_NTLogEvent class for describing Windows NT events.

Windows NT events are written to a log file in the order in which they are received. Because log files are restricted to a particular size and events are frequently sent, the Event Log service must adopt a strategy for maintaining the size. Log files can either refuse to accept new events, remove events that are older than a specified age, or replace old events with new events as necessary. A log file can also be cleared or archived. The Event Log Provider also supports a class named Win32_NTLogFile which represents the Windows NT log. This class allows the overwrite policy and max file size to be set. Also allows the clear and archive operations to be performed.

he Event Log instance Provider exposes an implementation of the IWbemProviderInit interface for initialization and implementations of the following methods of the IWbemServices interface:

  • GetObjectAsync
  • ExecMethodAsync
  • ExecQueryAsync
  • CreateInstanceEnumAsync
  • PutInstanceAsync
  • EnumInstanceAsync

Clients of the Event Log Provider can call either the asychronous or synchronous version of these methods. However, because all WBEM providers only implement the asynchronous IWbemServices methods, it is up to CIMOM to pass all client requests asynchronously.

As an event provider, the Event Log Provider registers with the NT Event Log service to receive notifications of new NT events. For each notification that it receives, the Event Log Provider generates a corresponding WBEM event by creating an instance of the __InstanceCreationEvent class. The Event Log Provider embeds an instance of Win32_NTLogEvent class as the TargetInstance property with the data taken from the logged event. CIMOM sends the instance creation event to all consumers that have registered to receive events of type __InstanceCreationEvent with an embedded Win32_NTLogEvent.

The Win32_EventlogFile and Win32_NTLogEvent classes and related association classes are included as part of the Win32 schema. The Event Log Provider is supported only in the \Root\Cimv2 namespace.

The Event Log Provider consists of a COM server implemented as a dynamic link library (DLL) and a MOF file. The DLL is loaded by CIMOM when it is needed to handle a client request. The MOF file contains definitions of the classes that the Event Log Provider supports as an instance provider, an event provider, and for registration. However, because the Event Log Provider is automatically registered when the WBEM SDK is installed, registration by a client is unnecessary.


Log File Registry Entries

The Windows NT Event Log service maintains a section in the Windows NT registry for each log file that it creates. The log file section contains four values and appears under the following hierarchy of keys:

HKEY_LOCAL_MACHINE
  SYSTEM
    CurrentControlSet
      Services
        Eventlog
          <name of logfile>

The four values are described in the following table:

Value | Type | Description
File | REG_SZ_EXPAND | Path to the log file. This value can include environment variables.
MaxSize | REG_DWORD | Log file's maximum size in bytes. This value must be between 64 KB and 419,240 KB and can only be incremented in 64 KB chunks.
Retention | REG_DWORD | Overwrite policy of the log file.
Sources | REG_MULTI_SZ | List of event sources registered for the log file.

The Retention value can be set to:

  • 0, indicating that any entry can be overwritten when necessary.
  • 1-365, indicating that events that have been in the log file for one year or less can be overwritten.
  • 4294967295, indicating that nothing can be overwritten.

If the log file becomes full and no events are old enough to be overwritten, the log file must be cleared manually; otherwise, new events are discarded until an event becomes old enough to be overwritten.


Win32_NTEventlogFile Class

The Event Log instance Provider defines the Win32_NTEventlogFile class to access the data stored in a Windows NT log file. The Win32_NTEventlogFile class derives from the CIM_DataFile class, which is part of the class hierarchy that ultimately inherits from CIM_ManagedSystemElement. Win32_NTEventlogFile inherits properties from the following superclasses:

  • CIM_ManagedSystemElement
  • CIM_LogicalFile

The following table describes the properties that are defined directly in the Win32_NTEventlogFile class:

Property | Description
LogfileName | Name of the log file. Standard log file names are application, system, and security.
MaxFileSize | Read/write value retrieved from the Windows NT Event Log service's MaxSize value in the registry.
NumberOfRecords | Determined by calling the Win32 function GetNumberOfEventLogRecords.

Clients of the Event Log Provider can change the value for the MaxFileSize property. If MaxFileSize is decreased, the change does not take effect until the log file is cleared.

Two other properties, OverWritePolicy and OverwriteOutDated, are based on the Windows NT Event Log service's Retention value in the registry. OverwriteOutDated is set to the same value as Retention and provides the number of days after which an event can be overwritten. Valid values for this property are:

  • 0, indicating that any entry can be overwritten when necessary.
  • 1-365, indicating that events that have been in the log file for one year or less can be overwritten.
  • 4294967295, indicating that nothing can be overwritten.

To change the overwrite policy being used for the log file, change the OverwriteOutDated property. When IWbemServices::PutInstance or IWbemServices::PutInstanceAsync is called to store the Win32_NTEventlogFile instance, the registry is updated. PutInstance or PutInstanceAsync fails if an attempt is made to set OverwriteOutDated to a value between 365 and 4294967295.

OverWritePolicy is a read-only property that identifies the current overwrite policy employed by the Windows NT Event Log service for this log file. Its value is based on the value of the OverwriteOutDated property and is set as follows:

OverwriteOutDated value | OverWritePolicy value
0 | WhenNeeded
1 - 365 | OutDated
4294967295 | Never

For more information about overwrite policy values, see Log File Registry Entries.

In addition to properties, the Win32_NTEventlogFile class includes two methods: BackupEventlog and ClearEventlog. These methods implement the corresponding Win32 functions and take one input parameter, the name of the archive file to be created. For BackupEventlog, this parameter must not be NULL or the name of a file that already exists. ClearEventlog accepts a NULL parameter if the caller does not require the log file to be archived before it is cleared. If the parameter is non-NULL, the file must not already exist. Both methods return 0 if they are successful; if unsuccessful, they return an error code obtained from the Win32 GetLastError function.


Properties Inherited from CIM_ManagedSystemElement

The Win32_NTEventlogFile class inherits several properties from its abstract base class: CIM_ManagedSystemElement. The following table lists these properties and describes the inherited values:

Property | Description
Name | Full path of the log file retrieved from the Windows NT Event Log service's File value in the registry.
Description | Same value as the Name property.
InstallDate | Same value as the CreationDate property.
Caption | Last 64 characters of the Name property. If Name has less than 64 characters, Caption has the same value as Name.
Status | Value indicating whether or not the log file can be opened. Valid values are: OK if the file can be opened, Unknown if the file cannot be opened due to a sharing violation, Error if the file cannot be opened for any other reason.


Properties Inherited from CIM_LogicalFile

The Win32_NTEventlogFile class inherits several properties from its parent class: CIM_LogicalFile. The following table lists these properties and describes the inherited values:

Property | Description
Readable | Always TRUE.
Encrypted | Always FALSE.
Open | Determined by calling the Win32 function CreateFile with exclusive access. If the call succeeds, Open is FALSE. If the call fails with a sharing violation, Open is TRUE. If the call fails for another reason, Open is NULL.
LastArchivedDate | Always NULL.
CSCreationClassName | Always Win32_ComputerSystem.
CreationClassName | Always Win32_NTEventlogFile.
FSCreationClassName | Always Win32_FileSystem.
CSName | Determined by calling the Win32 function GetComputerName. If the call fails, CSName is NULL.
FSName | Determined by calling the Win32 function GetVolumeInformation. If the call fails, FSName is NULL.
FileType | Determined by looking up the extension without the preceding period ('.') in the list of known file types in the registry. If the extension is not found, FileType contains the characters "File" appended to the extension in upper case. If there is no extension, FileType is NULL.

The following properties are determined by calling the C run-time function _wfindfirsti64 and querying the _wfinddatei64_t structure that is returned if the call succeeds. If the call fails, the property is set to NULL.:

  • Size
  • Writeable
  • Archive
  • CreationDate
  • LastModifiedDate
  • LastAccessDate
  • Compressed

The Extension and Path properties are determined by parsing the value of the Name property from the end of the string to the beginning. For the Extension property, the parsing process looks for a period ('.'). If a backward slash ('\') is encountered first or a period is not found, Extension is NULL. If a period is found, Extension contains a string consisting of the characters parsed, including the period. For example, if Name is "C:\file.evt", Extension is set to ".evt".

For the Path property, the parsing process looks for a backward slash ('\'). If a backward slash is not found, Path is NULL. If a backward slash is found, Path contains the backward slash appended to a string consisting of the characters that have yet to be parsed. For example, if Name is "C:\file.evt", Path is "C:\".


Win32_NTLogEvent Class

The Event Log Provider defines the Win32_NTEventlogFile class to access the data stored in a Windows NT log file.

The Event Log event Provider defines the Win32_NTLogEvent class to represent a Windows NT event in WBEM.

The Win32_NTLogEvent class is defined as follows:

class Win32_NTLogEvent
{
    uint32            RecordNumber;
    string            Logfile;
    uint32            EventIdentifier;
    string            SourceName;
    string            Type;
    uint16            Category;
    datetime        TimeGenerated;
    datetime        TimeWritten;
    datetime        TimeTranslated;
    string            ComputerName;
    string            User;
    string            Message;
    string            InsertionStrings[];
    uint8            Data[];
}

The following table describes each property:

Property | Description
RecordNumber | Used with the Logfile property to uniquely identify an event in the Windows NT event log and a Win32_NTLogEvent instance.
Logfile | Used with the RecordNumber property to uniquely identify an event within the Windows NT event log and a Win32_NTLogEvent instance.
EventIdentifier | Used with the SourceName property to uniquely identify a Windows NT event type.
SourceName | Variable-length null-terminated string specifying the component responsible for generating the Windows NT event. Used with the SourceName property to uniquely identify a Windows NT event type.
Type | Specifies the event type. Valid values are error, warning, information, audit success, and audit failure.
Category | Specifies a subcategory specific to the event source.
TimeGenerated | Specifies the time at which the source generated the event.
TimeWritten | Specifies the time at which the event was written to the event log.
TimeTranslated | Specifies the time at which this instance of the Win32_NTLogEvent class.
ComputerName | Variable-length null-terminated string specifying the name of the computer that generated this event.
User | Name of the user that was logged on when the event occurred or NULL if the user cannot be determined.
Message | Event message as it appears in the event log. This message consists of a standard message plus zero or more insertion strings supplied by the event source.
InsertionStrings | One or more strings that accompany the report of the event.
Data | Binary data that accompanies the report of the event.


Event Log Association Classes

There are three association classes that a client of the Event Log Provider typically uses. All three classes link an instance of the Win32_NTLogEvent class with an instance of another class.

The Win32_NTLogEventLog association class links instances of the Win32_NTLogEvent and Win32_NTEventlogFile classes. It is defined as follows:

class Win32_NTLogEventLog
{
    [key, read]  Win32_NTEventlogFile ref Log;
    [key, read]  Win32_NTLogEvent     ref Record;
}

The Win32_NTLogEventUser association class links instances of the Win32_NTLogEvent and Win32_UserAccount, a class defined in the Win32 schema. Win32_NTLogEventUser is defined as follows:

class Win32_NTLogEventUser
{
    [key, read]  Win32_NTUserAccount  ref User;
    [key, read]  Win32_NTLogEvent     ref Record;
}

The Win32_NTLogEventComputer association class links instances of the Win32_NTLogEvent and Win32_ComputerSystem, another class defined in the Win32 schema. Win32_NTLogEventComputer is defined as follows:

class Win32_NTLogEventComputer
{
    [key, read]  Win32_ComputerSystem  ref Computer;
    [key, read]  Win32_NTLogEvent      ref Record;
}


TroubleShooting the Event Log Provider

The following table presents some common problems that can occur in using the Event Log Provider and offers possible causes and solutions:

Problem | Cause and/or Solution
Classes supported by the Event Log Provider do not appear in a namespace. | Only the Root\Cimv2 namespace is supported; check that you are connected to the Root\Cimv2 namespace.
Classes supported by the Event Log Provider do not appear in the Root\Cimv2 namespace. | Use the MOF compiler to compile the MOF file that contains the missing classes. The target file is Ntevt.mof; this file can be found in the WBEM installation directory.
No instances are returned after enumerating instances of any class. | Windows NT event logs are empty.
No instances are returned after enumerating instances of the Win32_NTLogEventUser class. | Not all Windows NT event log records contain user information. Typically only security event log records contain user information.
Enumerating instances takes a long time. | Reasonable behavior if any of your event log files are large because the instance provider is enumerating all of the event logs and passing the results using COM.

When there is a total of 2000 or more events in the event logs, it is possible to observe a decline in the performance of the Event Log Provider. Under those conditions, viewing events with the standard Windows NT user interface can be faster.

To compile the Ntevt.mof file at the command prompt, type:

C:\> c:\winnt\system32\wbem\mofcomp c:\winnt\system32\wbem\ntevt.mof


Registry Provider

The Registry Provider enables management applications to retrieve and modify data in the system registry and to receive notifications when changes occur. The registry can either reside on the local machine or can be accessed remotely.

The Registry Provider can be registered as an instance provider, a property provider, or an event provider. As an instance provider, the Registry Provider supplies instances of classes representing registry keys. As a property provider, it retrieves and updates individual values for a particular key. As an event provider, it monitors changes to values, keys, and key hierarchies, and sends notifications when changes occur.

For example, the Registry Provider can provide access to data that is specific to Microsoft® Windows NT® machines and is located under the registry key HKEY_LOCAL_MACHINE\Hardware\ResourceMap. Applications retrieving this data create a class


Defining Classes for the Registry Provider

Management applications using the Registry Provider define classes with properties that represent registry data for particular keys and store the classes in the CIMOM repository. The classes are defined with several standard qualifiers. The particular qualifiers and their placement depends on whether the Registry Provider is used as an instance provider or a property provider.

The Dynamic qualifier can be attached to either a class or an instance and marks the class or instance as being managed dynamically by a provider. When Dynamic appears on a class or instance, the Provider qualifier must also appear. The Provider qualifier identifies the particular provider that is responsible for managing the dynamic class or instance.

The ClassContext qualifier is attached to a class and specifies the path to the registry key that contains the information the class represents. The ClassContext qualifier has the following format:

MACHINE_NAME | Subtree\\KeyPath

The value for KeyPath can be long if it includes keys with subkeys. For example, the following ClassContext qualifier contains the path to a particular machine's transport devices:

Machine_Name | HKEY_LOCAL_MACHINE\\SOFTWARE\\MICROSOFT\\WBEM
\\CIMOM\\TRANSPORTS

The following template for a class definition illustrates the use of the Dynamic, Provider, and ClassContext qualifiers. The provider named by the Provider qualifier is the instance Registry Provider. Note that registry paths are case insensitive, as are qualifier names.

[dynamic, provider("RegProv"), ClassContext("localhkey_local_machine\\software\\microsoft\\WBEM\\
cimom\\transports")]

class RegistryTransports
{
  //properties of the class
};

Management applications can use the Registry Provider to retrieve and modify registry data for a particular key. To use the Registry Provider as a property provider, applications define classes that are marked with the DynProps, Provider, and PropertyText standard qualifiers.

The DynProps qualifier identifies a class as having properties that are maintained by the property provider identified by the Provider qualifier. The PropertyContext qualifier specifies the name of the registry value to be stored by the property. The format of the PropertyContext qualifier is the same as the format of the ClassContext qualifier with additional valuename and expression values:

MACHINE_NAME | Subtree\\KeyPath [|valuename [expression]]

Both valuename and expression are optional. The valuename setting is only used if the registry value has a name. Expression is also optional and is used for resource descriptor data.

The following class uses the Registry Provider as a property provider to maintain its non-key properties:

[DYNPROPS]
class PropReg {

    [read, write, KEY]
         STRING  MyKey;
    [read, write]
         STRING Logging;
    [read, write]
         STRING Events;
         uint32 Resource1;
         uint32 Resource2;
};

[DYNPROPS]
instance of PropReg
{
  MyKey = "a";

  [PropertyContext("local|hkey_local_Machine\\software\\microsoft\\
   wbem\\cimom|Logging"), Dynamic, Provider("RegPropProv")]  Logging;

  [PropertyContext("local|hkey_local_Machine\\software\\microsoft\\
   wbem\\cimom|EnableEvents"), Dynamic, Provider("RegPropProv")]
   Events;

  [PropertyContext("local|hkey_local_Machine\\hardware\\
   ResourceMap\\Hardware Abstraction Layer\\PC Compatible Eisa/isa
   hal|.raw(\"Internal\")(0)(0)(\"interrupt.vector\")"), Dynamic,
   Provider("RegPropProv")]  Resource1;

  [PropertyContext("local|hkey_local_Machine\\hardware\\
   ResourceMap\\Hardware Abstraction Layer\\PC Compatible Eisa/isa
   hal|.raw(\"Internal\",0,0,\"interrupt.vector\")"), Dynamic,
   Provider("RegPropProv")]
   Resource2;
};


Registering the Registry Provider

Because the Registry Provider is not automatically registered with CIMOM as part of the WBEM installation process, applications wanting to use it must complete the registration. An application registers the Registry Provider by creating a MOF file with instances of registration classes and either compiling it as a stand-alone file or including it at the top of an application-specific MOF file. The application-specific MOF file contains the classes and instances used to access the registry data.

The newly-created MOF file contains an instance of the __Win32Provider class and one of the following instances, depending on whether the application intends to use the Registry Provider as an instance, property, or event provider:

  • __InstanceProviderRegistration
  • __PropertyProviderRegistration
  • __EventProviderRegistration

The __Win32Provider instance describes the name of the provider and its class identifier (CLSID). The following instances are used to register the Registry Provider as an instance provider or a property provider:

// Instance provider
instance of __Win32Provider as $P
{
    Name    = "RegProv" ;
    ClsId   = "{fe9af5c0-d3b6-11ce-a5b6-00aa00680c3f}" ;
};

//Property provider
instance of __Win32Provider as $P
{
    Name = "RegPropProv";
    Clsid = "{72967901-68EC-11d0-B729-00AA0062CBB7}";
};

The __InstanceProviderRegistration and __PropertyProviderRegistration instances describe the operations that the provider supports:

//Instance provider
instance of __InstanceProviderRegistration
{
    Provider = $P;
    SupportsPut = TRUE;
    SupportsGet = TRUE;
    SupportsDelete = FALSE;
    SupportsEnumeration = TRUE;
};

// Property provider
instance of __PropertyProviderRegistration
{
    Provider = $P;
    SupportsGet = TRUE;
    SupportsPut = TRUE;
};

For information on registering the Registry Provider as an event provider, see Registering for Registry Events.


Registering for Registry Events

To receive notifications from the Registry Provider, a management application must:

  1. Register the Registry Provider as an event provider.
  2. Register as a temporary event consumer.

Registering the Registry Provider as an event provider involves compiling the Regevent.mof file that is included with the WBEM SDK. Regevent.mof contains an instance of the __Win32Provider class to identify the Registry Provider by name and CLSID, and an instance of the __EventProviderRegistration class to publish queries that describe the types of event notifications that are supported. Each type of event notification is represented by a different class. The Registry Event Provider supports three classes of events:

  • RegistryKeyChangeEvent
  • RegistryTreeChangeEvent
  • RegistryValueChangeEvent

All three of these classes have a property called Hive that identifies the hierarchy of keys to be monitored for change, such as HKEY_LOCAL_MACHINE, and a path to the key or tree of keys to be monitored. RegistryValueChangeEvent also has a ValueName property to hold the changed key value.

The Regevent.mof file contains the following instances to register the Registry Provider as an event provider:

instance of __Win32Provider as $P
{
    Name = "RegistryEventProvider";
    Clsid = "{fa77a74e-e109-11d0-ad6e-00c04fd8fdff}";
};

instance of __EventProviderRegistration
{
    Provider = $P;
    EventQueryList = {
            "select * from RegistryKeyChangeEvent",
            "select * from RegistryValueChangeEvent",
            "select * from RegistryTreeChangeEvent"};
};

Registering as a temporary event consumer involves:

  • Implementing the IWbemObjectSink interface.
  • Calling the IWbemServices::ExecNotificationQueryAsync method.

IWbemObjectSink contains two methods: Indicate and SetStatus. Indicate is the method that the Registry Event Provider calls to deliver its notifications. SetStatus is the method that is called to report the completion of a delivery.

When a consumer is ready to receive registry event notifications, it calls ExecNotificationQueryAsync and passes a pointer to the IWbemObjectSink implementation in the pResponseHandler parameter. The bstrQuery parameter describes which registry events are to be delivered. For each class of event, a WHERE clause needs to be included in the query that names values for each property in the class. For example, the following query registers to receive RegistryTreeChangeEvents for "HKEY_LOCAL_MACHINE\Software":

select * from RegistryTreeChangeEvent
    where Hive = "HKEY_LOCAL_MACHINE" and Rootpath = "Software";

When using the AND and OR operators, make sure that a list of possible values for every event property can be inferred from the query. For example, the following query is valid:

select * from RegistryTreeChangeEvent
    where (hive = "hkey_local_machine" and rootpath = "software")
    or    (hive = "hkey_current_user" and rootpath = "console");

However, this next query is not valid because there is no way for CIMOM to evaluate the possible values for each of the properties:

select * from RegistryTreeChangeEvent
    where hive = hkey_local_machine" OR rootpath="software";

If the WHERE clause is missing or is too broad to be of use, the Registry Event Provider returns the error WBEM_E_TOO_BROAD.

Note The WITHIN clause must be included in queries to be used on Windows 95 and Windows 98 platforms. This clause is unnecessary on Windows NT platforms. For information about the WITHIN clause, see SELECT Statement WITHIN Clause.


Mapping Registry Types to CIMOM Types

Because the registry has its own set of data types, it is important to use a CIMOM data type that accurately reflects the registry data when making requests of the Registry Provider. . The following table lists the mapping between registry and CIMOM data types:

Registry data type | CIMOM data type
REG_BINARY | BYTE array
REG_DWORD | Uint32
REG_SZ, REG_EXPAND_SZ | String
REG_MULTI_SZ | String array
REG_RESOURCE_LIST | As appropriate (see Resource Descriptor Data)


Accessing Unnamed Registry Values

The default, or unnamed, value of a registry key is shown as "(Default)" or "<No Name>" in the registry editors (Regedit and RegEdt32). To retrieve this unnamed value, define a property and set its PropertyContext qualifier to an empty string. For example, the following class defines properties to hold values for the key specified by the ClassContext qualifier. The default value is stored in the Default property:

[dynamic, provider("RegProv"), ClassContext("localhkey_local_machine\\software\\microsoft\\WBEM\\
cimom\\transports")]

class RegTrans
{
  [key]                         String TransportsDeviceName="";
  [PropertyContext("")]         String Default;
  [PropertyContext("Name")]     String Name;
  [PropertyContext("Enabled")]  String Enabled;
};

The Transports key does not use the unnamed value, so compilation of this MOF file does not produce any value for the Default property unless you use a registry editing tool to change the unnamed value.

To get a description of bitmap files, which is an unnamed value, you need to set the PropertyContext qualifier as follows:

Local|hkey_classes_root\\.bmp


Win32 Provider

The Win32 Provider retrieves and updates data using the Win32 API, enabling management applications to access this data through WBEM. The Win32 provider retrieves its information by making Win32 function calls and querying the system registry.

Because the Win32 Provider is registered automatically as part of the WBEM installation process, applications need not register it independently. All of the classes and instances defined in the Win32 schema are available through the CIMOM repository.


WMI Provider

Windows Management Instrumentation (WMI) is a set of extensions to the Windows Driver Model (WDM) that provides an operating system interface through which components can provide information and notification. The WMI Provider is modeled as a Push provider. All of its data is maintained by CIMOM in the CIMOM repository.

To register the WMI Provider, create instances of the following system classes:

instance of __Win32Provider as $P
{
    Name = "WMIProv";
    ClsId   = "{D2D588B5-D081-11d0-99E0-00C04FC2F8EC}" ;
};

instance of __InstanceProviderRegistration
{
    Provider = $P;
    SupportsGet = "TRUE";
    SupportsPut = "TRUE";
    SupportsEnumeration = "TRUE";
    SupportsDelete = "FALSE";
};

instance of __MethodProviderRegistration
{
    Provider = $P;
};

instance of __Win32Provider as $P1
{
    Name = "WMIEventProv";
    ClsId   = "{0725C3CB-FEFB-11d0-99F9-00C04FC2F8EC}";
};

class WMIEvent : __ExtrinsicEvent
{
};

instance of __Win32EventProviderRegistration
{
    Provider = $P1;
    EventQueryList = {"select * from WMIEvent"};
};

instance of __Win32ClassProviderRegistration
{
    Provider = $P;
    InteractionType = 1;
    ResultSetQueries={"select * from meta_class"};
    ReferencedSetQueries={"select * from meta_class"};
    UnsupportedQueries=NULL;
    SupportsDelete = "FALSE";
};


WBEM ODBC Adapter

The ODBC (Open Database Connectivity) interface allows applications to access data in database management systems (DBMS) using structured query language (SQL) as a standard. It allows an application developer to develop, compile, and ship an application without targeting a specific DBMS. The DBMS vendors provide their adapters to link the ODBC interface to their specific API functions.

The Web-Based Enterprise Management (WBEM) ODBC adapter provides a standard API that a programmer uses to obtain data contained in the WBEM database.

The WBEM ODBC adapter currently does not allow you to create tables, add records, or edit records.


Installing the ODBC Adapter

The WBEM SDK installs the 2.x ODBC components (driver manager and administrator) if required. The 3.0 ODBC driver manager is backward-compatible with 2.x ODBC drivers.

Use the Control Panel ODBC applet to add, modify, or delete data sources from the ODBC.ini file or the registry. An implementation of ConfigDSN is provided to enable adding a data source. When creating a data source, ConfigDSN may prompt you to specify its category.

If you use the SDK Driver Setup Toolkit, you can install the adapter from the standard Control Panel ODBC applet.

You can install the ODBC software programmatically, silently or non-silently, from SMS startup or a menu option. SQLInstallODBC is called to install the ODBC software and the adapters.

See Also

SDK Guide in the ODBC 2.0 Programmer's Reference and SDK Guide

Release Notes


API Conformance

The WBEM ODBC adapter conforms to ODBC API Level 1, which includes the following functionality:

  • Allocates and frees the environment, connection, and statement handles.
  • Assigns storage for parameters in an SQL statement and result columns.
  • Commits or rolls back transactions.
  • Connects to data sources with adapter-specific dialog boxes.
  • Prepares and executes SQL statements.
  • Sets and inquires about statement and connection options.
  • Sends all or part of a parameter value.
  • Retrieves all or part of a result column.
  • Retrieves data from and information about a result set.
  • Retrieves catalog information (columns, special columns, statistics, and tables).
  • Retrieves adapter and data source information, such as supported data types, scalar functions, and ODBC functions.
  • Retrieves error information.


CIM to ODBC Mapping

The Common Information Model (CIM) maps to ODBC as follows:

CIM namespaces map to ODBC databases.
In CIM, namespaces are instances of the __NameSpace class. Namespaces can contain child namespaces, which can be enumerated like any other instance of a class.
CIM classes map to ODBC tables.
The table qualifier is the fully qualified __NameSpace name. A class is unique. If a class exists in two different namespaces, the adapter maps them as two different tables.
CIM class properties map to table columns as follows:
  • The property name becomes the column name.
  • The property value becomes the column value.
  • The property qualifiers become column metadata.

The property qualifiers are exposed to the ODBC clients by using SQLColumns. Some of the metadata is used to determine the standard metadata exposed by SQLColumns. All qualifiers are contained as a SQL_LONGVARCHAR in a thirteenth column added to the resultant rowset. The adapter only exposes qualifiers on a per-class basis, not on a per-class, per-instance basis. Therefore, information in qualifiers that vary over instances is inaccessible. See SQLColumns for more information.

CIM class qualifiers map to metadata of a table (as exposed through SQLTables).
A sixth column of the rowset has been added to SQLTables to return all class qualifiers as an SQL_LONGVARCHAR. For more information, see SQLTables. The adapter exposes qualifiers on a per-class basis only. Therefore, the adapter does not access qualifier information that varies across instances.
CIM data types map to ODBC SQL data types.
CIM uses variants to return property values. The ODBC adapter supports these variant types. The CIMTYPE attribute has more semantics than the variant type. For example, if the variant type is BSTR and the CIMTYPE is IpAddress, the variant BSTR is in fact an IP address. The adapter uses the CIMTYPE attribute sparingly. For more information on data types, see Appendix D of the ODBC 2.0 Programmer's Reference and SDK Guide.

The following table shows the mapping of variant types to ODBC types.

Variant Type | Data source-Dependent Name | CIMTYPE String | SQL Type
VT_UI1 | UINT8 | UINT8 | SQL_TINYINT
VT_I2 | SINT8 | SINT8 | SQL_TINYINT
VT_I2 | SINT16 | SINT16 Default case if nothing else matches | SQL_SMALLINT
VT_I4 | UINT16 | UINT16 | SQL_SMALLINT
VT_I4 | UINT32 | UINT32 | SQL_INTEGER
VT_I4 | SINT32 | SINT32 Default case if nothing else matches | SQL_INTEGER
VT_BSTR | SINT64 | SINT64 | SQL_BIGINT
VT_BSTR | UINT64 | UINT64 | SQL_BIGINT
VT_BSTR | INTERVAL | INTERVAL | SQL_TIMESTAMP
VT_BSTR | TIMESTAMP | DATETIME | SQL_TIMESTAMP
VT_BSTR | DATE | DATE | SQL_DATE
VT_BSTR | TIME | TIME | SQL_TIME
VT_BSTR | SMALL_STRING | STRING The property must also have a MAX qualifier with a value <= 254. Default case if nothing else matches If the MAX qualifier value cannot be retrieved, the default value of 254 is used. | SQL_VARCHAR
VT_BSTR | STRING | STRING The property must also have a MAX qualifier with value > 254. If MAX qualifier value > 16384, it is truncated to 16384. | SQL_LONGVARCHAR
VT_R4 | REAL |  | SQL_DOUBLE
VT_R8 | DOUBLE |  | SQL_DOUBLE
VT_BOOL | BIT |  | SQL_BIT
VT_ARRAY | VT_UI1 | SINT8_ARRAY | SINT8 | SQL_LONGVARBINARY
VT_ARRAY | VT_I2 | UINT8_ARRAY | UINT8 | SQL_LONGVARBINARY
VT_ARRAY | VT_I2 | SINT16_ARRAY | SINT16 Default case if nothing else matches | SQL_LONGVARBINARY
VT_ARRAY | VT_I4 | UINT16_ARRAY | UINT16 | SQL_LONGVARBINARY
VT_ARRAY | VT_I4 | UINT32_ARRAY | UINT32 | SQL_LONGVARBINARY
VT_ARRAY | VT_I4 | SINT32_ARRAY | SINT32 Default case if nothing else matches | SQL_LONGVARBINARY
VT_ARRAY | VT_BOOL | BOOL_ARRAY |  | SQL_LONGVARBINARY
VT_ARRAY | VT_R4 | REAL_ARRAY |  | SQL_LONGVARBINARY
VT_ARRAY | VT_R8 | DOUBLE_ARRAY |  | SQL_LONGVARBINARY
VT_ARRAY | VT_BSTR | SINT64_ARRAY | SINT64 | SQL_LONGVARBINARY
VT_ARRAY | VT_BSTR | UINT64_ARRAY | UINT64 | SQL_LONGVARBINARY
VT_ARRAY | VT_BSTR | STRING_ARRAY | STRING Default case if nothing else matches | SQL_LONGVARBINARY
VT_ARRAY | VT_BSTR | INTERVAL_ARRAY | INTERVAL | SQL_LONGVARBINARY
VT_ARRAY | VT_BSTR | TIMESTAMP_ARRAY | DATETIME | SQL_LONGVARBINARY
VT_ARRAY | VT_BSTR | DATE_ARRAY | DATE | SQL_LONGVARBINARY
VT_ARRAY | VT_BSTR | TIME_ARRAY | TIME | SQL_LONGVARBINARY

As the table shows, CIM supports multiple array types. These array types are returned as binary data. However, through ODBC, these array values can also be returned as ASCII strings. For example:

  • An integer array is [-3] [200] [50] [45].
  • A floating point array is [1.234567] [234.567890].
  • A string array is [billy] [jack] [freddy].

Use SQLColumns to get the data source-dependent type in order to distinguish between [-3][200][50][45] as an array of integers and an array of strings (which just look like numbers).

If an array name or value contains a left or right square bracket within itself, the brackets are doubled in the ASCII representation. For example, fr[ed]dy is shown as:

[fr[[ed]]dy]

CIM class and property qualifiers that change with the instance of a class are not exposed.

CIM associations are only exposed insofar as they are represented by classes. Thus, foreign keys are not used in a table to relate the classes of an association.

An ODBC data source can include several databases. See Connecting to a Data Source for information on database configuration.


ODBC Handles

When an application requests it, the Driver Manager and each driver allocate memory storage for information about the ODBC environment, each connection, and each SQL statement. The handles to these storage areas are returned to the application, which then uses one or more of them in each ODBC function call.

The ODBC interface defines three types of handles:

  • The environment handle is a variable of type HENV. It identifies memory storage for global information, including the valid connection handles and the current active connection handle. An application uses a single environment handle, and it must request this handle before connecting to a data source.
  • The connection handle is a variable of type HDBC. It identifies memory storage for information about a particular connection. An application must request a connection handle before connecting to a data source. Each connection handle is associated with the environment handle. The environment handle, however, can have multiple connection handles associated with it.
  • The statement handle is a variable of type HSTMT. It identifies memory storage for information about an SQL statement. An application must request a statement handle before submitting SQL requests. Each statement handle is associated with only one connection handle. Each connection handle can, however, have multiple statement handles associated with it.

See Also

Connecting to a Data Source

Multi-threading Issues in the Adapter and Client Applications

ODBC Adapter Synchronous and Asynchronous Operation

SQL Select Handling


Connecting to a Data Source

In the connection string to SQLDriverConnect, the caller specifies either:

  • "DSN=dataSourceName," which can include the attribute-keywords, as described below, or
  • "DRIVER=driverName" which can include the attribute-keywords, as described below.

In addition to the standard data source name, user name, and password, the adapter recognizes the attribute-keywords NAMESPACES, DBQ, HOME, and SERVER.

If you specify the DRIVER keyword, the user is prompted to enter a database category.

Note If SQLDriverConnect is called with an fCompletionFlag of SQL_NO_PROMPT, SQLDriverConnect returns an error.

The keyword value is a string used to filter the total number of databases in WBEM. This number depends on the global environment variable ODBC Category, the value of which is equal to the keyword value. However, if the category string is ALL, then all databases are considered as included in this data source.

If the connection string information is insufficient and the fCompletionFlag is not SQL_NO_PROMPT, a dialog box is displayed for namespace selection. In this dialog box, a tree control shows the nesting of namespaces. Each namespace has an associated bitmap image representing its state. The bitmap image looks like a checkbox with a folder.

Clicking the folder alternately selects and cancels the selection of the namespace. If the checkbox or folder is not expanded (denoted by a + button next to the control), then all items in the folder are selected or canceled, depending on the current state of the folder. If the folder is already expanded or has no child items, then only the folder is affected.

The state of each folder is represented as follows:

Clear Unchecked Checkbox | Item is not selected and no child items (if any) are selected.
Gray Unchecked Checkbox | At least one child item is selected.
Clear Checked Checkbox | Item is selected but no child items (if any) are selected.
Gray Checked Checkbox | Item is selected and at least one child item is selected.

The dialog box also allows namespace selection from a remote WBEM database. This functionality is available through the Browse button and text box.

If you choose to manually enter a remote server name in the text box (maximum length 128 characters), the update does not occur until you exit the edit control by using the TAB key. The current tree control is cleared and replaced by the tree control for the new remote server. If the text box is empty, the local server is used.

Click the Browse button to display a new Server Selection dialog box. This presents information similar to the Microsoft® Windows NT® Network Neighborhood. The dialog box initially displays the network resources on the local area network (LAN). Another link enables you to view the entire network (represented by a globe). If you double-click on an image that does not represent a server, then the current display is cleared and the contents of the chosen network resource are displayed.

The dialog box also has three bitmap buttons:

  • The Folder button enables you to traverse back to the previous network resource selection.
  • The Link view button displays all the network resources in list view format.
  • The Report view button displays all the network resources in report view format.


The NAMESPACES Attribute-Keyword

NAMESPACES is a comma-separated list of namespace names. Unless the HOME is specified, these must be fully qualified namespaces that the adapter can use directly with the provider gateway API.

Specify the namespace names as follows:

NAMESPACES={namespace name, style}

Where style can be either:
shallow (include only the specified namespace), or

deep (include the specified namespace and all its children)

Examples

NAMESPACES={Root\Default, shallow}
This specifies just the Root\Default namespace.
NAMESPACES={Root\Default, deep}
This specifies the Root\Default namespace and all its children.
NAMESPACES={Root\Wellfleet, shallow},{Root\Cisco, deep}
This specifies the Root\Wellfleet namespace plus the Root\Cisco namespace plus all the children of the Root\Cisco namespace.
NAMESPACES=Root\Default
This is equivalent to NAMESPACES={Root\Default,shallow}.


The DBQ Attribute-Keyword

DBQ is the database qualifier. This is the fully qualified, default, working namespace.


The HOME Attribute-Keyword

HOME is the common root path name to all the namespaces specified in the NAMESPACES list. If the HOME keyword is defined, all names in the NAMESPACES list are assumed to be relative to the HOME namespace. The fully qualified namespace path can be derived by adding as a prefix the HOME namespace to each of the names in the NAMESPACE list. If the HOME keyword is not defined, all namespaces in the NAMESPACES list are assumed to be fully qualified.

Example: HOME=Root\Redmond;NAMESPACES=Fred

The fully qualified namespace is Root\Redmond\Fred.


The SERVER Attribute-Keyword

SERVER is the name of the WBEM server. This attribute-keyword is used primarily to specify a remote WBEM server. If this attribute-keyword is omitted, the local WBEM server is used.

Example: SERVER=\\REDMOND


Multi-threading Issues in the Adapter and Client Applications

Since the ODBC Driver Manager is thread-safe, the adapter is inherently thread-safe.

The only exception to this is where an SQLCancel is invoked on synchronously executing the statement handle hStmt object from a different thread. The Driver Manager uses critical sections (non-reentrant pieces of code) on the environment handle hEnvs, the connection handle hDbcs, and hStmts to guarantee synchronous operation on these objects.

An action on one of these objects causes the Driver Manager to enter a critical section for that object. In the case of SQLCancel, the Driver Manager enters a "cancel-in-progress" critical section. This prevents SQLCancel from being reentered before the first one is completed. The adapter's SQLCancel is then invoked.

If there is no simultaneous action on the statement handle, the SQLCancel is treated as an SQLFreeStmt or SQL_CLOSE operation. The adapter returns SQL_SUCCESS_WITH_INFO with a SQLSTATE of 01S05. This causes the Driver Manager to return SQL_SUCCESS to the application.

If there was simultaneous action on the statement handle, the return code from the original thread's ODBC function determines if the SQLCancel was successful.

The adapter's SQLCancel is implemented as follows:

  1. In the adapter, each statement has a critical section.
  2. This critical section is entered on all ODBC functions that take a statement handle (except SQLCancel), and is left upon exit.
  3. The SQLCancel code inspects this critical section to determine if it has been entered (non-zero owning thread). This is the test for determining if an SQLFreeStmt/SQL_CLOSE needs to be called.
  4. If there is activity on the statement, the adapter sets a CANCEL flag on the statement handle, which the original thread periodically checks for to determine if it needs to cancel the operation, however it deems appropriate.

The ODBC 2.0 Programmer's Reference and SDK Guide suggests two techniques for writing thread-safe multithreaded ODBC applications:

  • Have multiple statement handles on a single connection handle, with a single thread per statement handle.
  • Have multiple connection handles, with a single statement handle per connection handle and a single thread per connection handle.

The application must know which operations are being performed on an object. For example, if a thread does an SQLFetch on a statement handle, begins to process the data, and a second thread does an SQLFetch on the same statement handle into the same buffer, the first thread might get columns from the first row of the rowset mixed with columns from the second row.

Also, the application must be particularly careful in performing SQLFreeStmts. For example, if an application attempts to perform an operation on a statement handle that is being freed, it blocks on the statement handle. When it unblocks, it fails with an access violation because the statement handle no longer exists. The application must ensure that the statement handle is inactive before calling SQLFreeStmt, SQL_DROP, or SQLDisconnect.

See Also

ODBC Handles


ODBC Adapter Synchronous and Asynchronous Operation

By default, the adapter operates in synchronous mode. That is, the adapter does not return control to a client application until the function call completes.

However, the adapter also supports asynchronous operation. In ODBC, asynchronous processing is performed on a statement-by-statement basis.

To have a client application execute a statement asynchronously
  1. Call SQLSetStmtOption with the SQL_ASYNC_ENABLE option.
  2. Call the ODBC function. The adapter begins asynchronous operation and returns SQL_SQL_STILL_EXECUTING.
  3. Perform other operations and call other ODBC functions on different statement handles while the adapter is working.
  4. Optionally, the application can call the original function on the original statement handle to determine if the function has completed. If it has completed, the function returns with SQL_SUCCESS or SQL_SUCCESS_WITH_INFO. Otherwise, it returns with SQL_STILL_EXECUTING.

Note The ODBC adapter is a Common Information Model (CIM) client. Therefore, it has limited control over the duration of synchronous CIM calls, and this duration can be substantial. Applications may have to spawn a thread to implement ODBC functionality. This is especially true for all ODBC client applications designated for use with diverse ODBC data sources.

See Also

ODBC Handles


The SQL Grammar

The adapter supports a subset of the ODBC Minimum SQL Grammar. It does not support Data Definition Language (DDL) constructs and writeable Data Manipulation Language (DML) constructs. If the data provider supports queries, the adapter decomposes the ODBC Minimum SQL into a series of WBEM Level 1 queries, and then passes them to the data provider. Thus, queries can be optimized for specific data providers.

ODBC Minimum SQL Grammar

select-statement::= | SELECT [ALL|DISTINCT] select-list FROM table-reference-list [WHERE search-condition] [order-by-clause]
select-list::= | * | select-sublist[,select-sublist]
select-sublist::= | expression
expression::= | term|expression {+|-} term
term::= | factor | term {*|/} factor
factor::= | [+|-] primary
primary:: | column-name | dynamic-parameter | literal | (expression)
dynamic-parameter:= | ?
literal::= | character-string-literal
character-string-literal::= | '{character}...'
character::= | our character set
column-name::= | [table-name.]column-identifier
column-identifier::= | user-defined-name
user-defined-name::= | letter[digit|letter|_]...
table-reference-list::= | table-reference[table-reference]..
table-reference::= | table-name
table-name::= | table-identifier
table-identifier::= | user-defined-name
search-condition::= | boolean-term [OR search-condition]
boolean-term::= | boolean-factor [AND boolean-term]
boolean-factor::= | [NOT]boolean-primary
boolean-primary::= | predicate | (search-condition)
predicate::= | comparison-predicate | like-predicate | null-predicate
comparison-predicate::= | expression comparison-operator expression
comparison-operator::= | <|>|<=|>=|=|<>
like-predicate::= | expression [NOT] LIKE
pattern-value::= | character-string-literal | dynamic-parameter
null-predicate::= | column-name IS [NOT] NULL
order-by-clause::= | ORDER BY sort-specification[,sort-specification]
sort-specification::= | {unsigned-integer | column} [ASC |DESC]

In Level 1 provider SQL grammar, all operations are on a single table, and dynamic parameters are not supported. This grammar can be converted into postfix notation, which means the functions are preceded by all their operands, to facilitate the implementation of a simpler stack-based SQL parser in the data provider.

Level 1 Provider SQL Grammar

select-statement::= | SELECT [ALL|DISTINCT] select-list FROM table-reference [WHERE search-condition] [order-by-clause]
select-list::= | * | select-sublist[,select-sublist]
select-sublist::= | expression
expression::= | term|expression {+|-} term
term::= | factor | term {*|/} factor
factor::= | [+|-] primary
primary:: | column-name | literal | (expression)
literal::= | character-string-literal
character-string-literal::= | '{character}...'
character::= | our character set
column-name::= | [table-name.]column-identifier
column-identifier::= | user-defined-name
user-defined-name::= | letter[digit|letter|_]...
table-reference::= | table-name
table-name::= | table-identifier
table-identifier::= | user-defined-name
search-condition::= | boolean-term [OR search-condition]
boolean-term::= | boolean-factor [AND boolean-term]
boolean-factor::= | [NOT]boolean-primary
boolean-primary::= | predicate | (search-condition)
predicate::= | comparison-predicate | like-predicate | null-predicate
comparison-predicate::= | expression comparison-operator expression
comparison-operator::= | <|>|<=|>=|=|<>
like-predicate::= | expression [NOT] LIKE
pattern-value::= | character-string-literal | dynamic-parameter
null-predicate::= | column-name IS [NOT] NULL
order-by-clause::= | ORDER BY sort-specification[,sort-specification]
sort-specification::= | {unsigned-integer | column} [ASC |DESC]


SQL Select Handling

This topic outlines how the adapter parses SQL SELECT statements, and converts them into CIM calls. It describes SELECT statement processing in terms of the CIM calls that must be made, and touches on the data structures used within the ODBC adapter.

It does not consider the internal operation of the Managed Object (MO) Server, mini-servers, or providers.

Finally, it describes how SQL Query Decomposition proceeds. SQL Query Decomposition is the process whereby SQL SELECT statements are broken down into single table select queries, and passed as queries to the WBEM Gateway interface if it supports SQL handling.


Single-Table, Single-Column Example

The following pseudocode assumes a typical client-adapter interaction. The client wants to select c1t1 from table t1 in the database called Wellfleet. In CIM terms, this corresponds to getting the property fld1t1 from all instances of the class t1. This pseudocode for the client does not consider error handling.

HENV henv;
HBDC hdbc;
HSTMT hstmt;
SQLAllocEnv (&henv);
SQLAllocConnect (henv, &hdbc);
SQLConnect (hdbc, "SNMP", SQL_NTS,
  NULL, SQL_NTS, NULL, SQL_NTS);
SQLSetConnectionOption (hdbc, SQL_CURRENT_QUALIFIER,
  "Wellfleet");
HSTMT hstmt;
SQLAllocStmt (hdbc, &hstmt);
SQLExecDirect (hstmt, "select c1t1 from t1");
while (SQL_SUCCESS == SQLFetch (hstmt))
{
  char szData [MAX_DATA];
  SQLGetData (hstmt, 1, SQL_C_CHAR,
    szData, sizeof (szData), &cbData));
  MsgBox (NULL, szData, "ODBC", MB_OK);
}

Using SQLSetConnectionOption with the SQL_CURRENT_QUALIFER option sets the default database. This means the client can refer to tables without having to qualify them with the database name (in this case, Wellfleet). If the client had not invoked the SQLSetConnectOption, the adapter would have searched for t1 in the current database. In SQLSetConnectOption, the adapter stores the database (qualifier) in a data structure associated with the hdbc (the connection handle).


Understanding SQLExecDirect

SQLExecDirect has two phases: SQLPrepare and SQLExecute. These are used when a particular SQL command is performed more than once. In adapters for traditional database management systems (DBMS), SQLPrepare allows for the creation of an access plan on the DBMS.


The SQLPrepare Phase of SQLExecDirect

SQLPrepare prepares an SQL string for execution by:

  • Creating a parse tree that represents the SQL statement, and checking syntax. The nodes of the parse tree contain placeholders that are used for annotations during semantics checking.
  • First verifying, during semantics checking, that each table in the table list specified in the select statement exists. If the table does not exist, an error occurs.
  • Ensuring that table alias names are not duplicated.
  • Semantically checking the select list of the SELECT statement, which involves:
    • Finding the table to which each column in the select list refers.
    • Ensuring that a column does not ambiguously refer to multiple tables.
    • Storing a reference in the column node to its associated table definition.
  • Checking the semantics of the WHERE clause.

In terms of the single-table, single-column example, SQLPrepare ensures that table and alias names are not duplicated. It accomplishes this task by verifying that t1 exists within the Wellfleet database. Also, in terms of this example, SQLPrepare checks the semantics of the select list by ensuring that c1t1 exists within t1 and a reference to a definition of t1 is stored in the column node representing c1.


The SQLExecute Phase of SQLExecDirect

SQLExecute executes a prepared statement by:

  • Creating an enumeration of row instances for each table in each of the table definitions.
  • Storing the row instance enumeration pointer in the table definition.
  • For each invocation of SQLFetch, invoking the Next method on the enumeration, which corresponds to scrolling the cursor forward.

When the client invokes SQLGetData the adapter acts upon the row instance as returned by the most recent Next method call. ODBC uses integers to refer to the columns in the select list of a SELECT statement. This integer is a one-based index into the select list. In implementing SQLGetData, the adapter maps the column to an element in the select list. This element provides all necessary information for accessing the corresponding property in the row instance.


Two-Column, Two-Table Example

Consider the following SELECT statement:

SELECT c1t1, c1t2 FROM t1,t2

The SQLPrepare phase for this statement proceeds as before. Here, however, there are two columns, each from a separate table. The SELECT statement is asking for the Cartesian cross product of the columns in the tables. This differs from the single-column, single-table example in that, for each value of c1t1, the adapter must iterate over t2 (assuming the c1t1 spins fastest). Thus, for each c1t1, the adapter must reset the t2 enumeration and Next over the enumeration for all elements.

The behavior of an enumeration in each Next is unknown to the adapter. For example, one provider may get all the information it needs to return all row information when the enumeration is created. Another might only retrieve the information on a just-in-time basis. For example, when Next is invoked it gathers the information necessary to return the corresponding row information. Which strategy is employed is provider-dependent and depends on the static nature of the provided data. If the adapter is a dynamic instance provider, it may choose to get the data on a Next. In this case, if the adapter resets the enumeration and invokes Next again, the provider retrieves the data needed to build the row information to be returned.

There can be efficiency problems if there are many columns in the select list and many rows or instances per table. Further, during any particular invocation, the adapter expects the contents enumerated to remain the same. That is, the adapter really wants a snapshot of the enumerated instances when the execution is done. The adapter may have to do its own caching of row information as each enumeration is iterated through.

The next case adds a WHERE predicate to the select statement. Here is a straightforward restricted SELECT:

SELECT c1t1, c1t2 FROM t1, t2 WHERE  c2t1 = 10

In this case, SQLPrepare builds a complete predicate tree that represents the WHERE clause. SQLPrepare also checks and annotates the semantics of this parse tree, much the same way that it checks the semantics of the select list.

SQLFetch accesses the instances of the classes in a rightmost, slowest manner as for the previous case. Here, however, the predicate tree is evaluated with the properties of the current instances to determine if the current combination of instances qualify for the resultant rowset.

See Also

ODBC Handles


SQL Optimization

The WBEM ODBC adapter does not provide any traditional SQL query optimization. However, it does support decomposition of ODBC Minimum Level SQL queries into WBEM Level 1 queries. The data provider can then specify optimizations on single tables.

For the grammar of WBEM Level 1 queries, see The SQL Grammar. To summarize, a Level 1 query is an ODBC minimum-level query that can only act on a single table. The adapter decomposes an arbitrary ODBC minimum SQL into a number of these queries and sends them to the gateway.

During the SQLPrepare phase, the adapter examines the WHERE predicate tree. If no WHERE predicate tree exists, no optimization is performed. It then attempts to decompose the SQL statement into Level 1 queries. If successful, each Level 1 query is sent to the gateway server via an ExecQuery call. If query decomposition is unsuccessful, the adapter enumerates the whole row of instances as before.

The generation of the Level 1 query is handled by two classes. First, the PredicateParser class generates the WHERE predicate for the desired table. It does this by scanning the parse tree for the current SQL statement. It then converts the WHERE predicate portion of the parse tree into an ASCII text string for the desired table. The next phase is to generate the select list in the WBEM Level 1 query for the columns required for the desired table. This is handled by the TableColumnInfo class, which manages associations between tables and their associated columns. The TableColumnInfo class scans the parse tree for the current SQL statement and extracts any column names for the currently chosen table. It can then generate an ASCII select list text string from these column names.

Another optimization is also performed during the adapter's Parse phase. In the following SQL statement,

SELECT c1t1 FROM t1, t2

t2 is redundant. The adapter attempts to identify these redundancies and remove them from the parse tree.

This optimization is handled by the TableColumnInfo class. The TableColumnInfo class will scans the parse tree for the current SQL statement, and generates associations between tables and columns. It highlights any tables that do not have any associated columns. Once the tables have been identified, they can be removed from the parse tree.


The ODBC Functions

This section alphabetically lists only the supported WBEM ODBC functions. The descriptions of the functions include design issues relevant to the function's implementation.

For error codes and parameter descriptions, see the ODBC 2.0 Programmer's Reference and SDK Guide.


Quick Reference Table

The following table shows all supported WBEM ODBC functions. Those functions requiring extensive description have their own topics, as noted in the Description column.

ODBC Function | Description
SQLAllocConnect | See topic.
SQLAllocEnv | See topic.
SQLAllocStmt | Modified to support inclusion of table qualifiers.
SQLBindCol | Supported.
SQLBindParameter | Supported.
SQLCancel | Used to cancel a function executing asynchronously on a statement handle that needs data.
SQLColAttributes | See topic.
SQLColumns | See topic.
SQLConnect | The user of SQLConnect must only specify a data source name.
SQLDataSources | Implemented in the Driver Manager.
SQLDescribeCol | Similar to SQLColumns attributes. Imposes no requirements upon the property qualifiers in the WBEM class objects beyond those specified in SQLColumns.
SQLDisconnect | Supported.
SQLDriverConnect | See topic.
SQLDrivers | Implemented in the Driver Manager.
SQLError | See topic.
SQLExecDirect | Supported.
SQLExecute | Supported.
SQLExtendedFetch | Clients usually only need SQLFetch. However, SQLExtendedFetch returns rowset data in array form for each bound column, and it can scroll through the data.
SQLFetch | Supported.
SQLFreeConnect | Supported.
SQLFreeEnv | Supported.
SQLFreeStmt | Supported.
SQLGetConnectOption | See topic.
SQLGetCursorName | See ODBC 2.0 Programmer's Reference and SDK Guide.
SQLGetData | See ODBC 2.0 Programmer's Reference and SDK Guide.
SQLGetFunctions | See topic.
SQLGetInfo | See topic.
SQLGetStatementOption | See topic.
SQLGetTypeInfo | See topic.
SQLNumResultCols | Supported.
SQLParamData | Supported.
SQLPrepare | Supported.
SQLPutData | Supported.
SQLRowCount | Supported.
SQLSetConnectOption | See SQLGetConnectOption for a discussion of the options and what they mean for the adapter.
SQLSetCursorName | Supported.
SQLSetScrollOptions | Superseded by SQLSetStmtOption in ODBC 2.0. ODBC 2.0 applications should not call it. ODBC 2.0 Extension Level 2 adapters should implement it for backward compatibility with ODBC 1.0 applications.
SQLSetStmtOption | See SQLGetStatementOption .
SQLSpecialColumns | Only fColType equal to SQL_BEST_ROWID is supported.
SQLStatistics | Supported.
SQLTables | See topic.


SQLAllocConnect (Core)

This function allocates memory for a connection handle within the environment specified by the environment handle passed in. This returns SQL_ERROR if memory cannot be allocated for the handle. It returns a handle of SQL_NULL_HDBC. The client can then ask for more error information by using SqlError, this handle, and a statement of SQL_NULL_HSTMT. Otherwise, it returns SQL_SUCCESS.

See Also

ODBC Handles


SQLAllocEnv (Core)

This function allocates memory for an environment handle. This handle provides a context in which connections and statements are allocated. This only fails (return SQL_ERROR) if the function fails to allocate memory for the handle. Otherwise it returns SQL_SUCCESS.

See Also

ODBC Handles


SQLColAttributes (Core)

This function is modified to use information from the WBEM database. This function returns descriptor information for a column in a result set. See SQLColumns for a description of how this information is retrieved. This function does not impose any demands on the qualifiers that must be made available for a property (column) in a class object (table) in a WBEM database. It is possible to ask for an SQL_COLUMN_LABEL, which is a label that utilities can use to describe a column. In our case this can reduce to the column name.


SQLColumns (Extended Level 1)

SQLColumns returns a list of column names in specified tables. The information is returned in a result set on the specified hStmt.

For example, to get information on the columns in the TcpConnectionTable on the device (represented by a database) DatabaseName the client invokes:

SQLColumns (hstmt, "DatabaseName", SQL_NTS,  // qualifier
NULL, 0,                                     // owner
"TcpConnectionTable", SQL_NTS,               // table
"%",SQL_NTS);                                // all columns

The first task of the adapter is to get a WBEM Gateway interface for the specified namespace. In this example the namespace is called "DatabaseName". With the Gateway interface the adapter has access to all the information contained within that namespace.

The next stage is to get the information for the specified table. This is obtained through a Gateway interface call. This call returns another WBEM interface which contains all the information about the table.

The adapter can now use this new WBEM interface to access the class properties and qualifiers. In particular, for the purposes of SQLColumns it needs to return the following information as a rowset:

Column Name | Data Type | Description
TABLE_QUALIFIER_NAME | Varchar (128) | The table qualifier. This corresponds to the database name.
TABLE_OWNER | Varchar (128) | Not used.
COLUMN_NAME | VarChar (128) | The column name (a WBEM Property Name)
TYPE_NAME | VarChar (128), not NULLable | Data Type Name. This is a data source dependent type name.
PRECISION | Integer | The precision of the column in the SMIR
LENGTH | Integer | The length of the column.
SCALE | SmallInt | The scale of the column.
RADIX | SmallInt | The radix of the column.
NULLABLE | SmallInt, not NULLable | NULLability of the column.
REMARKS | Varchar (254) | A description of the column.
ATTRIBUTES | Longvarchar (16384) | The column metadata.

For a description of these terms, see the table in CIM to ODBC Mapping.

As can be observed from the preceding table, the WBEM ODBC Adapter extends the SQLColumns result set by an extra column. This is used to return the column metadata.

The metadata is displayed in the following format:

[metadata name][ metadata value]

[metadata name][ metadata value]

For example,

[ObjectId][1.2.3.4.5.6]

[Syntax][STRING(254)]

If the metadata name or value contains a left or right square bracket ([ or ]), then two such symbols are used instead. For example, in order to show fr[ed]dy, the following is displayed:

[fr[[ed]]dy]


SQLDriverConnect (Extension Level 1)

This is the most common way for applications to connect to a data source.

In the connection string to SQLDriverConnect, the caller specifies either:

  • "DSN=dataSourceName" (it can optionally include the correlation keywords as described below), or
  • "DRIVER=driverName" (it can optionally include the correlation keywords as described below).

In addition to the standard data source name, user name, and password, the adapter understands the following attribute-keywords: namespaces, dbq, home, server, sysprops.

Namespaces is a comma-separated list of database/namespace names. These must be fully qualified namespaces (if home is not specified) that the adapter can use directly with the provider gateway API.

The namespace names can be specified in the following format:

Namespaces={namespace name, style}

Where style can be either:

shallow
include only the namespace specified
deep
include the namespace specified and all its children

For example:

Namespaces={Root\Default, shallow}

This specifies just the Root\Default namespace

Namespaces={Root\Default,deep}

This specifies the Root\Default namespace and all its children

Namespaces={Root\Wellfleet,shallow},{Root\Cisco,deep}

This specifies the Root\Wellfleet namespace plus the Root\Cisco namespace plus all the children of the Root\Cisco namespace

If you specify just Namespaces=Root\Default, this is equivalent to

Namespaces={Root\Default,shallow}

DBQ is the database qualifier. This is the fully qualified default working namespace.

Home is the common root path to all the namespaces specified in the namespaces list. If the home keyword is defined, all names in the namespaces list are assumed to be relative names to the Homenamespace. The fully qualified namespace path can be derived by adding as a prefix the Home namespace to each of the names in the namespace list. If the Home keyword is not defined, then all namespaces in the namespaces list are assumed to be fully qualified.

For example:

Home=Root\Redmond; Namespaces=Fred

The fully qualified namespace is Root\Redmond\Fred

Server is the name of the WBEM server. This attribute-keyword is used primarily to specify a remote WBEM server. If this attribute-keyword is omitted, the local WBEM server is used.

For example:

Server=\\Redmond

Sysprops indicates whether or not the adapter exposes WBEM system properties. Set this to TRUE to expose system properties; that is, in the connection string, include SYSPROPS=TRUE. You can also activate system properties using the checkbox control in the Connection dialog box.

If you specify the Driver keyword, the user is prompted to enter a database category (if SQLDriverConnect was called with an fCompletionFlag of SQL_NO_PROMPT, this function returns an error). The keyword value is a string used to filter down the total number of databases present in WBEM. This is based on a global environment variable of the ODBC Category in the database with a value equal to this string. An exception to this is if the category string is specified as ALL. In that case, all databases fall under this data source.

If sufficient information has not been specified in the connection string (and if the fCompletionFlag is not SQL_NO_PROMPT), then a dialog box is displayed that allows users to select namespaces. The dialog box contains a standard tree control to show the nesting of namespaces. Each namespace has an associated bitmap image to represent its state. The bitmap image looks like a checkbox with a folder.

Clicking within the area of the checkbox or folder selects or clears the selection of the namespace. If the namespace tree control item has not been expanded (a + button is seen on the left), then the selection or cancellation of the selection, depending on its current state, occurs recursively. If the item is already expanded (or has no child tree items), then only the tree control item is affected

The state of each tree control item is represented as follows:

  • Clear Unchecked Checkbox. Item is not selected and no child items (if any) are selected.
  • Gray Unchecked Checkbox. Item is not selected. However, at least one child item is selected.
  • Clear Checked Checkbox. Item is selected but no child items (if any) are selected.
  • Gray Checked Checkbox. Item is selected and at least one child item is selected.

The dialog box also allows you to select namespaces from a remote WBEM database. This functionality is available by means of the Browse button and edit box.

If you choose to enter manually a remote server name in the edit box (maximum length 128 characters), the update does not take place until you exit the edit control using the TAB key. The current tree control is cleared and replaced by the tree control for the new remote server. If the edit box does not contain any text, then the local server is used.

If you click the Browse button, a new Server Selection dialog box is displayed. This presents information similar to the Microsoft® Windows NT® Network Neighborhood. The dialog box initially displays the network resources on the LAN. There is also a link to view the entire network (represented by a globe). If you double-click on an image that does not represent a server, then the current display is cleared and the contents of the chosen network resource are displayed.

The dialog box also has three bitmap buttons:

  • The Folder button allows you to go back to the previous network resource selection.
  • The Link view button displays all the network resources as a list.
  • The Report view button displays all the network resources as a report.


SQLError (Core)

The adapter provides support for the return of the standard error codes as defined in Appendix A of ODBC 2.0 Programmer's Reference and SDK Guide. These correspond to the SQLSTATE code as defined in the X/Open and SAG SQL CAE Specification (1992).

When the adapter finds an internal error, such as an invalid handle or memory allocation error, it returns the appropriate SQLSTATE code, which is a text string the component originating the error, and a text description of the error. This is in accordance with the guidelines established in ODBC 2.0 Programmer's Reference and SDK Guide.

For example, if the adapter fails to allocate memory, it reports the error with the following arguments:

szSQLState | "S1001"
pfNativeError | NULL
szErrorMsg | "[Microsoft] [WBEM ODBC Adapter] Unable to allocate sufficient memory"
pcberrorMsg | 68

If WBEM returns an error code, the adapter qualifies the error message (szErrorMsg) to indicate that the error message originated in WBEM. For example, if the client attempts to get the columns (properties) of a particular table (class), the adapter invokes the IMOSProvider::GetClass method. If GetClass returns OLEMS_E_INVALID_CLASS, the adapter reports the error with the following arguments:

szSQLState | "S0002"
pfNativeError | NULL
szErrorMsg | "[Microsoft][WBEM ODBC Adapter][OLE MS] Invalid class name;Class XXXX.YYYY could not be found"
pcberrorMsg | 94

The general method of discovering errors is to invoke SQLError iteratively until it reports no more errors. This is particularly, though not exclusively useful in multitier adapters where a downstream component can report an error, and the upstream component may want to add its own error to this error, identifying itself as the discoverer. In accordance with ODBC guidelines, the upstream component does not alter error messages; rather, it adds its own error message. The adapter has only one outstanding error per statement, connection, or handle.

See Also

ODBC Handles


SQLGetConnectOption (Extension Level 1)

Option | Possible Values
SQL_ACCESS_MODE | SQL_MODE_READ_ONLY.
SQL_AUTOCOMMIT | SQL_AUTOCOMMIT_ON.
SQL_CURRENT_QUALIFIER | The current qualifier in use by the data source. In WBEM terms, this indicates the current database in use by the data source.
SQL_LOGIN_TIMEOUT | This is intended to be the number of seconds to wait for a request to log on to complete before timing out and returning to the application. The adapter does not support this functionality.
SQL_ODBC_CURSORS | This returns an error saying the adapter does not support this functionality.
SQL_OPT_TRACE | This is implemented in the Driver Manager
SQL_OPT_TRACE_FILE | This is implemented in the Driver Manager
SQL_PACKET_SIZE | Intended to be used to allow the client to specify the network packet size. The adapter does not support this functionality.
SQL_QUIET_MODE | Unsupported.
SQL_TRANSLATE_DLL | Unsupported.
SQL_TX_ISOLATION_LEVEL | Unsupported.


SQLGetFunctions (Extension Level 1)

This function is modified to indicate that the data source write operations are unsupported.

Core Functions

Function | Supported
SQL_API_SQLALLOCCONNECT | YES
SQL_API_SQLALLOCENV | YES
SQL_API_SQLALLOCSTMT | YES
SQL_API_SQLBINDCOL | YES
SQL_API_SQLCANCEL | YES
SQL_API_SQLCOLATTRIBUTES | YES
SQL_API_SQLCONNECT | YES
SQL_API_SQLDESCRIBECOL | YES
SQL_API_SQLDISCONNECT | YES
SQL_API_SQLERROR | YES
SQL_API_SQLEXECDIRECT | YES
SQL_API_SQLEXECUTE | YES
SQL_API_SQLFETCH | YES
SQL_API_SQLFREECONNECT | YES
SQL_API_SQLFREEENV | YES
SQL_API_SQLFREESTMT | YES
SQL_API_SQLGETCURSORNAME | YES
SQL_API_SQLNUMRESULTCOLUMNS | YES
SQL_API_SQLPREPARE | YES
SQL_API_SQLROWCOUNT | YES
SQL_API_SQLSETCURSORNAME | YES
SQL_API_SQLSETPARAM | NO
SQL_API_SQLTRANSACT | NO

Extended Level 1 Functions

Function | Supported
SQL_API_SQLBINDPARAMETER | YES
SQL_API_SQLCOLUMNS | YES
SQL_API_SQLDRIVERCONNECT | YES
SQL_API_SQLGETCONNECTOPTION | YES
SQL_API_SQLGETDATA | YES
SQL_API_SQLGETFUNCTIONS | YES
SQL_API_SQLGETINFO | YES
SQL_API_SQLGETSTMTOPTION | YES
SQL_API_SQLGETTYPEINFO | YES
SQL_API_SQLPARAMDATA | YES
SQL_API_SQLPUTDATA | YES
SQL_API_SQLSETCONNECTOPTION | YES
SQL_API_SQLSETSTMTOPTION | YES
SQL_API_SQLSPECIALCOLUMNS | YES
SQL_API_SQLSTATISTICS | YES
SQL_API_SQLTABLES | YES

Extended Level 2 Functions

Function | Supported
SQL_API_SQLBROWSECONNECT | NO
SQL_API_SQLCOLUMNPRIVILEGES | NO
SQL_API_DATASOURCES | YES
SQL_API_DESCRIBEPARAM | NO
SQL_API_DRIVERS | YES
SQL_API_EXTENDEDFETCH | NO
SQL_API_FOREIGNKEYS | NO
SQL_API_SQLMORERESULTS | YES
SQL_API_SQLNATIVESQL | NO
SQL_API_SQLNUMPARAMS | NO
SQL_API_SQLPARAMOPTIONS | NO
SQL_API_SQLPRIMARYKEYS | NO
SQL_API_SQLPROCEDURECOLUMNS | NO
SQL_API_SQLPROCEDURES | NO
SQL_API_SQLSETPOS | NO
SQL_API_SQLSETSCROLLOPTIONS | NO
SQL_API_SQLTABLEPRIVILEGES | NO


SQLGetInfo (Extension Level 1)

Information Type | Returns
SQL_ACCESSIBLE_PROCEDURES | 'Y' - SQLProcedures is unsupported.
SQL_ACCESSIBLE_TABLES | 'Y' - Can select on all tables returned by SQLTables.
SQL_ACTIVE_CONNECTIONS | 0 - Maximum number of active connections that the driver can support (0 means no limit) .
SQL_ACTIVE_STATEMENTS | 0 - Maximum number of active statements on a given connection (0 means no limit)
SQL_ALTER_TABLE | 0X0000 - A bitmask indicating how the columns of a table can be altered
SQL_BOOKMARK_PERSISTENCE | 0x0000 - A bitmask indicating persistence of bookmarks. The adapter does not support bookmarks
SQL_COLUMN_ALIAS | 'N' - The adapter does not support column aliasing.
SQL_CONCAT_NULL_BEHAVIOR | SQL_CB_NON_NULL - The result is the concatenation of non-null valued column or columns.
SQL_CONVERT_XXXXXXXXX | 0X0000 - The adapter does not support the Convert Scalar Function
SQL_CONVERT_FUNCTIONS | 0X0000 - The adapter does not support the Convert Scalar Functions.
SQL_CORRELATION_NAME | SQL_CN_ANY - The correlation name can be any user-defined name.
SQL_CURSOR_COMMIT_BEHAVIOR | SQL_CB_CLOSE - Close cursor after a commit operation. Cursors are unsupported.
SQL_CURSOR_COMMIT_BEHAVIOR | SQL_CB_CLOSE - Close Cursor after a rollback operation. Cursors are unsupported.
SQL_DATA_SOURCE_NAME | The data source name.
SQL_DATA_SOURCE_READONLY | 'Y'
SQL_DATABASE_NAME | See SQL_CURRENT_QUALIFIER
SQL_DBMS_NAME | This returns MOServer@ServerName. ServerName is obtained from a standard WBEM class
SQL_DBMS_VER | This returns the version number of the MO Server. This can be obtained from a standard WBEMclass
SQL_DEFAULT_TXN_ISOLATION | 0x0000 - The adapter does not support transactions
SQL_DRIVER_HDBC | Implemented by the Driver Manager. It returns the adapter's connection handle.
SQL_DRIVER_HENV | Implemented by the Driver Manager. It returns the adapter's environment handle.
SQL_DRIVER_HLIB | Implemented by the Driver Manager. The library handle returned to the Driver Manager when it loaded the adapter library.
SQL_DRIVER_HSTMT | Implemented by the Driver Manager. It returns the adapter's statement handle.
SQL_DRIVER_NAME | WBEM DR32.DLL
SQL_DRIVER_ODBC_VERSION | "02.10.0000"
SQL_EXPRESSION_IN_ORDERBY | "n" - The adapter does not support expressions in the ORDER BY clause
SQL_FETCH_DIRECTION | 0x0000 - The adapter does not support cursors.
SQL_FILE_USAGE | SQL_FILE_NOT_SUPPORTED - The adapter is not a single-tier adapter
SQL_GETDATA_EXTENSIONS | SQL_GD_ANY_COLUMN | SQLGD_ANY_ORDER | SQL_GD_BOUND
SQL_GROUP_BY | SQL_GROUP_BY_NOT_SUPPORTED. The Core SQL Grammar does not require support for GROUP BY.
SQL_IDENTIFIER_CASE | SQL_IC_MIXED - This means identifiers are case insensitive and are stored in the system catalog in mixed case, which is how WBEM treats class and property names.
SQL_IDENTIFIER_QUOTE_CHAR | "\""
SQL_KEYWORDS | "" - No data source-specific keywords
SQL_LIKE_ESCAPE_CLAUSE | "N" - No escape support for % and _ in a LIKE predicate.
SQL_LOCK_TYPES | 0x0000
SQL_MAX_BINARY_LITERAL_LEN | 0L - No limit on a binary literal in a SQL statement.
SQL_MAX_CHAR_LITERAL_LEN | Set to 255.
SQL_MAX_COLUMN_NAME_LEN | 0 - no limit.
SQL_MAX_COLUMNS_IN GROUP_BY | 0 - No limit. Does not matter, as GROUP BY is not supported.
SQL_MAX_COLUMNS_IN_INDEX | 0 - No limit. Does not matter, as indexes are not supported.
SQL_MAX_COLUMNS_IN_ORDER_BY | Set to 20.
SQL_MAX_COLUMNS_IN_SELECT | 0 - No limit on the number of columns in a select.
SQL_MAX_COLUMNS_IN_TABLE | 0 - No limit on the number of columns in a table.
SQL_MAX_CURSOR_NAME_LEN | Set to 19.
SQL_MAXINDEX_SIZE | 0 - No limit
SQL_MAX_OWNER_NAME_LEN | 0 - No limit
SQL_MAX_PROCEDURE_NAME_LEN | 0 - No limit. Does not matter, as the adapter does not support procedures.
SQL_MAX_QUALIFIER_NAME_LEN | 0 - No limit.
SQL_MAX_ROW_SIZE | 0 - No limit.
SQL_MAX_ROW_SIZE_INCLUDES_LONG | "Y" - The maximum row size returned by SQL_MAX_ROW_SIZE includes the length of SQL_LONG_VARCHAR and SQL_LONGVARBINARY
SQL_MAX_STATEMENT_LEN | 0L - No limit on the size of a SQL Statement.
SQL_MAX_TABLE_NAME_LEN | 128
SQL_MAX_TABLES_IN_SELECT | 0 - No limit on the number of tables in select statement.
SQL_MAX_USER_NAME_LEN | Set to 63.
SQL_MULT_RESULT_SETS | "N" - The adapter does not support multiple result sets.
SQL_MULTIPLE_ACTIVE_TXN | "N" - Does not matter, as transactions are not supported.
SQL_NEED_LONG_DATA_LEN | "N" - Need to check into this.
SQL_NON_NULLABLE_COLUMNS | SQL_NNC_NON_NULL
SQL_NULL_COLLATION | SQL_NC_LOW - NULLs are sorted at the low end of a list.
SQL_NUMERIC_FUNCTIONS | 0x0000 - The adapter does not support scalar numeric functions.
SQL_ODBC_API_CONFORMANCE | SQL_OAC_LEVEL
SQL_ODBC_SAG_CLI_CONFORMANCE | SQL_OSCC_COMPLIANT
SQL_ODBC_SQL_CONFORMANCE | SQL_OSC_MINIMUM (in spite of not supporting CREATE, and so forth.)
SQL_ODBC_OPT_IEF | "N" - The adapter does not support Integrity Enhancement Facility.
SQL_DRIVER_VER | "01.00.0000"
SQL_ORDER_BY_COLUMNS_IN_SELECT | "N" - The columns in the ORDER BY clause do not need to be in the select list.
SQL_OUTER_JOINS | "N" - The data source does not support outer joins
SQL_OWNER_TERM | "" - This is a character string with the data source vendor's name for an owner.
SQL_OWNER_USAGE | 0x0000 - The owner is not supported in any statements.
SQL_POS_OPERATIONS | 0x0000 - Does not have cursors.
SQL_POSITIONED_STATEMENTS | 0x0000 - Does not have cursors.
SQL_PROCEDURE_TERM | "" - The adapter does not support procedures.
SQL_PROCEDURES | "N" - The adapter does not support procedures.
SQL_QUALIFIER_LOCATION | SQL_QL_START - The qualifier comes first in a qualified table name; for example, we say Wellfleet.TcpConnectionTable, and not TcpConnectionTable.Wellfleet
SQL_QUALIFIER_NAME_SEPARATOR | "."
SQL_QUALIFIER_TERM | "Namespace"
SQL_QUALIFIER_USAGE | SQL_QU_DML_STATEMENTS, at least. For example, in all DML statements to allow it in SELECTs. You can use the logical OR with SQL_QU_PROCEDURE_INVOCATION and SQL_QU_TABLE_DEFINITION and SQL_QU_INDEX_DEFINITION, but since the adapter does not support procedures, table creation, or indexes, these items are not relevant.
SQL_QUOTED_IDENTIFIER_CASE | SQL_IC_MIXED - Quoted identifiers are case-insensitive, and are stored in mixed case.
SQL_ROW_UPDATES | "N" - The adapter does not support scrollable cursors.
SQL_SCROLL_CONCURRENCY | 0x0000 - The adapter does not support scrollable cursors.
SQL_SCROLL_OPTIONS | 0x0000 - The adapter does not support scrollable cursors.
SQL_SEARCH_PATTERN_ESCAPE | "\" is a search pattern escape character for % and _.
SQL_SERVER_NAME | "" - Unnecessary
SQL_SPECIAL_CHARACTERS | "" - This is a string that contains all the special characters (such as characters not in a-z, A-Z, 0-9) that can be included in a table name.
SQL_STATIC_SENSITIVITY | 0x0000 - The adapter does not support cursors.
SQL_STRING_FUNCTIONS | 0x0000 - The adapter does not support scalar string functions.
SQL_SUBQUERIES | 0x0000 - The adapter does not support sub-queries in predicates.
SQL_SYSTEM_FUNCTIONS | 0x0000 - The adapter does not support system scalar functions.
SQL_TABLE_TERM | "Class"
SQL_TIMEDATE_ADD_INTERVALS | 0x0000 - The adapter does not support the TIMESTAMPADD Scalar function.
SQL_TIMEDATE_DIFF_INTERVALS | 0x0000 - The adapter does not support the TIMESTAMPDIFF Scalar function.
SQL_TIMEDATE_FUNCTIONS | 0x0000 - The adapter does not support the TIMESTAMPXXXX Scalar functions.
SQL_TXN_CAPABLE | SQL_TC_NONE - The adapter does not support transactions.
SQL_TXN_ISOLATION_OPTION | 0x0000 - The adapter does not support transactions.
SQL_UNION | 0x0000 - The Data Source does not support the UNION clause.
SQL_USER_NAME | "" - Not applicable.


SQLGetStatementOption (Extension Level 1)

Option | Values
SQL_ASYNC_ENABLE | SQL_ASYNC_ENABLE_ON - Call any SQL functions on this statement asynchronously. SQL_ASYNC_ENABLE_OFF - Call any SQL functions on this statement synchronously. This is the default.
SQL_BIND_TYPE | The adapter does not support SQLExtendedFetch, so calling the function with this option returns an error.
SQL_CONCURRENCY | The adapter does not support cursors, so calling the function with this option returns an error (SQL_ERROR). The client can then invoke SQLError to determine the cause. SQLError informs the client that the adapter does not support this facility
SQL_CURSOR_TYPE | The adapter does not support cursors, so calling the function with this option returns an error (SQL_ERROR). The client can then invoke SQLError to determine the cause. SQLError informs the client that the adapter does not support this facility
SQL_KEYSET_SIZE | The adapter does not support cursors, so calling the function with this option returns an error (SQL_ERROR). The client can then invoke SQLError to determine the cause. SQLError informs the client that the adapter does not support this facility
SQL_MAX_LENGTH | 0 - No limit. This is intended for use in two-tier adapters where the client wants to limit the maximum size of data returned from a binary or character column in order to reduce network traffic. It supported only if the data source supports it. The adapter does not support this option.
SQL_MAX_ROWS | 0 - This is similar to SQL_MAX_LENGTH in that it is used in two-tier systems to reduce network traffic. In this case, however, the client is limiting the number of rows. The adapter does not support this option.
SQL_NOSCAN | QL_NOSCAN_OFF - The adapter scans statements for escape clauses.
SQL_QUERY_TIMEOUT | The number of seconds to wait for a query to execute without returning to the caller.
SQL_RETRIEVE_DATA | The adapter does not support cursors, so calling the function with this option returns an error (SQL_ERROR). The client can then invoke SQLError to determine the cause. SQLError informs the client that the adapter does not support this facility.
SQL_ROWSET_SIZE | The adapter does not support cursors, so calling the function with this option returns an error (SQL_ERROR). The client can then invoke SQLError to determine the cause. SQLError informs the client that the adapter does not support this facility.
SQL_SIMULATE_CURSOR | The adapter does not support cursors, so calling the function with this option returns an error (SQL_ERROR). The client can then invoke SQLError to determine the cause. SQLError informs the client that the adapter does not support this facility.
SQL_USE_BOOKMARKS | The adapter does not support cursors, so calling the function with this option returns an error (SQL_ERROR). The client can then invoke SQLError to determine the cause. SQLError informs the client that the adapter does not support this facility.


SQLGetTypeInfo (Extension Level 1)

WBEM uses variants exclusively to return property values. Thus, the base types that the ODBC adapter must support are the variant types. In addition, WBEM defines the SYNTAX attribute (borrowed from COM) to attribute extra semantics to the type in addition to those semantics the variant type provides. For example, the variant type can be BSTR and the SYNTAX IpAddress, indicating that the variant BSTR is, in fact, an IP address.


SQLTables (Extension Level 1)

SQLTables returns a list of table names stored in a specific data source. The information is returned in a result set. This function can also be used to enumerate either the table qualifiers in the data source or the owners in a given data source. In the case of the adapter supporting SNMP, qualifiers correspond to devices. Thus, a client can use this function to enumerate the devices supported by the data source. In fact, this is what MSQuery does to list the available databases in its Add Table dialog box.

An extra column is added to the SQLTables result set. This extra column is used to return the table metadata. The format of the metadata is identical to that returned by SQLColumns.


DMI Provider

DMI Support

The Web-Based Enterprise Management (WBEM) Software Development Kit (SDK) includes a single DMI provider that integrates into WBEM the modeling and manipulation of DMI information. The DMI provider gives WBEM applications the ability to interact with the DMI 2.0 Service Providers running on the local or remote platforms. For additional information, see DMI provider.

For additional information on DMI, visit the DMTF website at http://www.dmtf.org.


DMI Provider

The WBEM SDK includes a single DMI provider capable of acting as:

  • A dynamic class provider that enumerates all classes in the DmiNodes namespace and generates class definitions.
  • An instance provider that enumerates all instances of a particular class in the DmiNodes namespace.
  • An event provider that provides DMI events for the DmiNodes namespace.

A WBEM namespace must be created for each managed node. Each node's namespace resides in the \Default\DmiNodes namespace.

The DMI provider manipulates CIM class definitions. Therefore, the DMI Management Information Format (MIF) Components, Groups, and Attributes map to CIM classes, instances, and properties, respectively. For more information on how this mapping is done, see Mapping DMI to the CIM Schema

With the DMI provider, WBEM applications will be able to perform the following operations:

  • Access all DMI 2.0 Component, Group, and Attribute data.
  • Add and Delete DMI Components.
  • Add and Delete DMI Groups.
  • Add and Delete the Rows of a DMI tablular group.
  • Modify the writeable Attribute data.
  • Set the language mapping of a DMI Component.
  • Add or Delete Languages from a DMI Component.
  • Handle DMI Events.

The MOF file and executables for the DMI Provider are in the WBEM directory.

The software components of the DMI Provider are as follows:

DMI Provider Component | Description
WBEMDMIP.DLL | Main DMI Provider module responsible for schema translation, communication with WBEM and DMI, and construction of dynamic classes and instances.
WBEMDMIP.MOF | Sample MOF file shipped with the DMI Provider describing the DMI node namespace for the local node and registering the DMI Provider with WBEM.
MOTDMIENGINE.OCX | ActiveX Control used by the DMI Provider to establish communications and interactions with the DMI Service Providers.
WCDMI.DLL, WCDMIDCE.DLL, and WDMIUTIL.DLL | DLL modules used by MOTDMIENGINE.OCX to handle RPC connection and tear down with DMI 2.0 Service Providers on the local and remote nodes.


Setting Up the DMI Provider

To set up the DMI provider
  1. Create a MOF file.
  2. Create the \DmiNodes namespace. To create a namespace, create an instance of the __NAMESPACE class. The \DmiNodes namespace must reside in the \Root namespace:
    #pragma namespace("\\\\.\\root")
instance of __Namespace
{
Name = "DmiNodes";
};
  3. Create a namespace for each managed node under DmiNodes. Each namespace representing a DMI node must include a class and an instance that describes the node, as well as instances of the required provider registration class.
    #pragma namespace("\\\\.\\root\\DmiNodes")
instance of __NameSpace
{
Name = "ManagedNode1";    // Logical name given to a
// remote node
};
  4. Create the class DmiNode. This class must have the qualifier singleton and the string property called "NetworkAddress":
    [singleton]
class DmiNode
{
string NetworkAddress;
};
  5. Create an instance of DmiNode. Set the NetworkAddress property to the network name or address of the managed node:
    instance of DmiNode
{
// Network address for ManagedNode1 or its machine name
NetworkAddress = "206.170.168.35"
};
  6. Create an instance of __Win32Provider to register the DMI provider to handle class and instance operations for the node created above:
    #pragma namespace("\\\\.\\root\\DmiNodes\\ManagedNode1")
instance of __Win32Provider As $Provider
{
Name = "WbemDmip" ;    // Provider DLL name
ClsId = "{DE065A70-19B5-11D1-B30C-00609778D668}" ;
};
  7. Create an instance of __InstanceProviderRegistration to tell the Common Information Model Object Manager (CIMOM) that the provider supports instance operations:
    {
Provider = $Provider;
SupportsGet = TRUE;
SupportsPut = TRUE;
SupportsDelete = TRUE;
SupportsEnumeration = TRUE;
};
  8. Create an instance of __MethodProviderRegistration to tell CIMOM that the provider handles methods:
    instance of __MethodProviderRegistration
{
    Provider = $Provider;
};
  9. Create an instance of __ClassProviderRegistration to tell CIMOM that the provider supports class operations:
    instance of __ClassProviderRegistration
{
  Provider = $Provider;
  SupportsGet = TRUE;
  SupportsPut = FALSE;
  SupportsDelete = TRUE;
  SupportsEnumeration = TRUE;
  QuerySupportLevels = NULL ;
ResultSetQueries = {
"Select * From meta_class Where __this isa \"DmiComponent\"" ,
"Select * From meta_class Where __this isa   \"DmiGroupRoot\"" ,
"Select * From meta_class Where __this isa \"DmiBindingRoot\"" ,
"Select * From meta_class Where __this isa \"DmiNodeData\"" ,
"Select * From meta_class Where __this isa \"DmiLanguage\"" ,
"Select * From meta_class Where __this isa \"DmiEvent\"" ,
"Select * From meta_class Where __this isa \"DmiAddMethodParams\"" ,
"Select * From meta_class Where __this isa \"DmiGetEnumParams\"" ,
"Select * From meta_class Where __this isa \"DmiLanguageMethodsParams\""
} ;
} ;
};
  10. Create an instance of __Win32Provider to tell CIMOM that the provider supports events:
    instance of __Win32Provider as $EventProv
{
    Name = "WbemDmiEventp" ;
    ClsId =  "{B21FBFA0-1B39-11d1-B317-00609778D668}";
};
  11. Create an instance of __EventProviderRegistration to tell CIMOM the types of events that the provider can handle:
    Instance of __EventProviderRegistration
{
 Provider = "WbemDmiEventp";
 EventQueryList = {
  "select * from DmiEvent",
"select * from __InstanceCreationEvent where TargetInstance is a \"DmiComponent\"",
"select * from __InstanceDeletionEvent where TargetInstance is a \"DmiComponent\"",
"select * from __InstanceCreationEvent where TargetInstance is a \"DmiLanguage\"",
"select * from __InstanceDeletionEvent where TargetInstance is a \"DmiLanguage\""
"select * from __ClassCreationEvent where TargetInstance is a \"DmiGroupRoot\""
"select * from __ClassDeletionEvent where TargetInstance is a \"DmiGroupRoot\""

 };
};

    Alternately, you can use the WBEM Developer Studio to create namespaces and the required class and instance definitions. For instructions, see the WBEM SDK Applications Guide for instructions. See the sample MOF file WBEMDMIP.MOF included with the WBEM SDK.

  12. After you create a MOF for a managed node, you must submit the file to WBEM's MOF compiler.
    mofcomp  <MOF-file>


Mapping DMI To The CIM Schema

The WBEM DMI Provider uses the following schema to represent the MIF component group attribute information:

DmiNode
Static class defined in MOF. Used to establish the network address of the managed node.
DmiNodeData
Dynamic singleton class with a dynamic instance. Contains DmiGetConfig data. Has methods that allow you to add and delete components, and set the default language.
DmiComponent
A dynamic class with dynamic instances. Contains component and component ID group data. Has methods that allow you to add a group, add and delete a language, and extract the component ID group attribute enumeration.
DmiLanguage
A dynamic class with dynamic instances. Contains language data.
DmiGroupRoot
This is an abstract class that does not have any instances. All dynamic group classes are derived from this class.
Dynamic DmiGroup Classes
A dynamic class is created for each group on the managed node. Each dynamic group class is given a name in the form:
Component<Component Id>__Group<Group Id>__<Class String>.

A dynamic instance is created for each row of a tabular group. For a scalar group, only one instance is created.

DmiBindingRoot
This is an abstract class from which all bindings in the namespace are derived. The classes derived from DmiBindingRoot are used to bind a DmiComponent class to a DmiNode class, a DmiGroup class to a DmiComponent class, and so on.
DmiLanguageBinding
Instances of this dynamic class bind DmiLanguage instances to instances of DmiComponent.
Dynamic DmiGroupBinding Classes
A dynamic group binding class is created for each group on the managed node. Each dynamic group binding class is given a name in the form:
Component<Component Id>__Group<Group Id>__<Class String>__Binding.

Dynamic instances of these classes are created for each row of a tabular group. For a scalar group, only one instance is created. An instance of a dynamic group binding class binds an instance of a dynamic group class to an instance of a DmiComponent.

DmiAddMethodParams
Instances of this dynamic class contain the parameters required by the add language, add group, and delete language methods.
DmiGetEnumParams
Instances of this dynamic class contain the parameters required by the get attribute enumeration method.
DmiEnum class
A dynamic class created for attribute enumeration. Instances of this class contain the value string pair of a DMI attribute's enumeration.
DmiLanguageMethodParams
Instances of this dynamic class are used in setting the default language.
DmiEvent
Instances of this dynamic class are generated when a DMI event is generated.


DMI Operations Using WBEMDMIP.DLL

This section briefly describes the WBEM methods used for common DMI management tasks. See the DMITEST sample application included in this SDK for an example of how to use the DMI access methods.

DmiGetVersion
Use IWbemServices::CreateInstanceEnum with the class set to the singleton instance of DmiNodeData.
DmiGetConfig
Use IWbemServices::GetObject with the path for the singleton instance of DmiNodeData.
DmiSetConfig
Use the IWbemServices::ExecMethod with the path for the singleton instance of DmiNodeData, the method SetDefaultLanguage, and the instance of DmiLanguageMethodParams with the Language property set to the desired language string.
DmiListComponents
Use the IWbemServices::CreateInstanceEnum method with the class set to DmiComponent.
DmiListLanguages
Use the IWbemServices::CreateInstanceEnum method with the class set to DmiLanguage.
DmiListGroups
Use the IWbemServices::CreateClassEnum method with the superclass set to DmiGroupRoot.
DmiListAttributes
Use the IWbemServices::GetObject method with the path set to the desired instance of the desired dynamic group class.
DmiGetAttribute
Use the IWbemServices::GetObject method with the path set to the desired instance of the desired dynamic group class.

Note This gives you all the attributes in the group. There is no way to access just one attribute. Once you get the object that contains all the attributes, you can perform the Get operations on the object to get the class property representing a given DMI attribute.

DmiSetAttribute
Use the IWbemServices::GetObject method with the path set to the desired instance of the desired dynamic group class. Use the WBEM's PUT method on the object to modify the instance returned, then use IWbemServices::PutInstance.
DmiGetMultiple
Use the IWbemServices::GetObject method with the path set to the desired instance of the desired dynamic group class.

Note This gives you all the attributes in the group.

DmiSetMultiple
Use the IWbemServices::GetObject method with the path set to the desired instance of the desired dynamic group class. Modify the instance returned. Then use IWbemServices::PutInstance.
DmiAddRow
Use the IWbemServices::GetObject method with the path set to the desired instance of the desired dynamic group class. Modify the instance returned then use IWbemServices::PutInstance.

Note The RowId property must be changed to a nonexistent RowId.

DmiDeleteRow
Use the IWbemServices::DeleteInstance with the path set to the desired dynamic instance of the dynamic class.
DmiAddComponent
Use the IWbemServices::ExecMethod with the path for the singleton instance of DmiNodeData, the method of AddComponent, and the MifFile property of the instance of the DmiAddMethodParams set to the desired MIF file path.
DmiAddLanguage
Use the IWbemServices::ExecMethod with the path to the instance of the component to which the language is to be added. Set the method to AddLanguage, and the MifFile property of the instance of the DmiAddMethodParams set to the desired MIF file path.
DmiAddGroup
Use the IWbemServices::ExecMethod with the path to the instance of the component to which the language is to be added. Set the method to AddGroup, and the MifFile property of the instance of the DmiAddMethodParams set to the desired MIF file path.
DmiDeleteComponent
Use IWbemServices::DeleteInstance with the path set to the desired dynamic instance of the DmiComponent class.
DmiDeleteLanguage
Use the IWbemServices::ExecMethod with the path to the instance of component to which the language is going to be deleted. Set the method to DeleteLanguage, and the Language property of the instance of the DmiLanguageMethodParams set to the language string to be deleted.
DmiDeleteGroup
Use IWbemServices::DeleteClass with the path set to the desired dynamic group class.


DMITEST Code Sample

This section describes the dmitest code sample (DMITEST.EXE), a Win32 console application that uses the WBEM API to access and manipulate a DMI 2.0 enabled Win32 platform. The sample includes examples of DMI 2.0 MIF files that will be used to install components in the DMI database.

The same code reads input data from a script file, DMITEST.SCR, processes the command script, and makes appropriate WBEM API calls to access the DMI database. The application then will store the output data into a file called DMITEST.OUT.

The DMITEST application relies on the user to ensure that the DMI 2.0 Service Provider is already running on the system and that the WBEMDMIP.MOF file has already been compiled and installed into the CIMOM's repository to enable DMI operations.

The DMITEST code sample was developed using Microsoft Visual C++ version 5.0, and is in the \WBEM\SDK\COM\DMITEST directory.

The DMITEST' s MIF data

The application uses the MIF files DBTYPES1.MIF and TEMPCOM1.MIF to install three components in the DMI database and access them through the DMI provider. The DBTYPES1.MIF is installed twice.

The DMITEST.SCR script uses hard-coded path of C:\TESTMIFS for the location of the above two MIF files. To access the MIF files from a different directory, change the DMITEST.SCR file to look for the correct path.

The files included in this sample

Sample File | Description
DMITEST.CPP | Main source file for the DMITEST application responsible for reading and processing command scripts from the DMITEST.SCR input file and submitting DMI requests to WBEM.
DMITEST.H | Header file for DMITEST.CPP module.
DMITEST.SCR | Containing the DMI command scripts processed by the DMITEST application.
DMITEST.OUT | DMITEST application generated output file containing the results from executing the DMI service requests.
DATATYPES.CPP | Code for manipulating the OLE data types used by DMITEST.CPP.
DATATYPES.H | Header file for DATATYPES.CPP.
DEFINES.H | Header file of definitions used to turn off some sections of the WINDOWS.H header file not used by the application.
WBEMSVC.H | Header file containing the CIMOM interface definitions.
DBTYPES1.MIF | MIF file used to install a DMI component called "First Database Types MIF."
TEMPCOM1.MIF | MIF file used to install a DMI component called "Test System Temporary Component."
DMITEST.DSP, DMITEST.DSW | Visual C++ 5.0 project file used to build the DMITEST.EXE executable.

To build the DMITEST module
  1. Run the Microsoft Visual C++ 5.0 Development Studio program.
  2. Load the DMITEST.DSP project file.
  3. From the BUILD menu, select SETTINGS. Choose the Preprocessor option from the C/C++ Tabbed dialog box. Set the Additional Include Directory entry to the INCLUDE directory of the WBEM SDK installed on your system.
  4. Replace the WBEMUUID.LIB module in the project files list with the one in the LIB directory of the WBEM SDK installed on your system.
  5. From the BUILD menu, select UPDATE ALL DEPENDENCIES.
  6. Rebuild the project to generate the DMITEST.EXE module.
  7. Verify that DMITEST.SCR file is in the same directory as the DMITEST.EXE module.
  8. Run the DMITEST application and view DMITEST.OUT file for the results after the program terminates.
  9. Open the DMITEST.CPP module and set breakpoints on the ProcessScriptFile( ) function, run the DMITEST application again, and observe how the application accesses DMI information through WBEM.


SNMP Support


Introduction to SNMP Support

The Simple Network Management Protocol (SNMP) uses a distributed architecture consisting of several nodes (network devices such as hosts, routers, terminal servers, and so on), and one or more management stations. Management stations run applications that monitor and control the nodes. Each node includes a processing element, called an agent, that retrieves and updates local management information based on requests from the management stations. The agent also notifies management stations when significant events occur. Management information about the nodes is stored as a collection of managed objects in a database called the Management Information Base (MIB). SNMP communicates management information between the management stations and the agents.

The Web Based Enterprise Management (WBEM) SDK includes the following components to support SNMP:

  • Two SNMP providers, a dynamic instance provider and a dynamic class provider, that seamlessly integrate the modeling and manipulation of SNMP information into WBEM. For additional information, see SNMP Providers.
  • An SNMP information module compiler that compiles native SNMP schema information defined in MIBs into the equivalent Common Information Model (CIM) schema. For additional information, see SNMP Information Module Compiler and Mapping SNMP to the CIM Schema.

Because the SNMP providers manipulate CIM class definitions, they also provide mapping between MIB object values and CIM class instance values. For more information on how this mapping is done, see Mapping SNMP to the CIM Schema.

For a list of documents that provide more information on SNMP, see Additional Reading on SNMP.


Additional Reading on SNMP

The documents listed in the following topics provide additional information about SNMP.


Internet Engineering Task Force (IETF) Documents

The following tables list Internet Engineering Task Force (IETF) Request for Comments (RFC) describing SNMPv1 and SNMPv2C. All of these documents can be freely obtained from ftp://ds.internic.net/rfc.

SNMPv1 Documents

RFC number | Title and author
RFC 1155 | Rose, M., and K. McCloghrie. "Structure & Identification of Management Information for TCP/IP-based Internets." May 1990.
RFC 1157 | Case, J., M. Fedor, M. Schoffstall, and J. Davin. "A Simple Network Management Protocol." May 1990.
RFC 1212 | Rose, M., and K. McCloghrie. "Concise MIB Definitions." March 1991.
RFC 1213 | McCloghrie, K., and M. Rose. "Management Information Base for Network Management of TCP/IP-based Internets: MIB-II." March 1991.
RFC 1215 | Rose, Marshall, ed. "A Convention for Defining Traps for Use with SNMP." March 1991.

SNMPv2C Documents

RFC number | Title and author
RFC 1901 | Case, J., K. McCloghrie, M. Rose, and S. Waldbusser. "Introduction to Community-based SNMPv2." January 1996.
RFC 1902 | Case, J., K. McCloghrie, M. Rose, and S. Waldbusser.. "Structure of Management Information for Version 2 of the Simple Network Management Protocol." January 1996.
RFC 1903 | Case, J., K. McCloghrie, M. Rose, and S. Waldbusser. "Textual Conventions for Version 2 of the Simple Network Management Protocol." January 1996.
RFC 1904 | Case, J., K. McCloghrie, M. Rose, and S. Waldbusser. "Conformance Statements for Version 2 of the Simple Network Management Protocol." January 1996.
RFC 1905 | Case, J., K. McCloghrie, M. Rose, and S. Waldbusser. "Protocol Operations for Version 2 of the Simple Network Management Protocol." January 1996.
RFC 1906 | Case, J., K. McCloghrie, M. Rose, and S. Waldbusser. "Transport Mappings for Version 2 of the Simple Network Management Protocol." January 1996.
RFC 1907 | Case, J., K. McCloghrie, M. Rose, and S. Waldbusser. "Management Information Base for Version 2 of the Simple Network Management Protocol." January 1996.
RFC 1908 | Case, J., K. McCloghrie, M. Rose, and S. Waldbusser. "Coexistence between Version 1 and 2 of the Internet-standard Network Management Framework." January 1996.


SNMP Publications

The following list contains a selection of commercial publications on SNMP:

  • Rose, Marshall T. The Simple Book: An Introduction to Network Management. 2d ed. Prentice Hall, 1994.
  • Stallings, William. SNMP, SNMPv2 and CMIP: The Practical Guide to Network Management Standards. Addison Wesley, 1993.
  • Hein, Mathias, and David Griffiths. SNMP Versions 1 and 2: Simple Network Management Protocol Theory & Practice. Thomson Computer Press, 1995.
  • Perkins, David. Understanding SNMP MIBs. Prentice Hall, 1996.
  • Feit, Dr. Sidnie M. SNMP: A Guide to Network Management. McGraw-Hill, 1995.


SNMP Providers

The Web-Based Enterprise Management (WBEM) SDK includes two Simple Network Management Protocol (SNMP) providers:

  • An instance provider that enumerates all instances of a particular class in a namespace.
  • A dynamic class provider that enumerates all classes in a particular namespace and generates class definitions.

A WBEM namespace can be created that represents an SNMP Management Information Base (MIB) view associated with an SNMP agent. By creating such namespaces and registering the SNMP providers in each namespace, WBEM applications can access both static and dynamic SNMP information in a Common Information Model (CIM) schema.


Setting Up the SNMP Providers

Û To set up the SNMP providers
  1. Create a namespace for each MIB view associated with a network device.
  2. Register the SNMP providers in each of the namespaces created in step 1.

The following topics describe each of these steps.


Creating an SNMP Namespace

You create a namespace by creating an instance of the __NAMESPACE class. The namespace must include implementation-specific context information. For the SNMP providers, this context information consists of transport properties that define how the providers access an SNMP agent. The namespace, together with its context, defines a view of a network device.

Context information is stored within a namespace as a set of class qualifiers. The following table shows the context qualifiers for the SNMP providers. Note that in the current release, only one of these qualifiers, AgentAddress, is mandatory.

Namespace class qualifier | Type | Description | Default value | Comments
AgentAddress | string | Mandatory. Transport address associated with the SNMP agent. | None | Specify a valid unicast host address or a domain host name that can be resolved through the operating system's domain-name-resolution process.
AgentTransport | string | Optional. Transport protocol used to communicate with the SNMP agent. | IP | Currently the only valid value is IP.
AgentReadCommunityName | string | Optional. Optional. The SNMP community name access string that the SNMP agent uses to authenticate an SNMP PDU during a read operation. | public | An SNMP community name is a variable-length octet string that must be mapped to a unicode string representation. It is, therefore, a limitation of the SNMP providers that community names be restricted to alphanumeric characters.
AgentWriteCommunityName | string | Optional. The SNMP community name access string that the SNMP agent uses to authenticate an SNMP PDU during a write operation | public | An SNMP community name is a variable-length octet string that must be mapped to a unicode string representation. It is, therefore, a limitation of the SNMP providers that community names be restricted to alphanumeric characters.
AgentRetryCount | int32 | Optional. The number of times a single SNMP request can be retried when there is no response from the SNMP agent before the request is deemed to have failed. | 1 | Specify an integer between 0 and 2^32-1. You must perform the twos-complement operation to generate signed integer representation.
AgentRetryTimeout | int32 | Optional. The time, in milliseconds, to wait for a response to an SNMP request sent to the SNMP agent. | 500 | Specify an integer between 1 and 2^32-1. You must perform the twos-complement operation to generate signed integer representation.
AgentVarBindsPerPdu | int32 | Optional. Every SNMP request sent to the SNMP agent contains one or more SNMP variables. This parameter specifies the largest number of variables that may be included in a single request. | 10 | Specifying zero causes the implementation to determine the optimal variable bindings. Otherwise, specify an integer between 1 and 2^32-1. You must perform the twos-complement operation to generate signed integer representation. Note that while increasing this value can improve performance, some agents and/or networks cannot deal with the resulting request.
AgentFlowControlWindowSize | int32 | Optional. The maximum number of concurrently outstanding SNMP requests that can be sent to this agent while a response has not been received. A large window size generally improves performance, but some agents might not work well under a heavy load. | 10 | Specifying zero indicates an infinite window size. Otherwise, specify a value between 1 and 2^32-1. You must perform the twos-complement operation to generate signed integer representation.
AgentSNMPVersion | string | Optional. The version of the SNMP protocol to be used when communicating with the SNMP agent. | 1 | Currently, the only valid value is 1 (for SNMPv1).

To create a namespace
  1. Create an instance of the __NAMESPACE class.
  2. Define the AgentAddress qualifier for the newly-created namespace instance.
  3. Define other context qualifiers, if desired.

You can use the CIM Studio to create namespaces and to define context qualifiers. See the WBEM SDK Applications Guide for instructions.


Registering the SNMP Providers

The SNMP providers must be registered in the CIM Object Manager (CIMOM) database. This is done by creating an instance of the class __Win32Provider for the provider in each namespace associated with that provider.

The instance provider is mandatory. The class provider is optional. Users can create their own static classes instead of, or in addition to, using the dynamic class provider.

To register the instance provider, create the following Managed Object Format (MOF) file and submit it to the MOF compiler:

instance of __Win32Provider
{
    MethodSet=331793;
    Provider="MS_SNMP_INSTANCE_PROVIDER";
    ProviderClsId="{D45BD3C1-EF23-11cf-8CBC-00AA00A4086C}";
};

To register the class provider, create the following MOF file and submit it to the MOF compiler:

instance of __Win32Provider
{
    MethodSet=332817;
    Provider="MS_SNMP_CLASS_PROVIDER";
    ProviderClsId="{3296BF00-A1FC-11cf-8C8B-00AA00A4086C}";
};

Alternatively, you can use the CIM Studio to create the instances, and to generate and compile the MOF file. See the WBEM SDK Applications Guide for instructions.


RFC MIBs

The WBEM SDK includes a set of SNMPv1 Request for Comments (RFC) MIBs (including MIB-II definitions, RFC 1213) that have been mapped to CIM schema definitions for use with the SNMP providers. The mapped information is in two forms:

  • Static MOF files

    These files are located in <Wbem-directory>\Snmp\Mofs\Snmpv1\Rfcs, where <Wbem-directory> is the directory in which WBEM is installed. To use these files for static class operation, they must first be loaded into CIMOM.

  • SMIR MOF files

    These files are located in <Wbem-directory>\Snmp\SMIR_MOFS\Snmpv1\Rfcs. To use these files for dynamic class operation, they must first be loaded into the SNMP Module Information Repository (SMIR) which is an SNMP schema database.

Note that the MIB text files are also included with the SDK in the <Wbem-directory>\Snmp\Mibs\Snmpv1 directory.

For instructions on loading MOF and SMIR MOF files into CIMOM or the SMIR, see Loading Static MOF Files and SMIR MOF Files.


Loading Static MOF Files and SMIR MOF Files

A static MOF file does not contain the name of its associated namespace, which must be specified when loading the file into CIMOM.

To load a static MOF file into a CIMOM namespace
  1. Create the namespace if you have not already done so. For instructions, see Creating an SNMP Namespace.
  2. Run the MOF compiler on the MOF file, specifying the namespace created in step 1. Use the following command:

    mofcomp -u <WBEM-user-name> -p <WBEM-password> -n:<object-path> <MOF-file>

    The object-path can be either relative to the current namespace or fully qualified (for example, \\myserver\root\mynamespace).

A SMIR MOF file contains the name of its associated namespace.

To load a SMIR MOF file into the SMIR

Run the MOF compiler on the SMIR MOF file using the following command:

mofcomp -u <WBEM-user-name> -p <WBEM-password> <SMIR-MOF-file>


Logging Support

The SNMP providers support logging to files and to the debugger. A number of registry keys and values define the level and type of logging currently being generated.


Enabling Logging

The following registry key is the parent of all logging-related information:

HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\WBEM\PROVIDERS\SNMP\LOGGING

The following values are associated with this key:

Value name | Data type | Description
LOGGING | REG_DWORD | One of the following integer values: '0' Default. Turns off all debugging output. '1' Enables debugging output.


SNMP Component Logging

The following registry key is the parent of all SNMP instance and class provider logging-related information:

HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\WBEM\PROVIDERS\SNMP\LOGGING\WBEMSNMP

The following values are associated with this key:

Value name | Data type | Description
Type | REG_SZ | Takes one of the following values: 'File' Default. Sends debugging output to a file. 'Debugger' Sends debugging output to the debugger.
File | REG_SZ | Defines the file name where the debugging output is sent when the logging Type is set to 'File'. The default value is 'c:\wbemsnmp.log'.
Level | REG_DWORD | Takes integer values from 0 through 2^32-1. The value is a logical mask consisting of 32 bits. The following bit masks are combined to define the type of debugging output generated: Bit/Description 0 SNMP class provider IWbemServices method invocations 1 SNMP class provider implementation 2 SNMP instance provider IWbemServices method invocations 3 SNMP instance provider implementation 4 SNMP class library 5 SNMP SMIR 6 SNMP correlator 7 SNMP type mapping code


SNMP Information Module Compiler

The Simple Network Management Protocol (SNMP) information module compiler compiles native SNMP management information defined in Management Information Bases (MIB) into the equivalent Common Information Model (CIM) schema definitions that can be used with the SNMP providers. This CIM schema can exist either as output in a Managed Object Format (MOF) file or it can be loaded directly into an SNMP schema database known as the SNMP Module Information Repository (SMIR). The SNMP dynamic class provider uses the SMIR to retrieve and instantiate class definitions automatically.

The SNMP compiler runs as a single executable file in command-line mode. It accepts as input one SNMP information module, plus any additional modules that might be required to resolve external references. An SNMP information module is a collection of management information that typically includes a combination of the following:

  • MIB modules (collections of related MIB objects).
  • AGENT-CAPABILITIES statements that describe an agent's minimal level of compliance to the set of MIB modules it supports.
  • MODULE-COMPLIANCE statements that describe the agent's capabilities with respect to object definitions.

SNMP information modules are written in a subset of the Abstract Syntax Notation One (ASN.1) language called the Structure of Management Information (SMI). The SNMP compiler loads data from an SNMP information module into the SMIR or creates an intermediate MOF file either in a format suitable for loading into the SMIR at a later date or in a format suitable for loading as static classes into a CIM Object Manager (CIMOM) namespace at a later date. A SMIR MOF file contains the name of its associated namespace. A static MOF file does not contain this information, and the namespace must be specified when loading the MOF file.

The compiler can also perform the following functions:

  • Perform checking operations on the information module, such as local syntax-checking, and checking external references against information in the subsidiary modules.
  • Remove all previously-loaded data from the SMIR, or remove data loaded from one information module.
  • Return the ASN.1 module name of a specified file or return the ASN.1 module names of all imported modules in a specified file.
  • Return the ASN.1 module names of all SNMP information modules currently loaded in the SMIR.
  • Perform automatic resolution of imported modules rather than requiring users to specify manually the required modules.
  • Perform a silent loading mode of operation that does not generate any output, but can be used to load data into the SMIR during an installation operation.


MIB Lookup Table

When parsing an SNMP MIB file, the compiler sometimes encounters definitions/declarations that are external to the file being processed. These definitions/declarations are specified in modules that are referenced by the IMPORTS statement in the file being processed. The compiler must access these modules and retrieve the definitions/declarations in order to complete the file processing.

The compiler maintains a lookup table in the registry that maps ASN.1 module names to MIB file locations. This lookup table allows you quickly to compile an information module without manually locating and specifying dependent files on the command line. When run in auto-resolution mode, the compiler uses the lookup table to locate the MIB files referenced by the IMPORTS statement. The compiler then processes these MIB files and any other modules that they reference to obtain a consistent set of definitions/declarations for use in processing the original SNMP MIB file.


Registry Configuration

All compiler configuration information stored in the registry is located under the root key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WBEM\PROVIDERS\SNMP\COMPILER

The following values are associated with this key:

Value name | Data type | Description | Default value at installation
File Path | REG_MULTI_SZ | An ordered list of strings, each specifying a directory in which the compiler searches for MIB files. The compiler searches from left to right. The directories are always stored as fully qualified path names. Relative path names in the registry are ignored. |
File Suffixes | REG_MULTI_SZ | An ordered list of file suffixes that the compiler uses to determine whether a file contains a MIB module. The ordering is significant when there are two files for the same MIB module in a directory and each of these files has a different extension. In this case, the file whose extension occurs first in this list is considered to be the file that corresponds to the MIB module. | mib

The following example shows sample registry entries for the SNMP compiler configuration settings described above:

There is a further subkey called MIB under the root key defined above. This subkey stores the MIB lookup table. For each MIB in the lookup table, a value is created and placed under this subkey. The name of the value is the ASN.1 module name of the MIB and the actual value is as defined below:

Value name | Data type | Description
MIB Module Name | REG_SZ | The full path name of the file containing the MIB module.

The following example shows sample registry entries for a MIB lookup table:


Running the SNMP Compiler

The syntax for running the compiler is as follows:

smi2smir options

Where:

options
Specifies the appropriate command-line options for the actions you want to perform. The available options are described in the next topic.


SNMP Compiler Options

The following table shows the SNMP compiler options. The arguments shown in these option descriptions are:

MIBfile(s)
Specifies the name of an SNMP information module file. The compiler accepts both SNMPv1 and SNMPv2C information modules. You can specify a file name, or specify an absolute or relative path name of a file. In addition to the main input file, you can also specify subsidiary files that can sometimes be required to resolve external references.
MIBdirectory
Specifies a directory to search for MIB files. This can also be an absolute or relative path.
modulename
Specifies the ASN.1 module name of an SNMP information module file. For example, RFC1213-MIB is the module name of the SNMP MIB commonly referred to as MIB-II.

Note also that there must be at least one space between an option and its arguments.

The SNMP compiler options are as follows:

Option | Description
/a [/auto] [/s] MIBfiles | Performs local syntax-checking, locates IMPORTS references automatically, and, if no errors are found, loads data into the SMIR. Specify /auto to repair the lookup table automatically, if necessary. Specify /s to prevent loading of text subclauses into the SMIR.
/auto Repairs the MIB lookup table, if necessary. When used with /a, /ec, /g, or /gc, this option automatically tries to rebuild the lookup table if any of the following conditions occur:
  • The lookup table cannot be found, or is corrupt. In this case, the compiler completely rebuilds the lookup table.
  • A module name referenced in an IMPORTS statement cannot be located in the lookup table. If the compiler locates the file, a new entry is added to the lookup table; otherwise, the compiler reports an error.
  • A MIB file name referenced in the lookup table cannot be found. The compiler removes the entry from the lookup table, and tries to locate the referenced file. If the file is located, the compiler adds it to the lookup table; otherwise, the compiler reports an error.
/c count | Specifies the maximum number of errors the compiler reports; count must be a positive decimal integer. If /c is not specified, there is no limit to the number of errors that can be reported.
/ch | Used with /g or /gc. Generates context information in the MOF file header. This information includes the command line, date and time, host name, user name, and process directory.
/d modulename | Deletes the specified information module from the SMIR.
/ec [/auto] MIBfiles | Performs local syntax-checking, locates IMPORTS references automatically, and reports any errors found. Specify /auto to repair the lookup table automatically, if necessary.
/g [/auto] [/s] [/ch] MIBfiles Performs local syntax-checking, locates IMPORTS references automatically, and writes a SMIR MOF file to the standard output. The SNMP class provider uses a SMIR MOF file to dynamically provide SNMP classes for one or more namespaces. Specify /auto to automatically repair the lookup table, if necessary. Specify /s to prevent loading of text subclauses into the MOF file. Specify /ch to generate context information in the MOF file header.

Use the /g option when you do not know which MIBs are supported by the SNMP devices being managed. The SNMP class provider checks the device at runtime for the presence of this MIB and supplies the classes dynamically to the namespace.

See Loading Static MOF Files and SMIR MOF Files for information on loading the MOF file into CIMOM.
/gc [/auto] [/s] [/ch] MIBfiles Same as /g, but generates a static MOF file which can be loaded as static classes in one or more namespaces.

Use the /gc option when you know which MIBs are supported by the SNMP devices being managed.

See Loading Static MOF Files and SMIR MOF Files for information on loading the MOF file into CIMOM.
/h | Displays help on the SNMP compiler syntax. Same as /?.
/i MIBdirectory | Adds the specified directory to the list of directories to search for dependent MIB modules. The /i option can appear multiple times on the command line; in this case, directories are searched in the order specified on the command line.
/l | Lists all modules in the SMIR.
/lc MIBfile | Performs local syntax-checking of the MIB file, but does not resolve IMPORTS references. The compiler reports any errors found.
/m diagnosticlevel Specifies one of the following levels:

0—Completely silent.

1—Reports fatal errors only.

2—Reports fatal errors and warning messages.

3—Reports fatal errors, warnings, and informational messages.

The default is 2.
/n MIBfile | Returns the ASN.1 module name of the specified information module.
/ni MIBfiles | Returns the ASN.1 module name of all IMPORTS modules referenced by the input file. The compiler does not try to determine second, or greater, level IMPORTS modules.
/p | Deletes all information modules from the SMIR.
/pa [MIBdirectory] Adds the directory to the list of directories in the registry and adds the information modules in this directory to the MIB lookup table. This is followed by an implicit /r operation.

If you do not specify a directory, the default is the current directory in which the compiler is being run.
/pd [MIBdirectory] Deletes the directory from the list of directories in the registry and deletes the information modules in this directory from the MIB lookup table. This is followed by an implicit /r operation.

If you do not specify a directory, the default is the current directory in which the compiler is being run.
/r | Rebuilds the lookup table.
/s | Does not load text subclauses into the SMIR or MOF file. When used with /a, /g, or /gc, this option generates the DESCRIPTION and REFERENCE subclauses of the OBJECT-TYPE macro as empty strings in the SMIR or MOF file. Use this option when minimizing storage requirements is important.
/sa [/auto] [/s] MIBfiles | Same as /a, but runs silently. The compiler tries to perform the /a operation but generates no error, warning, or information messages, even if the operation is unsuccessful.
/v1
/v2c 		Specifying /v1 compiles the module as an SNMPv1 information module. The compiler reports an error if it detects non-SNMPv1 statements.

Specifying /v2c compiles the module as an SMNPv2C information module. The compiler reports an error if it detects non-SNMPv2C statements.

The default is the union of SNMPv1 and SNMPv2C; as long as a MOF file can be generated or data can be loaded into the SMIR, no errors are reported.
/? Displays help on the SNMP compiler syntax. Same as /h.

For details on the error messages generated by the compiler, see SNMP Compiler Error Messages.


Loading MOF Files

The SNMP compiler can generate MOF files in a format suitable for loading into the SMIR, or in a format suitable for loading as static classes into a CIM namespace. A SMIR MOF file contains the name of its associated namespace. A static MOF file does not contain this information, and the namespace must be specified when loading the MOF file.

For instructions on loading MOF and SMIR MOF files, see Loading Static MOF Files and SMIR MOF Files.


SNMP Compiler Error Messages

This section describes the various error conditions that can result when the SNMP information module compiler parses a Management Information Base (MIB) module.

The error messages have three severity levels:

  • Fatal errors
  • Warnings
  • Information messages

The severity level is shown in parentheses at the beginning of the error message description.

See Also

General Information Messages

Running the SNMP Compiler

SNMP Compiler Options


Errors 101 through 110

Fatal Error 101

Fatal Error 102

Fatal Error 103

Fatal Error 104

Fatal Error 105

Fatal Error 106

Fatal Error 107

Fatal Error 108

Fatal Error 109

Warning 110

See Also

Running the SNMP Compiler

SNMP Compiler Options


Errors 201 through 210

Fatal Error 201

Fatal Error 202

Fatal Error 203

Fatal Error 204

Fatal Error 205

Fatal Error 206

Fatal Error 207

Information Message 208

Fatal Error 209

Fatal Error 210


Errors 211 through 220

Information Message 211

Fatal Error 212

Fatal Error 213

Fatal Error 214

Fatal Error 215

Fatal Error 216

Fatal Error 217

Fatal Error 218

Fatal Error 219

Fatal Error 220


Errors 221 through 230

Fatal Error 222

Fatal Error 223

Fatal Error 224

Fatal Error 225

Fatal Error 226

Fatal Error 227

Fatal Error 228

Fatal Error 229

Warning 230


Errors 231 through 240

Fatal Error 232

Fatal Error 233

Fatal Error 234

Fatal Error 236


Errors 281 through 290

Fatal Error 282

Fatal Error 283


Errors 1001 through 1010

Fatal Error 1001

Fatal Error 1002

Fatal Error 1003

Warning 1004

Warning 1005

Fatal Error 1006

Fatal Error 1008


Errors 1011 through 1020

Fatal Error 1011

Fatal Error 1012

Fatal Error 1013

Warning 1014

Fatal Error 1015

Fatal Error 1016

Fatal Error 1018

Fatal Error 1020


Errors 1021 through 1030

Fatal Error 1021

Fatal Error 1022

Fatal Error 1023

Fatal Error 1024

Fatal Error 1025

Fatal Error 1026

Warning 1027

Fatal Error 1028

Fatal Error 1029

Fatal Error 1030


Errors 1031 through 1040

Warning 1031

Fatal Error 1032

Fatal Error 1033

Warning 1034

Warning 1036

Fatal Error 1037

Fatal Error 1038

Fatal Error 1039

Fatal Error 1040


Errors 1041 through 1050

Fatal Error 1041

Fatal Error 1042

Warning 1043

Fatal Error 1044

Warning 1045

Warning 1046

Warning 1047

Warning 1048

Fatal Error 1049


Errors 1051 through 1060

Fatal Error 1051

Fatal Error 1054

Fatal Error 1055


Errors 1061 through 1070

Fatal Error 1063

Fatal Error 1064

Fatal Error 1070


Errors 1071 through 1080

Warning 1071

Warning 1072

Fatal Error 1074

Fatal Error 1075

Fatal Error 1077

Fatal Error 1079

Warning 1080


Errors 1081 through 1090

Fatal Error 1081

Fatal Error 1082

Fatal Error 1084

Warning 1085

Warning 1086

Fatal Error 1087

Fatal Error 1089

Fatal Error 1090


Errors 1091 through 1100

Warning 1091

Fatal Error 1092

Fatal Error 1093

Fatal Error 1094

Fatal Error 1095

Fatal Error 1097

Fatal Error 1098

Fatal Error 1099


Errors 1101 through 1110

Fatal Error 1101


Errors 1451 through 1460

Fatal Error 1451

Fatal Error 1453


Errors 1501 through 1510

Fatal Error 1502


General Information Messages

These information messages describe compiler operation.

smi2smir: Version <version #> MIB definitions compiled from <file name>
This message appears at the beginning of every file compilation. This file may have been explicitly specified on the command line by the user, or it may have been pulled in by the compiler from the registry include directories or the include directories mentioned on the command line.
smi2smir: Syntax check failed on <file name>
The specific error messages that precede this message give the nature of the syntax error(s).
smi2smir: Semantic check failed on <file name>
The specific error messages that precede this message give the nature of the semantic error(s).
smi2smir: Could not load <file name> into the smir
Syntax or semantic check failed on the module, or SMIR interaction was not complete.
smi2smir: Syntax check successful on <file name>
smi2smir: Semantic check successful on <file name>
smi2smir: Loaded <file name> successfully into the smir
smi2smir: Could not resolve one or more symbols in <module name>
The module(s) corresponding to one or more of the imported symbols in the specified module was not found or could not be compiled.
smi2smir: Could not connect to the SMIR
Ensure that SMIR.DLL exists, has been registered using the regsvr32 command, and that the CIMOM server is up and running.
smi2smir: Modules in the SMIR: <list of modules, 1 on each line>
This is the output of the /l switch.
smi2smir Could not list the modules in the SMIR
This indicates a failure of the /l switch due to no SMIR connection.
smi2smir: Deleted module <module name> successfully
The /d switch succeeded.
smi2smir: Could not delete module <module name>
This indicates a failure of the /d switch due to no SMIR connection.
smi2smir: Deleted all the modules in the SMIR
The /p switch succeeded.
smi2smir: Could not delete all the modules in the SMIR
The /p switch failed due to no SMIR connection.
smi2smir: Module <module name> does not exist in the SMIR
The /d switch failed because the specified module is not in the SMIR.
smi2smir: Generated MOF successfully
The /g or /gc switch worked successfully.
smi2smir: Could not generate MOF
The /g or /gc switch did not work successfully due to no SMIR connection.
smi2smir: Name of the module: <module name>
This is the successful output of the /n switch.
smi2smir: Could not parse <file name> successfully
This indicates failure of the /n or /ni switch because the specified file is not a valid MIB file.
smi2smir: Processed <number> files successfully
This specifies the number of files that were successfully parsed when the /r or the /auto switch were used.
smi2smir: Repeated files in the input for module <module name>. Only the file <file name> will be compiled
The user has explicitly specified more than one file on the command line, and two or more of these files have the same MIB module.
smi2smir: Added directory <directory name> to the registry
Success of the /pa switch.
smi2smir: Could not add directory <directory name> to the registry
Failure of the /pa switch, which happens only if the registry API fails.
smi2smir: Deleted directory <directory name> from the registry
Success of the /pd switch.
smi2smir: Could not delete <directory name> from the registry
Failure of the /pd switch. The specified directory does not exist in the list of directories in the registry.
smi2smir: <file name> is not a valid mib file
More than one file has been specified on the command line, one of which is not a valid MIB file.

See Also

Running the SNMP Compiler

SNMP Compiler Options


Mapping SNMP to the CIM Schema

Because they manipulate Common Information Model (CIM) class definitions, the CIM SNMP providers must specify a mapping between the SNMPv1 and SNMPv2C Management Information Base (MIB) schema and CIM class definitions. The following topics define the SNMP/CIM mapping.


Mapping the SNMPv1 and SNMPv2C MIB Schema

An SNMPv1 and SNMPv2C Management Information Base (MIB) instantiates a number of macro definitions that describe the schema associated with a particular network device. For the purposes of the SNMP providers, only the SNMPv1 OBJECT-TYPE, SNMPv2C OBJECT-TYPE, and SNMPv2C TEXTUAL-CONVENTION macros are considered.


Mapping the SNMPv1 and SNMPv2C OBJECT-TYPE Macro

The SNMPv1- and SNMPv2C-defined ASN.1 macro OBJECT-TYPE describes the characteristics of a manageable unit of data. A set of OBJECT-TYPE macros can be thought of as a collection of objects that share some relationship. In SNMPv2C, you can formally specify the constituent elements of a group using the OBJECT-GROUP macro; however, there is no formal mechanism to do this in SNMPv1. For the purposes of the SNMP providers, you can invent a collection relationship and fabricate collections. This can be done for both SNMPv1 and SNMPv2C MIB definitions; that is, the SNMPv2C OBJECT-GROUP macro is ignored.

You can fabricate collections for each SNMPv1 and SNMPv2C information module. The following notation is needed to define precisely how such collections are constructed:

  • A named node in an SNMP information module is a definition of the form:
    namedNode OBJECT IDENTIFIER ::= <object identifier value>
  • The function objId, applied to a named node, returns the object identifier assigned to that named node.
  • The function objId, applied to an instance of the OBJECT-TYPE macro, returns the object identifier value assigned to that instance.

Using the preceding notation, the manner in which fabricated OBJECT-GROUP instances are defined in an SNMPv1 and SNMPv2C information module can be stated as follows:

Let n be a named node in an SNMP information module M, and CS(M,n) the set of OBJECT-TYPE instances in M defined by:

CS(M,n) = { s | s is a scalar and objId(s) = objId(n).x, for some integer x}

Then if CS(M,n) is not empty, it defines a scalar collection for the SNMPv1 or SNMPv2C information module M.

Let n be a named node in an SNMP information module M, and CT(M,n) the set of OBJECT-TYPE instances in M defined by:

CT(M,n) = { c | c is a column of table n and objId(c) = objId(n).x.y, for some integers x, y}

Then if CT(M,n) is not empty, it defines a table collection for the SNMPv1 or SNMPv2C information module M.

This definition provides a basis for the following mapping process:

  1. All objects present within a table collection map to properties of a single CIM class definition. The object descriptor for a table collection is defined as the object descriptor of n for CT(M,n).
  2. All objects present within a scalar collection map to properties of a single CIM class definition. The object descriptor for a scalar collection is defined as the object descriptor of n for CS(M,n).


Mapping Collections to CIM Classes

In all cases, hyphens (-) in SNMP MIB identifiers are replaced by underscores (_) when mapped to CIM class names.

A scalar collection maps to a CIM class whose name can be generated by appending the scalar collection object descriptor to the concatenation of "SNMP_", the MIB module identity name, and "_". For example, system translates to SNMP_RFC1213_MIB_system.

A table collection maps to a CIM class whose name can be generated by appending the table object descriptor to the concatenation of "SNMP_", the MIB module identity name, and "_". For example, ifTable translates to SNMP_RFC1213_MIB_ifTable. The elements of the table collection map to properties of the CIM class.

Naming conflicts can occur due to CIM name case-insensitivity. If a naming conflict occurs, the providers choose one of the conflicting group definitions and ignore the remaining definitions.

All generated class definitions must be derived from the class SnmpObjectType. The following class definitions parent all generated class definitions:

[abstract]
class SnmpMacro
{
};

[abstract]
class SnmpObjectType:SnmpMacro
{
};

The CIM class qualifier module_name defines the SNMP MIB module identity name containing the scalar or table collection.

The CIM class qualifier group_objectid defines the fabricated collection object identifier.

The CIM class qualifier module_imports contains a comma-separated list of module names used in the SNMP MIB module imports list, which is obtained from the MODULE-IDENTITY macro definition.


Mapping MIB Object Names

A unique name or object descriptor identifies each SNMPv1 and SNMPv2C MIB object. Each MIB object descriptor maps to a CIM property name verbatim. For example, ifIndex translates to ifIndex.


Mapping the Type Syntax Clause

Each SNMPv1 and SNMPv2C MIB object, whether in a scalar or table collection, contains a SYNTAX clause within the SNMPv1 and SNMPv2C OBJECT-TYPE macros that refers to one of the following types:

Type | Description
SNMP primitive type | One of the types defined in the Structure of Management Information (SMI) documents Rfc1213.txt and Rfc1903.txt.[I'm assuming these are file names. If so, they need to be initcapped.]
SNMP textual convention | A type definition generated through the explicit use of the SNMPv2C TEXTUAL-CONVENTION macro or generated through the use of a named type and generally agreed to convey some textual convention (for example, the SNMPv1 named type Displaystring within Rfc1213.txt).
SNMP constrained type | A primitive type, named type, or textual convention that has been constrained by some subtyping mechanism defined within the SMI documents Rfc1213.txt and Rfc1903.txt.
SNMP named type | A named reference to one of the primitive types, textual conventions, or another named type.

The following CIM qualifiers are used to map SNMPv1 and SNMPv2C MIB object properties:

CIM qualifier | Description
textual_convention | CIM SNMP textual representation that formats an underlying SNMP protocol value.
encoding | SNMP protocol encoding value type.
object_syntax | SNMP OBJECT-TYPE macro SYNTAX clause value.
cimtype | CIM textual representation that formats an underlying CIM protocol value.


SNMP Primitive Types

SNMP primitive types map to CIM defined types. The following tables define the mapping where the SYNTAX clause explicitly refers to a primitive type.

Table 1: Mapping SNMPv1 Primitive Types

MIB type | Variant type | Textual convention qualifier | Encoding qualifier | Object syntax qualifier | Cimtype qualifier | Default value
INTEGER | VT_I4 | INTEGER | INTEGER | INTEGER | sint32 | 0
OCTET STRING | VT_BSTR | OCTETSTRING | OCTETSTRING | OCTETSTRING | string |
OBJECT IDENTIFIER | VT_BSTR | OBJECTIDENTIFIER | OBJECTIDENTIFIER | OBJECTIDENTIFIER | string | 0.0
NULL | VT_NULL | NULL | NULL | NULL | Not supported (1) | N/A
IpAddress | VT_BSTR | IpAddress | IpAddress | IpAddress | string | 0.0.0.0
Counter | VT_I4 | Counter | Counter | Counter | uint | 0
Gauge | VT_I4 | Gauge | Gauge | Gauge | string | 0
TimeTicks | VT_I4 | TimeTicks | TimeTicks | TimeTicks | uint32 | 0
Opaque | VT_BSTR | Opaque | Opaque | Opaque | string |
NetworkAddress | VT_BSTR | NetworkAddress | NetworkAddress | NetworkAddress | string | 0.0.0.0

(1) When the SYNTAX clause of the OBJECT-TYPE macro refers to NULL either explicitly or through a named type assignment, that OBJECT-TYPE macro is ignored.

Table 2: Mapping SNMPv2C Primitive Types

MIB type | Variant type | Textual convention qualifier | Encoding qualifier | Object syntax qualifier | Cimtype qualifier | Default value
INTEGER | VT_I4 | INTEGER | INTEGER | INTEGER | sint32 | 0
OCTET STRING | VT_BSTR | OCTETSTRING | OCTETSTRING | OCTETSTRING | string |
OBJECT IDENTIFIER | VT_BSTR | OBJECTIDENTIFIER | OBJECTIDENTIFIER | OBJECTIDENTIFIER | string | 0.0
IpAddress | VT_BSTR | IpAddress | IpAddress | IpAddress | string | 0.0.0.0
Counter32 | VT_I4 | Counter32 | Counter32 | Counter32 | uint32 | 0
Gauge32 | VT_I4 | Gauge32 | Gauge32 | Gauge32 | uint32 | 0
Unsigned32 | VT_I4 | Unsigned32 | Unsigned32 | Unsigned32 | uint32 | 0
Integer32 | VT_I4 | Integer32 | Integer32 | Integer32 | sint32 | 0
Counter64 | VT_BSTR | Counter64 | Counter64 | Counter64 | uint64 | 0
TimeTicks | VT_I4 | TimeTicks | TimeTicks | TimeTicks | uint32 | 0
Opaque | VT_BSTR | Opaque | Opaque | Opaque | string |

The CIM named qualifier textual_convention defines the textual representation of the SYNTAX clause of the OBJECT-TYPE macro.

The CIM named qualifier object_syntax defines the named type definition present within the SYNTAX clause of the OBJECT-TYPE macro. The object_syntax is copied verbatim from the SYNTAX clause of the OBJECT-TYPE macro.

The CIM named qualifier encoding defines the SNMP type used when encoding SNMPv1 and SNMPv2C protocol frames.


Textual Conventions for SNMPv1 and SNMPv2C

SNMP textual conventions map to CIM defined types. The following table defines the mapping where the SYNTAX clause explicitly refers to a textual convention or refers to an implied textual convention.

Table 3: Mapping SNMPv1 and SNMPv2C Textual Conventions

Textual convention | Variant type | Textual convention qualifier | Encoding qualifier | Object syntax qualifier | Cimtype qualifier | Default value
DateAndTime | VT_BSTR | DateAndTime | OCTETSTRING | DateAndTime | string | 0-0-0,0:0:0.0,+0:0
Displaystring | VT_BSTR | Displaystring | OCTETSTRING | Displaystring | string |
MacAddress | VT_BSTR | MacAddress | OCTETSTRING | MacAddress | string | 00:00:00:00:00:00
PhysAddress | VT_BSTR | PhysAddress | OCTETSTRING | PhysAddress | string |
SnmpUDPAddress | VT_BSTR | SnmpUDPAddress | OCTETSTRING | SnmpUDPAddress | string | 0.0.0.0/0
SnmpOSIAddress | VT_BSTR | SnmpOSIAddress | OCTETSTRING | SnmpOSIAddress | string | 00/00
SnmpIPXAddress | VT_BSTR | SnmpIPXAddress | OCTETSTRING | SnmpIPXAddress | string | 0.00:00:00:00:00:00.0

The CIM named qualifier textual_convention defines the textual representation of the SYNTAX clause of the OBJECT-TYPE macro.

The CIM named qualifier object_syntax defines the named type definition present within the SYNTAX clause of the OBJECT-TYPE macro. The object_syntax is copied verbatim from the SYNTAX clause of the OBJECT-TYPE macro.

The CIM named qualifier encoding defines the SNMP type used when encoding SNMPv1 and SNMPv2C protocol frames.

For textual conventions not present within the preceding table, the CIM-defined variant type, textual_convention qualifier, encoding qualifier, object_syntax qualifier, and CIMType qualifier are mapped using the primitive type mapping table specified previously and the underlying primitive type, possibly generated through a type assignment hierarchy.

The CIM named qualifier display_hint defines the DISPLAY-HINT clause present within a referenced SNMPv2C TEXTUAL-CONVENTION macro. Where the SYNTAX clause of the SNMPv2C OBJECT-TYPE macro references an SNMPv2C TEXTUAL-CONVENTION macro that contains a DISPLAY-HINT clause, the display_hint qualifier is set to the value of that DISPLAY-HINT clause. Where no reference is made to an SNMPv2C TEXTUAL-CONVENTION macro or no DISPLAY-HINT clause is present within the referenced SNMPv2C TEXTUAL-CONVENTION macro, the display_hint qualifier is not generated.

Example 1 (SNMPv1):

myNamedType ::= DISPLAYSTRING (SIZE (0..127))

    myNamedProperty OBJECT-TYPE
    SYNTAX  myNamedType
    ACCESS read-only
    STATUS MANDATORY
    DESCRIPTION ""

This SNMPv1 example generates the following CIM qualifiers:

object_syntax("myNamedType"),
textual_convention("DISPLAYSTRING"),
encoding("OCTETSTRING"),
variable_length("0..127")

Example 2 (SNMPv2C):

myDisplaystring ::= TEXTUAL-CONVENTION
DISPLAY-HINT "255a"
STATUS current
DESCRIPTION ""
SYNTAX OCTET STRING (SIZE (0..127))

myNamedProperty OBJECT-TYPE
SYNTAX  myDisplaystring
MAX-ACCESS read-only
STATUS current
DESCRIPTION ""

This SNMPv2C example generates the following CIM qualifiers:

object_syntax("myDisplaystring"),
textual_convention("OCTETSTRING"),
encoding("OCTETSTRING"),
display_hint("255a"),
variable_length("0..127")


SNMP Constrained Types

The following topics define changes to the mapping based on the set of allowable subtyping rules imposed on a primitive type, named type, or textual convention.


Mapping Subtype Enumeration Definitions

The following table defines the mapping where the SYNTAX clause of the SNMPv1 and SNMPv2C OBJECT-TYPE macro refers to an SNMP primitive type, named type, or textual convention containing a subtype definition of the type enumerated INTEGER.

Table 4: Mapping SNMPv1 and SNMPv2C Subtype Enumeration Definitions

Constrained MIB type | Variant type | Textual convention qualifier | Encoding qualifier | Cimtype qualifier | Default value
Enumerated Integer | VT_BSTR | enumeratedinteger | INTEGER | string | Named value of first element of enumeration

The CIM named qualifier textual_convention defines the textual representation of the SYNTAX clause of the OBJECT-TYPE macro.

The CIM named qualifier object_syntax defines the named type definition present within the SYNTAX clause of the OBJECT-TYPE macro. The object_syntax is copied from the SYNTAX clause of the OBJECT-TYPE macro up to but not including the enumerated value assignments, if present.

The CIM named qualifier encoding defines the SNMP type used when encoding SNMPv1 and SNMPv2C protocol frames.

The CIM property qualifier enumeration defines the enumerated values. The enumeration qualifier is represented as a string containing a comma-separated list of signed 32-bit integer values.

For example:

Status := INTEGER {

up(1),
down(2),
testing(3)
}

This example maps to:

enumeration("up(1),down(2),testing(3)")


Mapping Subtype BITS Definitions

The following table defines the mapping where the SYNTAX clause of the SNMPv1 and SNMPv2C OBJECT-TYPE macro refers to an SNMP primitive type, named type, or textual convention containing a subtype definition of type BITS.

Table 5: Mapping SNMPv1 and SNMPv2C Subtype BITS Definitions

Constrained MIB type | Variant type | Textual convention qualifier | Encoding qualifier | Cimtype qualifier | Default value
BITS | VT_ARRAY | VT_BSTR | bits | OCTETSTRING | string | N/A

The CIM named qualifier textual_convention defines the textual representation of the SYNTAX clause of the OBJECT-TYPE macro.

The CIM named qualifier object_syntax defines the named type definition present within the SYNTAX clause of the OBJECT-TYPE macro. The object_syntax is copied from the SYNTAX clause of the OBJECT-TYPE macro up to but not including the enumerated value assignments, if present.

The CIM named qualifier encoding defines the SNMP type used when encoding SNMPv1 and SNMPv2C protocol frames.

The CIM property qualifier bits defines the enumerated values. The bits qualifier is represented as a string containing a comma-separated list of singed 32-bit integer values.

For example:

Status := BITS {

up(1),
down(2),
testing(3)
}

This example maps to:

bits("up(1),down(2),testing(3)")


Mapping Variable-Length Subtype Definitions

The following mapping applies where the SYNTAX clause of the SNMPv1 and SNMPv2C OBJECT-TYPE macro refers to an SNMP primitive type, named type, or textual convention containing a subtype definition derived from a variable-length OCTET STRING or "Opaque".

The CIM named qualifier textual_convention defines the textual representation of the SYNTAX clause of the OBJECT-TYPE macro.

The CIM named qualifier object_syntax defines the named type definition present within the SYNTAX clause of the OBJECT-TYPE macro. The object_syntax is copied from the SYNTAX clause of the OBJECT-TYPE macro up to but not including the size constraints.

The CIM named qualifier encoding defines the SNMP type used when encoding SNMPv1 and SNMPv2C protocol frames.

The CIM property qualifier variable_length specifies the minimum, maximum, and fixed-length values associated with the type definition. The variable_length qualifier is implemented as a qualifier string in the following format where the variable-length values are represented as unsigned 32-bit integers:

(((0.9) .. (0.9)) | (0.9))(, (((0.9) .. (0.9)) | (0.9)))*

For example:

MySnmpOSIAddress ::=  TEXTUAL-CONVENTION

    DISPLAY-HINT    "*1x:/1x:"
    STATUS        current
    DESCRIPTION
            "Represents an OSI transport-address:

               octets   contents           encoding
                  1     length of NSAP     'n' as an unsigned-integer
                                              (either 0 or from 3 to 20)
               2..(n+1) NSAP                concrete binary representation
               (n+2)..m TSEL               string of (up to 64) octets
            "
    SYNTAX         OCTET STRING (SIZE (1|4..85))

This example maps to:

display_hint("*1x:/1x:"),
encoding("OCTETSTRING"),
textual_convention("OCTETSTRING"),
variable_length ("1,4..85")


Mapping Fixed-Length Subtype Definitions

Where the SYNTAX clause of the SNMPv1 and SNMPv2C OBJECT-TYPE macro refers to an SNMP primitive type, named type, or textual convention containing a subtype definition derived from a fixed-length OCTET STRING or "Opaque", an additional qualifier is required to specify that fixed-length value.

The CIM property qualifier fixed_length specifies the fixed-length value. The fixed_length qualifier is represented as an unsigned 32-bit integer value.

For example:

IPXADDRESS := OCTET STRING (SIZE (6))

This example maps to:

fixed_length(6)


Mapping Range Subtype Definitions

Where the SYNTAX clause of the SNMPv1 and SNMPv2C OBJECT-TYPE macro refers to an SNMP primitive type, named type, or textual convention containing a subtype definition derived from a ranged or fixed-value, INTEGER or "Gauge", an additional qualifier is required to specify the ranged and fixed values associated with that type definition.

The CIM property qualifier variable_value specifies the ranged and fixed values associated with the type definition. The variable_value qualifier is implemented as a qualifier string in the following format where the range and fixed-length values are represented as unsigned 32-bit integers:

(((0.9)..(0.9))|(0.9))(,(((0.9)..(0.9))|(0.9)))*

For example:

Status := INTEGER (10..20|8)

This example maps to:

variable_value("10..20,8")


SNMP Named Types

SNMP named types map to CIM defined types. The following process applies where the SYNTAX clause refers to a primitive type, textual convention, or constrained type through some type assignment derivation:

  1. If, through derivation of the type assignment rules a constrained type definition is encountered, then:
    1. If, through further derivation, one of the textual conventions listed in Table 3 is encountered, then apply the mapping rules for constrained types and textual conventions.
    2. Otherwise, through further derivation, one of the primitive types listed in Table 1 or Table 2 is encountered. Apply the mapping rules for primitive types and constrained types.
  2. Otherwise, if through derivation of the type assignment rules, one of the textual conventions listed in Table 3 is encountered, then apply the mapping rules for textual conventions.
  3. Otherwise, through derivation of the type assignment rules, one of the primitive types listed in Table 1 or Table 2 is encountered. Apply the mapping rules for primitive types.

The CIM named qualifier object_syntax defines the named type definition present within the SYNTAX clause of the OBJECT-TYPE macro. The object_syntax is copied verbatim from the SYNTAX clause of the OBJECT-TYPE macro.

The CIM named qualifier encoding defines the SNMP type used when encoding SNMPv1 and SNMPv2C protocol frames.

Note A class definition containing a property type definition that does not conform to the property type mapping presented above is considered an invalid CIM SNMP provider-defined class definition. In this case, the provider is responsible for returning an error condition if and when the provider requests the retrieval of a class definition while executing an instance retrieval function.


Textual Conventions for Type Values

Each MOF syntax type is assigned a syntactical convention used when specifying values for property assignments. The following table defines the MOF syntax type definition and its syntactical representation in the Lex notational convention:

Table 6: Syntactical Conventions for MOF Syntax Types

MOF syntax type | Can be empty? | Syntactical representation
INTEGER | FALSE | ( [1-9] ) ( [0-9] )* | ( [0-7] )+ | ( 0x ( ( [0-9] | [a-f] | [A-F] ) + ) )
OCTETSTRING | TRUE | ( ( [0-9] | [a-f] | [A-F] ) ( [0-9] | [a-f] | [A-F] ) )*
OBJECTIDENTIFIER | FALSE | ( [1-9] ) ( [0-9] )* ( . ( [1-9] ) ( [0-9] )* ) *
NULL | MANDATORY |
IPADDRESS | FALSE | ( [1-9] ) ( [0-9] )* ( . ( [1-9] ) ( [0-9] )* ) 3
COUNTER | FALSE | ( [1-9] ) ( [0-9] )* | ( [0-7] )+ | ( 0x ( ( [0-9] | [a-f] | [A-F] ) ) + )
GAUGE | FALSE | ( [1-9] ) ( [0-9] )* | ( [0-7] )+ | ( 0x ( ( [0-9] | [a-f] | [A-F] ) )+ )
TIMETICKS | FALSE | ( [1-9] ) ( [0-9] )* | ( [0-7] )+ | ( 0x ( ( [0-9] | [a-f] | [A-F] ) )+ )
OPAQUE | TRUE | ( ( [0-9] | [a-f] | [A-F] ) ( [0-9] | [a-f] | [A-F] ) )*
NETWORKADDRESS | FALSE | ( [1-9] ) ( [0-9] )* ( . ( [1-9] ) ( [0-9] )+ ) 3
Displaystring | TRUE | .*
MacAddress | FALSE | ( [0-9] | [a-f] | [A-F] ) ( [0-9] | [a-f] | [A-F] )
 |  | ( : ( [0-9] | [a-f] | [A-F] ) ( [0-9] | [a-f] | [A-F] ) ) ) 5
PhysAddress | TRUE | ( [0-9] | [a-f] | [A-F] ) ( [0-9] | [a-f] | [A-F] )
 |  | ( : ( [0-9] | [a-f] | [A-F] ) ( [0-9] | [a-f] | [A-F] ) ) ) *
EnumeratedINTEGER | FALSE | One of enumerated values
BITS | TRUE | Array of enumerated values
DateTime | FALSE | ( [1-9] ) ( [0-9] )* '-' ( [1-9] ) ( [0-9] )* '-' ( [1-9] ) ( [0-9] )* '.' ( [1-9] ) ( [0-9] )* ':' ( [1-9] ) ( [0-9] )* ':' ( [1-9] ) ( [0-9] )* '.' ( [1-9] ) ( [0-9] )* ',' ( '+' | '-' ) ( [1-9] ) ( [0-9] )* ':' ( [1-9] ) ( [0-9] )*
SnmpOSIAddress | FALSE | ( ( [0-9] | [a-f] | [A-F] )+ '/' ( ( [0-9] | [a-f] | [A-F] )+
SnmpUDPAddress | FALSE | ( [1-9] ) ( [0-9] )* ( . ( [1-9] ) ( [0-9] )+ ) 3 '/' ( [1-9] ) ( [0-9] )*
SnmpIPXAddress | FALSE | ( [0-9] | [a-f] | [A-F] ) 4 '.' ( ( ( [0-9] | [a-f] | [A-F] ) ( [0-9] | [a-f] | [A-F] ) ) (':' ( [0-9] | [a-f] | [A-F] ) ( [0-9] | [a-f] | [A-F] ) ) 5 ) '.' ( [0-9])+

Note The NETWORKADDRESS type currently only supports IpAddress; therefore, the syntactical representation is always assumed to be IpAddress.


Mapping the INDEX Clause

No key property is defined for a scalar collection that maps to a class definition. In this case, there will be only one instance of the class definition. A class generated from a scalar collection will contain a class qualifier named Singleton that is of type Bool.

Each SNMPv1 and SNMPv2C table collection that maps to a class definition must contain at least one property that defines the object key; that is, a property that uniquely identifies an instance of a class. The INDEX clause of an SNMP table collection specifies the set of properties that define the keys of the class. The ordering of the INDEX information within the table collection defines the ordering of the keys within the class definition.

The CIM qualifier of a property that defines itself as a key is key, which is of type Bool. The CIM property qualifier that defines the ordering of the keys is key_order. The key_order qualifier is defined as an unsigned 32-bit integer value which, for the purposes of the MOF qualifier syntax, must be converted to a signed 32-bit integer value using the twos-complement operation.

Because of the flexibility of the INDEX clause within the OBJECT-TYPE macro, the specification of keyed properties is not straightforward. There are a number of possibilities to consider when mapping the INDEX clause to the set of keyed properties. The current mapping of the SNMPv2C INDEX clause does not handle the use of the IMPLIED qualifier. A class definition will not be generated in this case.


INDEX Clause Containing Internal Accessible MIB OBJECT-TYPE References

It is possible, even canonical, to specify an INDEX clause containing an accessible "indexobject", a named value referencing an OBJECT-TYPE definition, that refers to a MIB object definition appearing within the conceptual row of the table containing the INDEX clause. In this case, the MIB object definition referred to in the INDEX clause becomes a keyed property of the class definition.


INDEX Clause Containing External Accessible MIB OBJECT-TYPE References

It is possible to specify an INDEX clause containing an accessible "indexobject", a named value referencing an OBJECT-TYPE definition that refers to a MIB object definition appearing within the conceptual row of another table. In this situation, the MIB object definition referred to in the INDEX clausebecomes a keyed property of the class definition.


INDEX Clause Containing a MIB Type Reference

It is possible to specify an INDEX clause that contains an accessible "indextype", a named type referencing one of "INTEGER", "OCTET STRING", "OBJECT IDENTIFIER", "NetworkAddress" or "IpAddress". In this case, a property definition is created and its type syntax is based on the "indextype" specified within the INDEX clause. The MIB object definition referred to in the INDEX clause becomes a keyed property of the class definition. The property type qualifiers are defined by the SNMP type syntax mapping specified previously. The property is annotated with the qualifier virtual_key. This qualifier specifies that the SNMP providers should calculate the value of the property based on the superset of instance information associated with all the accessible MIB object definitions present within the class definition. A class definition must contain at least one property that does not have an associated virtual_key qualifier; failure to specify this property invalidates the class definition. The property definition name is generated using the following algorithm:

  1. Take the MIB table object descriptor and map to a CIM class name by copying the characters verbatim. For example, ifTable translates to ifTable.
  2. Append an underscore (_) to the result of 1.
  3. Append the rank order of the INDEX clause "indextype" to the result of 2.

The result is a unique property name. For example, the property name for the third component "indextype" of the MIB table "enterpriseIfTable" is enterpriseIfTable_3.


INDEX Clause Containing Inaccessible MIB OBJECT-TYPE References

It is possible to specify an INDEX clause containing an inaccessible "indexobject", a named value referencing an OBJECT-TYPE definition, that refers to a MIB object definition appearing within the conceptual row of the table containing the INDEX clause or another table. In this case, the MIB object definition referred to in the INDEX clause becomes a keyed property of the class definition but is annotated with the CIM property qualifier virtual_key. The virtual_key qualifier specifies that the SNMP providers calculate the value of the property based on the superset of instance information associated with all the accessible MIB object definitions present within the class definition. A class definition must contain at least one property that does not have an associated virtual_key qualifier; failure to specify this property invalidates the class definition.


Subtyping Properties in the OBJECT-TYPE INDEX Clause

When an SNMP table collection contains an INDEX clause that contains an SNMP supported type that, in turn, contains a subtype definition derived from a fixed-length OCTET STRING, then the property must also define a further qualifier which specifies that fixed-length value. The CIM property qualifier fixed_length specifies this value.

The following example is an excerpt from the bridge-forwarding table:

MacAddress ::= OCTET STRING (SIZE (6))

dot1dTpFdbTable OBJECT-TYPE
       SYNTAX  SEQUENCE OF Dot1dTpFdbEntry
       ACCESS  not-accessible
       STATUS  mandatory
       DESCRIPTION
               "A table that contains information about unicast
               entries for which the bridge has forwarding and/or
               filtering information.  This information is used
               by the transparent bridging function in
               determining how to propagate a received frame."
       ::= { dot1dTp 3 }

dot1dTpFdbEntry OBJECT-TYPE
       SYNTAX  Dot1dTpFdbEntry
       ACCESS  not-accessible
       STATUS  mandatory
       DESCRIPTION
               "Information about a specific unicast MAC address
               for which the bridge has some forwarding and/or
               filtering information."
       INDEX   { dot1dTpFdbAddress }
       ::= { dot1dTpFdbTable 1 }

   Dot1dTpFdbEntry ::=
       SEQUENCE {
           dot1dTpFdbAddress
               MacAddress,
           dot1dTpFdbPort
               INTEGER,
           dot1dTpFdbStatus
               INTEGER
       }

   dot1dTpFdbAddress OBJECT-TYPE
       SYNTAX  MacAddress
       ACCESS  read-only
       STATUS  mandatory
       DESCRIPTION
               "A unicast MAC address for which the bridge has
               forwarding and/or filtering information."
       REFERENCE
               "P802.1d/D9, July 14, 1989: Section 3.9.1, 3.9.2"
       ::= { dot1dTpFdbEntry 1 }

This example maps to the following CIM class definition:

[
        description (

            "A table that contains information about unicast
            entries for which the bridge has forwarding and/or
            filtering information.  This information is used
            by the transparent bridging function in
            determining how to propagate a received frame.

            Information about a specific unicast MAC address
          for which the bridge has some forwarding and/or
            filtering information."
        ) ,
        module_name ("RFC1286-MIB"),
        group_objectid ("1.3.6.1.2.1.17")
    ]
    class SNMP_RFC1286_MIB_Dot1dTpFdbTable
    {
        [   read,key,key_order(1),
            fixed_length(6),
            object_syntax("MacAddress"),
            textual_convention("MacAddress"),
            encoding("OCTETSTRING"),
            object_identifier("1.3.6.1"),
            description (

            "A unicast MAC address for which the bridge has
           forwarding and/or filtering information."
            )
        ]
        string dot1dTpFdbAddress;
    }


Mapping the SNMPv2C AUGMENTS Clause

In SNMPv2C it is possible to replace the use of the INDEX clause with the AUGMENTS clause. The AUGMENTS clause indicates that the following table collection can be considered an extension of a referenced table collection. Where an AUGMENTS clause is specified, the set of collections referred to by that AUGMENTS clause can be combined with the referencing table collection to form one collection. The resultant collection shares the primary key properties specified in the last table collection in that chain. The previous mapping rules for the INDEX clause should be applied to the last table collection in that chain. The collection of objects then defines one CIM class definition.


Mapping the Object Identifier

Each SNMPv1 and SNMPv2C MIB object, whether in a scalar or table collection, is referred to by an object identifier. The SNMP object identifier maps to the CIM property qualifier object_identifier.


Mapping the ACCESS and MAX-ACCESS Clauses

Each MIB object, whether in a scalar or table collection, contains either an ACCESS or MAX-ACCESS clause depending on the version of the MIB. The following tables define the mapping of SNMP-defined access to CIM-defined access.

Table 7: Mapping SNMPv1 MIB ACCESS Class

MIB ACCESS class | MOF qualifiers
read-only | read
read-write | read, write
write-only | write
not-accessible | not-accessible

Table 8: Mapping SNMPv2C MIB MAX ACCESS Class

MIB MAX ACCESS class | MOF qualifiers
read-only | read
read-write | read, write
read-create | read
accessible-for-notify | not-accessible
not-accessible | not-accessible

Where a MIB object maps to "not-accessible" and is not a keyed property of the class, there is no mapping of the MIB object itself.


Mapping the DESCRIPTION Clause

Each SNMPv1 and SNMPv2C MIB object, whether in a scalar or table collection, contains a possibly empty DESCRIPTION clause. The SNMP DESCRIPTION clause maps to the CIM property qualifier description.

Each TABLE and ENTRY object within an SNMP table definition contains a possibly empty DESCRIPTION clause. The TABLE and ENTRY DESCRIPTION clauses are concatenated and the result maps to the CIM class qualifier description.


Mapping the STATUS Clause

Each SNMPv1 and SNMPv2C MIB object, whether in a scalar or table collection, contains a STATUS clause. Where the STATUS clause defines an "obsolete" value, the MIB object is discarded from the mapping. Otherwise, the associated CIM property is augmented with a status qualifier using the property qualifier status.

For SNMPv1, it is preferable that the value of the status property qualifier be either "mandatory" or "optional" but it is not considered an error for this qualifier to contain some other value.

For SNMPv2C, it is preferable that the value of the status property qualifier be either "current" or "deprecated" but it is not considered an error for this qualifier to contain some other value.


Mapping the DEFVAL Clause

Each SNMPv1 and SNMPv2C MIB object, whether in a scalar or table collection, can optionally contain a DEFVAL clause. The SNMP DEFVAL clause maps to the CIM property qualifier defval.


Mapping the REFERENCE Clause

Each SNMPv1 and SNMPv2C MIB object, whether in a scalar or table collection, can optionally contain a REFERENCE clause. The SNMP REFERENCE clause maps to the CIM property qualifier reference.


Mapping the UNITS Clause

Each SNMPv2C MIB object, whether in a scalar or table collection, can optionally contain a UNITS clause. The SNMP UNITS clause maps to the CIM property qualifier units.


CIM Property and Qualifier Compliance

The following table defines the system properties that can be present within a CIM class. Each property is defined as mandatory or optional. A mandatory property must be present for the SNMP provider to fully resolve a group object. Failure to define a mandatory property returns an error condition.

Table 9: CIM System Properties

Property name | Property syntax | Status | Description
__CLASS | string | Mandatory | For instances, the class to which the object belongs. For classes, this is the class name.
__GENUS | uint32 | Mandatory | Type of object. Can be one of : 1 - Class 2 - Instance
__NAMESPACE | string | Mandatory | The namespace where the object is located.
__SERVER | string | Mandatory | The machine where the object is located.
__SUPERCLASS | string | Optional | The immediate parent class.
__DYNASTY | string | Optional | The name of the class that is the ultimate base class for the current object (not its immediate parent class).
__PROPERTYCOUNT | uint32 | Mandatory | The number of nonsystem properties.
__PATH | string | Mandatory | The absolute path of the class or instance.
__RELPATH | string | Mandatory | The relative path of the class or instance.

The following table defines the qualifiers that can be associated with a CIM class. Each qualifier is defined as mandatory or optional. A mandatory qualifier must be present for the SNMP provider to fully resolve a group object. Failure to define a mandatory qualifier returns an error condition.

Table 10: CIM Class Qualifiers

Qualifier | Qualifier syntax | Status | Description
description | string | Optional | Class description.
module_name | string | Optional | SNMP-defined module name.
group_objectid | string | Optional | Fabricated group object identifier. Mandatory if the class is for the SNMP class provider.
module_imports | string | Optional | SNMP-defined list of module names used to resolve imports.

The following table defines the qualifiers that can be associated with a CIM property. Each qualifier is defined as mandatory or optional. A mandatory qualifier must be present for the SNMP provider to resolve an SNMP MIB object fully. Failure to define a mandatory qualifier returns an error condition. If an illegal qualifier value is specified, the SNMP providers returns an error condition.

Table 11: CIM Property Qualifiers

Qualifier | Qualifier syntax | Status
name | string | Mandatory; note that this qualifier is not explicitly defined.
description | string | Optional.
status | string | Optional.
object_identifier | string | Mandatory.
object_syntax | string | Optional.
cimtype | string | Mandatory.
textual_convention | string | Mandatory.
encoding | string | Optional.
fixed_length | uint32 | Optional.
variable_length | string | Optional.
variable_value | string | Optional.
enumeration | string | Mandatory if textual_convention == ENUMERATEDINTEGER.
bits | string | Mandatory if textual_convention == BITS.
display_hint | string | Optional.
key | Bool | Optional.
key_order | uint32 | Optional; mandatory if key is specified.
virtual_key | Bool | Optional.
read | Bool | Optional; at least one of read or write must be specified.
write | Bool | Optional; at least one of read or write must be specified.
defval | string | Optional.
reference | string | Optional.
units | string | Optional.


SNMPv1 Protocol Encoding

It is necessary to emphasize that although the class mapping accepts both SNMPv1 and SNMPv2C schemas, the SNMP providers only generate SNMPv1 protocol requests in an SNMPv1 defined namespace.

Where no corresponding conversion between SNMPv2C and SNMPv1 type is applicable, the SNMP providers do not generate a request for that property and the property value retains its default value.

The following table defines the protocol encoding type used when generating SNMPv1 protocol frames.

Table 12: SNMPv1 Protocol Encoding

Encoding qualifier | SNMP V1 protocol encoding
INTEGER | INTEGER
OCTETSTRING | OCTET STRING
OBJECTIDENTIFIER | OBJECT IDENTIFIER
NULL | NULL
IpAddress | IpAddress
Counter | Counter
Gauge | Gauge
TimeTicks | TimeTicks
Opaque | Opaque
NetworkAddress | NetworkAddress
Counter32 | Counter
Gauge32 | Gauge
Unsigned32 | Gauge
Integer32 | INTEGER
Counter64 | No Supported Conversion


SNMP Troubleshooting Guide

This guide is designed to help users retrieve information from an Simple Network Management Protocol (SNMP) device. The guide describes common errors that can occur during operations performed by the SNMP providers, and suggests solutions for correcting the problems.

The error descriptions and solutions are grouped according to the following categories:

  • Installation and registration
  • Transport protocol operation
  • SNMP Management Information Base (MIB) mapping


Installation and Registration

The following topics describe errors that can occur during installation and registration. These errors are associated with the SNMP device namespace configuration.

  • Dynamic class provider not registered in the SNMP device namespace.
  • Dynamic instance provider not registered in the SNMP device namespace.
  • Dynamic class provider incorrectly registered in the SNMP device namespace.
  • Dynamic instance provider incorrectly registered in the SNMP device namespace.
  • No classes loaded into the SNMP device namespace.
  • No classes loaded into the SMIR for an SNMP dynamic class provider-backed SNMP device namespace.


Transport Protocol Operation

The following topics describe errors associated with the transport protocol operation.

  • SNMP device namespace instance or SNMP-compatible class contains an illegal transport address.
  • The AgentAddress qualifier of the SNMP device namespace instance or SNMP-compatible class is correct but the operation hangs for a period of time before successfully returning.
  • The AgentAddress qualifier of the SNMP device namespace instance or SNMP-compatible class is a resolvable host name but the operation hangs for a period of time before unsuccessfully returning.
  • The AgentAddress qualifier of the SNMP device namespace instance or SNMP-compatible class is an IP address but the operation hangs for a period of time before unsuccessfully returning.
  • The SNMP protocol data units generate ICMP-port-unreachable packets.
  • The SNMP protocol data units generate ICMP-host-unreachable packets.
  • The SNMP protocol data units generate ICMP-net-unreachable packets.
  • The SNMP agent receives an SNMP protocol data unit but does not return a response.
  • The SNMP agent does not respond to an SNMP protocol operation because the SNMP operation protocol data units are being dropped before reaching their destination.
  • The SNMP agent does not respond to an SNMP protocol operation because the SNMP response protocol data units are being dropped before reaching their destination.
  • The SNMP agent does not respond to an SNMP protocol operation because the SNMP agent is dropping the SNMP protocol data units.
  • The SNMP agent responds to an SNMP protocol operation after the SNMP provider times out of the protocol operation response.
  • The SNMP provider sends out multiple packets with the same protocol request identifier even when the agent is responding to the SNMP protocol operation.
  • The SNMP provider returns a subset of the properties present for a given class definition because some entity is dropping a percentage of SNMP packets between the source and destination.
  • The SNMP provider returns a subset of the instances expected for a class definition because the SNMP agent device is returning GET-NEXT variable bindings that are not lexicographically ordered.
  • The SNMP provider returns a subset of the properties present for a class definition because the SNMP agent does not return properties that are defined as optional.
  • The SNMP provider returns a subset of the properties present for a class definition because the SNMP agent experiences some internal error processing those properties.
  • The SNMP provider returns a subset of the properties present within an instance of a class because the SNMP agent is returning key information that is incompatible with the CIM MOF definition.
  • The SNMP provider returns an empty result set for a given instance because the SNMP agent is returning key information that is inconsistent with the CIM MOF definition.
  • The SNMP provider returns an empty result set for a given instance because the SNMP agent is expecting key information that is inconsistent with the CIM MOF definition.
  • The SNMP provider returns an error result because the qualifier values of the SNMP device namespace instance or SNMP-compatible class do not match the expected type or values.
  • The set of classes returned by the SNMP providers changes intermittently.
  • The set of instances returned by the SNMP providers changes intermittently.


SNMP MIB Mapping

The following topics describe errors associated with SNMP MIB mapping.

  • The SNMP provider returns an error for a class because some mandatory property qualifiers are not present or some qualifiers are not of the correct type and value.
  • The SNMP provider returns an error for a class because some mandatory qualifiers are not present within the class definition or some qualifiers are not of the correct type and value.
  • The SNMP provider returns an error for a class because some properties of a CIM MOF class definition do not contain valid values for some property qualifiers.
  • The SNMP provider returns a subset of the properties present for a class definition because the object_identifier qualifier value is incorrect with respect to the SNMP MIB definition.
  • The SNMP provider returns an error for a CIM MOF class because none of the properties of the class definition have read access.
  • The SNMP provider returns an error for a CIM MOF class because none of the properties of a given CIM MOF class definition have write access.
  • The SNMP provider returns an error for a CIM MOF class because some properties of a given CIM MOF class definition are marked as keyed and no associated key_order qualifier is present, or the key_order values are invalid.


CIM Object Manager (CIMOM) Guide

The CIM Object Manager (CIMOM) provides access to information about objects in the management environment. Through CIMOM, applications can query for and make changes to static information in the CIMOM repository and dynamic information maintained by object providers.

The CIMOM Guide provides discussions of the following core features of CIMOM:

  • Programming Basics, a collection of topics that should be interest to anyone using the CIMOM programming interface (API).
  • Event Notification, an architectural description of how CIMOM supports event registration and notification.
  • WBEM Query Language, a guide to writing WQL queries for information retrieval and event notification.
  • Security and Authentication, a description of the classes that are used to check the validity of users accessing CIMOM.
  • Localization Services, a guide to localizing classes, instances, properties, and qualifiers.
  • Remote Access, a description of CIMOM's approach to providing access remotely across networks.
  • Implementing a Schema Extension, a guide to creating a custom schema based on the CIM or Win32 schemas.


Programming Basics

The Web-Based Enterprise Management (WBEM) SDK provides tools and programming interfaces that enable management applications and providers to be created quickly and easily. Although they implement a diffferent set of features, applications and providers perform some of the same basic tasks due to their use of the single CIMOM API.

For example, most WBEM developers need to:

  • Understand the IUnknown interface
  • Understand how to use output parameters
  • Understand asynchronous processing
  • Understand semisynchronous processing
  • Understand how to specify object paths
  • Understand the date/time format
  • Understand how to handle errors
  • Understand how to create namespaces, classes, and instances


Using the IUnknown Interface

The IUnknown interface is the base interface for all Component Object Model (COM) interfaces exposed by COM objects. The COM objects implemented by CIMOM, WBEM providers, and event consumers expose one or more interfaces specified in the CIMOM API. For example, WBEM class providers implement a COM object that includes the IWbemProviderInit and IWbemServices interfaces.

IUnknown manages the lifespan of the COM object and handles client requests for access. To manage the COM object's lifespan, IUnknown maintains what is known as a reference count. The reference count is a tally of the number of active clients of a particular interface. Only when all of the reference counts for all of the interfaces exposed by a COM object reach zero can the object be deleted and its memory safely freed.The methods that support lifespan management are:

· AddRef

· Release

The third method of IUnknown, QueryInterface, is used to handle client access to the COM object. Clients gain access to a COM object by retrieving a pointer to one of the interfaces implemented by the object. To gain access to a particular interface, a client calls QueryInterface and sets the riid parameter to the identifier of the desired interface.

If this interface is not implemented by the COM object, QueryInterface returns the error value E_NOINTERFACE. If the interface is implemented by the object, QueryInterface calls AddRef to increment the reference count and returns a pointer to the interface in the ppv parameter.

Whenever a caller receives an interface pointer as an output parameter to a method, the caller must call the interface's AddRef method before calling any of the other methods. Receiving an interface pointer through QueryInterface is an exception to this rule because QueryInterface automatically calls AddRef as part of its implementation.

Whenever a user of an interface is finished with that interface, it must call Release.

Because that AddRef and Release are not required to return accurate values, callers of these methods should not use the return values to determine whether or not the COM object is still valid. Due to the concurrent use of objects by multiple threads, the reference count can easily be altered while it is being examined.


Working with Output Parameters

Web-Based Enterprise Management (WBEM) observes the standard Component Object Model (COM) rules for passing input and output parameters. Observing the rules for output parameters is especially important because failing to observe them can result in memory leaks and unpredictable behavior.

If a method returns an interface pointer to its caller in an output parameter, it is the caller's responsibility to release the pointer when it is no longer needed. This is done by using the pointer to call Release. Because the Release method is part of the IUnknown interface, it is inherited by every WBEM interface.

For example, if an application calls the IWbemClassObject::GetPropertyQualifierSet method, a pointer to the IWbemQualifierSet interface is passed in the contents of the ppQualSet output parameter. The pointer can be released by calling IWbemQualifierSet::Release as is shown in the following sample:

IWbemQualifierSet* pSet;pObject->GetPropertyQualifierSet(strPropName, &pSet);if(pSet != NULL){  // call IUnknown::Release  pSet->Release();  // don't use pSet anymore!}

Because methods that return an interface pointer always set it to NULL whenever an error occurs, a Release call is necessary only if the method has been successful.

If a method has either a binary string (BSTR) or VARIANT output parameter, the incoming value of the parameter is ignored and overwritten by the method. With string parameters, either a new string is allocated or the contents of the original string is set to NULL. A memory leak results if the parameter has an initial value. It is the caller's responsibility to ensure that the output parameter does not contain data that requires deallocation. One option for string parameters is to always call SysFreeString; SysFreeString can be called regardless of the parameter's contents.

Always call VariantInit to initialize a VARIANT parameter. When finished using VARIANT data that is returned by a method, call VariantClear.


Asynchronous Processing

Asynchronous methods increase the performance of a management application by allowing it to proceed with other tasks while requests are pending, and while results are delivered through another thread. The IWbemServices interface supports both the synchronous and asynchronous versions of several methods. Whereas applications can make calls to either version, providers implement only the asynchronous versions.

The asynchronous version of a method has the Async suffix attached to its name as is shown in the following table:

Synchronous method | Asynchronous method
CreateClassEnum | CreateClassEnumAsync
CreateInstanceEnum | CreateInstanceEnumAsync
DeleteClass | DeleteClassAsync
DeleteInstance | DeleteInstanceAsync
ExecMethod | ExecMethodAsync
ExecNotificationQuery | ExecNotificationQueryAsync
ExecQuery | ExecQueryAsync
GetObject | GetObjectAsync
PutClass | PutClassAsync
PutInstance | PutInstanceAsync

The asynchronous methods return immediately whether or not they have finished performing the requested operation. The results of an asynchronous call are provided through the IWbemObjectSink interface. Each asynchronous method has as an input parameter a pointer to an IWbemObjectSink implementation.

If the asynchronous method completes successfully, it:

  1. Increments the reference count for the IWbemObjectSink object by calling its AddRef method.
  2. Returns WBEM_NO_ERROR.

As the operation is progressing, calls are made to IWbemObjectSink::Indicate. Indicate has two parameters: an array of pointers to objects accessible through the IWbemClassObject interface and a count of the number of pointers in the array. The object pointer array contains data that is relevant to the particular operation. For example, a query operation invoked through the IWbemServices::ExecQueryAsync method returns one or more data objects from the query's result set in the array.

Status is reported through the IWbemObjectSink::SetStatus method. An asynchronous operation can report an intermediate status, a final status, or an error. After the final status has been reported, a call is made to IWbemObjectSink::Release to release the IWbemObjectSink pointer.

An application calls IWbemServices::CancelAsyncCall if it wants to shut down before it has received all of the results from its asynchronous call. CancelAsyncCall cancels asynchronous processing by immediately releasing the IWbemObjectSink pointer included in the pSink parameter. Note, however, that timing and the nature of an asynchronous operation can affect whether or not the operation is truly canceled. Only lengthy queries are likely to be successfully canceled before they have completed. Faster operations such as asynchronous deletions or modifications typically complete before a CancelAsyncCall can be made. CancelAsyncCall attempts to cancel the current operation, but sometimes all that can be done is to release the IWbemObjectSink pointer.

Applications must never delete the object that exposes their IWbemObjectSink implementation without verifying that its reference count has reached zero. Due to the way in which Distributed COM (DCOM) forwards Release calls, there is no guarantee that this object will remain unused. Applications must always obey standard COM rules regarding reference counts.


Semisynchronous Processing

Semisynchronous processing is a compromise between synchronous processing and asynchronous processing, providing the advantages of each technique. Semisynchronous processing can be used by management applications to improve the speed and efficiency of processing queries, enumerations, and events.

With synchronous processing, applications call the methods of the IEnumWbemClassObject to retrieve objects. The application's thread is blocked until the call completes. This blockage can cause a lengthy delay in processing time.

With asynchronous query processing, applications must implement IWbemObjectSink. WBEM calls IWbemObjectSink::Indicate to deliver objects, allowing the application to continue with other work. One disadvantage with asynchronous processing is that it can be difficult for a provider or CIMOM to control the flow of information back to the application process. Large result sets can take a considerable amount of time to deliver, forcing the application to spend significant system resources to handle the delivery.

The semisynchronous technique solves both the thread blockage and uncontrolled delivery problems. To take advantage of semisynchronous query processing, an application:

  1. Calls IWbemServices::ExecQuery to execute the query.
  2. Calls IEnumWbemClassObject::Next or IEnumWbemClassObject::NextAsync using the ppEnum pointer returned by ExecQuery to retrieve the results of the query in small groups. The uCount parameter should be set to the number of objects to be returned in the group.
  3. Sets the pSink parameter if using NextAsync to point to an implementation of the IWbemObjectSink interface. As the implementor of NextAsync, CIMOM calls the IWbemObjectSink::Indicate method to deliver the query results asynchronously.

The IEnumWbemClassObject::NextAsync call is nonblocking and returns immediately. In the background CIMOM begins to deliver the requested number of objects by calling IWbemObjectSink::Indicate. It then stops, waiting for another NextAsync call. NextAsync places the number of objects actually returned in the lObjectCount parameter and the objects themselves in the contents of the ppObjArray parameter.

If the entire result set is not needed, an application should release the enumerator by calling IEnumWbemClassObject::Release. Calling this Release method results in CIMOM canceling its delivery of any remaining objects.


Specifying Object Paths

Web-Based Enterprise Management (WBEM) object paths are used to access:

  • Namespaces
  • Classes
  • Instances

Each object on the system has a unique path that identifies it locally or over the network. Object paths are conceptually similar to Universal Resource Locators (URL). Object paths can be fully qualified or relative to a certain location, such as the local machine or a particular namespace on the local machine.

To view the Backus-Naur Form definition for object paths, see Object Path BNF.


Object Paths to Namespaces

A namespace's object path is made up of two parts:

<server><namespace>

The <server> portion of the syntax is a double leading backslash followed by the network name of the machine. The <namespace> portion is the object path to the appropriate namespace on that server.

For example, use the following object path to specify the default namespace on the server MyServer:

\\MyServer\Root\Default

To specify the current server, use the pseudonym "\\.":

\\.\Root\Default

Object paths to namespaces are used in calls to IWbemLocator::ConnectServer and IWbemServices::OpenNamespace.


Object Paths to Classes

The object path to a class consists of three parts:

<server><namespace>:<classname>

The <server> portion of the syntax is a double leading backslash followed by the network name of the machine. The <namespace> portion is the object path to the appropriate namespace on that server. The <classname> portion is the relative object path to the instance within the namespace.

For example, to reach MyClass residing in the Root\Default namespace on the server MyServer, use the following object path:

\\MyServer\Root\Default:MyClass

To specify the current server, use the pseudonym "\\.":

\\.\Root\Default:MyClass

If the namespace is deeply nested, use the entire path of namespaces, employing a backslash as a separator:

"\\\\MyServer\\Ns1\\Ns2\\Ns3\\MyClass"

If the class resides in the current namespace on the current server, the object path can contain only the class name:

"MyClass"

The following code fragment illustrates how to use the relative object path to retrieve the class definition for MyClass:

BSTR Path = SysAllocString(L"MyClass");
    IWbemClassObject *pMyClass = 0;
    pHmmSvcs->GetObject(Path, 0, 0, &pMyClass, 0);

Object paths to classes are used in calls to:

  • IWbemServices::ExecMethod and IWbemServices::ExecMethodAsync to execute a particular method.
  • IWbemServices::GetObject and IWbemServices::GetObjectAsync to retrieve a particular class.


Object Paths to Instances

The syntax for an object path to an instance with a single key property is as follows:

<server><namespace>:<classname>.<key property>=<key>

For an instance that includes multiple key properties, the syntax is:

<server><namespace>:<classname>.<key property>=<key>,
                                    <keyproperty>=<key>, etc...

The following table describes the items in the object path syntax:

Object path syntax item | Description
<server> | A double leading backslash followed by the network name of the machine.
<namespace> | Object path to the appropriate namespace on the server specified by <server>.
<classname> | Relative object path to the instance within the namespace.
<key property> | Name of the property that serves as the key for the instance.
<key> | Value of the key property.

When accessing an instance that resides on the current server and in the current namespace, all that is necessary is the classname and key. For example, the following object paths point to single instances in the current namespace on the current server:

LogicalDisk="E:"

    ComPort=2

To retrieve a particular instance, use code similar to the following sample. The call to SysAllocString allocates and initializes the character string for the object path.The call to IWbemServices::GetObject retrieves the instance and places it in the contents of the pComPort parameter.

BSTR Path = SysAllocString(L"ComPort=2");
    IWbemClassObject *pComPort = 0;
    pWbemSvcs->GetObject(Path, 0, 0, &pComPort, 0);

For instances of classes that specify multiple properties as the key, there is no implied ordering of properties that make up the key. It is necessary to specify the value of each of the properties in the object path. For example, assume that the class MyClass2 has a compound key consisting of an integer property IntVal and a string property StrVal. The following object paths show two different ways to identify the same instance of MyClass2:

"MyClass.IntVal=33,StrVal=\"AAA\""
    "MyClass.StrVal=\"AAA\",IntVal=33"

Notice that because of the embedded quotes, the escape character must be used, as in a C-language or Microsoft® Visual C++® program.

Object paths to instances are used in calls to:

  • IWbemServices::DeleteInstance and IWbemServices::DeleteInstanceAsync to remove a particular instance.
  • IWbemCallResult::GetResultString to retrieve the path to an instance that has been newly added to the CIMOM repository.
  • IWbemServices::GetObject and IWbemServices::GetObjectAsync to retrieve a particular instance.

Note Only decimal integers of type VT_I4, Booleans of type VT_BOOL, and strings of type VT_BSTR can act as keys or parts of compound keys. Other key types, including arrays, are not permitted. Within the object path string, only decimal values are recognized as numeric portions of keys. Escaped quotes are permitted as part of an object path if embedded quotes are required.


Specifying Dates and Times

Date, date/time, interval, and time data types are aliases for each other and use the same fixed string format:

yyyymmddHHMMSS.ssssssXutc

Field | Size | Description
yyyy | 4 digits | Year
mm | 2 digits | Month
dd | 2 digits | Day
HH | 2 digits | Hour using the 24 hour clock
MM | 2 digits | Minute
SS | 2 digits | Second
ssssss | 6 digits | Microseconds
X | 1 character | Sign of the GMT offset field. Must be a "+" or "-".
Utc | 3 digits | Offset from GMT in minutes.

All fields must be of the indicated length, using leading zeros or asterisks as appropriate for the type.

As an example, Wednesday, May 25, 1994, at 1:30:15 PM EDT, would appear as:

"1994052513015.000000-300"


Handling Errors

Web-Based Enterprise Management (WBEM) providers can return extended error information using instances of the system class __ExtendedStatus. Applications can retrieve error information about operations completed with any of the asynchronous IWbemServices methods or methods from any of the other interfaces in the CIMOM API.

To access the error information, applications can call the COM function GetErrorInfo immediately after an error is indicated by an interface method, including any of the IWbemCallResult methods called during the processing of a semisynchronous call. GetErrorInfo returns a COM object that supports the IErrorInfo interface.

If errors occur during the processing of an asynchronous operation, the error object is delivered with the IWbemObjectSink::SetStatus method. The error object cannot be delivered through GetErrorInfo because there is no way to know when, or on which thread, such an asynchronous call is made.


Storing Resource Descriptor Data

The system registry contains resource-related data for machines that run Microsoft® Windows NT® . This data is located under the registry key HKEY_LOCAL_MACHINE\Hardware\ResourceMap, and is kept in a special registry data type named REG_RESOURCE_LIST. Obtain the resource-related data using the Registry Provider, one of the standard built-in providers that is included with the WBEM SDK.

To store resource-related data in the system registry, specify a string that contains the following fields:

Field | Description
Interface type | One of the following values are valid: Internal, Isa, Eisa, MicroChannel, TurboChannel, PCIBus, VMEBus, NuBus, PCMCIABus, CBus, MPIBus, or MPSABus.
Bus number | An integer specifying the bus number.
Partial descriptor number | An integer specifying the descriptor number.
Offset or union type | One of the following values are valid: Port.Start, Port.PhysicalAddress, Port.Length, Interrupt.Level, Interrupt.Vector, Interrupt.Affinity, Memory.Start, Memory.PhysicalAddress, Memory.Length, Dma.Channel, Dma.Port, Dma.Reserved1, DeviceSpecificData.DataSize, DeviceSpecificData.Reserved1, or DeviceSpecificData.Reserved2.

For example, the following resource descriptor illustrates a valid string:

local|hkey_local_machine\hardware\resourcemap\
  hardware abstraction layer\
  pc compatible eisa/isa HAL|.raw("eisa",0,0,"interrupt.affinity")


Creating a Namespace

Namespaces are used in WBEM to differentiate among the groups of classes and instances that represent particular management environments. Each new schema or version of a schema requires a new namespace. For example, all of the classes and instances that are defined in the Microsoft® Win32® schema reside in the \\root\cimv2 namespace.

Namespaces are represented by the __Namespace system class and classes that derive from this system class. The __Namespace class has a single property called Name, which must be unique within the scope of the parent namespace. The Name property must be set to a string that begins with a letter. All other characters in the string can be letters, digits, or underscores. All characters are case-insensitive.

Namespaces can be created using the Managed Object Format (MOF) language or the CIMOM API.

To create a new namespace with MOF, create a file with an instance of the __Namespace system class as follows:

instance of __Namespace
{
    Name = "MyNamespace";
};

This example shows the creation of a new namespace within the current namespace.

To create a namespace within a specific namespace other than the current one, use the #pragma namespace directive prior to the instance declaration. The next example shows how to create a namespace as a sibling to the \Root\Default namespace:

#pragma namespace("\\\\.\\Root")

instance of __Namespace
{
    Name = "MyNamespace";
};

To create a namespace using the COM interfaces of the CIMOM API:

  1. Call IWbemClassObject::SpawnInstance to define an instance of the __Namespace system class.
  2. Call IWbemServices::PutInstance, setting the contents of the pInst parameter to the new instance.


Creating a Base Class

Classes can be created using the Managed Object Format (MOF) language or the CIMOM COM API. To create a class with MOF, see Declaring Classes.

To create a class with the COM interfaces of the CIMOM API, use code similar to the following sample. This sample creates a class called Example. The g_pNamespace pointer is an IWbemServices pointer bound to the Root\Default namespace and obtained from IWbemLocator::ConnectServer. Some of the error-checking code is omitted for clarity:

void CreateClass()
{
  IWbemClassObject *pNewClass = 0;
  HRESULT hRes = g_pNamespace->GetObject(0, 0, &pNewClass, 0);
  VARIANT v;
  VariantInit(&v);

  // Create the class name
  // =====================

  V_VT(&v) = VT_BSTR;
  V_BSTR(&v) = SysAllocString(L"Example");
  BSTR Class = SysAllocString(L"__CLASS");
  pNewClass->Put(Class, 0, &v);
  SysFreeString(Class);
  VariantClear(&v);

  // Create the key property
  // =======================

  V_VT(&v) = VT_BSTR;
  V_BSTR(&v) = SysAllocString(L"<default>");
  BSTR KeyProp = SysAllocString(L"Index");
  pNewClass->Put(KeyProp, 0, &v);
  VariantClear(&v);
  SysFreeString(KeyProp);

  // Mark the "Index" property as the 'key'.
  // =======================================
  IWbemQualifierSet *pQual = 0;
  pNewClass->GetPropertyQualifierSet(KeyProp, &pQual);

  V_VT(&v) = VT_BOOL;
  V_BOOL(&v) = VARIANT_TRUE;
  BSTR Key = SysAllocString(L"Key");

  pQual->Put(Key, 0, &v);   // Qualifier flavors not required for KEY
  SysFreeString(Key);

  pQual->Release();   // No longer need the qualifier set for "Index"
  VariantClear(&v);

  // Create another property
  // =======================
  V_VT(&v) = VT_BSTR;
  V_BSTR(&v) = SysAllocString(L"<default>");
  BSTR OtherProp = SysAllocString(L"OtherInfo");
  pNewClass->Put(OtherProp, 0, &v, NULL);
  SysFreeString(OtherProp);
  VariantClear(&v);

  // Register the class with CIMOM
  // ============================
  hRes = g_pNamespace->PutClass(pNewClass, 0, 0);
  pNewClass->Release();
}

Note The class name is specified by setting the system property __CLASS to Example. Because properties marked as keys or indexes cannot be changed after a class has been created, it is important to specify key and index properties by calling IWbemServices::PutClass or IWbemServices::PutClassAsync before creating the class.


Creating a Derived Class

Creating a derived class is similar to creating a base class. The main difference is that before the class is created, the parent class must be located as shown in the following fragment. The class Example2 is created as a subclass to the Example class.

IWbemClassObject *pNewDerivedClass = 0;
  IWbemClassObject *pExampleClass = 0;

  BSTR PathToClass = SysAllocString(L"Example");
  HRESULT hRes = g_pNamespace->GetObject(PathToClass, 0,
    &pExampleClass, 0);

  SysFreeString(PathToClass);

  if (hRes != 0)
    return;

  pExampleClass->SpawnDerivedClass(0, &pNewDerivedClass);
  pExampleClass->Release();  // Don't need the superclass any more

  VARIANT v;
  VariantInit(&v);

  // Create the class name
  // =====================

  V_VT(&v) = VT_BSTR;
  V_BSTR(&v) = SysAllocString(L"Example2");
  BSTR Class = SysAllocString(L"__CLASS");
  pNewDerivedClass->Put(Class, 0, &v);
  SysFreeString(Class);
  VariantClear(&v);

  // Create another property
  // =======================
  V_VT(&v) = VT_BSTR;
  V_BSTR(&v) = SysAllocString(L"<default>");
  BSTR OtherProp = SysAllocString(L"OtherInfo2");
  pNewDerivedClass->Put(OtherProp, 0, &v);

  SysFreeString(OtherProp);
  VariantClear(&v);

  // Register the class with CIMOM
  // ============================
  hRes = g_pNamespace->PutClass(pNewDerivedClass, 0, 0);
  pNewDerivedClass->Release();


Creating and Modifying an Instance

To create an instance of an existing class, call IWbemClassObject::SpawnInstance. Every instance of a class inherits the properties that are defined with the class. Instances can differ from their classes only in the values of properties and qualifiers and in the number and types of qualifiers. Each instance can have its own set of qualifiers attached both to the instance itself and to any of the properties of the instance. These instance-specific qualifiers do not need to appear in the class declaration.

To store the instance in the CIMOM repository, call IWbemServices::PutInstance.

An instance can have instance-specific qualifiers and qualifiers that are attached to a property of the instance. These qualifiers do not have to appear in the class definition. An instance can override the value of a class qualifier only if the flavor of that qualifier was set to EnableOverride. See Qualifier Flavors for more information about overriding qualifier values.

An overridable qualifier can be modified or deleted by any instance of the class to which the qualifier is attached. Class qualifiers with flavors set to DisableOverride cannot be modified or deleted in any way.

The following code creates an instance of the Example class:

IWbemClassObject *pNewInstance = 0;
IWbemClassObject *pExampleClass = 0;

BSTR PathToClass = SysAllocString(L"Example");
HRESULT hRes = g_pNamespace->GetObject(PathToClass, 0, &pExampleClass, 0);
SysFreeString(PathToClass);

if (hRes != 0)
   return;

pExampleClass->SpawnInstance(0, &pNewInstance);
pExampleClass->Release();  // Don't need the class any more

VARIANT v;
VariantInit(&v);

// Create the index value.
// =======================

V_VT(&v) = VT_BSTR;

V_BSTR(&v) = SysAllocString(L"IX100");
BSTR KeyProp = SysAllocString(L"Index");
pNewInstance->Put(KeyProp, 0, &v);
SysFreeString(KeyProp);
VariantClear(&v);

// Other properties acquire the 'default' value specified
// in the class definition unless otherwise modified here.

// Write the instance to CIMOM
hRes = g_pNamespace->PutInstance(pNewInstance, 0, 0);
pNewInstance->Release();

After its creation, this instance has a path of \\.\Root\Default:Example.Index="IX100."

New properties are created initially with the VARIANT data type unless the Cimtype standard qualifier is attached to the property to specify its true type. For example, a date/time property should be created with the Cimtype qualifier set to the DATETIME type. When the Cimtype qualified is used, CIMOM checks that the qualifier specifies a type that is correct for the property.

To establish references to other objects, attach the Cimtype qualifier containing a string of the following format to a property of type VT_BSTR:

REF:ClassName

For example, if you require an object reference property that refers to Win32LogicalDisk instances, the Cimtype qualifier is attached to the property when you create your class definition.

BSTR RefProp = SysAllocString(L"MyReferenceProperty");
  IWbemQualifierSet *pQual = 0;
  pNewClass->GetPropertyQualifierSet(RefProp, &pQual);

  VARIANT v;
  VariantInit(&v);
  V_VT(&v) = VT_BSTR;
  V_BSTR(&v) = SysAllocString(L"REF:Win32LogicalDisk");
  BSTR QualName = SysAllocString(L"CIMTYPE");
  pQual->Put(QualName, WBEM_FLAVOR_FLAG_PROPAGATE_TO_INSTANCE, &v);

However, if there is an embedded object, use the keyword object instead of ref.


Event Notification

Web-Based Enterprise Management (WBEM) events are occurrences that either correspond to conditions that arise in the real world or to changes in repository managed by the Common Information Model Object Manager (CIMOM). After an event, a notification of its occurrence is generated by an event provider and delivered by CIMOM to one or more registered recipients, known as event consumers. Event providers send notifications in response to event occurrences, regardless of whether or not there are registered consumers. Event consumers register to receive notifications without knowledge of how and by whom events and their corresponding notifications are provided. Consumers register to receive notifications by specifying a filter. The filter is created using the WBEM Query Language (WQL). It describes the conditions under which the consumer wants to receive notification.

CIMOM serves as the intermediary between consumers and providers. Providers route notifications to appropriate consumers through CIMOM. Consumers registering for an event send their registration to CIMOM where it is held until it is cancelled or, in some cases, the consumer terminates. Providers generating a notification for an event also send their notification to CIMOM. By matching notifications with registered consumers and discarding those notifications that do not pass through the filter. The location of the consumer is not a factor; CIMOM forwards notifications to both local and remote consumers.


Intrinsic and Extrinsic Events

WBEM defines events as either intrinsic or extrinsic. Intrinsic events occur in response to changes to data in the CIM repository. For example, the creation of an instance is an intrinsic event. Both CIMOM and event providers send notifications of intrinsic events. CIMOM reports changes to data stored statically, such as instances of system classes. Event providers report changes to dynamic data, data related to the classes and instances that they create.

Extrinsic events occur in response to changes in both hardware and software system components, such as the breakage of a cable or the failure of a database. Because these events occur outside of CIMOM's scope, CIMOM has no understanding of their purpose and has no responsibility for sending notifications. Only event providers send notification of extrinsic events. However, CIMOM forwards both extrinsic and intrinsic event notifications to appropriate consumers.

WBEM defines a fixed set of intrinsic event types that are represented by system classes derived from the __Event system class. Event types correspond to the creation, modification, or deletion of a namespace, class, or instance. WBEM also defines a special timer event that can be generated either periodically or at a specific day and time. Because intrinsic events map to system classes, they can not be modified or extended. The following table briefly describes the intrinsic event classes:

Event system class | Description
__ClassCreationEvent | Generated when a class is created.
__ClassModificationEvent | Generated when a class is modified.
__ClassDeletionEvent | Generated when a class is deleted.
__InstanceCreationEvent | Generated when an instance is created.
__InstanceModificationEvent | Generated when an instance is modified.
__InstanceDeletionEvent | Generated when an instance is deleted.
__NamespaceCreationEvent | Generated when a namespace is created.
__NamespaceModificationEvent | Generated when an instance of a class derived from a class representing a namespace is modified.
__NamespaceDeletionEvent | Generated when a namespace is deleted.

Unlike intrinsic events, there is neither a fixed set of extrinsic event types nor any limit to the number of extrinsic event types that can be created. Extrinsic events correspond to the wide range of changes that can occur in the real world. WBEM allows event providers to create whatever event types best support the components that they monitor. Extrinsic events are represented by classes that derive from the __ExtrinsicEvent system class, a subclass of the system class __Event.

For example, consider the event provider that needs to report security violations. The following class would be defined to represent the extrinsic event:

class SecurityViolation : __ExtrinsicEvent
{
  string   Building;                    // Building where violation occurred
  sint32   EntranceNumber;            // Entrance where violation occurred
  datetime TimeOfDetection;            // Time of day of violation
};

To receive the SecurityViolation notifications, a consumer registers for the SecurityViolation event type. By default, the consumer receives notifications of all violations in all buildings during each 24-hour period. However, because the class allows the consumer to specify a particular building, entrance, and time of day, it is possible for the consumer to register a detailed filter and thus receive only notifications for violations that occur, for example, in a particular building.


Event Queries

When consumers register to receive event notifications, they specify a query that defines the type of event and the conditions under which it is delivered to them. These conditions depend on the properties that exist for the class used to represent the event. To create a query, consumers use the WBEM Query Language (WQL). WQL is a structured query language (SQL) dialect with extensions to support WBEM event notification and other WBEM-specific features.

In general, a query is limited to the form:

select <* | property_list> from <ClassName>
  where <selection_criteria>;

The SELECT clause specifies the properties and the FROM clause specifies the class that correspond to the event of interest. The WHERE clause specifies additional filtering and is optional. Without a WHERE clause, consumers receive all notifications for the event class; with a WHERE clause, consumers receive only particular notifications for the event class. WBEM strongly encourages consumers to use extremely detailled WHERE clauses. The cost of a complex query is minimal compared to the cost of delivering and processing unneeded notifications..

The following query shows how to request notification when disk space falls below one megabyte of free space. The SELECT statement requests all properties of the event class __InstanceModificationEvent. The WHERE clause narrows the receipt of that event to instances of the Win32LogicalDisk class when the FreeSpace property has a value of less than one million:

Select * from __InstanceModificationEvent
where TargetInstance isa "Win32LogicalDisk" and TargetInstance.FreeSpace < 1000000

Note that CIMOM can reject a query for a number of reasons. For example, the query can be too complex or resource-intensive for evaluation. When this occurs, CIMOM returns WBEM_E_INVALID_PARAMETER. For more information about event queries, see SELECT Statements for Event Notifications.

Queries are specified differently depending on the type of consumer. Temporary consumers are consumers whose event registration lasts only for the lifetime of the consumer. Temporary consumers specify their queries in the bstrQuery parameter when they call either IWbemServices::ExecNotificationQuery or IWbemServices::ExecNotificationQueryAsync. Permanent consumers are consumers whose registration lasts until it is explicitly cancelled. Permanent consumers specify their queries in instances of the __EventFilter system class.


Timer Events

Timer events are events that either occur once at a particular time of day or repeatedly at regular intervals. Unlike all other types of events, timer events require explicit action by the consumer in order for them to occur. Notifications of timer events are sent by CIMOM.

There are two types of timer events:

  • Absolute timer events, represented by instances of the __AbsoluteTimerInstruction class.
  • Interval timer events, represented by instances of the __IntervalTimerInstruction class.

Absolute timer events occur at particular times; interval timer events occur periodically. Both timer event classes derive from the system class __TimerInstruction. The __TimerInstruction class has two properties: TimerId and SkipIfPassed. The TimerId property is a unique user-assigned string that specifies the identifier for the events generated by this instruction. Each event generated by a timer instruction contains that instruction's TimerId property as its own TimerId property. SkipIfPassed defaults to FALSE, indicating that if an event occurs when CIMOM is unavailable, a belated notification is generated.

The __AbsoluteTimerInstruction class causes an event to occur only once at a specified date and time. This class has one property, EventDateTime, that consumers use to specify when the timer fires and the event occurs. EventDateTime is a fixed-length and fixed-format string that uses the DMTF time format shown as follows:

yyyymmddhhxxss.uuuuuuuu+GMT

Because the DMTF time format always has an explicit offset from GMT (Greenwich Mean Time), specifying the time zone is the job of the consumer. The GMT offset is in minutes. ‹.For more information about using this representation, see the DateTime topic in the Win32 Programmer's Reference. ›

The following table describes the valid contents for each portion of the EventDateTime property:

Part of EventDateTime property | Description
yyyy | Year, such as 1997 or 2000
mm | Month, such as 07 or 12
dd | Day, such as 01 or 30
hh | Hour in military format, such as 14
xx | Minute, such as 01 or 59
uuuuuuuu | Microseconds

The __IntervalTimerInstruction class causes an event to occur at a regular interval, much like the WM_TIMER message in Microsoft® Windows®: The __IntervalTimerInstruction class has one property: IntervalBetweenEvents. The IntervalBetweenEvents property defines the number of milliseconds between events. It is possible for CIMOM to ignore very small figures due to limitations in some operating systems.

CIMOM generates a timer event notification by creating an instance of the __TimerEvent class. The __TimerEvent class has a TimerId property which is a copy of the TimerId property included in the associated __TimerInstruction instance. A globally unique identifier (GUID) is often useful for preventing conflicts with other timer identifiers. A NumFirings property specifies how many times the timer event notification was sent during an interval when it was not possible to reach the consumer. This property has the value of 1 during normal operation.

The query entered as the filtering query in the event registration is usually based on the TimerId property of the timer event: Many consumers can receive event notifications generated by the same __TimerInstruction.


Event Consumers

Event consumers are the recipients of notifications that report the occurrence of an event. Event consumers register with CIMOM to receive the notifications by specifying a query that defines the event class and conditions under which delivery occurs.

WBEM identifies two types of consumers:

  • Temporary
  • Permanent

A temporary consumer receives event notifications only while it is active; its registration is temporary. Because registration is temporary, temporary consumers must re-register each time they start up. For example, a user interface application might register to receive notifications about objects that it displays. This type of consumer need not receive notifications when it is inactive.

A permanent consumer receives event notifications until its registration is explicitly cancelled; it does not matter whether the consumer is active. When CIMOM receives an event notification for a permanent consumer, it determines whether the consumer is currently running. If not, it locates and starts the consumer.

Permanent consumers correspond to actions that occur as the result of events. Notifications of the events are forwarded to permanent consumers by CIMOM if they match a user-specified filter. For example, a permanent consumer might register to receive notification of an event that results in a fax being sent.


Temporary Event Consumers

Temporary event consumers receive notifications of events only when they are running. Typical temporary consumers are user interface applications requiring notification of events that affect the data that displayed to end-users. Temporary consumers register for events whenever they wish and cancel the registration when they are no longer interested. CIMOM holds the registrations in memory; they are not stored persistently.

There are two ways that an application can register as a temporary consumer:

  • Create an object that implements the methods of the IWbemObjectSink interface and make two calls: one to IWbemServices::ExecNotificationQueryAsync, passing a pointer to this object in the pResponseHandler parameter, and the other to CoInitializeSecurity. CIMOM calls the IWbemObjectSink::Indicate method asynchronously whenever an event arrives.

    -- or --

  • Call IWbemServices::ExecNotificationQuery and poll for events by making repeated calls to IEnumWbemClassObject::Next . A pointer to IEnumWbemClassObject is returned by ExecNotificationQuery.

WBEM recommends that all temporary consumers implement the first approach. The main advantage of this approach is that notifications are delivered asynchronously as they occur. Asynchronous delivery of notifications makes polling unnecessary and it improves performance.

The only advantage to the second approach is that the consumer need not implement IWbemObjectSink. However, it means the consumer must poll each time it wants to receive event notifications, and polling is a time-consuming and inefficient technique. This approach is recommended for use only in unusual circumstances.


Registering as a Temporary Consumer

One of the following IWbemServices methods are called to register as a temporary event consumer:

  • ExecNotificationQuery, if the consumer relies on polling to receive events
  • ExecNotificationQueryAsync, if the consumer receives events asynchronously

Both of these methods require a query that specifies the event type and the conditions under which a notification is delivered. The asynchronous version of the call also specifies the sink, the object to receive the notifications as they arrive. The sink is an implementation of the IWbemObjectSink interface.

Do not call IWbemServices::ExecNotificationQueryAsync multiple times with the same sink. Use a separate sink for each class of registered event. Having a dedicated sink simplifies processing and aids in maintenance, making it possible to cancel one registration without affecting the others.

Temporary consumers that perform separate tasks after notification of a particular event type need to make separate calls to ExecNotificationQuery or ExecNotificationQueryAsync for each event type. For example, a consumer might be interested in instance modification events for a specific class of device and security violation events. The tasks to be performed upon receiving the instance modification event notification are much different than those to be performed upon receiving the security violation event. The consumer makes one call to the IWbemServices method of choice to register for the instance modification event and another call to register for the security violation event.

Make each query as specific as possible. The goal of registration is to register to receive only wanted notifications. Receiving superfluous notifications wastes processing and delivery time and does not use CIMOM's filtering ability to its fullest potential.


Implementing IWbemObjectSink

By implementing the IWbemObjectSink interface, a temporary consumer enables CIMOM to deliver event notifications asynchronously. IWbemObjectSink contains two unique methods:

  • Indicate
  • SetStatus

CIMOM calls Indicate to notify the consumer. The input parameters for Indicate are an array of objects and a count of the number of objects in the array. Each object in the array represents a separate event. A consumer's implementation of Indicate must quickly process the event notifications included in the array and return. It is important that Indicate be fast. If extensive processing is required, determine which of the notifications are affected and make a copy of the corresponding event object. Use a different thread to handle the processing for each affected event.

CIMOM calls SetStatus to report any errors pertaining to the consumer's registration.


Initializing DCOM Security

Because CIMOM handles security through DCOM, all temporary consumers that implement IWbemObjectSink to receive notifications must call the COM function CoInitializeSecurity in their process. Calling CoInitializeSecurity grants CIMOM the permission to call into the consumer's process.

Use the following parameters in the CoInitializeSecurity call:

CoInitializeSecurity(NULL, -1, NULL, NULL, RPC_C_AUTHN_LEVEL_NONE,
        RPC_C_IMP_LEVEL_IMPERSONATE, NULL, EOAC_NONE, NULL);

Call CoInitializeSecurity immediately after calling CoInitialize to initialize COM as is shown in the following code sample:

void main(int argc, char **argv)
{
    CoInitializeEx(0, COINIT_MULTITHREADED);
    CoInitializeSecurity(NULL, -1, NULL, NULL, RPC_C_AUTHN_LEVEL_NONE,
        RPC_C_IMP_LEVEL_IMPERSONATE, NULL, EOAC_NONE, NULL);
...
}


Cancelling Registration as a Temporary Consumer

Temporary consumers can register to receive notifications by calling either IWbemServices::ExecNotificationQuery or IWbemServices::ExecNotificationQueryAsync.

To cancel a registration that was created with ExecNotificationQueryAsync, temporary consumers can call IWbemServices::CancelAsyncCall. Regardless of whether the call to CancelAsyncCall succeeds or fails, temporary consumers must not delete their sink object until its reference count reaches zero.

To cancel a registration that was created with ExecNotificationQuery, temporary consumers release the IEnumWbemClassObject enumerator that was received in the call.

Registration is cancelled for each temporary consumer when it terminates.


Permanent Event Consumers

Permanent event consumers receive notifications whether or not they are running. The registration of a permanent consumer is stored persistently until the user explicitly removes it. When an event occurs, CIMOM determines whether or not the permanent consumer is active. If the consumer is inactive, CIMOM uses information stored in the system registry to locate the consumer and then loads it before attempting the notification.

Permanent consumers are implemented as COM objects. Depending on the platform, a permanent consumer can be implemented as an in-process DLL, local server, or remote server. In-process permanent consumers work on all platforms, have a higher rate of delivery, and a lower system overhead. This is because of the absence of network traffic and interprocess communication.

Permanent consumers implemented as local and remote servers require Distributed COM (DCOM) running on one of the following platforms:

  • Microsoft® Windows® 95
  • Microsoft® Windows® 98
  • Microsoft® Windows NT® 4.0 or later

On Windows NT, DCOM is run automatically. On the Windows 95 and Windows 98 platforms, DCOM must be enabled.

Permanent consumers can be configured to receive their event notifications either asynchronously or synchronously. With asynchronous event notification, the event provider is not blocked while a notification is delivered. The sending thread is unrelated to the receiving thread. The disadvantage to asynchronous delivery is that a context switch occurs between the time the provider produces the event and the consumer receives it.

With synchronous notification, the notification is delivered on the same thread that the event provider used to deliver the event to CIMOM. The event provider sends a notification and is blocked until it is delivered. To request synchronous notification, an administrator sets the SynchronousDelivery property in the Binding instance to TRUE. Only consumers that are extremely fast and can process an event in 20 micrseconds or less should consider supporting synchronous notification.


Permanent Consumer Architecture

The permanent consumer architecture consists of the following components:

Component | Description
Logical consumer | Instance of a class derived from the __EventConsumer system class. The properties of the class describe the action to be taken upon receipt of a notification.
Event filter | Instance of the __EventFilter system class that describes an event type and the conditions under which a notification is delivered.
Consumer - filter binding | Instance of the __FilterToConsumerBinding system class that describes a relationship between a logical consumer and an event filter.
Physical consumer (sink) | COM object implementing the IWbemUnboundObjectSink interface. Known as the sink, it identifies a physical destination for a particular notification.
Event consumer provider | WBEM provider that implements the IWbemEventConsumerProvider interface and provides access to a sink associated with a logical consumer.

A developer and an administrator typically share the responsibility for creating the logical consumer class and the various instances and for implementing the COM objects. The developer creates the logical consumer class and implements the two COM objects: the event consumer provider and the physical consumer. The administrator creates the logical consumer, event filter, and binding instances.

The following diagram shows how these components interact with CIMOM and the order in which the interaction occurs. First, CIMOM receives a notification to deliver. CIMOM examines the notification to determine if it matches any of the registered event filters. Next, to notify logical consumers, CIMOM examines the bindings for any of the filters that match.

For each logical consumer that is bound to a matching filter, CIMOM must then locate a corresponding event consumer provider. The event consumer provider bridges the gap between a logical consumer referenced in a binding and the physical sink that is dedicated to receive the notification. To locate and start the event consumer provider for a particular logical consumer, CIMOM uses the information registered by the provider. Once started, CIMOM calls the event consumer provider's IWbemEventConsumerProvider::FindConsumer method.

FindConsumer creates an instance of the physical consumer, which is also known as the sink. The physical consumer is the other COM object in the permanent consumer architecture. A physical consumer does not expose a CLSID; it implements only the IWbemUnboundObjectSink interface to provide the processing necessary to handle the event. CIMOM calls IWbemUnboundObjectSink::IndicateToConsumer, and includes a pointer to the logical consumer in its parameter list.

CIMOM releases its pointer to the event consumer provider after a configurable amount of time has passed. To configure this time value:

  1. Locate the singleton instance of the __EventConsumerProviderCacheControl class in the Root namespace.
  2. Set its single property to a time value that conforms to the DMTF time format. The new time value will take effect immediately.


Registering as a Permanent Consumer

To register to receive an event notification, permanent consumers must create at least one of each of the following instances:

  • Event consumer instance
  • Event filter instance
  • Binding between the event consumer and event filter

The event consumer instance, also known as the logical consumer, belongs to a class that is derived from the __EventConsumer system class. The logical consumer class provides data to be used by the physical consumer (sink) processing the notification.

The event filter is an instance of the __EventFilter system class and it contains the query that defines the type of event to be delivered and the conditions under which it is delivered.

The binding is an instance of the __FilterToConsumerBinding system class and specifies a relationship between a particular logical consumer and a particular event filter.

Users can create an unlimited number of logical consumers, event filters, and bindings.Because WBEM defines separate consumer, filter, and binding instances, permanent consumers can:

  • Send events matching multiple filters to a single consumer.
  • Send events from one filter to multiple consumers.
  • Send each type of event to a consumer that is dedicated to handling that particular event type.

To remove a registration, a user deletes the binding that represents it.


Creating a Logical Consumer

A logical consumer is an instance of a class that is derived from the __EventConsumer system class. The logical consumer class is designed by a developer to describe the action to be taken upon receipt of an event notification. As class designer, the developer can define as many properties as are appropriate. For example, to forward events to all of the employees of a particular building, the following class with the e-mail address of the employees can be defined:

class EMailConsumer : __EventConsumer
{
    [key] string EmailAddress;
}

Creating instances of the logical consumer class is up to the administrator. The administrator creates one instance of the EMailConsumer class for each employee to receive the event notification:

instance of  EMailConsumer
{
    EmailAddress = "mike@anywhere.com";
}

instance of  EMailConsumer
{
    EmailAddress = "susan@somewhere.com";
}

Note Permanent consumers that receive events generated with the HyperMedia Management Protocol (HMMP) must define their logical consumers to be instances of a class derived from the __HMMPEventConsumer system class, a subclass of __EventConsumer. The __HMMPEventConsumer class has one property: URLToFinalConsumer. The administrator sets this property to the object path of the consumer.


Creating an Event Filter

An event filter defines the criteria for receiving an event notification and is an instance of the system class __EventFilter. Administrators create event filters to indicate the class of event that they want to receive and the conditions under which they want to receive it. As with events, event filters belong to a namespace. That is, each event filter works only on events that belong to the namespace to which the filter also belongs.

The __EventFilter system class has three properties:

  • Name
  • Query
  • QueryLanguage

The Name property is a string that uniquely identifies the event filter. Because an event filter is only used internally by CIMOM, WBEM recommends that the Name be set to a GUID converted into a string. However, consumers can use any private scheme for filter naming as long as there is no chance for conflict with other filters.

The Query property is a string that specifies the event criteria.

The QueryLanguage property specifies the language used for the query. Because WBEM currently supports only WQL as a query language, Query must be set to a valid WQL statement and QueryLanguage must be set to "WQL.".

For example, the following event filter requests an instance creation event whenever a new DiskDrive instance is created:

Instance of __EventFilter
{
    Name = "{7ca44681-045f-11d1-ae97-00c04fb68820}";'
].
    Query =
           "select * from __InstanceCreationEvent "
           "where TargetInstance.__CLASS = \"DiskDrive\"";
    QueryLanguage = "WQL";
}

Note that the preceding query specifies that only creation events for instances of the DiskDrive class are candidates for event notification. This does not include instances of classes derived from the DiskDrive class. If you want to receive events that apply to any instance of DiskDrive class or its derived classes, use the isa ("is a") operator in the Query property of the event filter as follows:

Instance of __EventFilter
{
    Name = "{7ca44681-045f-11d1-ae97-00c04fb68820}"
    Query =
           "select * from __InstanceCreationEvent "
           "where TargetInstance isa \"DiskDrive\"";
    QueryLanguage = "WQL";
}

Administrators can narrow the scope of their queries if there are properties defined for the target class. For example, if the DiskDrive class includes an ID property, it is possible to request an event notification only when the value of the drive's ID property is within a particular range:

Instance of __EventFilter
{
    Name = "{7ca44681-045f-11d1-ae97-00c04fb68820}"
    Query =
          "Select * from __InstanceCreationEvent"
          "where TargetInstance isa \"DiskDrive\""
          "and (TargetInstance.ID < 100 or TargetInstance.ID > 500)";
    QueryLanguage = "WQL";
}

TargetInstance contains a copy of the object that was created, modified, or deleted. Because TargetInstance is weakly typed, it is legal to use property names that occur in the affected object at event time.

Since the query can take on any legal form within the bounds of WQL, administrators can achieve very precise filtering. For example, placing the NOT operator in front of the parenthesized OR clause in the previous query example returns the complement result set. Administrators are encouraged to specify the most restrictive query possible to avoid needless interprocess communication and network traffic. It is best to allow CIMOM do as much filtering as possible.


Binding a Logical Consumer to an Event Filter

After creating a logical consumer and an event filter, an administrator must associate a particular consumer with a particular filter. This association is accomplished by creating a binding object, an instance of the __FilterToConsumerBinding system class. The __FilterToConsumerBinding class is an association class; that is, its properties include references to the instance of the derived __EventConsumer class and the __EventFilter instance.

A third property, SynchronousDelivery, determines whether event notifications are delivered synchronously or asynchronously. Setting this property to TRUE is a request for synchronous delivery. Whether or not events are actually delivered synchronously depends on whether the associated event consumer provider supports synchronous delivery. Synchronous delivery should only be considered when the permanent consumer can process an event within 20 msec.

The following __FilterToConsumerBinding instance shows how to associate an instance of the EmailConsumer class, a class derived from __EventConsumer, with a particular event filter. The object path of the logical consumer is its e-mail address, stored in the EmailAddress property of the class. The object path of the event filter is the GUID value stored in its Name property. Events are to be delivered asynchronously.

Instance of __FilterToConsumerBinding
{
    Consumer = "EmailConsumer = \"mike@anywhere.com\"";
    Filter = "__EventFilter =
       \"{7ca44681-045f-11d1-ae97-00c04fb68820}\"";
    SynchronousDelivery = FALSE;
}


Implementing an Event Consumer Provider

An event consumer provider is a WBEM provider that supplies the link between a logical consumer, which is an instance of a class in the CIM repository that provides data for processing the event, and a physical consumer, which is a COM object that implements the IWbemUnboundObjectSink interface. CIMOM calls the IndicateToConsumer method of this interface to deliver the event. Physical consumers are also known as sinks.

Implementing an event consumer provider involves the following three tasks:

  • Implementing the IWbemEventConsumerProvider interface.
  • Supplying one or more implementations of the IWbemUnboundObjectSink interface.
  • Registering the event consumer provider.


Implementing IWbemEventConsumerProvider

The IWbemEventConsumerProvider interface includes one unique method: FindConsumer. The first time an event must be delivered to a particular consumer, CIMOM calls this method to retrieve a pointer to the sink for that logical consumer. All subsequent occurrences of the event are sent to the sink provided in the initial call through its IWbemUnboundObjectSink::IndicateToConsumer method. CIMOM will release the sink after a configurable period of no deliveries. If an event is targeted for a consumer that has been released, FindConsumer will be called again to acquire a new sink.

There are three approaches to implementing the FindConsumer method:

  • Provide a single sink (i.e. a single implementation of IWbemUnboundObjectSink) for all logical consumers.
  • Provide a different sink for each logical consumer.
  • Divide logical consumers into groups and provide a different sink for each group.

Regardless of approach, a sink should not be implemented in such a way that it is dependent on the event consumer provider. CIMOM releases an event consumer provider after a designated interval has lapsed between calls. Because the event consumer provider is needed only to supply pointers to sinks for new logical consumers, CIMOM can release it after all of the logical consumers have been serviced. The sinks, however, must remain to receive all of the events that occur.

Deciding which of the three approaches to take is important because the decision can affect performance and efficiency. The first approach, implementing a single sink, is the most efficient in terms of space because only one COM object is stored in memory. The second approach is the opposite of the first and is intended to optimize performance. Having a dedicated sink ready to receive an event as it occurs saves time. The third approach is a hybrid, a compromise between the first two approaches.

To illustrate the trade-offs between implementation strategies, consider an event consumer provider that supplies sinks for logical consumers that log messages to files. With the first strategy, the event consumer provider supplies the same sink for all events that arrive for all logical consumers. The single sink bears the responsibility for examining the data included with the logical consumer and determines how to proceed. Most likely, each event involves opening a file, logging the message, and closing the file. While efficient in terms of space, this strategy would involve a significant amount of processing time.

The second strategy is faster, but less efficient because of its cost in terms of memory. The event consumer provider supplies a different sink for each logical consumer. Because each sink maintains its own file, the file is always open and ready to log messages as events occur. The sink could then close the file when it is released by CIMOM after a timeout, providing efficient performance both in high-speed and in low-speed delivery scenarios.

The hybrid approach can involve having a few different files, possibly tied to the particular message to be logged. As a compromise between the first two strategies, multiple COM objects handle multiple open files. An event consumer provider taking this approach reads the file name during the FindConsumer call, opens the file, and returns the sink that will log all messages into this file, closing it on the last Release. With this approach, the efficiency of knowing exactly which file to log to without searching or opening it anew is preserved. Also, the consumer can save memory by combining the sinks that log different messages to the same file, an area where no performance gains are to be had.


Implementing IWbemUnboundObjectSink

Implementing a sink involves implementing the IWbemUnboundObjectSink interface. The IWbemUnboundObjectSink interface has one unique method: IndicateToConsumer. IndicateToConsumer contains the code for processing the events that it receives. It has three parameters: a pointer to the logical consumer, an array of objects, and the number of objects in the array. Because each object in the array corresponds to a separate event, each object must be treated separately.

To support synchronous notification, a sink must be able to complete its event processing in less than 20 msec. Extremely fast event consumer providers that want to support synchronous notification must not hold onto the IWbemClassObject pointer or increment its reference count in the IndicateToConsumer method. If the object is needed beyond the lifetime of the IndicateToConsumer call, a copy needs to be made. However, long term access ito the information pointed to by the IWbemClassObject pointer is required, then it is recommended that the event consumer provider not support synchronous notification. Event consumer providers indicate the type of notification that they support when they complete their registration.


Implementing an Event Provider

An event provider is implemented as a COM object that exposes a class identifier (CLSID) and supports one required interface: IWbemEventProvider. IWbemEventProvider has one method that it adds to the three IUnknown methods: ProvideForNamespace.

CIMOM calls an event provider's ProvideForNamespace method soon after it loads the provider. In the call, CIMOM passes a pointer to the sink, the target location for the event. Event providers must increment the reference count on the sink by calling its IWbemObjectSink::AddRef method, the standard COM method for incrementing a reference count. There are no special requirements that CIMOM introduces above and beyond the COM standard.

CIMOM also supplies an IWbemServices pointer to an event provider in the ProvideForNamespace call. Event providers can use this pointer to request services such as the creation or deletion of instances. Event providers should increment the reference count on the services object using the standard COM technique by calling IWbemServices::AddRef and return immediately. A separate thread must be spawned for sending events.

To access and load an event provider, CIMOM creates a separate provider object using the COM function CoCreateInstance. This call is made for each namespace that CIMOM requires the event provider to function in. When CIMOM no longer requires the provider, it calls IWbemEventProvider::Release.

A second interface, IWbemEventProviderQuerySink, can also be implemented by an event provider as an option. IWbemEventProviderQuerySink is most useful for providers that generate multiple types of notifications because it allows them to produce notifications based on specific consumer requests. IWbemEventProviderQuerySink helps to avoid sending useless event notifications.

IWbemEventProviderQuerySink includes two methods in addition to those inherited from IUnknown: NewQuery and CancelQuery. Whenever CIMOM receives a new or modified query on behalf of a consumer, CIMOM calls the NewQuery method to echo the query to the provider. The provider can examine the query to see what event notifications are actually being requested. For example, a provider supporting ten classes of events does not want to generate notifications for all classes unless absolutely necessary. IWbemEventProviderQuerySink allows a provider to examine incoming queries and generate only notifications that will be delivered to a registered consumer. Whenever a consumer registration is cancelled, CIMOM calls CancelQuery to report the cancellation to the provider.

For more information about creating and evaluating queries, see WBEM Query Language.

Whereas IWbemEventProvider is called only once after an event provider becomes active, IWbemEventProviderQuerySink is called continuously as appropriate. The provider can ignore all calls at its own discretion. This is very important; supporting IWbemEventProviderQuerySink indicates that a provider has agreed to supply at least the events that are requested by the queries. A provider can generate more events than are requested and CIMOM will post-filter the events as appropriate. This gives providers the freedom to implement IWbemEventProviderQuerySink and optimize their processing without a complete understanding of the query language. For instance, if a provider cannot understand a particular query, it can generate all possible events.

Whereas IWbemEventProvider is called only once after an event provider becomes active, IWbemEventProviderQuerySink is called continuously as appropriate. The provider can ignore all calls at its own discretion.

Because not all event providers support IWbemEventProviderQuerySink, CIMOM calls a provider's IWbemEventProvider::QueryInterface method at load time to determine if support exists.

Event providers that want to supply many notifications rapidly for the same class of event should reuse the same event object. CIMOM never holds onto the event object past the completion of the IWbemObjectSink::Indicate call.


WBEM Query Language

The Web-Based Enterprise Management (WBEM) Query Language (WQL) is a subset of standard ANSI SQL with minor semantic changes to support WBEM. WQL includes operations for reading classes and instances and operations to support WBEM-specific schema relationships and event notification. WQL is a retrieval-only language and cannot be used to update, insert, or delete classes or instances.

WQL supports three statements:

  • SELECT
  • ASSOCIATORS OF
  • REFERENCES OF

The SELECT statement is the standard SQL statement for retrieving information with a few restrictions and a few extensions to support event notification . The ASSOCIATORS OF and REFERENCES OF statements are WBEM-specific variations of the SELECT statement that support the traversal of associations.

To view the Backus-Naur Form definition for WQL, see the SQL1 BNF Syntax Description appendix.


WQL SELECT Statement

The WQL SELECT statement is much like the standard SQL statement for retrieving information. Where the SQL SELECT statement is typically used in the database environment to retrieve particular columns from tables, the WQL SELECT statement is used in WBEM to retrieve properties from classes. The supported scope also differs from SQL. While SQL supports queries across multiple tables, WQL supports only single class queries.

The most basic SELECT statement uses the following syntax:

select * from <ClassName>

This statement returns an instance that contains all of the properties for the specified class and its derived classes. To request particular properties, replace the asterisk with a property list delimited by commas:

select <property_1, property_2,   property_N> from <ClassName>

Using normal SQL rules, subsets of class instances can be selected by specifying a query constrained by a WHERE clause. The WHERE clause is limited to the following forms:

property operator constant

--or—

constant operator property

The constant must be of the correct type for the property and the operator must be one of the following values:

  • < (less than)
  • > (greater than)
  • <= (less than or equal to)
  • >= (greater than or equal to)
  • = (equal to)
  • != or <> (not equal)

String comparisons using = and != are always case-insensitive.

When the WHERE clause contains more than one property, operator, and constant, each group must be joined with AND, OR, or NOT.

The following examples show valid SELECT statements. The first example retrieves all of the properties of the Win32_LogicalDisk class belonging to instances that have their Name property set to either "C:" or "D:":

select * from Win32_LogicalDisk
    where Name = "C:" or Name = "D:"

The second example retrieves disks named "C:" or "D:" only if they have a certain amount of free space remaining and have NTFS file systems:

select * from Win32_LogicalDisk
    where (Name = "C:" or Name = "D:")
    and   FreeSpace > 2000000
    and   FileSystem = "NTFS"

Note In addition to queries involving multiple classes, the following features of the SQL SELECT statement are not supported by WQL:

  • Arbitrary arithmetic expressions on one side of a relational operator
  • Property names on both sides of a relational operator

    For example, the following statement is not legal because of the use of property names and arbitrary arithmetic expressions:

    select * from PhysicalDisk
    where Partitions < (4 + 7 - 2)
    or   (Partitions = SectorsPerTrack / 7)


SELECT Statement Result Sets

A SELECT statement returns a result set. If a SELECT statement specifies a class with many derived classes as the target class, instances of all of the derived classes are automatically included in the result set. To override this default behavior and retrieve only instances of the target class, the SELECT statement must include a WHERE clause that includes the __CLASS system property:

/* Retrieve instances of the Device class and its derived classes */
select * from Device

/* Retrieve only instances of the Device class */
select * from Device where __CLASS = "Device"

Similarly, using the __CLASS system property to test for classes derived from the target class restricts the result set to instances only of those classes:

Select * from Device where __CLASS="Modem" or __CLASS="Motherboard"

Projection operations using the SELECT statement are accomplished by explicitly listing the desired properties. The following statement shows how to retrieve only the Name and FreeSpace properties from every instance of the Win32_LogicalDisk class. Attempts to access other properties known to be in the class will fail.

Select Name, FreeSpace from Win32_LogicalDisk

In addition to the __CLASS property, there are other system properties that are automatically included in the result set regardless of whether they were specified in the WHERE clause. The following table describes the rules that govern the use of these system properties:

System property | WQL usage
__CLASS | Always returned with each instance whether requested or not.
__SERVER | Only returned if the __PATH property is requested.
__NAMESPACE | Only returned if the __PATH property is requested.
__DERIVATION | Only returned if explicitly requested.
__DYNASTY | Only returned if explicitly requested.
__SUPERCLASS | Only returned if explicitly requested.
__PATH | Causes the key property or properties to be returned along with the __SERVER and __NAMESPACE properties.
__RELPATH | Causes the key property or properties to be returned.


SELECT Statements for Event Notifications

Event providers use WQL to specify the types of event notifications that they support; event consumers use WQL to specify the types of event notifications that they receive. The WQL SELECT statement includes several extensions to the standard SQL syntax to support event notification:

  • WITHIN clause
  • GROUP BY clause
  • HAVING COUNT clause
  • ISA operator (pronounced "is a")

Since many almost-identical events can occur within a specified amount of time, flooding is possible. To prevent possible flooding, WQL supports the GROUP BY and HAVING COUNT clauses to aggregate nearly-identical events into a single "representative" event. The result event is always an instance of the system class __AggregateEvent:. All related events are summarized by the Representative property, and the Count property tells the user how many events actually occurred.


SELECT Statement WITHIN Clause

The WITHIN clause is used to reduce the number of notifications that are sent for events that occur with great frequency. The WITHIN clause is also used by CIMOM to simulate events when no event provider exists that can generate notifications for a particular class.

The WITHIN clause appears immediately prior to the WHERE clause:

select <property_list> from <class> WITHIN interval <where_clause>

The interval value that follows the WITHIN keyword is the maximum amount of time that can pass before a notification must be sent representing the specified event class. This interval is a floating-point number and can be fractional to deal with values smaller than one second. However, it is recommended that the interval represent a number of seconds rather than an extremely small value such as 0.001. Specifying too small a value can cause CIMOM to reject the statement as invalid.

For example, this query requests notification of instance modification events for the Win32_LogicalDisk class. However, only one notification is sent every 10 seconds, regardless of how many events actually occur in that timeframe.

select * from __InstanceModificationEvent within 10.0
    where TargetInstance isa "Win32_LogicalDisk

If the query requests notification of an intrinsic event for a class that has is unsupported by any of the registered event providers, CIMOM generates the notifications. CIMOM polls instances of the class according to the interval specified in the WITHIN clause looking for changes.


SELECT Statement GROUP BY Clause

The GROUP BY clause is used to reduce the flow of notifications by combining several notifications into a single aggregate notification. The aggregate notification is an instance of the system class __AggregateEvent, a class that contains two properties: Representative and NumberOfEvents. Representative is an object property that contains the event instance, while NumberOfEvents stores the number of events that were combined to form the single aggregate event.

The GROUP BY clause can be placed anywhere after the WHERE clause as is shown in the following syntax:

select <property_list> from <class> <where_clause>
        GROUP BY property_list

The property list that follows the BY keyword is a comma-delimited list of properties that are included in the event class.

For example, the following statement requests notifications about instance modification events reporting changes to Win32_LogicalDisk instances. CIMOM groups all events that occur for a particular drive letter and sends one notification for each group. The notification is an instance of the __AggregateEvent class:

select * from __InstanceModificationEvent
    where TargetInstance isa Win32_LogicalDisk
    group by DriveLetter

Without the GROUP BY clause, the aggregate event would not provide any meaningful information about drive letters. Without the WITHIN clause, the consumer runs the potential risk of being flooded with notifications. Combining the WITHIN and GROUP BY clauses simplies the processing of event notifications and reduces excessive traffic.

Event providers implement the following tasks to support aggregated event notifications:

  1. Start a clock at the next event.
  2. Aggregate any new events within the time interval in the WITHIN clause.
  3. When the interval expires, deliver an aggregate event.
  4. Restart the clock and repeat with steps 2 and 3.


Combining the WITHIN and GROUP BY Clauses

The WITHIN clause can be used in conjunction with the GROUP BY clause. The order of these clauses is not important although they must follow the WHERE clause as shown in the following syntax:

select <property_list> from <class>
   <WHERE clause> GROUP WITHIN interval BY property_list

The interval that follows the WITHIN keyword specifies the number of seconds that should pass before an aggregate event is sent. The property list that follows the BY keyword specifies the properties that are included in the event class.

To handle a query that contains the WITHIN and GROUP BY clauses, CIMOM performs the following tasks:

  1. Filters incoming events based on critieria in WHERE clause.
  2. Computes the values of the properties in the property list for each matching event.
  3. Places the event in a bin that contains other events with the same property values.
  4. Generates one aggregate event for each of the bins after the number of seconds specified by the interval in the WITHIN clause has passed. Empties each bin after the event has been sent.


SELECT Statement HAVING COUNT Clause

The HAVING COUNT clause sets a minimum limit on the number of discrete events that produce an aggrevate event, reducing overall event traffic. The HAVING COUNT clause is used after the GROUP BY clause:

select…  <where_clause>
         <GROUP BY proplist>  <HAVING COUNT operator constant>

The HAVING COUNT operator is one of the operators that are valid in the SELECT statement. The constant is an unsigned integer. For example, the following statement returns notifications of instance modification events if more than 25 events occur during a 10 second interval:

select * from __InstanceModificationEvent
    where TargetInstance isa Win32_LogicalDisk
    group by DriveLetter within 10 having count > 25


SELECT Statement ISA Operator

The ISA operator occurs within the WHERE clause in the same place as any other relational operator. This operator is used to assert that an instance is a member of a particular class hierarchy. For example, the following statement requests notification of instance notification events for all instances that are members of any class deriving from the LogicalDisk class:

select * from __InstanceModificationEvent
where TargetInstance isa LogicalDisk

Using this SELECT statement differs from using an identical statement that replaces the ISA operator with an equal sign (=). The statement with the equal sign only returns instances that are members of the LogicalDisk class. No instances from derived classes are included in the result set. When requesting a hierarchy of event classes, using the ISA operator eliminates the need to keep track of new derived classes. Subclasses of LogicalDisk that appear after the SELECT statement has been submitted are automatically included in the result set if they satisfy the criteria specified by the WHERE clause.

When a modifier such as TargetInstance is used with a property, the property can be applied to the target class and to any of its subclasses. Because weak typing is used, CIMOM cannot detect an invalid property name at the time the query is submitted:

Select * from __InstanceModificationEvent within 10.0
    where TargetInstance isa "Win32_LogicalDisk"
    and   TargetInstance.FreeSpace < 1000000

The ISA operator can also be used in a SELECT statement with a property that is an embedded object. The result set will include all instances of classes that are derived from the embedded object class.


WQL and Associations

WQL supports the programmatic traversal of associations with a SELECT statement that uses an association class as the target class and with the following two query extension statements:

  • ASSOCIATORS OF
  • REFERENCES OF

An association describes a relationship between two classes or instances of classes. Each association is described by an association class, which is tagged with the Association standard qualifier and has as two of its properties references to the related classes or instances.

The ASSOCIATORS OF statement retrieves all instances that are associated with a particular instance, referred to as the source. The instances that are retrieved are referred to as the endpoints. For example, consider a source that is an instance of the class Adapter. The Adapter class is associated with the Protocol class and with the Driver class. Issuing the following ASSOCIATORS OF statement retrieves all of the Protocol and Driver instances associated with that Adapter instance:

associators of {Adapter="AHA-294X"}

The following diagram illustrates this example. The source is an instance of the Adapter class. There are three association instances, two that reference a Protocol instance and one that references a Driver instance. The endpoints are the Driver and Protocol instances:

The REFERENCES OF statement is similar to the ASSOCIATORS OF statement in its syntax, but rather than retrieving endpoint instances it retrieves association instances.


ASSOCIATORS OF Statement

The ASSOCIATORS OF statement supports the traversal of associations programmatically by retrieving all endpoint instances that are associated with a particular source instance.

The syntax of the ASSOCIATORS OF statement is:

associators of {SourceObject} where
    AssocClass = AssocClassName
    ClassDefsOnly
    RequiredAssocQualifier = QualifierName
    RequiredQualifier = QualifierName
    ResultClass = ClassName
    ResultRole = PropertyName
    Role = PropertyName

To specify a source instance, use any valid object path. As with the SELECT statement, the WHERE clause is optional and is used to further define the query. That is, the following statement is perfectly valid:

associators of {Adapter="AHA-294X"}

ASSOCIATORS OF statements that include a WHERE clause use one or more of the predefined keywords: AssocClass, ClassDefsOnly, RequiredAssocQualifiler, RequiredQualifier, ResultClass, ResultRole, or Role.

The AssocClass keyword indicates that the returned endpoints must be associated to the source through the specified class or one of its derived classes. For example, the following statement returns only endpoints that are associated to the source through the AdapterDriver association class or any of its derived classes:

associators of {Adapter="AHA-294X"} where AssocClass=AdapterDriver

The ClassDefsOnly keyword indicates that a list of class names is returned rather than actual instances of the classes. These are the classes that the endpoint instances belong to. For example, the following statement returns the Driver and Protocol class names:

associators of {Adapter="AHA-294X"} where ClassDefsOnly

The RequiredAssocQualifier keyword indicates that the returned endpoints must be associated to the source object through an association class that includes the specified qualifier. This type of filtering is used to eliminate broad ranges of endpoints unless they associate to the target through a particular set of tagged association classes. For example, the following statement returns endpoint instances if the association class includes a qualifier called SpecialTag:

associators of {Adapter="AHA-294X"}
    where RequiredAssocQualifier = SpecialTag

The RequiredQualifier keyword indicates that the returned endpoints associated to the source object must include the specified qualifier. The RequiredQualifier keyword can be used to include particular types of instances in the result set. For example, the following statement returns endpoint instances that include a qualifier called AdapterTag:

associators of {Adapter="AHA-294X"}
    where RequiredQualifier = AdapterTag

The ResultClass keyword indicates that the returned endpoints associated to the source object must belong to or derive from the specified class. For example, the following statement returns endpoint instances that are derived from the SystemDriver class:

associators of {Adapter="AHA-294X"}
    where ResultClass = SystemDriver

The ResultRole keyword indicates that the returned endpoints must play a particular role in their association with the source object. The role is defined by the the specified property and must be a reference property of type ref. For example, the ResultRole keyword can be used to retrieve all endpoints that play the role of child in their association with a source object, as following query illustrates:

associators of {Adapter="AHA-294X"}
    where ResultRole = child

The Role keyword indicates that the returned endpoints participate in an association with the source object where the source object plays a particular role. The role is defined by the the specified property and must be a reference property of type ref. For example, the Role keyword can be used to retrieve all endpoints associated with a source object that plays the child role, as the following query illustrates:

associators of {Adapter="AHA-294X"}
    where Role = child


REFERENCES OF Statement

The REFERENCES OF statement supports the traversal of associations programmatically by retrieving all association instances that refer to a particular source instances.

The syntax of the REFERENCES OF statement is:

references of {SourceObject} where
    ClassDefsOnly
    RequiredQualifier = QualifierName
    ResultClass = ClassName
    Role = PropertyName

To specify a source object, use any valid object path. As with the SELECT statement, the WHERE clause is optional and is used to further define the query. That is, the following statement is perfectly valid:

references of {Adapter="AHA-294X"}

REFERENCES OF statements that include a WHERE clause use one or more of the predefined keywords: ClassDefsOnly, RequiredQualifier, ResultClass, or Role.

The ClassDefsOnly keyword indicates that a list of association class names is returned rather than actual association instances. The class names returned are the class names of all association instances that reference the source object. For example, the following statement returns AdapterDriver and AdapterProtocol class names:

references of {Adapter="AHA-294X"} where ClassDefsOnly

The RequiredQualifier keyword indicates that the returned association objects must include the specified qualifier. The RequiredQualifier keyword can be used to include particular instances of associations in the result set. For example, the following statement returns association instances that include a qualifier called AdapterTag:

references of {Adapter="AHA-294X"}
    where RequiredQualifier = AdapterTag

The ResultClass keyword indicates that the returned association objects must belong to or derive from the specified class. For example, the following statement returns asssociations of the AdapterDriver class or subclasses of AdapterDriver:

references of {Adapter="AHA-294X"}
    where ResultClass = AdapterDriver

The Role keyword indicates that the returned associations are only those in which the source object plays a particular role. The role is defined by the specified property, a reference property of type ref. This is the property in the association that holds the reference to the source object. The Role keyword is useful in associations where a certain object can play one role in some cases and another role in others, such as in hierarchical associations. The Role keyword can be used to retrieve all of the associations in which the source object plays the role of parent, for example. The following statement illustrates the syntax for retrieving associations that include a reference to the source object as the parent:

references of {Adapter="AHA-294X"}
    where Role = parent


Schema Associations

The ASSOCIATORS OF and REFERENCES OF statements can be used to query for schema associations in addition to querying for data associations. With data association queries, instances are returned. With schema association queries, names of classes are returned. For example, a schema query can be used to find all of the association classes defined in the schema that reference a source class.

The syntax for the ASSOCIATORS OF and REFERENCES OF statements is the same for schema association queries as it is for data association queries with two exceptions:

  • The source is a class rather than an instance.
  • There is an additional keyword, SchemaOnly, which identifies the query as applying to a schema rather than to data.

The complete syntax of the ASSOCIATORS OF statement for a schema query is:

associators of {SourceClass} where
    AssocClass = AssocClassName
    ClassDefsOnly
    RequiredAssocQualifier = QualifierName
    RequiredQualifier = QualifierName
    ResultClass = ClassName
    ResultRole = PropertyName
    Role = PropertyName
    SchemaOnly

The complete syntax of the REFERENCES OF statement for a schema query is:

references of {SourceClass} where
    ClassDefsOnly
    ResultClass = ClassName
    Role = PropertyName
    RequiredQualifier = QualifierName
    SchemaOnly

For example, the following query returns the Protocol and Driver classes, the two classes that refer to the source class:

associators of {Adapter} where
    SchemaOnly

This next query returns only the Driver class because of the restriction placed by the AssocClass keyword:

associators of {Adapter} where
    AssocClass = AdapterDriver
    SchemaOnly


Security and Authentication

Web-Based Enterprise Management (WBEM) supports a limited form of security for the Microsoft® Windows® 98 platform that involves validating a user's logon for the local machine and for remote access. A validated user is granted access to the entire Common Information Model (CIM) schema. WBEM does not secure system resources, such as individual classes, instances, and namespaces. Security is limited because Windows 98 is not a secure operating system and does not support file system or registry security.

All security-related information is represented by instances of WBEM system classes located in the Root\Security namespace. These classes and instances can only appear in the Root\Security namespace and must remain there permanently.

The WBEM Administrator application can be used to set permissions for WBEM users. It is similar to the User Manager application supplied with Microsoft® Windows NT®.

In WBEM, all security accounts are referred to as subjects. There are two types of subjects: user and group. Users are represented by instances of the __NTLMUser system class, which describes individual users. Groups are represented by instances of the __NTLMGroup system class, which describes multiple users. Both the __NTLMUser and __NTLMGroup classes derive indirectly from the __Subject system class, an abstract class that is not intended to be used for instantiation. More directly, __NTLMUser derives from the generic __User class and __NTLMGroup derives from the generic __Group class.


Security Classes

Web-Based Enterprise Management (WBEM) defines the following system classes for describing data that is related to security:

  • The abstract base class __SecurityRelatedClass.
  • The abstract base class __Subject.
  • The __User class.
  • The __NTLMUser class.
  • The __Group class.
  • The __NTLMGroup class.

All of these classes belong to the Root\Security namespace. The __SecurityRelatedClass abstract class serves as the base class for all security classes. The __Subject class is the base class for all users, represented by the __User class, and all groups, represented by the __Group class.

The properties defined for the __Subject class include the full name for the user, assigned permissions, and three boolean flags. One flag indicates whether or not the subject is active and should be assigned permissions, the second whether ir not the subject can execute object methods, and the third whether or not the subject has access to the Root\Security namespace.

An instance of the __User or __Group class is created for every user or group to be validated by WBEM. These classes are intermediate abstract base classes and are only used as derivation points.

An instance of the __NTLMUser class is created to permit a user to access the Common Information Model Object Manager (CIMOM). The __NTLMUser class specifies the user's domain. Because __NTLMUser derives from the __Subject class, all of the __Subject properties must be set correctly before the user can be granted access to CIMOM. Instances of this class have no effect during a local login to Windows 95/98 systems; they are used only to authenticate remote logins. On Windows NT systems, instances of this class participate in both local and remote logins.

An instance of the __NTLMGroup class is created to permit a group to access CIMOM. Any user belonging to a group inherits the permissions assigned to the group. Its properties include the type of group (i.e. local or global) and, for a global group, the name of the domain. The __NTLMGroup class is used on Window NT platforms only. Instances of this class do not affect a login to Windows 95/98 systems.


NTLM Group Support on Windows NT

WBEM supports several features that enable native Windows NT security to be transparently integrated with WBEM security. Whenever an NTLM user logs on, his or her membership in various groups is checked. If the user is a member of any or all groups, he acquires the union of permissions assigned to those groups.

There need not be a __User instance associated with the user; he or she only has to be a member of one of the groups already in the security access database of Windows NT. In this way, the Windows NT User Manager can become the tool for controlling group membership, thereby simplifying the administration of access to WBEM.

In most cases, instances of the __NTLMGroup class are created using the WBEM User Manager, permissions are assigned, and no other security instances are created.

There are a few built-in groups on Windows NT platforms. All users who belong to the local Administrators group are given access to all CIMOM namespaces with full access at all times. On some Windows NT workstations, the Domain Administrators group is often automatically added to the local Administrators group when the machine joins the domain. This is outside the control of CIMOM and under the control of the user through the Windows NT User Manager.

A Windows NT local group called WbemUsers is automatically created by CIMOM when it starts. The default settings for this gorup are read-only access to all namespaces except for root\security. There is no access to the Root\Security namespace. There are no members of this group by default.

Most CIMOM access can be controlled entirely from the Windows NT User Manager immediately after installation. At this time, the following permissions are in effect:

  • All local administrators have full CIMOM access.
  • Domain administrators have full CIMOM access unless the user has removed then from his or her local Administrators membership
  • Members of the WBEM Users group can read anything except the Root\Security namespace.


Authentication

Authentication is the process of ensuring that only valid users are allowed access to managed objects through CIMOM. Valid users include individual users as well as group users.

There are two parts to authentication:

  • User identification
  • Permission assignment

User identification involves verifying the user name and password and is the responsibility of marshalers: DCOM, COM, or anonymous pipes. Marshalers have no knowledge of access rights; their only responsibility is to positively identify users.

Permission assignment involves granting access to valid users and is CIMOM's responsibility. Depending on the operating system, WBEM supports varying levels of authentication. On Windows 95/98 platforms, all users are assumed to be authentic regardless of the user and password. There is no local authentication and true authentication only occurs over remoted connections.

Because Windows 95 and Windows 98 are not secure operating systems, the meaning of permissions is weaker on these systems than on other systems. Permissions on Windows 95 and Windows 98 systems refer to the fact that certain users shouldn't do particular operations, but there is no mechanism to prevent a determined user from forcing an operations to occur.

On Windows NT systems, all users are authenticated by marshalers. After authentication, the user is still subject to permissions settings.


Default Access and Permissions

On Windows NT platforms, there is no distinction between local and remote access. The current user is assumed if no user and password is specified. For remote access, a user name and password can be specified which overrides the current user. For local access, it is not possible to override the current user name and password in the call to IWbemLocator::ConnectServer because it is disallowed in DCOM. By default, any user that is a member of the local Administrators group is granted full local and remote access to CIMOM. This typically includes the owner of the machine and the domain administrator.

On Windows 95 and Windows 98 platforms, local users are considered administrators and given full rights. There is no authentication. However, remote users are always validated using __NTLMUser instances in the Root\Security namespace. Because there is no default remote access on Windows 95/98 platforms, one or more __NTLMUser instances must be created to enable remote access.


Login Scenarios

The following tables indicate the result of the authentication process under various conditions using a particular marshaler on a particular platform.

When a user and password is specified on a local connection:

Marshaler | Source and Destination | Result
Anonymous pipes | Win95 IPC | Full permission in all cases
COM | Win98 IPC | Full permission in all cases
DCOM | NT4/5 IPC | Specified user and password are ignored and the current user is assumed regardless. Group memberships are checked as well as any matching __NTLMUser instances. User is denied access if he is not a member of Administrators, WBEM Users, any __NTLMGroup, or does not have a corresponding __NTLMUser instance.

When a user and password is specified on a remote connection:

Marshaler | Source and Destination | Result
DCOM | To Win95 or Win98 | Specified user and password is used for authentication against the domain controller. A corresponding __NTLMUser instance must be present in the CIMOM schema.
DCOM | To NT4 or NT5 | Specified user and password is authenticated. Group memberships are checked, as are any matching __NTLMUser memberships. User is denied access if he is not a member of Administrators, WBEM Users, any __NTLMGroup, or does not have a corresponding __NTLMUser instance.

When no user or password is specified on a local connection:

Marshaler | Source and Destination | Result
Anon pipes | Win95 IPC | Full permission in all cases
DCOM | Win98 IPC | Full permission in all cases
DCOM | WinNT4 or WinNT5 | Current user is assumed. Group memberships are checked and matching __NTLMUser instances. User is denied access if he is not a member of Administrators, WBEM Users, any __NTLMGroup, or does not have a corresponding __NTLMUser instance.

When no user or password is specified on a remote connection:

Marshaler | Source and Destination | Result
DCOM | Win95 or Win98 | Current user is propagated. A corresponding __NTLMUser instance must be present in the CIMOM repository or access is denied.
DCOM | WinNT4 or WinNT5 | Current user is assumed. Group memberships are checked and matching __NTLMUser instances. User is denied access if he is not a member of Administrators, WBEM Users, any __NTLMGroup, or does not have a corresponding __NTLMUser instance.


Localization Services

Web-Based Enterprise Management (WBEM) supports services that enable developers to localize classes created for the Microsoft® Windows NT®, Microsoft® Windows® 95, and Windows 98 platforms. WBEM provides mechanisms for localizing static and dynamic property and qualifier values and for decoupling lengthy descriptive text from the class to which it applies. Existing classes and instances can be localized after they have been introduced and remain unaffected.

The WBEM localization process affects the Common Information Model (CIM) schema, the CIM Object Manager (CIMOM), the built-in providers, and the Managed Object Format (MOF) compiler. Localization services are provided entirely through WBEM classes specified in Unicode MOF files; the CIMOM API is not involved.


Localizing a Class

CIMOM supports the localization of the following WBEM class elements:

  • Class names
  • Property names
  • Property values
  • Descriptive help text
  • Qualifier names
  • Qualifer values

These elements can be localized whether a class was created using the Managed Object Format (MOF) language or the CIMOM API.

There are three steps to localizing a system or custom class:

  1. Build a translation table by creating an instance of the system class __Lexicon.
  2. Bind the class or particular element to be localized to the translation table by attaching the Lexicon qualifier.
  3. Specify the original language of the class or particular element to be localized by attaching the Locale qualifier.

Some derived classes can use the same translation tables as their superclasses. If the derived class inherits all of its properties from the superclass and does not add new ones, it can use the translation table or the superclass. A derived class that introduces new properties must define its own translation table.


Building a Translation Table

A translation table contains the elements to be localized in their original language and a translation to their target language. To build a translation table, create an instance of the __Lexicon system class. The __Lexicon class is defined as follows:

class __Lexicon
{
    [key] string GUID;
    [key] string SourceLocale;
    [key] string TargetLocale;

    string Keywords[ ];        // In the source language
    string Translations[ ];    // Translations to the target language
    string Descriptions[ ];    // Descriptions in the target language
};

The GUID property can contain a unique identifier or one that already exists and is known to be appropriate. The SourceLocale and TargetLocale properties contain strings that define the source and target languages.

The Keywords and Translations properties are ordered pairs of strings. Each pair consists of the string in its original language and the translation to another language. All of the strings in the class to be translated must be included in the Keywords and Translations arrays. If the translation table is to be used for an entire class hierarchy, translations for all of the strings in all of the classes must be listed in these arrays.

The Descriptions property is optional and contains help text in the target language for each Keyword entry.

For example, to translate from English to German, create a __Lexicon instance similar to the following:

Instance of __Lexicon
{
    GUID = "{e588652-edb5-11d0-00c04fb68820}";
    SourceLocale = "ms\\0x409";
    TargetLocale = "ms\\0x407";

    Keywords =
      { "File", "Search", "Copy","Tree", "Dog", "Pencil" };

    Translations =
      { "Datei", "Suchen", "Kopieren", "Baum", "Hund", "Bleistift" };

    Descriptions = NULL;
};

The__Lexicon class provides a general purpose translation table; it is not specifically related to any particular class. One instance can be used to localize many different classes if the classes include the strings defined in the Keywords property.

All non-English strings in the Keywords, Translations, or Descriptions properties must be submitted as Unicode text on all platforms to prevent problems with foreign characters.

The __Lexicon class can also be used to supply a list of possible values for a property without translation. To use a translation table to enumerate valid values, set the SourceLocale and TargetLocale properties to the same value. List the possible values in the Keywords property as is shown in this __Lexicon instance:

instance of __Lexicon
{
    GUID = "{e588653-edb5-11d0-00c04fb68820}";
    SourceLocale = "ms\\0x409";
    TargetLocale = "ms\\0x409";
    Keywords = {
        "640x480 16 Color",
        "800x600 256 Color",
        "1024x768 True Color"
        }
}

CIMOM defines a special instance of the __Lexicon class that can be used to translate system properties and standard qualifiers. To identify this translation table as special, the GUID property is set to all zeros:

instance of __Lexicon
{
    GUID = "{00000000-0000-0000-000000000000}";
    SourceLocale = "ms\\0x409";
    TargetLocale = "ms\\0x407";
    Keywords = { "__CLASS", "__PATH",         ... etc. }
    Translations = { "__KLASSE", "__PFAND",   ... etc. }
}


Binding a Translation Table to a Class

To bind a translation table to a class, attach the Lexicon standard qualifier to the class. A translation table is an instance of the __Lexicon system class that includes all of the strings to be localized for a class or any or all of its elements. A translation table can be bound to an entire class, handling the translation for all of the instances of the class, or to an individual instance or property.

The Lexicon qualifier specifies the GUID property of a __Lexicon class instance. The following class definition shows how to attach the Lexicon qualifier to the class to bind the translation table to the entire class:

[Lexicon("{e588652-edb5-11d0-00c04fb68820}"), Locale("ms\\0x409")]
class MyClass
{
    string Tree;
    string Dog;
    string Pencil;
}

To bind a private translation table to a particular property, attach a Lexicon qualifier to the property. The following class definition specifies one translation table for the class and another translation table for the Pencil property:

[locale("ms\\0x409"), Lexicon("{e588652-edb5-11d0-00c04fb68820}") ]
class MyClass
{
    string Tree;
    string Dog;

    [Lexicon("{d224344-dcd5-24b1-00c12cd24464}")]
    string Pencil;
}

The translation table translates the value of the Pencil property rather than its name. The translation table attached to the class is used for the name of the property.

To use the special translation table that WBEM provides for translating system properties and standard classes, attach a Lexicon qualifier and set GUID value to all zeroes:

[Lexicon("{00000000-0000-0000-000000000000}"), locale("ms\\0x409")]
class MyClass
{

}

Note Associations are not used to bind a __Lexicon instance to an intended class because some classes include a different instance for each property. Associations are not meant to relate individual properties to instances of classes.


Specifying the Language of Origin

The language of origin is the language in which a class is created. Typically a class is created using the language that is supported by the current machine, but this is not a requirement. WBEM supports classes that use characters and words from any language.

A class, its instances, properties, and qualifiers share a single language of origin; a class cannot be created with multiple languages. For example, the class name cannot be defined in Russian while the property names are in English or German.

To specify the language of origin, attach the Locale qualifier to the class. Using this qualifier facilitates optimization because if the user is requesting data presented in English and the Locale qualifier indicates that the classes containing the data were defined in English, no translation is required.

The value of the Locale qualifier is a character string containing the name of the localization scheme, such as Desktop Management Interface (DMI) or the Microsoft scheme, a single backslash, and scheme-specific information. In MOF syntax, a double backslash is required to indicate the single embedded backslash, as is also the case in the C and C++ programming languages.

Although WBEM is designed to support locale strings from multiple systems, only Microsoft-specific locale strings are supported in this release. The localization schemes used on Microsoft Windows platforms appear with the "MS\\" prefix, followed by the 32-bit locale identifier in the form of a hexadecimal string. The value of the Locale qualifier on Windows platforms typically corresponds to the locale identifier of the current user available from the Microsoft® Win32® API. For cross-platform use, there is no widespread standard for identifying or specifying a locale, and no standard in use by Microsoft that is also recognized on other platforms.

The following strings illustrate values for the Locale qualifier that identify Microsoft locales:

"MS\\0x409"        (Microsoft Locale Id, English)
"MS\\0x40C"        (Microsoft Locale Id, French)

Other localization schemes use their own prefixes and formats:

"ISO639-2\\deu"        (ISO 639-2 trigraph for German)
"ISO639\\en"           (ISO 639 for English)
"RFC1766\\az-arabic"   (RFC 1766, Azerbaijani with arabic script)
"RFC1766\\az-cyrillic" (RFC 1766, Azerbaijani with cyrillic script)

Locale strings specified by users when they log on are progated to providers so that they can attempt to supply localized data for the end user. However, there is no automatic translation between locales. If no locale is specified, then it is assumed that the current locale of the running operating system is in force.


Specifying Nonlocalized Descriptive Text

Nonlocalized descriptive text for a class can be specified in one of two ways:

  • Attaching a Description qualifier to the class.
  • Setting the Description property in the instance of the __Lexicon class that is associated with the class.

There are two disadvantages to using the Description qualifier. First, the text becomes available only in the original language for the class—the language that is specified by the Locale qualifier. Second, it hinders performance because all of the descriptive text is retrieved whenever the class definition is retrieved.

Using a translation table allows the descriptive text to be decoupled from the class definition. In the __Lexicon instance created to translate the text, set the SourceLocale and TargetLocale properties to the same value. Specify the properties or class to be described in the Keywords property and the text in the Descriptions property. The Translations property remains empty. Examine the following example.

instance of __Lexicon
{
    GUID = "{e588652-edb5-11d0-00c04fb68820}";

    SourceLocale = "ms\\0x409";
    TargetLocale = "ms\\0x409";

    Keywords =
        { "MyClass", "Tree", "Dog", "Pencil" };

    // We do not use the Translations array

   Descriptions = {
        "This is My Class",
        "This is a tree",
        "This is a canine",
        "This is a graphite-based writing instrument")
       };

};


Localizing Online Help

For classes with online help files, the Lexicon qualifier can be used to retrieve the appropriate HTML page or Microsoft Help file. The help source is represented by an instance of the system class __HelpSource, defined as follows:

class __HelpSource
{
    [key] string GUID;
    [key] string SourceLocale;
    [key] string TargetLocale;

    string HelpType;
    string HelpSource

    string Keywords[];
    string Contexts[];
};

The __HelpSource class is generic enough to be mapped to either Microsoft® Win32® Help or HTML-based Help. For Win32 Help, the HelpType property is set to "Win32" and the HelpSource property points to the help file for the locale specified in the TargetLocale property. For HTML-based Help, HelpType is set to "HTML" and HelpSource points to a URL for the appropriate World Wide Web page.

If there are specific help context values for keywords that apply to the class or its properties, the keywords are specified in the Keywords property and their associated context values in the Contexts property.

The same Lexicon qualifier used for class localization is also used for online Help.

To map this class to Win32 online Help, the following hypothetical instance of __HelpSource is created:

Instance of __HelpSource
{
    GUID = "{e588652-edb5-11d0-00c04fb68820}";
    SourceLocale = "ms\\0x409";
    TargetLocale = "ms\\0x409";

    HelpType = "WIN32";
    HelpSource = "C:\\HELP\\MyClass.HLP";

    Keywords = { "MyClass", "Tree", "Dog", "Pencil" };

    Contexts = { "100", "101", "102", "103"; }    // Help context ids
};


Localization Tasks for Applications

To localize a class or element of a class:
  1. Retrieve the class definition in its original language.
  2. Examine the Locale qualifier of the class. If the Locale qualifier specifies the application's native language, no further processing is required.
  3. If the Locale qualifier does not specify the application's native language, retrieve the appropriate translation table by:
    • Constructing an object path that is made up of the value of the Lexicon qualifier attached to the class.
    • Calling IWbemServices::GetObject with the bstrObjectPath parameter set to the object path.
  4. If GetObject fails, translation is not possible. Warn the user and display the class in English.
  5. If GetObject succeeds, look up the string to be translated in the Keywords property of the __Lexicon instance. After locating it, retrieve the same string in the parallel entry in the Translations property. In addition , if any lengthy descriptive text is available, retrieve it from the same location in the Descriptions property.

    Cache the __Lexicon instance for as long as possible to avoid needless network traffic.

  6. If a string cannot be located in the translation table, it is possible that another translation table exists. Properties or instances can have private translation tables, as indicated by the presence of the Lexicon qualifier.

If the class to be localized is a derived class, examine each class in the hierarchy to determine the appropriate translation table. Some derived classes share a translation table with their superclass; others have their own private tables.


Localization Tasks for Providers

Providers have three choices for supplying character strings in a requested language:

  • Supply the strings in the language specified in a translation table.
  • Supply the strings directly in the requested language.
  • Supply the strings in a supported language.

Regardless of how a string is supplied, a provider must tag the class or instance in which the string resides with the Locale qualifier. The Locale qualifier specifies the language of the string.

Classes, instances, and properties can be associated with a translation table, an instance of the __Lexicon class. When a suitable translation table exists, a provider can supply the information in the Translations property. The provider can rely on the client application to subsequently translate the information if necessary.

If a translation table is unavailable or property values cannot be predetermined and submitted by means of a Managed Object File (MOF) file, a provider must provide information directly in the requested locale, if possible. When a provider is loaded by CIMOM, CIMOM advises the provider of the locale in which it is expected to operate. A provider that does not support the requested locale then supplies information in whatever language it can and tags the associated class or instance with the Locale qualifier to indicate the locale with which it is working.

All error objects supplied by providers should contain text localized into the requested language. Providers can use the standard resource string table approach.

Dynamic property providers are typically hard-coded to retrieve values from certain data sources and are not aware of localization issues. For example, retrieving a string from a registry location simply results in whatever string was there. There may be no opportunity to "localize" it dynamically. However, the IWbemPropertyProvider interface does advise the provider of the required locale. Therefore, if the provider is intelligent enough to do the job, it should. Providers suppyling dynamic valuescan be required to provide values in the current locale if such values need to be localized.


Remote Access

‹^›Remote Access¦@¦

This is a placeholder topic.


Implementing an Object Provider

‹^›Implementing an Object Provider¦@¦

This is a placeholder topic.


Implementing a COM Provider


Creating a Provider with WBEM CIM Studio

The WBEM CIM Studio Web application can be used to generate a skeletal provider, eliminating the need to learn the details of the CIMOM API and COM. To run CIM Studio, you must have Microsoft® Internet Explorer version 3.01 or higher. For detailed information on using CIM Studio, see the WBEM SDK Applications Guide.

The InstProv and PropProv sample programs show how to code an instance provider and a property provider. These samples can be found in the Samples subdirectory of the WBEM installation.

Û To create a provider
  1. Create the class for which you want to return data.
  2. Generate skeleton provider code for the class.
  3. Register the provider with CIMOM.
  4. Compile the skeleton code.
  5. Register the provider with COM.
  6. Add instrumentation to the code.
  7. Try the provider.


Creating a Provider Class

To create the class for which you want to return data
  1. Create a directory to contain all of the provider files.
  2. Open Internet Explorer and make sure its security level allows the installation of ActiveX™ tools. Under View/Options…/Security/Safety Level…, choose Medium or None. If you choose None, be careful if you use the same Internet Explorer elsewhere.
  3. Open WBEM CIM Studio. Click Start, select Programs, then select WBEM SDK. Then select WBEM CIM Studio.

    If you set the security level to Medium, you must allow all the .cab and ActiveX controls to be installed. In other words, you must answer Yes to All when asked if it is OK to install the controls.

  4. Log in to CIMOM. If you have made no changes to security since installing WBEM, you can click OK here.
  5. Click the Add Class button to the right of the Classes in box.
  6. Clear the Parent field, enter MyClass in the New Class field, and click OK. At this point, the new class appears in the left frame. (You can also create a derived class. In this case, select the parent class first, then click the Add Class button and enter the new class name without clearing the Parent field.)
  7. Add a property to the new class. In the right frame, click the Name field in the blank line at the bottom. Type MyName in this field. Leave the type as string and the value blank.
  8. Add two qualifiers to the MyName property. Double-click MyName to display the Qualifiers window.
  9. For the first qualifier, enter Key as the name, BOOL as the type, and true as the value. Leave the other default settings as is.
  10. For the second qualifier, enter Read as the name, BOOL as the type, and true as the value. Leave the other default settings as is.
  11. Click OK to close the Qualifiers window.
  12. Add another new property named Age. It should be of type sint32 (32-bit integer). Leave the value as 0.
  13. Add a qualifier to the Age property. Double-click the Age field. The Qualifiers window appears.
  14. Enter Read as the name, BOOL as the type, and true as the value. Leave the other default settings as is.
  15. Click OK to close the Qualifiers window.
  16. Add two qualifiers to the MyClass class. Right-click the Age property and select Object qualifiers.
  17. For the first qualifier, enter Dynamic as the name, BOOL as the type, and true as the value. Leave the other default settings as is.
  18. For the second qualifier, enter Provider as the name, BSTR as the type, and MyProv as the value. Leave the other default settings as is.
  19. Click OK to close the Qualifiers window.
  20. Click the Save button.
  21. In the left frame, click the check box to the left of the MyClass class.
  22. Double-click the MOF Generator button to run the MOF Generator Wizard and generate a MOF file for the new class definition.
  23. Click the Next button on the first and second screens that appear. (Click OK to dismiss the "Cannot get instance enumeration…" warning message.) On the third screen, enter MyClass in the MOF File Name field and <drive>:\Prov in the Directory for the MOF file field. (You can also use the Browse button to select the directory.)
  24. Click the Finish button. The MOF file is generated and a confirmation message appears. Click OK to dismiss the message.


Generating Skeleton Code

To generate skeleton code for the class
  1. In the left frame, make sure the check box next to the MyClass class is checked. Double-click the CPP Generator icon to run the C++ Code Generator Wizard.
  2. Click the Next button on the first screen. In the second screen enter A simple class in the Description field.
  3. Click the Next button. In the next screen, change the provider name to MyProv. Enter My first provider as the provider description. Change the directory to <drive>:\Prov (or use the Browse button to select this directory).
  4. Click the Finish button. The skeleton code files are generated. A confirmation message appears. Click OK to dismiss the message.


Registering the Provider with CIMOM

To register the provider with CIMOM
  1. Open WBEM CIM Studio and double-click the MOF Compiler icon.
  2. In the first screen, select Compile a MOF file then click the Next button.
  3. In the next screen, type <drive>\Prov\myprov.mof or use the Browse button to select the file. Click the Next button.
  4. Click the Finish button on the next screen that appears. When compilation is complete, a confirmation message appears. Click OK to dismiss the message.


Compiling the Skeleton Code

To compile the skeleton code
  1. From the \Wbem\include directory, type the following commands:

    midl wbemsvc.idl

    midl providl.idl

    midl wbemdisp.idl

  2. From the \Prov directory, run: MKTYPLIB myprov.odl /h myprov.h.
  3. Make sure \Wbem\include and \Wbem\Include are in your include path.
  4. Make sure \Wbem\Lib is in your lib path.
  5. You must compile Myprov.cpp and Olesrvr.cpp. You are creating a Microsoft Foundation Class (MFC) DLL.
  6. When you link, you must include framedyn.lib and framestat.lib and you must use myprov.def.

For Microsoft® Visual C++® version 5 users, this would be done as follows:

  1. Create a new project named MyProv of type Win32 Dynamic Link Library in location \Prov.
  2. Project/AddtoProject/Files olesrvr.cpp, myprov.def and myclass.cpp.
  3. Go to Project/Settings.
  4. Under C/C++ Preprocessor tab, select the category options and add the two paths for the include files: c:\Wbem\Include and c:\Wbem\Include.
  5. Under Link/Input tab add the lib path and the two lib files (framedyn.lib and framestat.lib).
  6. Under the Additional Lib Path tab add c:\Wbem\Lib.
  7. Make sure \Wbem\Lib is in your lib path.
  8. Save the settings.
  9. Under Build, select Build MyProv.dll.


Registering the Provider with COM

The generated provider code includes self-registration code for COM. This step tells COM the location of your DLL.

To register the provider with OLE
  • Use the following command:

    regsvr32 myprov.dll

Note that if you move the .DLL file to a different directory, you must reregister it with OLE.


Adding Instrumentation to the Code

To add instrumentation to the code

There are two ways that a provider can be called: either it is asked to enumerate all instances (which calls AddDynamicInstances, or it can be asked for one specific instance through the GetObject call, which calls RefreshInstance.

In real code, you could use this fact to implement "expensive" properties. When the enumerate function is called, you could return only the "cheap" values. When the GetObject function is called, you can get all information.

In the following sample, different values are returned to show that both methods are being called.

  1. Add the following code to CMyClass::AddDynamicInstances just before the return statement:
    BuildNewInstance();
    MyName = "Fred";
    Age = 15;
    dwInstanceCount++;
    CommitNewInstance();

    BuildNewInstance();
    MyName = "Mary";
    Age = 16;
    dwInstanceCount++;
    CommitNewInstance();

    This means we will be returning two instances. You can also structure this as:

    {
   BuildNewInstance();
   .
   .
   .
   CommitNewInstance();
   dwInstanceCount++;
}
  2. Add the following code to CMyClass::RefreshInstance just before the return statement:
    char szTemp[255];
    CHString sTemp;
    sTemp=MyName;

    strcpy(szTemp, sTemp.GetBuffer(255));

    if (stricmp(szTemp, "Fred") == 0) {
        Age = 15;
    } else if (stricmp(szTemp, "Mary") == 0) {
        Age = 16;
    } else {
        return FALSE;
    }
  3. Stop CIMOM.
  4. Recompile the code.


Trying the Provider

To try the provider
  1. Open CIM Studio and select the newly-defined class in the left frame.
  2. Click the Multi-Instance Viewer button to invoke the instance enumeration in the provider. An instance table for the class appears.
  3. To invoke the GetObject implementation, double-click an instance in the table.

Also, try the sample program WBEMDump as follows:

Wbemdump root\default MyClass  <- This will do the enumeration


Implementing a Schema Extension

‹^›Implementing a Schema Extension¦@¦

This is a placeholder topic.


CIM Object Manager (CIMOM) Reference

The CIM Object Manager (CIMOM) provides access to information about objects in the management environment. Through CIMOM, applications can query for and make changes to static information in the CIMOM repository and dynamic information maintained by object providers.

The CIMOM Reference provides discussions of the following core features of CIMOM:

  • C/C++ APIs, a complete listing of the COM interfaces that are used by C or C++ management applications and object providers to access CIMOM services.
  • Visual Basic APIs, a complete listing of the interfaces that are used by Visual Basic and VBA applications to access CIMOM services.
  • System Class Reference, a complete listing of the classes that are defined by CIMOM.
  • System Property Reference, a complete lislting of the properties that are supported by CIMOM.
  • Standard Qualifier Reference, a complete listing of the qualifiers that are supported by CIMOM.
  • Appendixes, a description of the command line syntax used by CIMOM and the MOF compiler and the Backus Naur Form (BNF) syntax for MOF, SQL1, and object paths.


COM APIs

The Common Information Model Object Manager (CIMOM) programmer's reference provides the application programming interface (API) definitions for the Web-Based Enterprise Management (WBEM) Win32® Component Object Model (COM). This programmer's reference describes the communication link to CIMOM; these APIs enable you to access CIMOM services. The reference provides information for advanced system administrators, as well as developers who are writing client and provider applications.

Note Microsoft only supports WBEM C++ development using Microsoft Visual C++ version 5.0; However, other compilers such as Borland, Watcom, etc. can easily be used.

Each of the many different CIMOM objects inherits from an interface that is ultimately inherited from IUnknown. COM dictates how object implementers, or interfaces, handle tasks such as memory management, parameter management, and multithreading. By conforming to this model, an interface adheres to a contract as specified by the interfaces included in the object.

CIMOM is accessed through the following COM interfaces specific to WBEM:

WBEM COM Interfaces | Description
IEnumWbemClassObject | This interface is an enumerator that works with objects of type IWbemClassObject. It is similar to standard COM enumerators, such as IEnumVariant.
IWbemCallResult | This interface is optionally used to query for the result of semisynchronous calls.
IWbemClassObject | This interface contains and manipulates both class definitions and class object instances. Users do not implement this interface; the implementation is provided.
IWbemContext | This interface is used optionally to provide additional context information along with the other WBEM calls.
IWbemEventConsumerProvider | This interface is used to initiate communication with a consumer provider.
IWbemEventProvider | This interface is used to initiate communication with a provider.
IWbemEventProviderQuerySink | This interface is optionally implemented by event providers that expose what kinds of event query filters are currently active in order to optimize performance.
IWbemLocator | This interface obtains the initial IWbemServices pointer to CIMOM on a particular host machine.
IWbemPropertyProvider | This interface is implemented only by dynamic property providers, which need to expose their data sources at the granularity of properties rather than instances.
IWbemProviderInit | This interface is used to initialize all provider types.
IWbemQualifierSet | This interface enables WBEM clients to read or modify qualifiers on properties or entire objects. Users do not implement this interface; the implementation is provided.
IWbemServices | This is the primary CIMOM interface. It provides management services to client processes and to other providers.
IWbemUnboundObjectSink | This interface is implemented by event consumers. It is a simple sink interface which accepts delivery of event objects.

The Microsoft® Platform SDK documentation includes a comprehensive discussion of the rules for implementing objects that conform to the COM. These rules address how to:

  • Design interfaces and objects.
  • Implement IUnknown.
  • Manage memory.
  • Handle reference counting.


IEnumWbemClassObject

The IEnumWbemClassObject interface is similar to a standard Component Object Model (COM) enumerator. It works with objects of type IWbemClassObject. However, some extensions over standard COM enumerators have been added to accommodate Web-Based Enterprise Management (WBEM) requirements.

The enumerator is a logical container of Common Information Model (CIM) objects, and is designed for sequential retrieval. An enumerator has a current position, or cursor beginning, at offset zero, the first element, and moves sequentially through the set of objects. When you call the Reset method, once again the current position is set to zero, or the first object. Calling the Next method retrieves the requested objects. It updates the current position so that subsequent calls to Next retrieve the objects. Eventually, you reach the end of the sequence, and cannot retrieve any more objects. At this point, you can restart the enumerator by calling Reset, or you can discard it by using the Release method.

For documentation on the semantics of COM enumerators, see IEnumVariant in the Microsoft® Platform SDK. The IEnumWbemClassObject interface semantically resembles the standard enumerators, except that it is designed also to support asynchronous and semisynchronous call behavior.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count by 1, and frees the object when the reference count is zero.

IEnumWbemClassObject Methods | Description
Reset | Resets the cursor position to zero so that the enumeration can be repeated.
Next | Retrieves the next object or objects in the enumeration starting from the current position.
NextAsync | Retrieves the next object or objects using asynchronous integration with IWbemObjectSink.
Clone | Makes a logical copy of the enumerator.
Skip | Skips over the object or objects, resulting in a new cursor position.


IEnumWbemClassObject::QueryInterface

The IEnumWbemClassObject::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that is filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface is not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each other's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IEnumWbemClassObject::AddRef

The IEnumWbemClassObject::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object, or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IEnumWbemClassObject::Release

The IEnumWbemClassObject::Release method decreases the object's reference count by 1.

ULONG Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IEnumWbemClassObject::Reset

The IEnumWbemClassObject::Reset method resets the current position of the enumerator to zero, or to the beginning of the enumeration. Since CIM objects are dynamic, calling this method does not necessarily return the same list of objects that you obtained previously.

Note This method will fail if the enumerator was originally created with the WBEM_FLAG_FORWARD_ONLY option.

HRESULT Reset( );

Parameters

None.

Return Values

S_OK | The operation succeeded.
S_FALSE | The operation failed.

If S_OK is not returned, a call to the COM function GetErrorInfo provides more information about the error.


IEnumWbemClassObject::Next

The IEnumWbemClassObject::Next method returns the next object or objects starting at the current cursor position. It then advances the cursor position by that many objects, so that subsequent calls return the subsequent objects.

HRESULT Next(
  [in] long lTimeOut,
  [in] ULONGARG uCount,
  [out, size_is(uCount), length_is(*puReturned)] IWbemClassObject **ppObjects,
  [out] ULONGARG *puReturned
);

Parameters

lTimeout
Specifies the maximum amount of time in milliseconds you must wait before objects are available. If you use the Win32® constant INFINITE (0xFFFFFFFF), the call blocks until objects are available. If you use the value zero, the call immediately returns with those objects that are waiting.
uCount
The number of requested objects.
ppObjects
A pointer to enough storage to hold the number of pointers specified by uCount. This storage must be supplied by the caller. It cannot be NULL, but must point to NULL. The caller must call Release on each of the objects using the pointers that are returned when they are no longer needed.
puReturned
A pointer to a ULONG that receives the number of objects returned. This number can be less than the number requested in uCount. This pointer cannot be NULL.

Note The IWbemClassObject::Next method returns S_FALSE even when a nonzero number of objects is returned. S_OK is returned only when the number of objects returned matches the number requested in uCount. Therefore, loop termination logic should examine the puReturned value to ensure you have reached the end of the enumeration.

Return Values

S_OK | The number of objects returned was the same as the number requested.
S_FALSE | The number of objects returned was less than the number requested.
WBEM_S_TIMEDOUT | A timeout occurred before you obtained all the objects.

On error, you can call the COM function GetErrorInfo to obtain more error information.

In the following sample, since objects are only requested one at a time, checking the return code for S_OK is correct:

void ListObjects(IEnumWbemClassObject *pEnum)
{
    pEnum->Reset();

    IWbemClassObject *pObject = 0;
    ULONG uReturned;

    while (pEnum->Next(INFINITE, 1, &pObject, &uReturned) == S_OK)
    {
        pObject->… // Access IWbemClassObject methods
        pObject->Release();
    }
}

In the next sample, Next may return S_FALSE, even though some objects are returned, so checking uReturned is required:

void ListObjects2(IEnumWbemClassObject *pEnum)
{
    pEnum->Reset();

    IWbemClassObject *paObjects[10];
    ULONG uReturned;
    HRESULT hRes;

    while (1)
    {
        hRes = pEnum->Next(INFINITE, 10, paObjects, &uReturned);

        if (uReturned == 0)
            break;

        for (ULONG u = 0; u < uReturned; u++)
        {
            IWbemClassObject *pObj = paObjects[u];

            // ... use the object

            pObj->Release();
        }

    }

    // examine hRes to see if the termination finished normally
}


IEnumWbemClassObject::NextAsync

The IEnumWbemClassObject::NextAsync method is used when a controlled asynchronous retrieval of objects to a sink is required. Normal asynchronous retrieval, such as a call to IWbemServices::ExecQueryAsync , results in uncontrolled delivery of objects to the caller's implementation of IWbemObjectSink. This method is helpful for cases where components can only handle a reduced rate of delivery.

HRESULT NextAsync(
  [in] ULONGARG uCount,
  [in] IWbemObjectSink *pSink
);

Parameters

uCount
The number of objects being requested.
pSink
The sink to receive the objects. The sink must be implemented by the caller.

Return Values

S_OK | The call succeeded. The system begins delivery of objects to the sink.
S_FALSE | The call failed, and no objects will be delivered to the sink. A call to the COM function GetErrorInfo provides more information about the error.

Remarks

This call returns immediately, and delivery to the sink occurs in the background. If multiple calls are made to this method from one or more threads, they are logically queued, and the order of calls and object delivery is preserved. A call to Reset does not affect delivery of objects currently in progress as a result of previous calls. Reset only causes new calls to start at the beginning of the object sequence.

The IWbemObjectSink::SetStatus method is called to indicate the actual result of the request. As the objects become available, IWbemObjectSink::Indicate is called zero or more times to deliver the objects, followed by a call to IWbemObjectSink::SetStatus with a value of S_OK, if uCount items are returned.

If fewer objects are available than the number requested, then IWbemObjectSink::Indicate is called for those objects that are available. This is followed by a call to IWbemObjectSink::SetStatus with a value of S_FALSE, or the error code if an error occurred. If there are no available objects, Indicate is not called.

Sample Code

void ListObjects3(
    IEnumWbemClassObject *pEnum,
    IWbemObjectSink *pSink
    )
{
    HRESULT hRes;

    while (1)
    {
        hRes = pEnum->NextAsync(5, pSink);

            // Wait until sink is ready for more by
            // some private mechanism. Note that hRes gives
            // no indication as to whether to continue the
            // enumeration or not.

           BOOL bContinue = WaitUntilMoreObjectsNeeded();

            if (!bContinue)
                break;
    }
}


IEnumWbemClassObject::Clone

The IEnumWbemClassObject::Clone method makes a logical copy of the entire enumerator, retaining its current cursor position. This method will make only a "best effort" copy. Due to the dynamic nature of many CIM objects, it is possible that the new enumerator does not enumerate the same set of objects as the source enumerator.

Note Any pending asynchronous deliveries begun by NextAsync are not cloned.

HRESULT Clone(
  [out] IEnumWbemClassObject **ppEnum
);

Parameters

ppEnum
Receives a pointer to a new IEnumWbemClassObject object. The caller must call Release when the interface pointer is no longer required. On error, there will not be a return of a new object.

Return Values

S_OK | The call succeeded, and the enumerator has been cloned.
S_FALSE | The call failed, and no enumerator has been returned.

On error, you can call the COM function GetErrorInfo to obtain more error information.

Sample Code

BOOL CloneEnum(IEnumWbemClassObject *pSrc)
{
    IEnumWbemClassObject *pCopy = 0;

    HRESULT hRes = pSrc->Clone(&pCopy);

    if (hRes != S_OK)       // Failed to clone it
        return FALSE;

    // Use the copy of the enumerator
    // ...

    pCopy->Release();

    return TRUE;
}


IEnumWbemClassObject::Skip

You can use the IEnumWbemClassObject::Skip method to move the current cursor position ahead by a specified number of objects. Also, this affects subsequent calls to NextAsync, but it does not affect pending deliveries begun with NextAsync.

HRESULT Skip(
  [in] long lTimeOut,
  [in] ULONGARG nCount
);

Parameters

lTimeout
Specifies the maximum amount of time in milliseconds you must wait for the Skip operation to succeed. If you use the Win32® constant INFINITE (0xFFFFFFFF), the call will block until the operation succeeds. If you use the value zero, the call immediately returns with S_OK or S_FALSE. This indicates success or failure.
uCount
The number of objects to skip.

Return Values

S_OK | The call succeeded, and the cursor position has been updated.
S_FALSE | The call failed, and the cursor position is at its position before the call. A call to the COM function GetErrorInfo provides more information about the error.


IWbemCallResult

You can use the IWbemCallResult interface for semisynchronous calls of the IWbemServices interface. When you make such calls, the IWbemServices method returns immediately, along with an IWbemCallResult object. Periodically, you must poll the returned IWbemCallResult object to determine the status of the call. When the call completes, you can also obtain from this interface the result of the original IWbemServices call.

This call-return paradigm is useful in cases where a thread cannot afford to be blocked for more than a few seconds because it is servicing other tasks, such as processing window messages.

Not all IWbemServices methods support this interface because it is not required for all of them. The intent is to allow nonblocking synchronous operation (semisynchronous operation) for all cases. Since many of the IWbemServices methods are already nonblocking due to the use of enumerators or other constructs. Only OpenNamespace, GetObject, PutInstance, DeleteClass, DeleteInstance, and ExecMethod need this helper interface to support semisynchronous operation.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count by 1, and frees the object when the reference count is zero.

IWbemCallResult Methods | Description
GetResultObject | Returns an IWbemClassObject; which is the result of a semisynchronous call to IWbemServices::GetObject.
GetResultString | Returns an Object Path; which is the result of a semisynchronous call to IWbemServices::PutInstance.
GetResultServices | Returns the result of a semisynchronous call to IWbemServices::OpenNamespace verb action.
GetCallStatus | Tells you whether a semisynchronous call was successful.


IWbemCallResult::QueryInterface

The IWbemCallResult::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemCallResult::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, it returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, you must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with the existing or future functionality of the objects.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemCallResult::AddRef

The IWbemCallResult::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When you create the object, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count increases by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemCallResult::Release

The IWbemCallResult::Release method decreases the object's reference count by 1.

ULONG Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemCallResult::GetResultObject

The IWbemCallResult::GetResultObject method returns the object. This results from a semisynchronous invocation of IWbemServices::GetObject or IWbemServices::ExecMethod. If the object is not yet available, the call returns WBEM_S_PENDING. Also, before invoking this method to get the resultant object, you may call IWbemCallResult::GetCallStatus until it returns WBEM_NO_ERROR.

HRESULT GetResultObject(
  [in] LONG lTimeout,
  [out] IWbemClassObject **ppResultObject
);

Parameters

lTimeout
Specifies the maximum time in milliseconds you must wait for the call to return. If you use the Win32® constant INFINITE (0xFFFFFFFF), the call will block until the object is available. If you use zero, the call immediately returns either the object or a status code.
ppResultObject
This parameter cannot be NULL. It receives the copy of the object when it becomes available. You must call IWbemClassObject::Release on the returned object when the object is no longer required.

A new object is not returned on error.

Return Values

WBEM_NO_ERROR | The object successfully returned .
WBEM_S_PENDING | The object was not yet available after the lTimeout value expired.
WBEM_E_NOT_FOUND | The object did not exist.
WBEM_E_UNEXPECTED | The call failed, and it is not expected to complete.
WBEM_E_TRANSPORT_FAILURE | The remote or network connection to CIMOM has failed.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_ACCESS_DENIED | The caller attempted an unauthorized operation.

On error, you can call the COM function GetErrorInfo to obtain more error information.

See Also

IWbemServices::GetObject IWbemServices::ExecMethod.


IWbemCallResult::GetResultString

The IWbemCallResult::GetResultString method returns the assigned object path of an instance newly created by IWbemServices::PutInstance.

Note The call result object is primarily used when the PutInstance call is carried out by a provider and the client needs to know the object path (the values of the key properties) assigned the provider. For example, if the the key property to the class is a GUID and is assigned by the provider during the PutInstance operation, the client would have no way of knowing this GUID unless the provider was able to return it in this way.

HRESULT GetResultString(
  [in] Long lTimeout,
  [out] BSTR *pbstrResultString
);

Parameters

lTimeout
Specifies the maximum time in milliseconds you must wait for the call to return. If you use the Win32® constant INFINITE (0xFFFFFFFF), the call will block until the object path is available. If you use zero, the call immediately returns either the object path or a status code.
pbstrResultString
Cannot be NULL. This parameter receives a pointer to the object path, which, in turn, leads to the newly created object. The returned string must be deallocated using the system call SysFreeString. On error, a new string is not returned.

Return Values

WBEM_NO_ERROR | The object path was retrieved.
WBEM_S_PENDING | The call has not yet completed.
WBEM_E_UNEXPECTED | An internal failure occurred.
WBEM_E_TRANSPORT_FAILURE | The remote connection to CIMOM has failed.
WBEM_E_ACCESS_DENIED | The caller attempted an unauthorized operation.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.

On error, you can call the COM function GetErrorInfo to obtain more error information.

See Also

IWbemServices::PutInstance


IWbemCallResult::GetResultServices

You can use the IWbemCallResult::GetResultServices method to retrieve the IWbemServices pointer, which resulted from a semisynchronous call to IWbemServices::OpenNamespace when it becomes available.

HRESULT GetResultServices(
  [in] LONG lTimeout,
  [out] IWbemServices **ppServices
);

Parameters

lTimeout
Specifies the maximum time in milliseconds you must wait for the call to return. If you use the Win32® constant INFINITE (0xFFFFFFFF) is used, the call will block until the interface pointer is available. If you use zero, the call immediately returns either the pointer or a status code.
ppServices
This parameter cannot be NULL. It receives a pointer to the IWbemServices interface requested by the original call to OpenNamespace when it becomes available The caller must call Release on the returned object when it is no longer required.

On error, a new object is not returned.

Return Values

WBEM_NO_ERROR | The call succeeded and returned an IWbemServices pointer.
WBEM_S_PENDING | The time-out occurred and the call has not yet completed.
WBEM_E_UNEXPECTED | An internal failure occurred.
WBEM_E_TRANSPORT_FAILURE | The network transport to CIMOM has failed.
WBEM_E_ACCESS_DENIED | The user attempted to perform an unauthorized operation.

On error, the COM function GetErrorInfo can be called to obtain more error information.

See Also

IWbemServices::OpenNamespace


IWbemCallResult::GetCallStatus

The IWbemCallResult::GetCallStatus method returns to the user the status of the current outstanding semisynchronous call. When this call returns WBEM_NO_ERROR, then the original call to the IWbemServices method has completed.

HRESULT GetCallStatus(
  [in] LONG lTimeout,
  [out] LONG *plStatus
);

Parameters

lTimeout
Specifies the maximum time in milliseconds you must wait for the call to return. If you use the Win32® constant INFINITE (0xFFFFFFFF), the call will block until the original semisynchronous call to an IWbemServices method has completed. If you use zero, the call immediately returns the call status.
plStatus
If you return WBEM_NO_ERROR from the GetCallStatus call. If WBEM_NO_ERROR is returned in the HRESULT to this method, this parameter will receive the final result status of a call this parameter receives the result of the original semisychronous call to one of the IWbemServices methods: OpenNamespace, PutInstance, GetObject, DeleteInstance, DeleteClass, or ExecMethod. The error code returned by the corresponding synchronous calls of one of these methods will also be returned by this method upon completion of the call. The error code returned by the corresponding synchronous calls of one of these methods will also be returned by this method upon completion of the call. On error, plStatus will be ignored.

Return Values

WBEM_NO_ERROR | The call has completed and plStatus has been assigned.
WBEM_S_PENDING | The call has not yet completed.
WBEM_E_TRANSPORT_FAILURE | The underlying remote connection to CIMOM has failed.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_FAILED | An unexpected system error has occurred.

On error, you can call the COM function GetErrorInfo to obtain more error information.

Remarks

After invoking an IWbemServices method semisynchronously, you can call GetCallStatus at any time to determine whether the call has completed. After GetCallStatus has returned WBEM_NO_ERROR, which indicates completion of the original IWbemServices operation, calls to other IWbemCallResult methods may be required to retrieve the result of the call, according to the following rules:

  1. For the IWbemServices method OpenNamespace, the GetResultServices method must be called to retrieve the new IWbemServices pointer.
  2. For the IWbemServices method PutInstance, the GetResultString method must be called to obtain the object path that was assigned to the object.
  3. For the IWbemServices method GetObject, the GetResultObject method must be called to retrieve the object.
  4. For the IWbemServices methods DeleteInstance, DeleteClass, and ExecMethod, the GetCallStatus method is the only call that returns information regarding these operations.

See Also

IWbemServices::OpenNamespace, IWbemServices::PutInstance, IWbemServices::GetObject, IWbemServices::DeleteInstance, IWbemServices::DeleteClass, IWbemServices::ExecMethod


IWbemClassObject

The IWbemClassObject interface contains and manipulates both class definitions and class object instances.

From the WBEM client perspective, this interface is always in-process. Put (write) operations will only affect the local copy of the object, and Get (read) operations always retrieve values from the local copy. You can perform updates to CIMOM only when entire objects are read or written using methods on the IWbemServices interface. Examples of such updates are: IWbemServices::PutInstance or IWbemServices::PutClass.

This interface is not implemented by the user or by a provider under any circumstances. The implementation provided by CIMOM is the only one that is recognized.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if this object supports WBEM interfaces.
AddRef | Increases the object's reference count by 1.
Release | Decrements the reference count by 1.

IWbemClassObject Methods |  | Description
GetQualifierSet | Allows access to the qualifier set of the entire object.
Get | Gets a particular property value.
Put | Edits or creates a particular property value.
Delete | Removes the specified property from the object.
GetNames | Obtains a list of the names of all the properties in the object.
BeginEnumeration | Begins an enumeration of all the properties.
Next | Obtains the next property in an enumeration after an initial call to BeginEnumeration.
EndEnumeration | Ends an enumeration begun with BeginEnumeration.
GetPropertyQualifierSet | Allows access to the qualifiers of a particular property.
Clone | Makes a copy of the current object.
GetObjectText | Obtains the textual rendition of the object (MOF syntax).
SpawnDerivedClass | Creates a new derived class from the current class.
SpawnInstance |  | Creates a new instance from the current class.
CompareTo |  | Tests two objects for equality.
GetPropertyOrigin | Reports the class in which a particular property was introduced.
InheritsFrom | Reports whether the current object inherits from a particular class.
GetMethod | TBD
PutMethod | TBD
DeleteMethod | TBD
BeginMethodEnumeration | TBD
NextMethod | TBD
EndMethodEnumeration | TBD
GetMethodQualifierSet | TBD
GetMethodOrigin | TBD


IWbemClassObject::QueryInterface

The IWbemClassObject::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemClassObject::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that is filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. This call will fail if the requested interface was not supported and the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with existing or future functionality of the objects.

The QueryInterface method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemClassObject::AddRef

The IWbemClassObject::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When you create the object, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count increases by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemClassObject::Release

The IWbemClassObject::Release method decreases the object's reference count by 1.

ULONG IWbemClassObject::Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemClassObject::GetQualifierSet

The IWbemClassObject::GetQualifierSet method returns an interface pointer that allows read and write operations on the set of qualifiers for the entire class object, whether the object is an instance or a class definition. Any qualifiers added, deleted, or edited using the returned pointer apply to the entire instance or class definition.

HRESULT IWbemClassObject::GetQualifierSet(
  [out] IWbemQualifierSet **ppQualSet
);

Parameters

ppQualSet
Receives the interface pointer that allows access to the qualifiers for the class object. The returned object has a positive reference count upon return from the call. The caller must call IWbemQualifierSet::Release when the object is no longer needed. This parameter cannot be NULL. On error, a new object is not returned and the pointer is set to point to NULL.

Return Values

WBEM_E_OUT_OF_MEMORY | There was not sufficient memory to complete the call.
WBEM_NO_ERROR | Success.

See Also

IWbemQualifierSet, IWbemClassObject::GetPropertyQualifierSet


IWbemClassObject::Get

The IWbemClassObject::Get method retrieves the specified property value, if it exists. This method also can return system properties.

HRESULT IWbemClassObject::Get(
  [in] BSTR bstrName,
  [in] long lFlags,
  [out, OPTIONAL] VARIANT *pVal,
  [out, OPTIONAL] VARTYPE *pvtType,
  [out, OPTIONAL] long *plFlavor
);

Parameters

bstrName
The desired property name. This must point to a valid BSTR It is treated as read-only.
lFlags
Reserved. It must be zero.
pVal
Points to an existing uninitialized VARIANT structure that receives the property value, if found. Since this is an out-only parameter, this method calls VariantInit on this VARIANT. The pVal parameter can be NULL if a property value is not required. If an error code is returned, the VARIANT pointed to by pVal is left unmodified.

Note It is required that the caller call VariantClear on the returned VARIANT when its value is no longer required. This will prevent memory leaks in the client process. The type of the VARIANT returned does not always indicate the real COM type of the property. If the property currently has no value (the null value), the VARIANT is of type VT_NULL. Client applications must use the plType parameter to learn the real COM type of the property.

If the type is VT_DISPATCH, the returned property in the VARIANT is an embedded IWbemClassObject. After extracting the IDispatch pointer, the user must call IDispatch::QueryInterface for IID_IWbemClassObject and use the returned pointer to access the embedded IWbemClassObject. Note that VariantClear invokes Release on the object. However, since the user causes an implicit AddRef to occur by calling QueryInterface, the user must explicitly Release the IWbemClassObject pointer retrieved from IDispatch::QueryInterface, as well as call VariantClear on the returned VARIANT.

pvtType
Can be NULL. If not NULL, it receives the COM Automation (VT_BSTR, VT_I4, and so on) type of the property.
plFlavor
Can be NULL. If not NULL, the Long value pointed to receives information on the origin of the property:
WBEM_FLAVOR_ORIGIN_LOCAL
The property belongs to the derived-most class.
WBEM_FLAVOR_ORIGIN_PROPAGATED
The property was inherited from a parent class.
WBEM_FLAVOR_ORIGIN_SYSTEM
The property is a standard system property.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_NOT_FOUND | The specified property was not found.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

Remarks

If the underlying type of the property is an object path, a date/time string, or another special type, the returned values will not contain enough information to identify the true type. In applications where you do not know in advance the true property type, you must retrieve the CIMTYPE qualifier for the specified propertyusing IWbemClassObject::GetPropertyQualifierSet.

Note When you create a new object using IWbemClassObject::SpawnInstance, it is important to note that some system properties are not set until the object has been written to CIMOM. In all cases, IWbemClassObject::Get returns the requested system property, but the return value can be NULL.

See Also

IWbemClassObject::GetPropertyQualifierSet, System Classes, Properties, and Qualifiers


IWbemClassObject::Put

The IWbemClassObject::Put method sets a named property to a new value. This method always overwrites the current value with the new one.

HRESULT IWbemClassObject::Put(
  [in] BSTR bstrName,
  [in] Long lFlags,
  [in] VARIANT *pVal,
  [in] VARTYPE vtType
);

Parameters

bstrName
Must point to a valid BSTR containing the property name. The pointer is treated as read-only. This cannot be NULL.
lFlags
Reserved. It must be zero.
pVal
Must point to a valid VARIANT, which becomes the new property value. If pVal is NULL or points to a VARIANT of type VT_NULL, the property is set to NULL, that is, no value.

Note The NULL value for a property designated by a VARIANT of type VT_NULL is distinguished from a property of type VT_I4 with a zero value.

If pVal is NULL or points to a VT_NULL, the type of the property is inferred from the vtType parameter.

If pVal is to contain an embedded IWbemClassObject, the caller must call IWbemClassObject::QueryInterface for IID_IDispatch and place the resulting pointer in the VARIANT using a type of VT_DISPATCH.

The pointer is treated as read-only. The caller is responsible for invoking VariantClear after this call has completed.

vtType
This parameter is used only when pVal is NULL or points to a VARIANT of type VT_NULL. In such a case, the vtType parameter specifies a COM type of the property. In every other case, vtType must be zero. vtType must also be zero whenever the underlying object is an instance (even if pVal is NULL), since the type of the property is fixed and cannot be changed. In other words, vtType is used if, and only if, pVal is NULL or points to a VT_NULL VARIANT, and the underlying object is a class.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_PROPERTY_TYPE | Property type is not recognized.
WBEM_E_OUT_OF_MEMORY | There was insufficient memory to complete the operation.
WBEM_E_TYPE_MISMATCH | For instances, this error code indicates that the pVal parameter points to a VARIANT of an incorrect type for the property. For class definitions, this is returned if the property already exists in the parent class, and the new COM type is different from the old COM type. Such properties are read-only for the derived class.
WBEM_NO_ERROR | Success.

Remarks

If the property exists in the superclass, its default value is changed unless it is a type mismatch. If the property does not exist and it is not a type mismatch, the property is created.

When executing this method on an instance, an overwrite always occurs. It occurs because the property always exists.

When you are creating a new class, and the underlying type of the property is an object reference, a date/time string, or other special type, it might be necessary to modify the CIMTYPE qualifier for the property to indicate the special new class. When modifying properties of an instance, the qualifiers are set to the correct values ahead of time.

You can only write system properties when you create a new class. In that case, the name of the class you create is designated by writing it to the system property __CLASS.

See Also

System Classes, Properties, and Qualifiers_


IWbemClassObject::Delete

The IWbemClassObject::Delete method deletes the specified property and all of its qualifiers. Since instances cannot have contents that are different from the owning class, delete operations for properties are only possible on class definitions. .

It is not possible to delete a property that was inherited from a parent class. However, if an override default value for a property inherited from a parent class was specified, it is possible to revert to the parent's default value by invoking this method. In this case, WBEM_S_RESET_TO_DEFAULT is returned. System properties cannot be deleted.

HRESULT IWbemClassObject::Delete(
  [in] BSTR bstrName
);

Parameters

bstrName
The property name to delete. This must point to a valid BSTR. It is treated as read-only.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_INVALID_PARAMETER | An invalid Name was specified.
WBEM_E_NOT_FOUND | The specified property does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_PROPAGATED_PROPERTY | The user attempted to delete a property that was not owned. The property was inherited from a parent class.
WBEM_NO_ERROR | Success.
WBEM_S_RESET_TO_DEFAULT | The caller deleted an override default value for the current class. The default value for this property in the parent class has been reactivated.

See Also

System Properties


IWbemClassObject::GetNames

The IWbemClassObject::GetNames method retrieves the names of all of the properties in the object. Depending on user-supplied selection criteria, furthermore, it can retrieve a subset of the properties. These properties can then be accessed by using IWbemClassObject::Get for each name. This method can also return system properties.

HRESULT IWbemClassObject::GetNames(
  [in] BSTR bstrQualifierName,
  [in] Long lFlags,
  [in] VARIANT *pQualifierVal,
  [out] SAFEARRAY (BSTR) *pbstrNames
);

Parameters

bstrQualifierName
Can be NULL. If not NULL, it must point to a valid BSTR specifying a qualifier name. This is treated as read-only. See Remarks.
lFlags
See Remarks.
pQualifierValue
Can be NULL. If not NULL, it must point to a valid VARIANT structure initialized to a filter value. See Remarks. This VARIANT is treated as read-only by the method. Thus, the caller is responsible for calling VariantClear on it, if required.
pbstrNames
Cannot be NULL, but on entry this parameter must point to NULL. A new SAFEARRAY is always allocated, and the pointer is set to point to it. The returned array can have zero elements, but is always allocated when WBEM_NO_ERROR is returned. On error, a new SAFEARRAY is not returned.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_INVALID_PARAMETER | One or more parameters were invalid, or an incorrect combination of flags and parameters was specified.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the task.
WBEM_NO_ERROR | Success.

Remarks

The names returned are controlled by a combination of flags and parameters. For example, all names of all properties can be specified, or only the key properties can be specified, and so on. The primary filter is specified in the lFlags parameter; the other parameters vary depending upon it.

The flag values are bit fields, and can be combined. One flag from each of the following groups can be combined with a flag from each of the other groups. Flag values within a group are mutually exclusive.

GROUP 1

WBEM_FLAG_ALWAYS
Return all property names. QualifierName and pQualifierVal are reserved.
WBEM_FLAG_ONLY_IF_TRUE
Return only properties that have a qualifier of the name specified by the parameter QualifierName. If this flag is used, you must specify QualifierName.
WBEM_FLAG_ONLY_IF_FALSE
Return only properties that do not have a qualifier of the name specified by the parameter QualifierName. If this flag is used, you must specify QualifierName.
WBEM_FLAG_ONLY_IF_IDENTICAL
Return only properties that have a qualifier of the name specified by the parameter QualifierName, and also have a value identical to the value specified by the VARIANT pointed to by pQualifierVal. If this flag is used, you must specify both QualifierName and pQualifierVal.

GROUP 2

WBEM_FLAG_KEYS_ONLY
Return only the names of the property or properties that define the keys.
WBEM_FLAG_REFS_ONLY
Return only property names that are object references.

GROUP 3

WBEM_FLAG_LOCAL_ONLY
Return only property names that belong to the derived-most class. Exclude properties from the superclass or superclasses.
WBEM_FLAG_PROPAGATED_ONLY
Return only property names that belong to the superclass or superclasses.
WBEM_FLAG_SYSTEM_ONLY
Return only system properties.
WBEM_FLAG_NONSYSTEM_ONLY
Return only property names that are not system properties.

It is not an error for an empty list, which is an array of zero elements, to be returned in cases where no properties match the specified filters.

See Also

IWbemClassObject::Get, System Properties, IWbemClassObject::BeginEnumeration


IWbemClassObject::BeginEnumeration

The IWbemClassObject::BeginEnumeration method resets the enumeration sequence of all the properties in the object. The caller must call this method prior to the first call to IWbemClassObject::Next to enumerate all of the properties on an object.

HRESULT IWbemClassObject::BeginEnumeration(
  [in] Long lEnumFlags
);

Parameters

lEnumFlags
A combination of flags described in Remarks.

Return Values

WBEM_E_INVALID_PARAMETER | The specified combination of flags was invalid, an invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There is not enough memory to begin a new enumeration.
WBEM_NO_ERROR | Success.

Remarks

You can control the properties included in the enumeration by specifying a combination of the following flags. You can combine one flag from each group with any flag from any other group. However, flags from the same group are mutually exclusive.

GROUP 1

WBEM_FLAG_KEYS_ONLY
Only include properties that constitute the key.
WBEM_FLAG_REFS_ONLY
Only include properties that are object references.

GROUP 2

WBEM_FLAG_LOCAL_ONLY
Only include properties that are defined or modified in the class itself. Exclude all properties that are inherited from superclasses. Exclude system properties from the enumeration.
WBEM_FLAG_PROPAGATED_ONLY
Only include properties that are inherited from superclasses. Exclude properties that are defined or modified in the class itself. Exclude system properties from the enumeration.
WBEM_FLAG_SYSTEM_ONLY
Limit the enumeration to system properties only.
WBEM_FLAG_NONSYSTEM_ONLY
Exclude system properties from the enumeration. Includes local and propagated properties.

See Also

IWbemClassObject::Next, System Properties, IWbemClassObject::EndEnumeration


IWbemClassObject::Next

The IWbemClassObject::Next method retrieves the next property in an enumeration that was started with IWbemClassObject::BeginEnumeration. This should be called repeatedly to enumerate all the properties until WBEM_S_NO_MORE_DATA is returned. If the enumeration is to be terminated early, then IWbemClassObject::EndEnumeration should be called.

The order of the properties returned during the enumeration is not defined.

HRESULT IWbemClassObject::Next(
  [in] Long lFlags,
  [out, OPTIONAL] BSTR *pbstrName,
  [out, OPTIONAL] VARIANT *pVal,
  [out, OPTIONAL] VARTYPE *pvtType,
  [out, OPTIONAL] Long *plFlavor
);

Parameters

lFlags
Reserved. It must be zero.
pbstrName
A new BSTR is allocated to contain the property name. This pointer is set to the address of the new string. To prevent memory leaks in the client process, the caller must call SysFreeString when the name is no longer needed. You can set it to NULL if the name is not required.
pVal
This VARIANT is filled with the value of the qualifier. The method calls VariantInit on this VARIANT. The caller must use VariantClear when the value is no longer needed.

You can set it to NULL if the value is not required. If an error code is returned, the VARIANT pointed to by pVal is left unmodified.

pvtType
Can be NULL. If it is not NULL, it must point to a VARTYPE into which the type of the property is placed. The value of the property can be a VT_NULL VARIANT, in which tcase this parameter would be necessary to determine the actual type of the property.
plFlavor
Can be NULL. If not NULL, the Long value pointed to receives information on the origin of the property as follows:
WBEM_FLAVOR_ORIGIN_LOCAL
The property belongs to the derived-most class.
WBEM_FLAVOR_ORIGIN_PROPAGATED
The property was inherited from a parent class.
WBEM_FLAVOR_ORIGIN_SYSTEM
The property is a standard system property.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_UNEXPECTED | Did not call IWbemClassObject::BeginEnumeration.
WBEM_NO_ERROR | Success.
WBEM_S_NO_MORE_DATA | No more properties are left in the enumeration.

Remarks

If the underlying type of the property is an object path, a date/time, or another special type, then the returned type does not contain enough information. The caller must examine the CIMTYPE qualifier for the specified property, and determine if the property is an object reference, date/time, or another special type.

This method also returns system properties.

See Also

IWbemClassObject::BeginEnumeration, IWbemClassObject::EndEnumeration, IWbemClassObject::Get, System Properties


IWbemClassObject::EndEnumeration

The IWbemClassObject::EndEnumeration method terminates an enumeration sequence started with IWbemClassObject::BeginEnumeration. This call is not required, but is recommended to developers because it releases resources associated with the enumeration. However, the resources are deallocated automatically when the next enumeration is started or the object is released.

HRESULT IWbemClassObject::EndEnumeration( );

Parameters

None.

Return Values

WBEM_E_FAILED | General failure.
WBEM_NO_ERROR | Success.

See Also

IWbemClassObject::BeginEnumeration, IWbemClassObject::Next


IWbemClassObject::GetPropertyQualifierSet

The IWbemClassObject::GetPropertyQualifierSet method gets the qualifier set for a particular property in the class object.

HRESULT IWbemClassObject::GetPropertyQualifierSet(
  [in] BSTR bstrProperty,
  [out] IWbemQualifierSet **ppQualSet
);

Parameters

bstrProperty
The property for which the qualifier set is requested. This must point to a valid BSTR, which is treated as read-only. The property can be local or propagated from the superclass. Note that system properties have no qualifiers so they return WBEM_E_SYSTEM_PROPERTY.
ppQualSet
Receives an interface pointer that allows access to the qualifiers for the named property. The caller must call IWbemQualifierSet::Release on the pointer when access to the object is no longer required. The property is set to point to NULL when there are error conditions; a new object is not returned.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_NOT_FOUND | The specified property does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_SYSTEM_PROPERTY | There was an attempt to get qualifiers on a system property.
WBEM_NO_ERROR | Success.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.

See Also

IWbemQualifierSet


IWbemClassObject::Clone

The IWbemClassObject::Clone method returns a new object that is a complete clone of the current object. The new object has a COM reference count of 1.

HRESULT IWbemClassObject::Clone(
  [out] IWbemClassObject **ppCopy
);

Parameters

ppCopy
This parameter cannot be NULL. It receives the copy of the current object. The caller must call IWbemClassObject::Release on the returned object when it is no longer required.

A new object is not returned on error.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_INVALID_PARAMETER | NULL was specified as a parameter, and it is not legal in this usage.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to clone the object.
WBEM_NO_ERROR | Success.

Remarks

This method is used to duplicate a class definition, or to duplicate an instance. This can be useful when the original copy of the object is required for backup purposes while a new copy is modified. Likewise, this method can be used to create many new instances from a single source instance. For example, you can use IWbemClassObject::SpawnInstance to create a single starting instance, and you can use IWbemClassObject::Clone to produce 100 copies of the instance quickly. Each object can be modified subsequently to take on its particular values.

It is not possible to use this method to convert a class definition into an instance, or convert an instance into a class definition.


IWbemClassObject::GetObjectText

The IWbemClassObject::GetObjectText method returns a textual rendering of the object. Currently, only Managed Object Format (MOF) syntax is supported as an output format. Notice that the MOF text returned does not contain all the information about the object, but only enough information for the MOF compiler to be able to re-create the original object. For instance, no propagated qualifiers or parent class properties are displayed.

HRESULT IWbemClassObject::GetObjectText(
  [in] Long lFlags,
  [out] BSTR *pbstrObjectText
);

Parameters

lFlags
Reserved. It must be set to zero.
pbstrObjectText
This must point to NULL on entry. This parameter receives a newly allocated BSTR that was initialized with SysAllocString. The caller must call SysFreeString on the pointer when the string is no longer required. This pointer points to a MOF syntax rendering of the object upon return from the call. Since this is an OUT parameter, the pointer must not previously point to a valid string, since the pointer is not be deallocated.

Return Values

WBEM_E_FAILED | Other unspecified failures.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

IWbemQualifierSet


IWbemClassObject::SpawnDerivedClass

Use the IWbemClassObject::SpawnDerivedClass method to create a new derived class object from the current object. The current object must be a class definition that becomes the superclass of the spawned object.

HRESULT IWbemClassObject::SpawnDerivedClass(
  [in] Long lFlags,
  [out] IWbemClassObject **ppNewClass
);

Parameters

lFlags
Reserved. It must be zero.
ppNewClass
Must not be NULL. This receives the pointer to the new class definition object. The caller must invoke IWbemClassObject::Release when the object is no longer required, typically after you have invoked IWbemServices::PutClass to write the class definition. On error, a new object is not returned, and ppNewClass is set to point to NULL.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_ILLEGAL_OPERATION | An illegal operation was requested, such as spawning a class from an instance.
WBEM_E_INCOMPLETE_CLASS | The source class was not completely defined or registered with CIMOM, so a new derived class is not permitted.
WBEM_E_INVALID_PARAMETER | ppNewClass is NULL.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

Remarks

The new object returned in ppNewClass automatically becomes a subclass of the current object. This behavior cannot be overridden. There is no other method by which derived classes can be created.

You cannot create a derived class from a class that is local to your own client process. The base class must be created and registered with CIMOM, and then retrieved using IWbemServices::GetObject before this method can be used to create a derived class. To create a class hierarchy, you must create the initial class with IWbemServices::PutClass, retrieve it using IWbemServices::GetObject, and use the retrieved object to create the newly derived class. Then, this new derived class must be created using IWbemServices::PutClass. To create other derived classes, you must call IWbemServices::GetObject , then call IWbemClassObject::SpawnDerivedClass, and so on, in a cycle for each new derivation level. You must follow this procedure in order to prevent version errors and concurrency conflicts. See Class Creation to create a class with no parent.

See Also

IWbemServices::GetObject, IWbemServices::PutClass


IWbemClassObject::SpawnInstance

Use the IWbemClassObject::SpawnInstance method to create a new instance of a class. The current object must be a class definition obtained from CIMOM using IWbemServices::GetObject or IWbemServices::CreateClassEnum. Then, use this class definition to create new instances. Each new instance is created locally within the process, and a call to IWbemServices::PutInstance is required to actually create the instance within CIMOM.

If you intend to discard the object before calling IWbemServices::PutInstance, simply make a call to IWbemClassObject::Release

Note that spawning an instance from an instance is legal.

HRESULT IWbemClassObject::SpawnInstance(
  [in] LONG lFlags,
  [out] IWbemClassObject **ppNewInstance
);

Parameters

lFlags
Reserved. It must be zero.
ppNewInstance
Must not be NULL. It receives a new instance of the class. The caller must invoke IWbemClassObject::Release when the pointer is no longer required. On error, a new object is not returned and the pointer is set to point to NULL.

Return Values

WBEM_E_INCOMPLETE_CLASS | The current object is not a valid class definition and cannot spawn new instances. Either it is incomplete, or it has not been registered with CIMOM using PutClass.
WBEM_E_ILLEGAL_OPERATION | Returned if this method is used on an instance instead of a class
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

IWbemServices::GetObject, IWbemServices::PutInstance


IWbemClassObject::CompareTo

The IWbemClassObject::CompareTo method compares an object to another CIMOM object. Note that there are certain constraints in this comparison process.

HRESULT IWbemClassObject::CompareTo(
  [in] Long lFlags,
  [in] IWbemClassObject *pCompareTo
);

Parameters

lFlags
Specifies the object characteristics to consider in comparison to other object. It can be WBEM_COMPARISON_INCLUDE_ALL to consider all features, or any combination of these flags:
WBEM_FLAG_IGNORE_OBJECT_SOURCE
The source of the objects, namely the server and the namespace they came from, are ignored in comparison to other objects.
WBEM_FLAG_IGNORE_QUALIFIERS
All qualifiers (including "key" and "dynamic") should be ignored in comparison.
WBEM_FLAG_IGNORE_DEFAULT_VALUES
Default values of properties should be ignored. This flag is only meaningful when comparing classes.
WBEM_FLAG_IGNORE_FLAVOR
Ignore qualifier flavors. This flag still takes qualifier values into account, but ignores flavor distinctions such as propagation rules and override restrictions (see Qualifier Flavors).
WBEM_FLAG_IGNORE_CASE
Compares strings in a case-insensitive manner. This applies both to strings and to qualifier values. Property and qualifier names are always compared in a case-insensitive manner.
WBEM_FLAG_IGNORE_CLASS
This flag instructs the system to assume that the objects being compared are instances of the same class. Consequently, this flag compares instance-related information only. Use this flag to optimize performance. If the objects are not of the same class, the results are unpredictable, and probably are worthless.
pCompareTo
The object in comparison. This pointer must point to a valid IWbemClassObject instance. It cannot be NULL.

Return Values

WBEM_E_FAILED | Unspecified failures.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_S_DIFFERENT | The objects are different.
WBEM_S_SAME | The objects are the same, subject to comparison flags.

See Also

Qualifier Flavors


IWbemClassObject::GetPropertyOrigin

The IWbemClassObject::GetPropertyOrigin method retrieves the name of the class in which a particular property was introduced. For classes with deep inheritance hierarchies, it is often desirable to know which properties were declared in which classes. If the object does not inherit from a parent class, as in the case of a base class, for example, then the current class name is always returned.

HRESULT IWbemClassObject::GetPropertyOrigin(
  [in] BSTR bstrName,
  [out] BSTR *pbstrClassName
);

Parameters

bstrName
The property name for which the parent class name is desired. This must point to a valid BSTR, which is treated as read-only.
pbstrClassName
A pointer to the address of a new BSTR that contains the parent class name. To prevent memory leaks in the client process, the caller must call SysFreeString when the name is no longer needed. Since this is an OUT parameter, the pointer must not previously point to a valid string, since the pointer will not be deallocated.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_NOT_FOUND | The specified property does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

IWbemClassObject::InheritsFrom


IWbemClassObject::InheritsFrom

The IWbemClassObject::InheritsFrom method determines if the current class or instance derives from a specified parent class.

HRESULT IWbemClassObject::InheritsFrom(
  [in] BSTR bstrAncestor
);

Parameters

bstrAncestor
Cannot be NULL. It contains the class name that is being tested. If the current object has this class for one of its ancestor classes, then WBEM_NO_ERROR is returned. This must point to a valid BSTR, which is treated as read-only.

Return Values

WBEM_NO_ERROR | The current object inherits from the specified ancestor class.
WBEM_S_FALSE | The current object does not inherit from the specified ancestor class.
WBEM_E_INVALID_PARAMETER | The strAncestor parameter is NULL.

See Also

GetPropertyOrigin


IWbemClassObject::GetMethod

The IWbemClassObject::GetMethod method …

HRESULT IWbemClassObject::GetMethod(
  [in] BSTR Name,
  [in] long lFlags,
  [out] IWbemClassObject **ppInSignature,
  [out] IWbemClassObject **ppOutSignature
);

Parameters

Name
TBD.
lFlags
Reserved. It must be zero.
ppInSignature
TBD.
ppOutSignature
TBD.

Return Values

Remarks

See Also


IWbemClassObject::PutMethod

The IWbemClassObject::PutMethod method …

HRESULT IWbemClassObject::PutMethod(
  [in] BSTR Name,
  [in] long lFlags,
  [out] IWbemClassObject *pInSignature,
  [out] IWbemClassObject *pOutSignature
);

Parameters

Name
TBD.
lFlags
Reserved. It must be zero.
pInSignature
TBD.
pOutSignature
TBD.

Return Values

Remarks

See Also


IWbemClassObject::DeleteMethod

The IWbemClassObject::DeleteMethod method …

HRESULT IWbemClassObject::DeleteMethod(
  [in] BSTR Name

);

Parameters

Name
TBD

Return Values

Remarks

See Also


IWbemClassObject::BeginMethodEnumeration

The IWbemClassObject::BeginMethodEnumeration method …

HRESULT IWbemClassObject::BeginMethodEnumeration(
  [in] long lEnumFlags
);

Parameters

lEnumFlags
A combination of flags described in Remarks.

Return Values

WBEM_E_INVALID_PARAMETER | The specified combination of flags was invalid, an invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There is not enough memory to begin a new enumeration.
WBEM_NO_ERROR | Success.

Remarks

The properties included in the enumeration are controlled by specifying a combination of the following flags. One flag from each group can be combined with any flag from any other group. However, flags from the same group are mutually exclusive.

GROUP 1

WBEM_FLAG_KEYS_ONLY
Only include properties that constitute the key.
WBEM_FLAG_REFS_ONLY
Only include properties that are object references.

GROUP 2

WBEM_FLAG_LOCAL_ONLY
Only include properties that are defined or modified in the class itself. Exclude all properties that are inherited from superclasses. Exclude system properties from the enumeration.
WBEM_FLAG_PROPAGATED_ONLY
Only include properties that are inherited from superclasses. Exclude properties that are defined or modified in the class itself. Exclude system properties from the enumeration.
WBEM_FLAG_SYSTEM_ONLY
Limit the enumeration to system properties only.
WBEM_FLAG_NONSYSTEM_ONLY
Exclude system properties from the enumeration. Includes local and propagated properties.

See Also


IWbemClassObject::NextMethod

The IWbemClassObject::NextMethod method …

HRESULT IWbemClassObject::NextMethod(
  [in] long lFlags,
  [out, OPTIONAL] BSTR *pName,
  [out, OPTIONAL] IWbemClassObject **ppInSignature,
  [out, OPTIONAL] IWbemClassObject **ppOutSignature
);

Parameters

lFlags
Reserved. It must be zero.
pName
TBD.
ppInSignature
TBD.
ppOutSignature
TBD.

d

Return Values

Remarks

See Also


IWbemClassObject::EndMethodEnumeration

The IWbemClassObject::EndMethodEnumeration method …

HRESULT IWbemClassObject::EndMethodEnumeration(
);

Parameters

None.

Return Values

Remarks

See Also


IWbemClassObject::GetMethodQualifierSet

The IWbemClassObject::GetMethodQuailifierSet method …

HRESULT IWbemClassObject::GetMethodQuailifierSet(
  [in] BSTR Method,
  [out] IWbemQualifierSet **ppQualSet
);

Parameters

Method
TBD.
ppQualSet
Receives the interface pointer that allows access to the qualifiers for the class object. The returned object has a positive reference count upon return from the call. The caller must call IWbemQualifierSet::Release when the object is no longer needed. This parameter cannot be NULL. On error, a new object is not returned and the pointer is set to point to NULL.

Return Values

Remarks

See Also


IWbemClassObject::GetMethodOrigin

The IWbemClassObject::GetMethodOrigin method …

HRESULT IWbemClassObject::GetMethodOrigin(
  [in] BSTR strMethodName,
  [out BSTR strClassName
);

Parameters

strMethodName
The name of the method for the object.
strClassName
Contains the parent class name.

Return Values

Remarks

See Also


IWbemContext

The IWbemContext interface communicates additional information to providers when submitting IWbemServices calls to CIMOM. All primary calls in IWbemServices take an optional parameter pointing to an object of this type.

In many cases, dynamic providers need more information than the information that is specified in the normal parameters of an IWbemServices method. For example, to manipulate any CIM schema objects it provides, a provider may need to know a Simple Network Management Protocol (SNMP) Community name, or an structured query language (SQL) database and table name. A client can add this information to an IWbemContext object, and send the IWbemContext object along with the call as one of the parameters.

Note It is very important that providers make as little use of this mechanism as possible. It is preferred they never require it. If a provider requires a large amount of highly specific context information to respond to a request, then all clients must be coded to provide this information, thus breaking the uniform access model that is the basis of WBEM. Nevertheless, in some cases it cannot be avoided. Therefore, this mechanism is provided to make it possible to access such providers.

An IWbemContext object, which is created using CoCreateInstance, is a simple container of named values. You can access these methods to fill in any context information required by a dynamic provider. After the call to one of the IWbemServices methods, the IWbemContext object can be reused for another call, or it can be deallocated using Release and another object created for other calls to IWbemServices methods

The information contained in an IWbemContext object is entirely determined by the underlying provider. CIMOM makes no use of the information, but simply forwards it to the provider. Providers must publish the context information they require for these service requests.

It is expected that the client application calls CoCreateInstance to create a single context object. Then, it calls SetValue one or more times to set up context values for the provider. Finally, it submits the object to one of the IWbemServices methods, which immediately calls Release on the context object after the call has returned. The other methods are for use primarily by providers that receive the context object and have to extract information.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count, and frees the object when the reference count is zero.

IWbemContext Methods | Description
Clone | Makes a complete copy of the current IWbemContext object.
GetNames | Retrieves the names of all of the context values available.
BeginEnumeration | Begins an enumeration of all context values in the IwbemContext object.
Next | Retrieves the next value in an enumeration of all context values beginning with BeginEnumeration.
EndEnumeration | Ends an enumeration begun with BeginEnumeration and Next.
SetValue | Sets a specific named context value.
GetValue | Retrieves the specified context value by name.
DeleteValue | Removes the specified context value.
DeleteAll | Removes all context values, making the IWbemContext object empty.


IWbemContext::QueryInterface

The IWbemContext::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemContext::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returnss S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemContext::AddRef

The IWbemContext::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemContext::Release

The IWbemContext::Release method decreases the object's reference count by 1.

ULONG Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemContext::Clone

The IWbemContext::Clone method makes a logical copy of the current IWbemContext object. This method can be useful when many calls must be made which have largely identical IWbemContext objects.

HRESULT Clone(
  [out] IWbemContext **ppNewCopy
);

Parameters

ppNewCopy
Must point to NULL on entry. It receives a pointer to the new object containing the clone of the current object. The returned pointer has a positive reference count. The caller must call Release on this pointer when it is no longer needed. This pointer is set to NULL when there are errors; a new object is not returned.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_INVALID_PARAMETER | NULL was specified as a parameter, which is not legal.
WBEM_E_OUT_OF_MEMORY | There is not enough memory to clone the object.
WBEM_NO_ERROR | Success.


IWbemContext::GetNames

The IWbemContext::GetNames method returns a SAFEARRAY of all of the names of the named context values. After all the names are known, GetValue can be called on each name to retrieve the value. This technique is a way of accessing the context values that is different from calling the BeginEnumeration, Next, and EndEnumeration methods.

HRESULT GetNames(
  [in] LONG lFlags,
  [out] SAFEARRAY (BSTR) *pbstrNames
);

Parameters

lFlags
Reserved. Itust be zero.
pbstrNames
This parameter cannot be NULL, but on entry it must point to NULL. If no error is returned, on exit pbstrNames receives a pointer to a new SAFEARRAY of type VT_BSTR containing all the context value names. The caller must call SafeArrayDestroy on the returned pointer when the array is no longer required. If an error code is returned, the pbstrNames pointer is set to point to NULL.

Note If there are no named values in the object, the call succeeds and returns an array of length zero.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

IWbemContext::GetValue, IWbemContext::BeginEnumeration


IWbemContext::BeginEnumeration

The IWbemContext::BeginEnumeration method resets the enumeration of all the context values in the object. This method must be called before the first call to IWbemContext::Next to enumerate all of the context values in the object.

HRESULT BeginEnumeration(
  [in] Long lFlags
);

Parameters

lFlags
Reserved. It must be zero.

Return Values

WBEM_E_INVALID_PARAMETER | The lFlags parameter was not valid.
WBEM_NO_ERROR | Success.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to begin an enumeration.
WBEM_E_FAILED | General failure.

See Also

IWbemContext::Next, IWbemContext::EndEnumeration


IWbemContext::Next

The IWbemContext::Next method

HRESULT Next(
  [in] LONG lFlags,
  [out] BSTR *pbstrName,
  [out] VARIANT *pValue
);

Parameters

lFlags
Reserved. It must be zero.
pbstrName
This parameter cannot be NULL. If no error code is returned, it is set to point to a newly allocated BSTR.

The caller must call SysFreeString on the returned string when it is no longer required. If WBEM_S_NO_MORE_DATA is returned, pbstrName is set to point to NULL, in which case SysFreeString should not be called.

Note If pbstrName points to a valid BSTR on entry, this BSTR is not freed, and a memory leak will occur.

pValue
This parameter cannot be NULL, and it must point to an uninitialized VARIANT. If no error is returned, the VARIANT is initialized using VariantInit. Then the VARIANT is set to contain the context value. The caller must call VariantClear on this pointer when the value is no longer required. If an error code is returned, the VARIANT pointed to by pValue is left unmodified.

If WBEM_S_NO_MORE_DATA is returned, this parameter is set to point to a VARIANT of type VT_NULL.

It is possible that an entire IWbemClassObject is returned inside the VARIANT. If that is the case, then VT_DISPATCH is the VARIANT type. The caller can take the IDispatch pointer and execute QueryInterface to obtain the IWbemClassObject pointer.

Note At the end of the enumeration, WBEM_S_NO_MORE_DATA is returned. The returned VARIANT is of type VT_NULL, and the returned pbstrName is NULL.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_UNEXPECTED | Caller did not call IWbemContext::BeginEnumeration.
WBEM_NO_ERROR | Success.
WBEM_S_NO_MORE_DATA | No more properties are left in the enumeration.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the call.

See Also

IWbemContext::BeginEnumeration, IWbemContext::EndEnumeration


IWbemContext::EndEnumeration

The IWbemContext::EndEnumeration method ends an enumeration sequence that begins with IWbemContext::BeginEnumeration. This call is not required, but it releases as early as possible any system resources associated with the enumeration.

HRESULT EndEnumeration( );

Parameters

None.

Return Values

WBEM_NO_ERROR | Success.
WBEM_E_UNEXPECTED | This call was made without a corresponding call to IwbemContext::BeginEnumeration.

See Also

IWbemContext::BeginEnumeration, IWbemContext::Next


IWbemContext::SetValue

The IWbemContext::SetValue method creates or overwrites a named context value.

HRESULT SetValue(
  [in] BSTR bstrName,
  [in] LONG lFlags,
  [in] VARIANT pValue
);

Parameters

bstrName
Cannot be NULL. It is a read-only pointer to a valid BSTR indicating the context value name.
lFlags
Reserved. It must be zero.
pValue
Must point to a valid VARIANT, which is treated as read-only. The value in the VARIANT becomes the named context value. An entire IWbemClassObject can be stored as well as a simple value by enclosing it in a VARIANT using the VT_DISPATCH type. The caller must execute QueryInterface on the IWbemClassObject, asking for IID_IDispatch, and use the returned pointer in the VARIANT.


IWbemContext::GetValue

The IWbemContext::GetValue method

HRESULT GetValue(
  [in] BSTR bstrName,
  [in] LONG lFlags,
  [out] VARIANT *pValue
);

Parameters

bstrName
The name for which the value is to be retrieved. This must point to a valid BSTR. The pointer is treated as read-only.
lFlags
Reserved. It must be zero.
pValue
This parameter cannot be NULL and must point to an uninitialized VARIANT. If no error is returned, the VARIANT is initialized using VariantInit, and then set to contain the context value. The caller must call VariantClear on this pointer when the value is no longer required. If an error code is returned, the VARIANT pointed to by pValue is left unmodified.

It is possible that an entire IWbemClassObject can be returned inside the VARIANT. If that is the case, then VT_DISPATCH is the VARIANT type. The caller can take the IDispatch pointer and execute QueryInterface to obtain the IWbemClassObject pointer.

Return Values

WBEM_E_NOT_FOUND | The requested value was not found.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

IWbemContext::SetValue


IWbemContext::DeleteValue

The IWbemContext::DeleteValue method deletes a named context value created by IWbemContext::SetValue.

HRESULT DeleteValue(
  [in] BSTR bstrName,
  [in] LONG lFlags
);

Parameters

bstrName
A pointer to a valid BSTR containing the named context value to delete. The pointer is treated as read-only.
lFlags
Reserved. It must be zero.

Return Values

WBEM_E_FAILED | General failure.
WBEM_E_INVALID_PARAMETER | An invalid Name or lFlags value was specified.
WBEM_E_NOT_FOUND | The specified named context value does not exist.
WBEM_NO_ERROR | Success.

See Also

IWbemContext::SetValue, IWbemContext::GetValue


IWbemContext::DeleteAll

The IWbemContext::DeleteAll method removes all named context values from the current object, thus emptying the object.

HRESULT DeleteAll( );

Parameters

None.

Return Values

WBEM_E_FAILED | General failure.
WBEM_NO_ERROR | Success.

See Also

IWbemContext::DeleteValue


IWbemEventConsumerProvider

TBD.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count and frees the object when the reference count is zero.

IwbemEventConsumerProvider Methods | Description
FindConsumer | TBD


IWbemEventConsumerProvider::QueryInterface

The IWbemEventConsumerProvider::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemEventConsumerProvider::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemEventConsumerProvider::AddRef

The IWbemEventConsumerProvider::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemEventConsumerProvider::Release

The IWbemEventConsumerProvider::Release method decreases the object's reference count by 1.

ULONG IWbemEventProvider::Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemEventConsumerProvider::FindConsumer

The IWbemEventConsumerProvider::FindConsumer method …

HRESULT IWbemEventConsumerProvider::FindConsumer(
  [in] IWbemClassObject *pLogicalConsumer,
  [out] IWbemUnboundObjectSink *ppConsumer
);

Parameters

pLogicalConsumer
A pointer to the logical consumer object for which this set of objects is delivered.
ppConsumer
TBD.

Return Values

Remarks

See Also


IWbemEventProvider

TBD.

Methods in Vtable Order

Iunknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count, and frees the object when the reference count is zero.

IWbemEventProvider Methods | Description
ProvideEvents | TBD


IWbemEventProvider::QueryInterface

The IWbemEventProvider::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemEventProvider::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemEventProvider::AddRef

The IWbemEventProvider::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemEventProvider::Release

The IWbemEventProvider::Release method decreases the object's reference count by 1.

ULONG IWbemEventProvider::Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemEventProvider::ProvideEvents

TBD

HRESULT IWbemEventProvider::ProvideEvents(
  [in] IWbemObjectSink *pSink,
  [in] LONG lFlags
);

Parameters

pSink
A pointer to the object sink that the provider will deliver its events to.
lFlags
Reserved. It must be zero.

Return Values

TBD

Remarks

TBD

See Also

TBD


IWbemEventProviderQuerySink

TBD.

Methods in Vtable Order

Iunknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count, and frees the object when the reference count is zero.

IWbemEventProviderQuerySink Methods | Description
NewQuery | TBD
CancelQuery | TBD


IWbemEventProviderQuerySink::QueryInterface

The IWbemEventProviderQuerySink::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, which means the application can use that interface immediately.

HRESULT IWbemEventProviderQuerySink::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemEventProviderQuerySink::AddRef

The IWbemEventProviderQuerySink::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemEventProviderQuerySink::Release

The IWbemEventProviderQuerySink::Release method decreases the object's reference count by 1.

ULONG IWbemEventProviderQuerySink::Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemEventProviderQuerySink::NewQuery

TBD

HRESULT IWbemEventProviderQuerySink::NewQuery(
  [in] UNSIGNED LONG dwId,
  [in] WBEM_WSTR wszQueryLanguage,
  [in] WBEM_WSTR wszQuery
);

Parameters

dwId
TBD.
wszQueryLanguage
TBD.
wszQuery
TBD.

Return Values

TBD

Remarks

TBD

See Also

TBD


IWbemEventProviderQuerySink::CancelQuery

TBD

HRESULT IWbemEventProviderQuerySink::CancelQuery(
  [in] UNSIGNED LONG dwId
);

Parameters

dwId
TBD.

Return Values

TBD

Remarks

TBD

See Also

TBD


IWbemLocator

Use the IWbemLocator interface to obtain the initial namespace pointer to the CIM Object Manager (CIMOM) on a particular host machine. You can access CIMOM itself using the IWbemServices pointer, which is returned by the ConnectServer method on this interface.

A client or provider that needs CIMOM services first obtains a pointer to the locator using CoCreateInstance or CoCreateInstanceEx, as specified in COM documentation in the Microsoft Platform SDK. The IWbemLocator object is always an in-process COM server. The interface pointer to the desired namespace on the desired target machine is then obtained through the IWbemLocator::ConnectServer method, the only method on this interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count, and frees the object when the reference count is zero.

IWbemLocator Methods | Description
ConnectServer | Connects to CIMOM on the specified machine.


IWbemLocator::QueryInterface

The IWbemLocator::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemLocator::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemLocator::AddRef

The IWbemLocator::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemLocator::Release

The IWbemLocator::Release method decreases the object's reference count by 1.

ULONG Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemLocator::ConnectServer

The IWbemLocator::ConnectServer method connects to CIMOM on the machine specified in the bstrNetworkResource parameter. This is typically a Microsoft® Windows NT® machine or a Microsoft® Windows® 95/98 target machine, which must have an operational CIMOM.

HRESULT IWbemLocator::ConnectServer(
  [in] BSTR bstrNetworkResource,
  [in] BSTR bstrUser,
  [in] BSTR bstrPassword,
  [in] BSTR bstrLocale,
  [in] long lSecurityFlags,
  [in] BSTR bstrAuthority,
  [in] IWbemContext *pCtx,
  [out] IWbemServices **ppNamespace
);

Parameters

bstrNetworkResource
A pointer to a valid BSTR containing the object path of the desired CIMOM and namespace. For local machine access to the default namespace, for example, use a simple object path: "root\default" or "\\.\root\default".

For access to the default namespace on a remote machine using Distributed COM (DCOM) or Microsoft-compatible networking, include the machine name: "\\myserver\root\default".

See Object Paths.

bstrUser
A pointer to a valid BSTR, which contains the user name you need for a connection.. This can be NULL if you use the current logged-on user name.
bstrPassword
A pointer to a valid BSTR, which contains the password you need for a connection. This can be NULL, but not a blank string, if you are using the current password. In contrast, treat a blank string as a valid password.
bstrLocale
If NULL, use the current locale. If not NULL, this parameter must be a valid BSTR, which indicates the desired locale for information retrieval. For Microsoft locale identifiers, the format of the string is "MS\xxxx", where xxxx is a string in hexadecimal form that indicates the LCID.

For example, American English would appear as "MS\\0x409" (C++ requires two backslashes because the first is considered an escape character).

The string format is required since WBEM accommodates other localization schemes besides Microsoft 32-bit LCIDs, such as ISO 639 or RFC 1766. See WBEM Localization Guidelines.

lSecurityFlags
Must be one of the following constants:
  • WBEM_AUTHENTICATION_DEFAULT
  • WBEM_AUTHENTICATION_NTLM
  • WBEM_AUTHENTICATION_WBEM

If you use WBEM_AUTHENTICATION_DEFAULT, bstrUser, bstrPassword, and bstrAuthority must remain NULL. In this case, log on using the currently logged-on Windows NT LanMan user. If that fails, try the WBEM Guest account (an anonymous logon). If both fail, the user is denied access.

If you use WBEM_AUTHENTICATION_NTLM, set bstrUser and bstrPassword to the desired Windows NT LanMan Domain account and password. Set the bstrAuthority parameter to the LanMan Domain name to which the user account belongs.

If WBEM_AUTHENTICATION_WBEM is specified, set bstrUser and bstrPassword to a valid WBEM user name and its corresponding password. bstrAuthority can be set to either "WBEM" or NULL.

bstrAuthority
TBD
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that produces the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppNamespace
Receives a pointer to an IWbemServices object bound to the specified namespace. This pointer has a positive reference count. The caller must call Release on the pointer when it is no longer required. This pointer is set to point to NULL when there is an error.

Return Values

WBEM_E_ACCESS_DENIED | The current or specified user name and password were not valid or authorized to make the connection.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_NAMESPACE | The specified namespace did not exist on the server.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | A networking error occurred, preventing normal operation.
WBEM_E_SERVER_NOT_FOUND | The specified server could not be located.
WBEM_NO_ERROR | Success.

See Also

IWbemServices


IWbemObjectSink

The IWbemObjectSink interface is a sink interface used for all types of notifications within the CIMOM programming model. Clients implement this interface to receive both the results of the asynchronous methods of IWbemServices and event notifications. Providers use this interface to provide events and objects.

In general, you call Indicate to provide objects. After that, call SetStatus to indicate the end of the notification sequence. You can also call SetStatus to indicate errors when the sink does not have any objects.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count, and frees the object when the reference count is zero.

IWbemObjectSink Methods | Description
Indicate | Provides notification objects to the implementer.
SetStatus | Provides notification status to the implementer.


IWbemObjectSink::QueryInterface

The IWbemObjectSink::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemObjectSink::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemObjectSink::AddRef

The IWbemObjectSink::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemObjectSink::Release

The IWbemObjectSink::Release method decreases the object's reference count by 1.

ULONG Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemObjectSink::Indicate

The IWbemObjectSink::Indicate method is called by a source to provide a notification. The number of objects in the array depends upon the type of event notification. See WBEM Events.

Use this interface and method in conjunction with the asynchronous methods of the IWbemServices interface.

Clients and providers must implement this interface to receive notifications or to execute the asynchronous methods of IWbemServices.

HRESULT IWbemObjectSink::Indicate(
  [in] LONG lObjectCount,
  [in, size_is(1ObjectCount)] IWbemClassObject **ppObjArray
);

Parameters

lObjectCount
The number of objects in the following array of pointers.
ppObjArray
An array of pointers to IWbemClassObject interfaces. The array memory itself is read-only, and is owned by the caller of the method. Since this is an in-parameter, the interface called has the option of calling IWbemServices::AddRef on any object pointer in the array and holding it before returning. The interface called is only required to copy and then call IWbemServices::AddRef on the pointers if the pointers will be used after the call returns, according to COM rules. The interface called should not call Release on the objects without corresponding calls to AddRef. For more information on the IUnknown Interface methods, see the Microsoft Platform SDK.

Return Values

WBEM_E_FAILED | The receiver was not able to process the notification properly.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | The call succeeded; the receiver acknowledges the notification.


IWbemObjectSink::SetStatus

The IWbemObjectSink::SetStatus method is called by sources to indicate the end of a notification sequence or the end of a result code of an asynchronous method of IWbemServices.

Normally, a client implements the IWbemObjectSink interface, and executes IWbemServices methods that return their results using this interface. During this operation, CIMOM calls Indicate as many times as required, followed by a final call to SetStatus, and in many cases, Release.

HRESULT IWbemObjectSink::SetStatus(
  [in] LONG lFlags,
  [in] HRESULT hResult,
  [in] BSTR bstrParam,
  [in] IWbemClassObject *pObjParam
);

Parameters

lFlags
Reserved. It must be zero.
hResult
Set to the HRESULT of the asynchronous operation or notification. This is typically one of the WBEM_E_ error codes or WBEM_S_ status codes.
bstrParam
Receives a pointer to a read-only BSTR, if the original asynchronous operation returns a string. For example, when using PutInstanceAsync, IWbemObjectSink::SetStatus is called with this parameter set to the object path of the newly created instance.
pObjParam
In cases where a complex error or status object is returned, this contains a pointer to the object. If the object is required after the call returns, the called object must AddRef the pointer before returning.

Return Values

WBEM_E_FAILED | The receiver was not able to process the notification properly.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | The call succeeded; the receiver acknowledges the notification.


IWbemPropertyProvider

The IWbemPropertyProvider interface is a callback interface implemented only by dynamic property providers. These providers must map their implementations to individual properties in a CIM class instance, usually by specifying qualifiers in a MOF file. CIMOM is the only client of this interface, and it calls the methods whenever the properties are required by a client application. At that time, the property provider looks up the corresponding property value from its own data sources, and returns it to CIMOM.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count and frees the object when the reference count is zero.

IWbemPropertyProvider Methods | Description
GetProperty | Called by CIMOM whenever a dynamic property value is required.
PutProperty | Called by CIMOM to write a dynamic property value.


IWbemPropertyProvider::QueryInterface

The IWbemPropertyProvider::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemPropertyProvider::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemPropertyProvider::AddRef

The IWbemPropertyProvider::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemPropertyProvider::Release

The IWbemPropertyProvider::Release method decreases the object's reference count by 1.

ULONG Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemPropertyProvider::GetProperty

The IWbemPropertyProvider::GetProperty method is implemented by a dynamic property provider. It is called by CIMOM whenever a dynamic property value is required. The guidelines below show the method's behavior in response to CIMOM's call.

HRESULT IWbemPropertyProvider::GetProperty(
  [in] Long lFlags,
  [in] BSTR bstrLocale,
  [in] BSTR bstrClassMapping,
  [in] BSTR bstrInstMapping,
  [in] BSTR bstrPropMapping,
  [out] VARIANT *pvValue
);

Parameters

lFlags
Reserved. It must be zero.
bstrLocale
A string indicating the desired locale in cases where the returned property value can be localized. If the property cannot be localized, the implementation can ignore this value. See Locale Strings.
bstrClassMapping
The class mapping string passed in by CIMOM. This indicates the CIM class for the requested property. This must point to a valid BSTR, which is treated as read-only.
bstrInstMapping
This is a private mapping string that can only be interpreted by the implementation. It is a literal copy of the string value for the INSTANCECONTEXT qualifier for the instance. This must point to a valid BSTR, which is treated as read-only.
bstrPropMapping
The property mapping string passed by CIMOM, which can only be interpreted by the implementation. It is a literal copy of the value of the PROPERTYCONTEXT qualifier for the property. This must point to a valid BSTR, which is treated as read-only.
pvValue
Points to an uninitialized VARIANT that receives the value for the property. The implementation must call VariantInit and return the value. If an error occurs, the implementation is expected to ignore the pointer.

Return Values

Must return S_OK if the call succeeds. If the call fails, the method must return S_FALSE.

See Also

PutProperty


IWbemPropertyProvider::PutProperty

The IWbemPropertyProvider::PutProperty method is implemented by a dynamic property provider. It is called by CIMOM whenever a dynamic property value is written. The guidelines below show the method's behavior in response to CIMOM's call.

HRESULT IWbemPropertyProvider::PutProperty(
  [in] Long lFlags,
  [in] BSTR bstrLocale,
  [in] BSTR bstrClassMapping,
  [in] BSTR bstrInstMapping,
  [in] BSTR bstrPropMapping,
  [in] VARIANT *pvValue
);

Parameters

lFlags
Reserved. It must be zero.
bstrLocale
A string indicating the desired locale in cases where the returned property value can be localized. If the property cannot be localized, the implementation can ignore this value. See Locale Strings.
bstrClassMapping
The class mapping string passed in by CIMOM. This indicates the CIM class for which the property is being requested. It must point to a valid BSTR, which is treated as read-only.
bstrInstMapping
This is a private mapping string that can only be interpreted by the implementation. It is a literal copy of the string value for the INSTANCECONTEXT qualifier for the instance. This must point to a valid BSTR, which is treated as read-only.
bstrPropMapping
The property mapping string passed by CIMOM, which can only be interpreted by the implementation. It is a literal copy of the value of the PROPERTYCONTEXT qualifier for the property. It will point to a valid BSTR, which must be treated as read-only.
pvValue
Points to an existing VARIANT that contains the value to be written.

Return Values

The implementation must return S_OK if the operation succeeds, or S_FALSE if not.

See Also

GetProperty


IWbemProviderInit

The IWbemProviderInit interface is used to …

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
Addref | Increases the object's reference count by 1.
Release | Decrements the object's reference count by 1, and frees the object when the reference count is zero.

IWbemProviderInit Methods | Description
Initialize | TBD


IWbemProviderInit::QueryInterface

The IWbemProviderInit::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemProviderInit::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemProviderInit::AddRef

The IWbemProviderInit::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemProviderInit::Release

The IWbemProviderInit::Release method decreases the object's reference count by 1.

ULONG IWbemProviderInit::Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemProviderInit::Initialize

The IWbemProviderInit::Initialize method …

HRESULT IWbemProviderInit::Initialize(
  [in] LPWSTR pszUser,
  [in] long lFlags,
  [in] LPWSTR pszNamespace,
  [in] LPWSTR pszLocale,
  [in] IWbemServices *pNamespace,
  [in] IWbemContext *pCtx,
  [in] IWbemProviderInitSink *pInitSink
);

Parameters

pszUser
Pointer to the user name, if per-user initialization was requested in the __Win32Provider instance.
lFlags
Reserved. It must be zero.
pszNamespace
The namespace name for which the provider is being initialized.
pszLocale
The locale name for which the provider is being initialized. This is typically a string of the following format, where the hex value is a Microsoft standard LCID value:
"MS\\0x409"
pNamespace
An IWbemServices pointer back into CIMOM. This pointer is capable of servicing any requests made by the provider. The provider should AddRef this pointer if it is going to need to call back into CIMOM during its execution.
PCtx
The context object associated with initialization. If the provider needs to make requests back into CIMOM before completing initialization, it should AddRef this object and return it in any dependent calls it makes using the pNamespacepointer.
PInitSink
The initialization sink exported by CIMOM to the provider. When the provider is partially or fully initialized or fails to initialize, it indicates initialization status using this sink. The provider should AddRef this pointer and use it until it has communicated its final status to CIMOM.

Return Values

Remarks

See Also


IWbemProviderInitSink

The IWbemProviderInitSink interface is used to

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
Addref | Increases the object's reference count by 1.
Release | Decrements the object's reference count by 1, and frees the object when the reference count is zero.

IWbemProviderInitSink Methods | Description
SetStatus | TBD


IWbemProviderInitSink::QueryInterface

The IWbemProviderInitSink::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemProviderInitSink::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemProviderInitSink::AddRef

The IWbemProviderInitSink::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemProviderInitSink::Release

The IWbemProviderInitSink::Release method decreases the object's reference count by 1.

ULONG IWbemProviderInitSink::Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemProviderInitSink::SetStatus

The IWbemProviderInitSink::SetStatus method indicates to CIMOM whether the provider is fully or partially initialized.

HRESULT IWbemProviderInitSink::SetStatus(
  [in] long lStatus,
  [in] long lFlags
);

Parameters

lStatus
Indicates to CIMOM whether the provider is fully or partially initialized using one of the following parameters:
Value | Description
WBEM_S_INITIALIZED | Indicates that the provider is ready to accept requests.
WBEM_S_LIMITED_SERVICE | Indicates that the provider is not ready to accept client requests, but can accept requests made by other providers during their attempts to initialize.
WBEM_E_Failed | Indicates that the provider has failed to initialize, and is not functional.

lFlags
Reserved. Must be zero.

Return Values

Remarks

See Also


IWbemQualifierSet

The object that exports the IWbemQualifierSet interface acts as a container for the entire set of named qualifiers for a single property, Also, it can act as a container for an entire class object, instance, or class definition, depending on how the pointer was obtained. If the pointer was obtained from IWbemClassObject::GetQualifierSet, the object consists of the set of qualifiers for an entire object (a class or instance). If the pointer was obtained from IWbemClassObject::GetPropertyQualifierSet, then the object represents the qualifiers for a particular property.

Within WBEM, this interface is always in-process. Put operations only affect the local copy of the object. Get operations retrieve values from the local copy. Updates are performed only when entire objects are read or written using methods on the IWbemServices interface.

It is strongly recommended that CIMOM dynamic providers never implement this interface. See IWbemClassObject for details.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the reference count.

IWbemQualifierSet Methods | Description
Get | Reads a particular named qualifier.
Put | Writes a particular named qualifier.
Delete | Deletes the specified named qualifier.
GetNames | Gets the names of qualifiers subject to certain filters.
BeginEnumeration | Resets prior to an enumeration of all qualifiers.
Next | Gets the next qualifier during an enumeration of all qualifiers.
EndEnumeration | Ends an enumeration of qualifiers.


IWbemQualifierSet::QueryInterface

The IWbemQualifierSet::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemQualifierSet::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer to be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface is not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemQualifierSet::AddRef

The IWbemQualifierSet::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemQualifierSet::Release

The IWbemQualifierSet::Release method decreases the object's reference count by 1.

ULONG IWbemQualifierSet::Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemQualifierSet::Get

The IWbemQualifierSet::Get method gets the specified named qualifier, if found.

HRESULT IWbemQualifierSet::Get(
  [in] BSTR bstrName,
  [in] LONG lFlags,
  [out, OPTIONAL] VARIANT *pVal,
  [out, OPTIONAL] LONG *plFlavor
);

Parameters

bstrName
The qualifier name for which the value is being requested. This must point to a valid BSTR. The pointer is treated as read-only.
lFlags
Reserved. It must be zero.
pVal
When successful, the VARIANT is assigned to the correct type and value for the qualifier. VariantInit is called on this VARIANT.

It is the responsibility of the caller to call VariantClear on the pointer when the value is no longer required. If there is an error code, the VARIANT pointed to by pVal is not modified.

If this parameter is NULL, the parameter is ignored.

plFlavor
Can be NULL. If not NULL, this must point to a LONG that receives the qualifier flavor bits for the requested qualifier. See Qualifier Flavors.

Return Values

WBEM_E_INVALID_PARAMETER | One or more parameters were not found, were invalid, or the namespace could not be parsed.
WBEM_E_NOT_FOUND | The specified qualifier did not exist.
WBEM_NO_ERROR | Success.

See Also

Qualifier Flavors


IWbemQualifierSet::Put

The IWbemQualifierSet::Put method writes the named qualifier and value. If the qualifier does not exist, it is created. The new qualifier overwrites the previously existing value of the same name.

In some cases, it is not possible to write the value of a qualifier if it was propagated from another object. Propagated qualifiers are generally read-only, but they can be overridden in some cases. See Qualifier Flavors.

When writing the key qualifier, it is not necessary to specify any flavors or propagation rules.

HRESULT IWbemQualifierSet::Put(
  [in] BSTR bstrName,
  [in] VARIANT *pVal,
  [in] LONG lFlavor,
);

Parameters

bstrName
The name of the qualifier that is being written. This must point to a valid BSTR. The pointer is treated as read-only.
pVal
Cannot be NULL. This must point to a valid VARIANT that contains the qualifier value to be written. The pointer is treated as read-only. It is the caller's responsibility to call VariantClear on this pointer after the value is no longer needed.

Only variants of type VT_I4, VT_R8, VT_BSTR, VT_BOOL and arrays of types VT_BSTR, VT_I4, VT_R8, and VT_BOOL are supported.

lFlavor
The desired qualifier flavor for this qualifier. See Qualifier Flavors.
Not required if the qualifier is the key qualifier.

Return Values

WBEM_E_CANNOT_BE_KEY | There was an illegal attempt to specify a key qualifier on a property that cannot be a key. The keys are specified in the class definition for an object, and cannot be altered on a per-instance basis.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified or the namespace could not be parsed.
WBEM_E_INVALID_QUALIFIER_TYPE | The pVal parameter is not of a legal qualifier type.
WBEM_E_OVERRIDE_NOT_ALLOWED | It is not possible to perform the IWbemQualifierSet::Put operation on this qualifier because the owning object does not permit overrides.
WBEM_NO_ERROR | Success.

See Also

Qualifier Flavors


IWbemQualifierSet::Delete

The IWbemQualifierSet::Delete method deletes the specified qualifier by name. If the qualifier is inherited from the parent class, it can be overriden with a new value. In this case, use Delete to delete the new value, which resets the qualifier to the original inherited value.

See Qualifier Flavors.

HRESULT IWbemQualifierSet::Delete(
  [in] BSTR bstrName
);

Parameters

bstrName
The name of the qualifier to delete. This must be a valid BSTR. The pointer is treated as read-only.

Return Values

WBEM_E_INVALID_OPERATION | Deleting this qualifier is illegal.
WBEM_E_INVALID_PARAMETER | The Name parameter was not valid.
WBEM_E_NOT_FOUND | The specified qualifier was not found.
WBEM_NO_ERROR | Success.
WBEM_S_RESET_TO_DEFAULT | When deleting an overridden qualifier, this status code (a non-error code) indicates that the local override was deleted, and that the original qualifier from the parent object has resumed scope. A subsequent attempt to get the qualifier will succeed, returning the parent's value.

See Also

Qualifier Flavors


IWbemQualifierSet::GetNames

The IWbemQualifierSet::GetNames method retrieves the names of all of the qualifiers available. Alternately, depending on the filter value of IFlags, this method retrieves the names of certain qualifiers.

You can access these qualifiers by name, using IWbemQualifierSet::Get for each name. It is not an error for any given object to have zero qualifiers, so the number of strings in pbstrNames on return can be zero, even though WBEM_NO_ERROR is returned.

HRESULT IWbemQualifierSet::GetNames(
  [in] LONG lFlags,
  [out] SAFEARRAY (BSTR) *pbstrNames
);

Parameters

lFlags
One of the following constants:
0 (Zero) | Return the names of all qualifiers.
WBEM_FLAG_LOCAL_ONLY | Return only the names of the local object. If the current qualifiers set refers to a property, return only the qualifiers set on this property, and not those qualifiers propagated from another qualifier set. If the current qualifiers set refers to an instance, return only instance-specific qualifier names. If the current qualifiers set refers to a class, return only qualifiers local to the derived-most class.
WBEM_FLAG_PROPAGATED_ONLY | Return only the names of qualifiers propagated from another object. For example, if the current qualifier set refers to a property, return only the qualifiers propagated to this property from another qualifier set, and not those set on this property itself. If the current qualifier set refers to an instance, only return those qualifiers propagated from the class definition. If the current qualifier set refers to a class, only return those qualifier names inherited from the superclasses.

pbstrNames
A new SAFEARRAYis created that contains the requested names.

In all cases where no error is returned, a new array is created and pbstrNames is set to point to it. This occurs even though the resulting array has zero elements. On error, a new SAFEARRAY is not returned.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

IWbemQualifierSet::Get

IWbemQualifierSet::BeginEnumeration


IWbemQualifierSet::BeginEnumeration

The IWbemQualifierSet::BeginEnumeration method resets before there is an enumeration of all the qualifiers in the object. To enumerate all of the qualifiers on an object, this method must be called prior to the first call to IWbemQualifierSet::Next.

HRESULT IWbemQualifierSet::BeginEnumeration(
  [in] LONG lFlags
);

Parameters

lFlags
Specifies the qualifiers to include in the enumeration. It must be one of the following constants:
0 (Zero) | Return the names of all qualifiers.
WBEM_FLAG_LOCAL_ONLY | Return only the names of the local object. If the current qualifier set refers to a property, return only the qualifiers set on this property, and not those propagated from another qualifier set. If the current qualifier set refers to an instance, return only instance-specific qualifier names. If the current qualifier set refers to a class, return only qualifiers local to the derived-most class.
WBEM_FLAG_PROPAGATED_ONLY | Return only the names of qualifiers propagated from another object. For example, if the current qualifier set refers to a property, return only the qualifiers propagated to this property from another qualifier set, and not those set on this property itself. If the current qualifier set refers to an instance, only return those qualifiers propagated from the class definition. If the current qualifier set refers to a class, only return those qualifier names inherited from the superclasses, and so on.

Return Values

WBEM_E_INVALID_PARAMETER | The lFlags parameter was not valid.
WBEM_NO_ERROR | Success.

See Also

IWbemQualifierSet::Next


IWbemQualifierSet::Next

The IWbemQualifierSet::Next method retrieves the next qualifier in an enumeration that was started with IWbemQualifierSet::BeginEnumeration. This method is called repeatedly to enumerate all the qualifiers until WBEM_S_NO_MORE_DATA is returned. To terminate the enumeration early, call IWbemQualifierSet::EndEnumeration.

The order of the qualifiers returned during the enumeration is not defined.

HRESULT IWbemQualifierSet::Next(
  [in] LONG lFlags,
  [out, OPTIONAL] BSTR *pbstrName,
  [out, OPTIONAL] VARIANT *pVal,
  [out, OPTIONAL] LONG *plFlavor
);

Parameters

lFlags
Reserved. It must be zero.
pbstrName
A new BSTR is always allocated whenever WBEM_NO_ERROR is returned.

The caller must call SysFreeString on the returned string when it is no longer required.

Note If pbstrName points to a valid BSTR on entry, the valid BSTR is not freed, and there will be a memory leak.

pVal
This parameter receives the value for the qualifier. VariantInit is called on this VARIANT by this method. The caller must call VariantClear on this pointer when the value is no longer required. If an error code is returned, the VARIANT pointed to by pVal is left unmodified.
plFlavor
If not NULL, the value pointed to is set to the qualifier flavor. See Qualifier Flavors.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_UNEXPECTED | Caller did not call IWbemQualifierSet::BeginEnumeration.
WBEM_NO_ERROR | Success.
WBEM_S_NO_MORE_DATA | No more properties are left in the enumeration.

See Also

IWbemQualifierSet::BeginEnumeration, IWbemQualifierSet::EndEnumeration, Qualifier Flavors


IWbemQualifierSet::EndEnumeration

Call the IWbemQualifierSet::EndEnumeration method when you plan to terminate enumerations using IWbemQualifierSet::BeginEnumeration and IWbemQualifierSet::Next . We recommend this call, but it is not required. It immediately releases resources associated with the enumeration.

HRESULT IWbemQualifierSet::EndEnumeration( );

Parameters

None.

Return Values

WBEM_NO_ERROR Success.

See Also

IWbemQualifierSet::BeginEnumeration, IWbemQualifierSet::Next


IWbemServices

CIMOM imports the IWbemServices interface. It is used by clients to access WBEM services. It is also exported by class and instance dynamic providers. This interface provides management services to client processes and to other providers.

Note Providers implementing this interface must obey the documented semantics of each method that they implement, and support the specified error return codes. While CIMOM implements all of the methods, any given provider usually implements a small subset of the available functionality on this interface. WBEM_E_NOT_SUPPORTED returns for unimplemented methods.

Note All outbound interface pointers from any IWbemServices method should be initialized to NULL prior to calling the interface method. For example, IWbemServices::GetObject returns an IWbemClassObject interface pointer. This pointer should be pre-initialized to NULL (or zero) before making the call:

IWbemClassObject *pObj = 0;

pWbemSvc->GetObject(strPath, 0, 0, &pObj, 0);

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Determines if the current object supports a given interface.
Addref | Increases the object's reference count by 1.
Release | Decrements the reference count.

IWbemServices Methods | Description
OpenNamespace | Opens a particular child namespace for operations.
CancelAsyncCall | Cancels a currently executing asynchronous call.
QueryObjectSink | Allows the caller to obtain a notification handler sink.
GetObject | Retrieves an object, whether an instance or class definition.
GetObjectAsync | Asynchronously retrieves an object (an instance or class definition).
PutClass | Creates or updates a class definition.
PutClassAsync | Asynchronously creates or updates a class definition.
DeleteClass | Deletes a class.
DeleteClassAsync | Deletes a class and receives confirmation asynchronously.
CreateClassEnum | Creates a class enumerator.
CreateClassEnumAsync | Creates a class enumerator that executes asynchronously.
PutInstance | Creates or updates an instance of a particular class.
PutInstanceAsync | Asynchronously creates or updates an instance of a particular class.
DeleteInstance | Deletes a particular instance of a class.
DeleteInstanceAsync | Deletes an instance and provides confirmation asynchronously.
CreateInstanceEnum | Creates an instance enumerator.
CreateInstanceEnumAsync | Creates an asynchronous instance enumerator.
ExecQuery | Executes a query to retrieve instances.
ExecQueryAsync | Executes a query and asynchronously returns the instances.
ExecNotificationQuery | Executes a query to receive events.
ExecNotificationQueryAsync | Executes a query and asynchronously receives the events.
ExecMethod | Executes an object method.
ExecMethodAsync | Executes an object method asynchronously.


IWbemServices::QueryInterface

The IWbemServices::QueryInterface method determines whether the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemServices::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that is filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because there is no support for the requested interface, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft® Platform SDK.

See Also

Using the IUnknown Interface


IWbemServices::AddRef

The IWbemServices::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemServices::Release

The IWbemServices::Release method decreases the object's reference count by 1.

ULONG Release( );

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemServices::OpenNamespace

The IWbemServices::OpenNamespace method provides the caller with a new IWbemServices pointer that has the specified child namespace as its operating context. All operations through the new pointer, such as class or instance creation, only affect that namespace. The namespace must be a child namespace of the current object through which this method is called.

HRESULT IWbemServices::OpenNamespace(
  [in]  BSTR bstrNamespace,
  [in]  LONG lFlags,
  [in] IWbemContext *pCtx,
  [out, OPTIONAL] IWbemServices **ppWorkingNamespace,
  [out, OPTIONAL] IWbemCallResult **ppResult
);

Parameters

bstrNamespace
The object path to the target namespace. See Namespaces. This namespace can only be relative to the current namespace associated with the IWbemServices interface pointer. This cannot be an absolute path. This parameter cannot be NULL.
lFlags
Reserved. It must be zero.
pCtx
Reserved. It must be NULL.
ppWorkingNamespace
Receives the object representing the new namespace context. The returned pointer has a positive reference count. The caller must call Release on this pointer when it is no longer needed. This pointer is set to NULL when there are errors. If this parameter is specified, then ppResult must be NULL.
ppResult
Typically NULL. If not NULL, then ppWorkingNamespace must be NULL. In this case, the parameter receives a pointer to a new IWbemCallResult object, and the call returns immediately. Then the caller can periodically poll the IWbemCallResult::GetResultServices method until the pointer for the requested namespace becomes available. This parameter is then set to point to NULL when there is an error, and a new object is not returned.

IMPORTANT If you use this parameter, then you must set ppResult to point to NULL before calling the method. This is a DCOM rule.

Return Values

WBEM_E_ACCESS_DENIED | The user does not have permission to access the requested context.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_NAMESPACE | The specified namespace does not exist.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the current process and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

Remarks

IWbemLocator::ConnectServer can also be used to open the same namespace. The only difference is that the OpenNamespace method allows you to place relative object paths in the Namespace parameter to open child namespaces recursively. IWbemLocator::ConnectServer requires a full object path. See Object Paths.

For example, if the current namespace associated with the IWbemServices interface pointer is Root, then using Default in the Namespace parameter yields a new pointer bound to the \Root\Default namespace.

The namespace is closed when Release is called and the reference count reaches zero.

See Also

Error Objects, IWbemLocator::ConnectServer, Namespaces


IWbemServices::CancelAsyncCall

The IWbemServices::CancelAsyncCall method cancels any currently pending asynchronous call based on the IWbemObjectSink pointer originally passed to the asynchronous method. Before this method returns, it is guaranteed that the outstanding IWbemObjectSink pointer passed to the original asynchronous call is released using Release.

HRESULT IWbemServices::CancelAsyncCall(
  [in] IWbemObjectSink *pSink
);

Parameters

pSink
The pointer to the IWbemObjectSink implementation provided by the client to any of the asynchronous methods of IWbemServices.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | The supplied handle in lAsyncRequestHandle did not correspond to a pending asynchronous request.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The RPC link between the current process and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Asynchronous Methods, IWbemObjectSink


IWbemServices::QueryObjectSink

The IWbemServices::QueryObjectSink method allows the caller to obtain a notification handler that is exported by CIMOM. This allows the caller to write notifications and events directly to CIMOM. The caller should only write Extrinsic Events to CIMOM. See WBEM Events.

HRESULT IWbemServices::QueryObjectSink(
  [in] Long lFlags,
  [out] IWbemObjectSink **ppResponseHandler
);

Parameters

lFlags
Reserved. It must be zero.
ppResponseHandler
Receives the interface pointer to the notification handler. This is set to point to NULL when there is an error. The returned pointer has a positive reference count, and the caller must call Release on the pointer when it is no longer needed. A NULL value can be returned if no notification handler is available. This is not an error.

Return Values

WBEM_E_ACCESS_DENIED | The caller does not have permission to provide notifications to CIMOM.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_RPC_FAILURE | The RPC link between the current process and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

See Also

WBEM Events, IWbemObjectSink


IWbemServices::GetObject

The IWbemServices::GetObject method locates an object by path.

This method retrieves an object, either a class definition or an instance, based on its path. This method only retrieves objects from the namespace associated with the current IWbemServices object.

HRESULT IWbemServices::GetObject(
  [in] BSTR bstrObjectPath,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [out, OPTIONAL] IWbemClassObject **ppObject,
  [out, OPTIONAL] IWbemCallResult **ppCallResult
);

Parameters

bstrObjectPath
The object path of the object to retrieve. If this is NULL, an empty object is returned that can become a new class. See Class Creation.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppObject
If not NULL, this receives the object, if it is found. The returned object has a positive reference count. The caller must use Release when the object is no longer needed. In all cases of error, this parameter is set to point to NULL.
ppCallResult
If NULL, this is not used. Otherwise, the call returns immediately and ppCallResult receives a pointer to a new IWbemCallResult object which can be periodically polled to determine the result of the call. The caller can call IWbemCallResult::GetResultObject to retrieve the object when it becomes available.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to access the object.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_PATH | The specified path was invalid.
WBEM_E_NOT_FOUND | The requested object could not be found.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_RPC_FAILURE | The RPC link between the client and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Class Creation, Error Objects, IWbemCallResult, IWbemServices::GetObjectAsync, Object Paths


IWbemServices::GetObjectAsync

The IWbemServices::GetObjectAsync method retrieves an object, either a class definition or instance, based on its path. This is similar to IWbemServices::GetObject except that the call returns immediately and the object is provided to the supplied object sink.

Currently, this method retrieves objects only from the namespace associated with the IWbemServices pointer.

HRESULT IWbemServices::GetObjectAsync(
  [in] BSTR bstrObjectPath,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] CALLBACK *pResponseHandler
);

Parameters

bstrObjectPath
The object path of the object to retrieve. If this is NULL, an empty object, which can become a new class, is returned. See Class Creation.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
Points to the caller's implementation of IWbemObjectSink. This handler receives the requested object when it becomes available through the IWbemObjectSink::SetStatus method. The pObjParam parameter contains the object. For a detailed explanation of this parameter, see also Asynchronous Methods. CIMOM only calls AddRef to the pointer in cases where WBEM_NO_ERROR is returned. In cases where an error code is returned, the reference count is the same as on entry.

Return Values

WBEM_E_FAILED | Other error codes are returned asynchronously to the IWbemObjectSink.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_PATH | The specified object path was invalid.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Asynchronous Methods, Class Creation, IWbemServices::GetObject, Object Paths


IWbemServices::PutClass

The IWbemServices::PutClass method creates a new class or it updates an existing one. The class specified by the pObject parameter must have been correctly initialized with all of the required property values.

The user may not create classes with names that begin with two leading underscores. This is reserved for system classes.

HRESULT IWbemServices::PutClass(
  [in] IWbemClassObject *pObject,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [out, OPTIONAL] IWbemCallResult **ppCallResult
);

Parameters

pObject
Must point to a valid class definition. The reference count is not changed.
lFlags
If WBEM_FLAG_CREATE_OR_UPDATE, the class is created if it does not exist or it is overwritten if it exists already. If WBEM_FLAG_UPDATE_ONLY, then the class must exist, and this call constitutes an update. If WBEM_FLAG_CREATE_ONLY, then this call is for creation only; the call fails if the class already exists.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppCallResult
If NULL, this is not used .If not NULL, the call returns immediately with WBEM_NO_ERROR. Then, IWbemCallResult must be polled for the result using IWbemCallResult::GetCallStatus.

Return Values

WBEM_E_ACCESS_DENIED | The current user is not permitted to create or modify classes.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INCOMPLETE_CLASS | Required properties for classes have not all been set.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the current process and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.
WBEM_E_ALREADY_EXISTS | WBEM_FLAG_CREATE_ONLY flag was specified, but the class already exists.
WBEM_E_NOT_FOUND | Update flag specified, but class is not found.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Class Creation and Modification Rules, Error Objects, IWbemCallResult


IWbemServices::PutClassAsync

The IWbemServices::PutClassAsync method creates a new class, or it updates an existing one. The class specified by the pObject parameter must be correctly initialized with all of the required property values. The call immediately returns. Success or failure is supplied to the object sink specified by the pResponseHandler parameter.

HRESULT IWbemServices::PutClassAsync(
  [in] IWbemClassObject *pObject,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] CALLBACK *pResponseHandler
);

Parameters

pObject
Points to the object containing the class definition.
lFlags
If WBEM_FLAG_CREATE_OR_UPDATE, the class is created if it does not exist, or it is overwritten if it exists already. If WBEM_FLAG_UPDATE_ONLY, then the class must exist, and this call constitutes an update. If WBEM_FLAG_CREATE_ONLY, then this call is for creation only, and the call fails if the class already exists.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
Points to the caller's implementation of IWbemObjectSink. This handler receives the status of the Put request when it becomes available using the SetStatus method. For a detailed explanation of this parameter, see Asynchronous Methods. CIMOM only calls AddRef to the pointer in cases where WBEM_NO_ERROR is returned. In cases where an error code is returned, the reference count is the same as on entry.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to create classes.
WBEM_E_ALREADY_EXISTS | WBEM_FLAG_CREATE_ONLY flag was specified but the class already exists.
WBEM_E_FAILED | Unspecified failure.
WBEM_E_INVALID_CLASS |
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_NOT_FOUND | WBEM_FLAG_UPDATE_ONLY flag was specified, but the class does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the current process and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

Other status or error codes are reported to the object sink specified by the pReponseHandler parameter.

See Also

Asynchronous Methods, Class Creation and Modification Rules, IWbemServices::PutClass


IWbemServices::DeleteClass

The IWbemServices::DeleteClass method deletes the specified class from the current namespace. If a dynamic instance provider is associated with the class, the provider is unregistered, and it is no longer called for that class. Any classes that derive from the deleted class are also deleted, and their associated providers are unregistered. All outstanding static instances of the specified class and its subclasses are also deleted when the class is deleted.

If the class is provided by a dynamic class provider, the success of the deletion depends on whether class deletion is supported by that provider.

Note System classes cannot be deleted.

HRESULT IWbemServices::DeleteClass(
  [in] BSTR bstrClass,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [out, OPTIONAL] IWbemCallResult **ppCallResult
);

Parameters

bstrClass
The name of the class targeted for deletion.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppCallResultt
If NULL, the status of the call is returned in the HRESULT return code. If not NULL, the call becomes semisynchronous. The call returns immediately and this parameter receives a pointer to a new IWbemCallResult object that must be periodically polled by calling IWbemCallResult::GetCallStatus to determine the final status of the operation. Using this technique, many nonblocking calls to DeleteClass may occur before checking the status of any of them. In error cases where CIMOM cannot be reached, this parameter will be set to NULL.

See Error Objects.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to delete classes.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_CLASS | The specified class does not exist.
WBEM_E_INVALID_OPERATION | Deletion is not supported for the specified class. It may have been a system class or a class supplied by a dynamic provider that does not support class deletion.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the current process and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Error Objects, IWbemServices::DeleteClassAsync


IWbemServices::DeleteClassAsync

The IWbemServices::DeleteClassAsync method deletes the specified class from the current namespace. This method is identical to IWbemServices::DeleteClass except that the call returns immediately. Confirmation or failure is asynchronously reported to the specified object sink using the IWbemObjectSink::SetStatus method after the operation has completed.

HRESULT IWbemServices::DeleteClassAsync(
  [in] BSTR bstrClass,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] CALLBACK *pResponseHandler
);

Parameters

bstrClass
The name of the class targeted for deletion.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
Points to an implementation of IWbemObjectSink implemented by the caller. This handler receives the status of the deletion request when it becomes available through the IWbemObjectSink::SetStatus method. For a detailed explanation of this parameter, see Asynchronous Methods. CIMOM only calls AddRef on the pointer in cases where WBEM_NO_ERROR is returned. In cases where an error code is returned, the reference count is the same as on entry.

Return Values

WBEM_E_FAILED | Other unspecified failures.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the current process and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

All other return codes are provided to the object sink specified by the pReponseHandler parameter through the SetStatus method. Error conditions, such as when the class does not exist or the user does not have permission to delete classes, are reported to the handler. They are not reported in the return code of this method.

Remarks

If a dynamic instance provider is associated with the class, the provider is unregistered, and is no longer called for that class. Any classes that derive from the deleted class are also deleted, and their associated providers become unregistered. All outstanding static instances of the specified class and its subclasses are also deleted when the class is deleted.

If the class is provided by a dynamic class provider, the success of the deletion depends on whether class deletion is supported by that provider.

Note Standard system classes cannot be deleted.

See Also

Asynchronous Methods, IWbemServices::DeleteClass


IWbemServices::CreateClassEnum

The IWbemServices::CreateClassEnum method returns an enumerator for all classes satisfying the selection criteria.

The caller must then use the returned enumerator to retrieve the class definitions, calling IEnumWbemClassObject::Next to obtain each class or blocks of classes. It finishes by calling IEnumWbemClassObject::Release.

Note that it is not an error for the returned enumerator to have zero elements.

HRESULT IWbemServices::CreateClassEnum(
  [in] BSTR bstrSuperclass,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [out] IEnumWbemClassObject **ppEnum
);

Parameters

bstrSuperclass
If not NULL or blank, specifies a superclass name. Only classes that are subclasses of this class are returned in the enumerator. If it is NULL or blank, and lFlags is WBEM_FLAG_SHALLOW, only the top-level classes, that is, classes that have no parent class or superclass, are returned. If NULL or blank and lFlags is WBEM_FLAG_DEEP, all classes within the namespace are returned.
lFlags
WBEM_FLAG_DEEP forces recursive enumeration into all subclasses derived from the specified superclass. The superclass itself is not returned in the enumeration. WBEM_FLAG_SHALLOW forces the enumeration to include only immediate subclasses of the specified superclass.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppEnum
Receives the pointer to the enumerator. The returned object has a positive reference count. The caller must call Release on the pointer when it is no longer required.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to view one or more of the classes that the call can return.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_CLASS | The specified class did not exist.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | A communications failure occurred between CIMOM and the client.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Error Objects, IWbemServices::CreateClassEnumAsync, IEnumWbemClassObject


IWbemServices::CreateClassEnumAsync

The IWbemServices::CreateClassEnumAsync method performs the same function as IWbemServices::CreateClassEnum except that the objects are returned to the specified IWbemObjectSink implementation instead of to an enumerator.

In cases where the call succeeds, CIMOM calls AddRef on the pointer pResponseHandler, and then returns immediately. It then asynchronously calls pResponseHandler – >Notify from another thread with class definitions until the query has been satisfied.

HRESULT IWbemServices::CreateClassEnumAsync(
  [in] BSTR bstrSuperclass,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in]CALLBACK *pResponseHandler
);

Parameters

bstrSuperclass
If not NULL or blank, this parameter specifies a superclass name. Only classes that are subclasses of this class are returned in the enumerator. If NULL or blank, and lFlags is WBEM_FLAG_SHALLOW, only top-level classes, those which have no parent class or superclass, are returned. If NULL or blank and lFlags is WBEM_FLAG_DEEP, all classes within the namespace are returned.
lFlags
WBEM_FLAG_DEEP forces recursive enumeration into all subclasses derived from the specified superclass. The superclass itself is not returned in the enumeration.

WBEM_FLAG_SHALLOW forces the enumeration to include only immediate subclasses of the specified superclass.

Note If bstrSuperclass is NULL or blank and WBEM_FLAG_DEEP is specified, all classes are returned.

pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
Points to the caller's implementation of IWbemObjectSink. This handler receives the objects as they become available using the IWbemObjectSink::Indicate method. When no more objects are available, the IWbemObjectSink::SetStatus method is called by CIMOM. For a detailed explanation of this parameter, see Asynchronous Methods. CIMOM only calls AddRef on the pointer in cases where WBEM_NO_ERROR is returned. In cases where an error code is returned, the reference count is the same as on entry.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | A communications failure has occurred between the client process and CIMOM.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain available information from the COM function GetErrorInfo.

See Also

Asynchronous Methods, IWbemServices::CreateClassEnum, IWbemObjectSink


IWbemServices::PutInstance

The IWbemServices::PutInstance method creates or updates an instance of a class object to CIMOM.

HRESULT IWbemServices::PutInstance(
  [in] IWbemClassObject *pInst,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [out, OPTIONAL] IWbemCallResult **ppCallResult
);

Parameters

pInst
Points to the instance to be written to the database. The caller cannot make assumptions about the reference count at the completion of this call. The operating system can call AddRef to the pointer, or leave the reference count unchanged.
lFlags
If WBEM_FLAG_CREATE_OR_UPDATE, the instance is created if it does not exist, or it is overwritten if it exists already. If WBEM_FLAG_UPDATE_ONLY, then the instance must exist, and this call constitutes an update. If WBEM_FLAG_CREATE_ONLY, then this call is for creation only, and the call fails if the instance already exists.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppCallResult
If NULL, this is not used. If not NULL, call returns immediately with WBEM_NO_ERROR. An object of type IWbemCallResult is then returned. It can be polled for the result of the operation through the IWbemCallResult::GetCallStatus method. The IWbemCallResult::GetResultString contains the object path assigned to the object. When the returned object is no longer required, it must be deallocated using Release .

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to update an instance of the specified class.
WBEM_E_ALREADY_EXISTS | WBEM_FLAG_CREATE_ONLY flag was specified, but the instance already exists.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_ILLEGAL_NULL | A NULL value was specified for a property that may not be NULL, such as one that is marked by a key, indexed, or not_null qualifier.
WBEM_E_INVALID_OBJECT | The specified instance is invalid (for example, PutInstance with a Class will invoke this return).
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_NOT_FOUND | WBEM_FLAG_UPDATE_ONLY flag was specified, but the instance does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the client and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

See Also

IWbemCallResult, IWbemServices::PutInstanceAsync, Instance Creation and Modification Rules


IWbemServices::PutInstanceAsync

The IWbemServices::PutInstanceAsync method performs the same task as IWbemServices::PutInstance except that the call returns immediately, and update confirmation or error reporting is provided to the specified response handler.

HRESULT IWbemServices::PutInstanceAsync(
  [in] IWbemClassObject pInst,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] CALLBACK *pResponseHandler
);

Parameters

pInst
Points to the instance to be written to the database. The caller cannot make assumptions about the reference count at the completion of this call. The operating system can either call AddRef to the pointer, or it can leave the reference count unchanged.
lFlags
If WBEM_FLAG_CREATE_OR_UPDATE, the instance is created if it does not exist, or it is overwritten if it exists already. If WBEM_FLAG_UPDATE_ONLY, then the instance must exist, and this call constitutes an update. If WBEM_FLAG_CREATE_ONLY, then this call is for creation only,and the call fails if the instance already exists.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
Points to the caller's implementation of IWbemObjectSink. This handler receives the status of the IWbemClassObject::Put operation when it becomes available using the IWbemObjectSink::SetStatus method.

For a detailed explanation of this parameter, see Asynchronous Methods. CIMOM only calls AddRef on the pointer in cases where WBEM_NO_ERROR is returned. In cases where an error code is returned, the reference count is the same as on entry.

Return Values

WBEM_E_ALREADY_EXISTS | WBEM_FLAG_CREATE_ONLY flag was specified, but the instance already exists.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_ILLEGAL_NULL | A NULL value was specified for a property that is not NULL, such as one marked by a key, indexed, or not_null qualifier.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_NOT_FOUND | WBEM_FLAG_UPDATE_ONLY flag was specified, but the instance does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_RPC_FAILURE | The RPC link between the client and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

See Also

Asynchronous Methods, IWbemContext, IWbemServices::PutInstance, Instance Creation and Modification Rules


IWbemServices::DeleteInstance

The IWbemServices::DeleteInstance method deletes the instance specified in the object path. Only instances in the current namespace can be deleted.

If the instance was supplied by a dynamic provider, it is sometimes not possible to delete the instance unless the provider supports instance deletion.

HRESULT IWbemServices::DeleteInstance(
  [in] BSTR bstrObjectPath,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [out, OPTIONAL] IWbemCallResult **ppCallResult
);

Parameters

bstrObjectPath
A valid BSTR containing the object path to the object to be deleted.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppCallResult
If NULL, this parameter is not used. If ppCallResult is specified it must be set to point to NULL on entry. In this case, the call returns immediately with WBEM_NO_ERROR. ppCallResult receives a pointer to a new IWbemCallResult object, which must then be polled to obtain the result using the GetCallStatus method.

Return Values

WBEM_E_ACCESS_DENIED | The current context does not have adequate rights to delete the object.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_CLASS | The specified class does not exist.
WBEM_E_INVALID_OPERATION | The object cannot be deleted.
WBEM_E_NOT_FOUND | The object did not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between CIMOM and the client has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Error Objects, IWbemCallResult, IWbemServices::DeleteInstanceAsync, Object Paths


IWbemServices::DeleteInstanceAsync

The IWbemServices::DeleteInstanceAsync method performs the same function as IWbemServices::DeleteInstance except that the call returns immediately, and the confirmation or failure of the operation is asynchronously reported to the supplied object sink through the IWbemObjectSink::SetStatus method.

If the instance was supplied by a dynamic provider, it is sometimes not possible to delete the instance unless the provider supports instance deletion.

HRESULT IWbemServices::DeleteInstanceAsync(
  [in] BSTR bstrObjectPath,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] CALLBACK *pResponseHandler
);

Parameters

bstrObjectPath
A valid BSTR containing the object path of the object to be deleted.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
Points to the caller's implementation of IWbemObjectSink. This handler receives the status of the delete operation as it becomes available through the SetStatus method. For a detailed explanation of this parameter, see Asynchronous Methods. CIMOM only calls AddRef on the pointer in cases where WBEM_NO_ERROR is returned. In cases where an error code is returned, the reference count is the same as on entry.

Return Values

WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The remote link between the client and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

Other error conditions are reported asynchronously to the object sink supplied by the pResponseHandler parameter.

See Also

Asynchronous Methods, IWbemServices::DeleteInstance, Object Paths


IWbemServices::CreateInstanceEnum

The IWbemServices::CreateInstanceEnum method creates an enumerator that returns the instances of a specified class according to user-specified selection criteria. This method implements a simple query. More complex queries may require the use of IWbemServices::ExecQuery.

Note that it is not an error for the returned enumerator to have zero elements

HRESULT IWbemServices::CreateInstanceEnum(
  [in] BSTR bstrClass,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [out] IEnumWbemClassObject **ppEnum
);

Parameters

bstrClass
A valid BSTR containing the name of the class for which instances are desired. This parameter cannot be NULL.
lFlags
WBEM_FLAG_DEEP forces recursive enumeration into all subclasses derived from the specified class. Instances of Class as well as those of its derived classes are returned. WBEM_FLAG_SHALLOW forces the enumeration to include only instances of the specified class.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppEnum
Receives the pointer to the enumerator, which has a positive reference count. The caller must use Release on the pointer after it is no longer required.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to view instances of the specified class.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_CLASS | The specified class is invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between CIMOM and the client has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Error Objects, IWbemServices::CreateInstanceEnumAsync


IWbemServices::CreateInstanceEnumAsync

The IWbemServices::CreateInstanceEnumAsync method performs the same task as IWbemServices::CreateInstanceEnum except that the call returns immediately, and the instances are asynchronously provided to the specified response handler.

HRESULT IWbemServices::CreateInstanceEnumAsync(
  [in] BSTR bstrClass,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] CALLBACK *pResponseHandler
);

Parameters

bstrClass
A valid BSTR containing the name of the class for which instances are desired. This parameter cannot be NULL.
lFlags
When set to zero, WBEM_FLAG_DEEP forces recursive enumeration into all subclasses derived from the specified class. Instances of Class as well as those of its derived classes are returned. WBEM_FLAG_SHALLOW forces the enumeration to include only instances of the specified class.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
Points to the caller's implementation of IWbemObjectSink. This handler receives the objects as they become available. For a detailed explanation of this parameter, see Asynchronous Methods. CIMOM only calls AddRef on the pointer in cases where WBEM_NO_ERROR is returned. In cases where an error code is returned, the reference count is the same as on entry.

Return Values

WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_RPC_FAILURE | The RPC link between the client and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain additional information from the COM function GetErrorInfo.

See Also

Asynchronous Methods, IWbemServices::CreateInstanceEnum


IWbemServices::ExecQuery

The IWbemServices::ExecQuery method executes a query to retrieve objects, which are available through the returned enumerator. All query results are returned through the enumerator as IEnumWbemClassObject.

For the valid types of queries that can be performed, see Queries.

HRESULT IWbemServices::ExecQuery(
  [in] BSTR bstrQueryLanguage,
  [in] BSTR bstrQuery,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [out] IEnumWbemClassObject **ppEnum
);

Parameters

bstrQueryLanguage
A valid BSTR containing one of the query languages supported by CIMOM. This must be the "WQL," the acronym for WBEM Query Language.
bstrQuery
A valid BSTR containing the text of the query. This cannot be NULL.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.

If the query is very broad and involves many instance providers, it is not practical to include enough context information for all providers. In these cases, the parameter should be NULL.

ppEnum
If no error occurs, this receives the enumerator that allows the caller to retrieve the instances in the result set of the query. It is not an error for the query to have a result set with zero instances. This be determined only by attempting to iterate through the instances. This object is returned with a positive reference count. The caller must call Release when the object is no longer needed.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to view the result set.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_QUERY | The query was not syntactically valid.
WBEM_E_INVALID_QUERY_LANGUAGE | The requested query language is not supported.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the client and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Error Objects, IWbemServices::ExecQueryAsync, Queries


IWbemServices::ExecQueryAsync

The IWbemServices::ExecQueryAsync method performs the same task as IWbemServices::ExecQuery except that the result set is supplied to the specified response handler.

For the valid types of queries that can be performed, see Queries.

HRESULT IWbemServices::ExecQueryAsync(
  [in] BSTR bstrQueryLanguage,
  [in] BSTR bstrQuery,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] CALLBACK *pResponseHandler
);

Parameters

bstrQueryLanguage
A valid BSTR containing one of the query languages supported by CIMOM. This must be WQL.
bstrQuery
A valid BSTR containing the text of the query. This cannot be NULL.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.

If the query is very broad and involves many instance providers, it is not practical to include enough context information for all providers. In these cases, it is recommended that the parameter be NULL.

pResponseHandler
Points to the caller's implementation of IWbemObjectSink. This handler receives the objects in the query result set as they become available. CIMOM calls IWbemObjectSink::Indicate with the objects any number of times, followed by a single call to IWbemObjectSink::SetStatus to indicate the final status.

For a detailed explanation of this parameter, see Asynchronous Methods.

CIMOM only calls AddRef to the pointer in cases where WBEM_NO_ERROR is returned. In cases where an error code is returned, the reference count is the same as on entry.

Return Values

WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the client and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

Other error codes are returned to the object sink specified by the pResponseHandler parameter.

See Also

Asynchronous Methods, IWbemServices::ExecQuery, Queries


IWbemServices::ExecNotificationQuery

The IWbemServices::ExecNotificationQuery method executes a query to receive events. The call returns immediately, and the user can poll the returned enumerator for events as they arrive. Releasing the returned enumerator cancels the query.

HRESULT IWbemServices::ExecNotificationQuery(
  [in] BSTR bstrQueryLanguage,
  [in] BSTR bstrQuery,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [out] IEnumWbemClassObject **ppEnum
);

Parameters

bstrQueryLanguage
A valid BSTR containing one of the query languages supported by CIMOM. This cannot be NULL. Currently, only the WBEM Query Language (WQL) is supported.
bstrQuery
A valid BSTR containing the text of the event-related query. This cannot be NULL.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppEnum
If no error occurs, this receives the enumerator that allows the caller to retrieve the instances in the result set of the query. The caller periodically calls IEnumWbemClassObject::Next to see if any events are available. Notice that in this usage, Reset does not move the enumerator back to the beginning of the event sequence; it has no effect. The parameter can continue to receive events until Release is called on the returned enumerator.

Return Values

WBEM_E_ACCESS_DENIED | The current user is not authorized to view the result set.
WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_QUERY | The query was not syntactically valid.
WBEM_E_INVALID_QUERY_LANGUAGE | The requested query language is not supported.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the client and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Error Objects, IWbemServices::ExecNotificationQueryAsync, Queries


IWbemServices::ExecNotificationQueryAsync

The IWbemServices::ExecNotificationQueryAsync method performs the same task as IWbemServices::ExecNotificationQuery except that events are supplied to the specified response handler until CancelAsyncCall is called to stop the event notification.

HRESULT IWbemServices::ExecNotificationQueryAsync(
  [in] BSTR bstrQueryLanguage,
  [in] BSTR bstrQuery,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] CALLBACK *pResponseHandler
);

Parameters

bstrQueryLanguage
A valid BSTR containing one of the query languages supported by CIMOM. This must be WQL.
bstrQuery
A valid BSTR containing the text of the event-related query. This cannot be NULL.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
Points to a the caller's implementation of IWbemObjectSink. This handler receives the objects in the query result set as they become available. To cease receiving events, the caller must call IWbemServices::CancelAsyncCall using the same pointer value for pResponseHandler.

For a detailed explanation of this parameter, see Asynchronous Methods.

CIMOM only calls AddRef on the pointer in cases where WBEM_NO_ERROR is returned. In cases where an error code is returned, the reference count is the same as on entry.

Return Values

WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the client and CIMOM has failed.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

Other error codes are returned to the object sink specified by the pResponseHandler parameter.

See Also

Asynchronous Methods, IWbemServices::ExecQuery, Queries


IWbemServices::ExecMethod

The IWbemServices::ExecMethod method executes a method exported by a CIM object. The method call is forwarded to the appropriate provider where it executes, and information and status are returned to the caller, which blocks until the circuit is complete.

Methods are not directly implemented by CIMOM, but are exported by method providers. For any given CIM class, the available methods and their parameters must be specified in the documentation for the provider in question.

HRESULT IWbemServices::ExecMethod(
  [in] BSTR bstrObjectPath,
  [in] BSTR MethodName,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] IWbemClassObject *pInParams,
  [out, OPTIONAL] IWbemClassObject **ppOutParams,
  [out, OPTIONAL] IWbemCallResult **ppCallResult
);

Parameters

bstrObjectPath
A valid BSTR containing the object path of the object for which the method is executed.
MethodName
The name of the method for the object.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pInParams
May be NULL if no inbound parameters are required to execute the method. Otherwise, this points to an IWbemClassObject that contains the properties acting as inbound parameters for the method execution. The contents of the object are method-specific, and are part of the specification for the provider in question.
ppOutParams
If not NULL, receives a pointer to the outbound parameters and return values for the method execution. The contents of this object are method-specific, and are part of the specification for the provider in question. The caller must call Release on the returned object when it is no longer required.
ppCallResult
If NULL, this is not used. If ppCallResult is specified it must be set to point to NULL on entry. In this case, the call returns immediately with WBEM_NO_ERROR. ppCallResult receives a pointer to a new IWbemCallResult object, which must be polled to obtain the result of the method execution using the GetCallStatus method. The out-parameters for the call are available by calling IWbemCallResult::GetResultObject

Return Values

WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the client and CIMOM has failed.
WBEM_E_INVALID_METHOD | The requested method was not available.
WBEM_E_ACCESS_DENIED | The current user was not authorized to execute the method.
WBEM_E_INVALID_METHOD_PARAMETERS | The supplied pInParams object was determined by the provider to be invalid.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

IWbemServices::ExecMethodAsync, IWbemCallResult::GetResultObject


IWbemServices::ExecMethodAsync

The IWbemServices::ExecMethodAsync method asynchronously executes a method exported by a CIM object. The call immediately returns to the client while the inbound parameters are forwarded to the appropriate provider where it executes. Information and status are returned to the caller through the supplied object sink.

Methods are not directly implemented by CIMOM, but are exported by method providers. For any given CIM class, the available methods and their parameters are part of the documentation for the provider in question.

HRESULT IWbemServices::ExecMethodAsync(
  [in] BSTR bstrObjectPath,
  [in] BSTR bstrMethodName,
  [in] LONG lFlags,
  [in] IWbemContext *pCtx,
  [in] IWbemClassObject *pInParams,
  [in] CALLBACK *pResponseHandler
);

Parameters

bstrObjectPath
A valid BSTR containing the object path of the object for which the method is to be executed.
bstrMethodName
The name of the method for the object.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pInParams
Can be NULL if no inbound parameters are required to execute the method. Otherwise, this points to an IWbemClassObject that contains the properties acting as inbound parameters for the method execution. The contents of the object are method-specific, and are part of the specification for the provider in question.
pResponseHandler
Must not be NULL. The object sink receives the result of the method call. The outbound parameters are sent to IWbemObjectSink::Indicate .The result of the call mechanism itself will be sent to IWbemObjectSink::SetStatus. Notice that IWbemObjectSink::SetStatus does not receive the return code of the CIM method. However, it receives the return code of the actual call-return mechanism, and is only useful for verifying that the call occurred or that it failed for mechanical reasons. The result code returned from the CIM method is returned in the outbound parameter object supplied to IWbemObjectSink::Indicate.

Return Values

WBEM_E_FAILED | Other unspecified errors.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | The communications link between the client and CIMOM has failed.
WBEM_E_ACCESS_DENIED | The current user was not authorized to execute the method.
WBEM_NO_ERROR | The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

Other errors will be reported asynchronously to the object sink supplied in the pReponseHandler parameter

See Also

IWbemServices::ExecMethod


IWbemUnboundObjectSink

This interface is implemented by all logical event consumers.

Methods in Vtable Order

Iunknown Methods | Properties
QueryInterface | Determines if the current object supports a given interface.
AddRef | Increases the object's reference count by 1.
Release | Decrements the object's reference count, and frees the object when the reference count is zero.

IWbemUnboundObjectSink Methods | Properties
IndicateToConsumer | TBD


IWbemUnboundObjectSink::QueryInterface

The IWbemUnboundObjectSink::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.

HRESULT IWbemUnboundObjectSink::QueryInterface(
  [in] REFIID riid,
  [out] LPVOID *ppv
);

Parameters

riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.

Return Values

Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.

Remarks

When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemUnboundObjectSink::AddRef

The IWbemUnboundObjectSink::AddRef method increases the object's reference count by 1.

ULONG AddRef( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see Using the IUnknown Interface.

For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemUnboundObjectSink::Release

The IWbemUnboundObjectSink::Release method decreases the object's reference count by 1.

ULONG IWbemUnboundObjectSink::Release( );

Parameters

None.

Return Values

Returns the new reference count.

Remarks

The object deallocates itself when its reference count reaches zero. Use the AddRef method to increase the object's reference count by 1.

This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.

See Also

Using the IUnknown Interface


IWbemUnboundObjectSink::IndicateToConsumer

TBD

HRESULT IWbemUnboundObjectSink::IndicateToConsumer(
  [in] IWbemClassObject *pLogicalConsumer,
  [in] LONG lNumObjects,
  [in, size_is(lNumObjects)] IWbemClassObject **ppObjects
);

Parameters

pLogicalConsumer
A pointer to the logical consumer object for which this set of objects is delivered.
lNumObjects
The number of objects delivered in the array that follows.
ppObjects
A pointer to an array of IWbemClassObject instances which represent the events delivered.

Return Values

WBEM_NO_ERROR The implementation should always return this.

Remarks

See Also

TBD


Visual Basic APIs

The Common Information Model Object Manager (CIMOM) programmer's reference for Microsoft® Visual Basic® contains dispatch interface definitions for the type library DWbemServices in the file Wbemdisp.tlb. Dispatch interfaces contain methods that allow users of Visual Basic version 5.0 and Visual Basic for Applications (VBA) to develop applications to access CIMOM services. Dispatch interfaces differ from standard interfaces in that they accept arguments of Visual Basic data types. WBEM supports only Visual Basic version 5.0, which in turn supports only DWbemServices for. . .

DIEnumWbemClassObject | This dispatch interface is an enumerator that works with objects of type DWbemClassObject. It is similar to standard COM enumerators such as IEnumVariant.
DIWbemCallResult | This dispatch interface is used to determine the status of semisynchronous calls to DIWbemservices calls.
DWbemClassObject | This interface contains and manipulates both class definitions and class object instances. Users do not implement this interface; the implementation is provided.
DWbemContext | This dispatch interface is optionally used to communicate additional information to providers when submitting DError! Bookmark not defined. calls to CIMOM
DWbemLocator | This dispatch interface obtains an object that is used to access CIMOM on a particular host machine.
DIWbemObjectSink | This is a sink interface used for all types of notifications within the programming model. Clients implement this interface to receive notifications and results of asynchronous call.
DIWbemQualifierSet | This interface enables WBEM clients to read or modify qualifiers on properties or entire objects. Users do not implement this interface; the implementation is provided.
DIWbemServices | This is the primary CIMOM interface. It provides management services to client processes and to other providers.


Visual Basic APIs

The Common Information Model Object Manager (CIMOM) programmer's reference for Microsoft® Visual Basic® contains dispatch interface definitions for the type library DWbemServices in the file wbemdisp.tlb. Dispatch interfaces contain methods that allow users of Visual Basic 5.0 and Visual Basic for Applications to develop applications that access CIMOM services. Dispatch interfaces differ from standard interfaces in that they accept arguments of Visual Basic data types. DWbemServices is the only type library that is supported for VB 5.0 developers. Moreover, VB 5.0 is the only version of Visual Basic that is supported for Web-Based Enterprise Management (WBEM).

DIEnumWbemClassObject | This dispatch interface is an enumerator that works with objects of type DWbemClassObject. It is similar to standard Component Object Model (COM) enumerators such as IEnumVariant.
DIWbemCallResult | This dispatch interface determines the status of semisynchronous calls to DIWbemservices
DWbemClassObject | This interface contains and manipulates both class definitions and class object instances.
DWbemContext | This dispatch interface is used as an option to communicate additional information to providers when you submit calls to CIMOM.
DWbemLocator | This dispatch interface obtains an object that is used to access CIMOM on a particular host machine.
DIWbemObjectSink | This is a sink interface used for all types of notifications within the programming model. Clients implement this interface to receive notifications and asynchronous call results.
DIWbemQualifierSet | This interface enables WBEM clients to read or modify qualifiers on properties or entire objects.
DIWbemServices | This is the primary CIMOM interface. It provides management services to client processes and to other providers.


DIEnumWbemClassObject

The DIEnumWbemClassObject interface resembles a standard Component Object Model (COM) enumerator. This interface works with objects of type DWbemClassObject. However, it differs in that it supports asynchronous and semisynchronous methods. The enumerator is a logical container of CIM objects, and is designed for sequential retrieval. Objects are retrieved from the enumerator sequentially with the Next method and the current position or cursor is updated so that subsequent calls to Next will retrieve the subsequent objects. When the last object has been retrieved the Reset method can be used to set the cursor back to the beginning of the enumeration.

Methods

Clone | Makes a logical copy of the enumerator.
Next | Retrieves the next object in the enumeration, starting from the current position.
NextAsync | Retrieves the next object or objects using asynchronous integration with DIWbemObjectSink .
Reset | Resets the cursor position to zero so you can repeat the enumeration.
Skip | Skips over the object or objects, resulting in a new cursor position.


DIEnumWbemClassObject.Clone

The DIEnumWbemClassObject.Clone method makes a logical copy of the entire enumerator. It retains its current cursor position.

Note You cannot clone any pending asynchronous deliveries begun by DIEnumWbemClassObject.NextAsync_hmm_DIEnumWbemClassObject.NextAsync.

Clone(
  [out] ppEnum As Object
) As Long

Parameters

ppEnum
DWbemClassObject object that will contain the cloned copy.

Return Values

WBEM_NO_ERROR | The call succeeded, and the enumerator has been cloned.
WBEM_S_FALSE | The call failed, and no enumerator has been returned.

For more information on return values see Visual Basic error handeling and return values

Sample Code

Function CloneEnum(pSrc  As DIEnumWbemClassObject)  As Boolean

    Dim pCopy As DIEnumWbemClassObject
    Dim Hres As Long '
    hRes = pSrc.Clone(pCopy)

    if (hRes <> WBEM_NO_ERROR) Then      ' Failed to clone it
        CloneEnum =FALSE
    Endif
    ' Use the copy of the enumerator
    ' ...
    Set pCopy = Nothing
    CloneEnum = TRUE

End Function


DIEnumWbemClassObject.Next

The DIEnumWbemClassObject.Next method returns the next object, starting at the current cursor position. It then advances the cursor position by one object. Subsequent calls return the subsequent objects.

Next(
  [in] lTimeOut As Long,
  [out] ppObject As Object

) As Long

Parameters

lTimeout
Specifies the maximum time in milliseconds to wait until objects are available. If you use the value WBEM_INFINITE, this call will block until objects are available. If you use the value zero, the call immediately returns with whatever objects are waiting.
ppObject
DWbemClassObject type object. Serves as a container for returned object.

Return Values

WBEM_NO_ERROR | The number of objects returned was the same as the number requested.
WBEM_S_FALSE | No more objects are available.
WBEM_S_TIMEDOUT | A timeout occurred before all the objects could be obtained.

Remarks

For more information on return values see Visual Basic error handeling and return values.

In the following sample, objects are requested only one at a time. Because WBEM_S_FALSE is returned when there are no more objects available, you should check the return code for WBEM_NO_ERROR after retrieving each object

Sample Code

sub ListObjects(pEnum As DIEnumWbemClassObject)

    pEnum.Reset

    Dim pObject As DWbemClassObject
    Dim uReturned As Long

    While (pEnum.Next(WBEM_INFINITE, pObject) = WBEM_NO_ERROR)

        pObject.… ' Access DWbemClassObject methods
        Set pObject = Nothing
    Wend
End Sub


DIEnumWbemClassObject.NextAsync

When you need a controlled asynchronous retrieval of objects to a sink, use the DIEnumWbemClassObject.NextAsync method. Normal asynchronous retrieval, such as a call to DIWbemServices.ExecQueryAsync, causes an uncontrolled delivery of objects to the caller's implementation of DIWbemObjectSink. This method is helpful in situations where components can only handle a reduced rate of delivery.

NextAsync(
  [in] uCount As Long,
  [in] pSink As Object
) As Long

Parameters

uCount
The number of objects requested.
pSink
DWbemClassObject type object The sink to receive the objects. The caller must implement the sink.

Return Values

WBEM_NO_ERROR | The call succeeded. The system begins delivery of objects to the sink.
WBEM_S_FALSE | The call failed, and no objects will be delivered to the sink.

Remarks

This call returns immediately, and delivery to the sink occurs in the background. If a call to Reset. it will not affect the ongoing delivery of objects as a result of previous calls but will cause new calls to start at the beginning of the object sequence.

Call the DIWbemobjectSink.SetStatus method to indicate the actual result of your request. As the objects become available, you can call DIWbemObjectSink.Indicate zero or more times to deliver the objects. After that, if uCount items return, call DIWbemObjectSink.SetStatus with a value of WBEM_NO_ERROR.

If fewer objects are available than the number requested, call DIWbemObjectSink.Indicate for whatever objects are available. After that, call DIWbemObjectSink.SetStatus with a value of WBEM_S_FALSE or the error code if there is an error. If no objects are available, do not call Indicate.

Sample Code

Sub ListObjects3(pEnum As DIEnumWbemClassObject , pSink As DIWbemObjectSink)
    Dim hRes As Long
    Dim bContinue As Boolean

    while (TRUE)

        hRes = pEnum.NextAsync(5, pSink)

            ' Wait until sink is ready for more by
            ' some private mechanism. Note that hRes gives
            ' no indication as to whether to continue the
            ' enumeration or not.

            bContinue = WaitUntilMoreObjectsNeeded()

            if  (bContinue <> True) Then
                Exit Sub
            Endif
    Wend
 End Sub


DIEnumWbemClassObject.Reset

The DIEnumWbemClassObject.Reset method resets the current position of the enumerator back to the beginning of the enumeration. Since CIM objects are dynamic, calling this method does not necessarily give you the same list of objects that may have been obtained previously.

Reset( ) As Long

Parameters

None.

Return Values

WBEM_NO_ERROR | Success.
WBEM_S_FALSE | Failure.

For more information on return values see Visual Basic error handeling and return values.


DIEnumWbemClassObject.Skip

Use the DIEnumWbemClassObject.Skip method to move the current cursor position ahead by a specified number of objects. This also affects subsequent calls to NextAsync , but it does not affect pending deliveries begun with NextAsync.

Skip(
  [in] lTimeOut As Long,
  [in] nCount As Long
) As Long

Parameters

lTimeout
Specifies the maximum time in milliseconds to wait for the Skip operation to succeed. If you use the value WBEM_INFINITE, this call will block until the operation is successful. If you use the value zero, the call immediately returns the value WBEM_NO_ERROR if the operation was a success or WBEM_S_FALSE. indicating that was a failure.
uCount
The number of objects to skip.

Return Values

WBEM_NO_ERROR | The call succeeded, and the cursor position has been updated.
WBEM_S_FALSE | The call failed, and the cursor position is at its original position before the call.

For more information on return values see Visual Basic error handeling and return values.


DIWbemCallResult

Use the DIWbemCallResult interface for semisynchronous calls of the DIWbemServices interface. When you make such calls, the DIWbemServices method returns immediately, along with an DIWbemCallResult object. Periodically, you must poll the returned DIWbemCallResult object to determine the status of the call. When the call completes, this interface gives you the result of the original DIWbemServices call.

This call-return paradigm is useful where a thread cannot be blocked for more than a few seconds because it is servicing many other tasks, such as processing window messages.

Not all DIWbemServices methods support the DIWbemCallResult interface because this interface is not required for all of them. The intent is to allow nonblocking synchronous operation (semisynchronous operation) for all situations. Since many of the DIWbemServices methods are already nonblocking due to the use of enumerators or other constructs, only OpenNamespace, GetObject, PutInstance, DeleteClass, DeleteInstance, and ExecMethod need this helper interface to support semisynchronous operation.

Methods

GetCallStatus | Informs the user whether or not a semisynchronous call has completed.
GetResultObject | Returns an DWbemClassObject. This is the result of a semisynchronous call to DIWbemServices.GetObject.
GetResultServices | Returns the result of a semisynchronous call to DIWbemServices.OpenNamespace verb action.
GetResultString | Returns an Object Path. This is the result of a semisynchronous call to DIWbemServices.PutInstance.


DIWbemCallResult.GetCallStatus

The DIWbemCallResult.GetCallStatus method gives you the status of the current outstanding semisynchronous call. When this call returns WBEM_NO_ERROR, you know the original call to the DIWbemServices method is complete.

GetCallStatus(
  [in] lTimeout As Long,
  [out] plStatus As Long
) As Long

Parameters

lTimeout
Specifies the maximum time in milliseconds to wait for the call to return. If you use the value WBEM_INFINITE, this call will block until the original semisynchronous call to an DIWbemServices method is complete. If you use zero, the call immediately returns the call status.
plStatus
If the GetCallStatus call returns WBEM_NO_ERROR, this parameter receives the result of the original semisynchronous call to one of the DIWbemServices methods. These methods are as follows: OpenNamespace, PutInstance, GetObject, DeleteInstance, DeleteClass, or ExecMethod. This method will also return any error codes that are returned if these methods are called syncronously. If GetCallStatus returns an error, plStatus will be ignored.

Return Values

WBEM_NO_ERROR | The call has completed.
WBEM_S_PENDING | The call has not yet completed.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_FAILED | There is an unexpected system error.

For more information on return values see Visual Basic error handeling and return values

Remarks

After invoking an DIWbemServices method semisynchronously, you can call GetCallStatus at any time to see if the call has completed. After GetCallStatus has returned, you may have to make calls to other DIWbemCallResult methods to retrieve the result of the call, according to the following rules:

  1. For the DIWbemServices method OpenNamespace, you must call the GetResultServices method to retrieve the new DIWbemServices object.
  2. For the DIWbemServices method PutInstance, you must call the GetResultString method to retrieve the object path assigned to the object.
  3. For the DIWbemServices method GetObject, you must call the GetResultObject methodto retrieve the object.
  4. For the DIWbemServices methods DeleteInstance, DeleteClass, and ExecMethod, the GetCallStatus method is the only call that returns information regarding these operations.

See Also

DIWbemServices.OpenNamespace, DIWbemServices.PutInstance, DIWbemServices.GetObject, DIWbemServices.DeleteInstance, DIWbemServices.DeleteClass, DIWbemServices.ExecMethod


DIWbemCallResult.GetResultObject

The DIWbemCallResult.GetResultObject method returns the object. This results from a semisynchronous invocation of DIWbemServices.GetObject or DIWbemServices.ExecMethod. If the object is not yet available, the call returns WBEM_S_PENDING. Before invoking this method to get the object you want, you may also call DIWbemCallResult.GetCallStatus until it returns WBEM_NO_ERROR.

GetResultObject(
  [in] lTimeout AS Long ,
  [out] ppResultObject As Object
) As Long

Parameters

lTimeout
Specifies the maximum time in milliseconds to waitfor the call to return. If you use the value WBEM_INFINITE, the call will block until the object is available. If you use zero, the call immediately returns either the object or a status code.
ppResultObject
Object of type DWbemClassObject. This parameter cannot be NOTHING It receives the copy of the object when the object becomes available.

On error, a new object is not returned.

Return Values

WBEM_NO_ERROR | The object was returned successfully.
WBEM_S_PENDING | The object was not yet available after the lTimeout value expired.
WBEM_E_NOT_FOUND | The object did not exist.
WBEM_E_UNEXPECTED | The call failed, and is not expected to complete.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_ACCESS_DENIED | The caller attempted an unauthorized operation.

For more information on return values see Visual Basic error handeling and return values.

See Also

DIWbemServices.GetObject DIWbemServices.ExecMethod.


DIWbemCallResult.GetResultServices

Use the DIWbemCallResult.GetResultServices method to retrieve the DIWbemServices object that resulted from a semisynchronous call to DIWbemServices.OpenNamespace when the object becomes available.

GetResultServices(
  [in] lTimeout As Long,
  [out] ppServices As Object
) As Long

Parameters

lTimeout
Specifies the maximum time in milliseconds to waitfor the call to return. If you use the value WBEM_INFINITE, the call blocks until the interface is available. If you use zero, the call immediately returns either the object or a status code.
ppServices
This parameter cannot be NOTHING. It receives a DIWbemServices interface requested by the original call to OpenNamespace when the DIWbemServices object becomes available.

On error, a new object is not returned.

Return Values

WBEM_NO_ERROR | The call succeeded, and it returned an DIWbemServices Object.
WBEM_S_PENDING | The time-out occurred, and the call has not yet completed.
WBEM_E_UNEXPECTED | An internal failure occurred.
WBEM_E_ACCESS_DENIED | The user tried to perform an unauthorized operation.

For more information on return values see Visual Basic error handeling and return values

See Also

DIWbemServices.OpenNamespace


DIWbemCallResult.GetResultString

The DIWbemCallResult.GetResultString method returns the assigned object path of an instance newly created by DIWbemServices.PutInstance.

GetResultString(
  [in] lTimeout As Long,
  [out] pstrResultString As String
)long

Parameters

lTimeout
Specifies the maximum time in milliseconds to wait for the call to return. If you use the value WBEM_INFINITE, the call blocks until the object path is available. If you use zero, the call immediately returns either the object path or a status code.
pstrResultString
String containing the assigned object path of the newly created instance . On error, a new string is not returned.

Return Values

WBEM_NO_ERROR | The object path was retrieved.
WBEM_S_PENDING | The call has not yet completed.
WBEM_E_UNEXPECTED | An internal failure occurred.
WBEM_E_ACCESS_DENIED | The caller attempted an unauthorized operation.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.

For more information on return values see Visual Basic error handeling and return values

See Also

DIWbemServices.PutInstance


DWbemClassObject

The DWbemClassObject interface contains and manipulates class definitions and class object instances.

From the WBEM client perspective, this interface is always in-process. Put (write) operations only affect the local copy of the object, and Get (read) operations always retrieve values from the local copy. Updates to CIMOM are performed only when entire objects are read or written using methods on the DIWbemServices interface, such as DIWbemServices.PutInstance or DIWbemServices.PutClass.

Methods

BeginEnumeration | Begins an enumeration of all the properties.
Clone | Makes a copy of the current object.
CompareTo | Tests two objects for equality.
Delete | Removes the specified property from the object.
EndEnumeration | Ends an enumeration begun with BeginEnumeration.
Get | Gets a particular property value.
GetNames | Gets a list of the names of all the properties in the object.
GetObjectText | Gets the textual rendition of the object (MOF syntax).
GetPropertyOrigin | Reports the class in which a particular property was introduced.
GetPropertyQualifierSet | Allows access to the qualifiers of a particular property.
GetQualifierSet | Allows access to the qualifier set of the entire object.
InheritsFrom | Reports whether the current object inherits from a particular class.
Next | Gets the next property in an enumeration after an initial call to BeginEnumeration.
Put | Edits or creates a particular property value.
SpawnDerivedClass | Creates a new derived class from the current class.
SpawnInstance | Creates a new instance from the current class.


DWbemClassObject.BeginEnumeration

The DWbemClassObject.BeginEnumeration method resets the enumeration sequence of all the properties in the object. You must call this method before the first call to DWbemClassObject.Next to enumerate all of the properties on an object.

DWbemClassObject.BeginEnumeration(
  [in] lEnumFlags As Long
) As Long

Parameters

lEnumFlags
A combination of flags described in Remarks.

Return Values

WBEM_E_INVALID_PARAMETER | The specified combination of flags was invalid, an invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There is not enough memory to begin a new enumeration.
WBEM_NO_ERROR | Success.

Remarks

You can control the properties included in the enumeration by specifying a combination of the following flags. You can combine one flag from each group with any flag from any other group. However, flags from the same group are mutually exclusive.

GROUP 1

WBEM_FLAG_KEYS_ONLY
Only include properties that constitute the key.
WBEM_FLAG_REFS_ONLY
Only include properties that are object references.

GROUP 2

WBEM_FLAG_LOCAL_ONLY
Only include properties defined or modified in the class itself. Exclude all properties inherited from superclasses. Exclude system properties from the enumeration.
WBEM_FLAG_PROPAGATED_ONLY
Only include properties inherited from superclasses. Exclude properties defined or modified in the class itself. Exclude system properties from the enumeration.
WBEM_FLAG_SYSTEM_ONLY
Limit the enumeration to system properties only.
WBEM_FLAG_NONSYSTEM_ONLY
Exclude system properties from the enumeration. This includes local and propagated properties.

See Also

DWbemClassObject.Next, System Properties, DWbemClassObject.EndEnumeration


DWbemClassObject.Clone

The DWbemClassObject.Clone method returns a new object that is a clone of the current object.

DWbemClassObject.Clone(
  [out]  ppCopy As Object
) As Long

Parameters

ppCopy
Object of type DWbemClassObject . This parameter cannot be NOTHING. It receives the copy of the current object. On error, a new object is not returned.

Return Values

WBEM_E_FAILED | Unspecified error..
WBEM_E_INVALID_PARAMETER | NOTHING was specified as a parameter, and is not legal in this usage.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to clone the object.
WBEM_NO_ERROR | Success.

Remarks

Use this method to duplicate a class definition, or to duplicate an instance. This is useful when you need the original copy of the object for backup purposes while you are modifying a new copy. Likewise, you can use this method to create many new instances from a single source instance. For example, you can use DWbemClassObject.SpawnInstance to create a single starting instance, and use DWbemClassObject.Clone to produce 100 copies of the instance quickly. Subsequently, you can modify each object to have specific values.

Note It is not possible to use this method to convert a class definition into an instance, or to convert an instance into a class definition.


DWbemClassObject.CompareTo

The DWbemClassObject.CompareTo method compares an object to another CIMOM object. This comparison is subject to certain constraints.

DWbemClassObject.CompareTo(
  [in]  lFlags As Long,
  [in]  pCompareTo As Object
) As Long

Parameters

lFlags
Specifies the object characteristics to consider in comparison to other objects. You can use WBEM_COMPARISON_INCLUDE_ALL to consider all features, or any combination of these flags:
WBEM_FLAG_IGNORE_OBJECT_SOURCE
Ignores, in comparison to other objects, the source of the objects, namely the server and the namespace from which they came.
WBEM_FLAG_IGNORE_QUALIFIERS
During comparison, ignores all qualifiers (including "key" and "dynamic").
WBEM_FLAG_IGNORE_DEFAULT_VALUES
Ignores the default values of properties. This flag is meaningful only when comparing classes.
WBEM_FLAG_IGNORE_FLAVOR
Ignores qualifier flavors. This flag still takes qualifier values into account. However, it ignores flavor distinctions such as propagation rules and override restrictions (see Qualifier Flavors).
WBEM_FLAG_IGNORE_CASE
Compares strings in a case-insensitive manner. This applies both to strings and to qualifier values.

Note Property and qualifier names are always compared in a case-insensitive manner.

WBEM_FLAG_IGNORE_CLASS
Instructs the system to assume that the objects being compared are instances of the same class. Consequently, it compares instance-related information only. To optimize performance, you should use this flag. If the objects are not of the same class, the results are unpredictable, and most probably the results are worthless.
pCompareTo
Object of class DWbemClassObject. This is the object in comparison. The object must be a valid DWbemClassObject instance, and it cannot be NOTHING.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory available to complete the operation.
WBEM_S_DIFFERENT | The objects are different.
WBEM_S_SAME | The objects are the same, subject to comparison flags.

See Also

Qualifier Flavors


DWbemClassObject.Delete

The DWbemClassObject.Delete method deletes the specified property and all of its qualifiers. Delete operations for properties are possible only on class definitions, since instances cannot have contents that are different from the owning class.

It is not possible to delete a property that was inherited from a parent class. However, if you specified an override default value for a property inherited from a parent class, it is possible to revert to the parent's default value by invoking this method. In this case, WBEM_S_RESET_TO_DEFAULT is returned. You cannot delete System properties.

DWbemClassObject.Delete(
  [in] Name As String
) As Long

Parameters

Name
String containing the property name to delete.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid Name was specified.
WBEM_E_NOT_FOUND | The specified property does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_PROPAGATED_PROPERTY | The user tried to delete a property that was not owned. The property was inherited from a parent class.
WBEM_NO_ERROR | Success.
WBEM_S_RESET_TO_DEFAULT | The caller deleted an override default value for the current class. The default value for this property in the parent class has been reactivated.

See Also

System Properties


DWbemClassObject.EndEnumeration

The DWbemClassObject.EndEnumeration method stops an enumeration sequence started with DWbemClassObject.BeginEnumeration. This call is not required. However, we recommend it to developers because it releases resources associated with the enumeration. However, the resources are deallocated automatically when the next enumeration starts.

DWbemClassObject.EndEnumeration( ) As Long

Parameters

None.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_NO_ERROR | Success.

See Also

DWbemClassObject.BeginEnumeration, DWbemClassObject.Next


DWbemClassObject.Get

The DWbemClassObject.Get method retrieves the specified property value, if it exists. This method also can return system properties.

DWbemClassObject.Get(
  [in] Name As String,
  [in] lFlags As Long,
  [out, OPTIONAL] pVal  As VARIANT ,
  [out, OPTIONAL] pvtType  As VARIANT ,
  [out, OPTIONAL] plFlavor  As Long
) As Long

Parameters

Name
String containing the desired property name.
lFlags
Reserved. It must be zero.
pVal
Receives the returned property value, if found. The pVal parameter can be NULL if a property value is not required. If an error code is returned, the VARIANT in pVal is left unmodified.
pvtType
Can be NULL. If not NULL, receives the CIM type of the property.
plFlavor
Can be NULL. If not NULL, the Long value receives information on the origin of the property:
WBEM_FLAVOR_ORIGIN_LOCAL
The property belongs to the derived-most class.
WBEM_FLAVOR_ORIGIN_PROPAGATED
The property was inherited from a parent class.
WBEM_FLAVOR_ORIGIN_SYSTEM
The property is a standard system property.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_NOT_FOUND | The specified property was not found.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

Remarks

If the underlying type of the property is an object path, a date/time string, or another special type, the returned values do not contain enough information to identify the true type. In applications that are not aware of the true property type ahead of time, the CIMTYPE qualifier for the specified property must be retrieved using DWbemClassObject.GetPropertyQualifierSet.

It is important to note that when creating a new object using DWbemClassObject.SpawnInstance, some system properties are not set until the object has been written to CIMOM. In all cases, DWbemClassObject.Get returns the requested system property, but the return value can be NULL.

See Also

DWbemClassObject.GetPropertyQualifierSet, System Classes, Properties, and Qualifiers


DWbemClassObject.GetNames

The DWbemClassObject.GetNames method retrieves the names of all of the properties in the object. Depending on user-supplied selection criteria, furthermore, it can retrieve a subset of the properties. You can retrieve these properties by using DWbemClassObject.Get for each name. This method can also return system properties.

DWbemClassObject.GetNames(
  [in] QualifierName As String,
  [in] lFlags As Long,
  [in] pQualifierVal  As VARIANT,
  [out] pNames() As String
) As Long

Parameters

QualifierName
String containing a qualifier name.
lFlags
See Remarks.
pQualifierVal
Can be NULL. If not NULL, it must be a valid VARIANT.
pNames
An array of strings that contain the names of the properties in the object.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | One or more parameters were invalid, or an incorrect combination of flags and parameters was specified.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the task.
WBEM_NO_ERROR | Success.

Remarks

The names returned are controlled by a combination of flags and parameters. For example, all names of all properties can be specified, or only the key properties, and so on. The lFlags parameter specifies the primary filter, and the other parameters vary depending on the value of lFlags. For example, if WBEM_FLAG_ONLY_IF_IDENTICAL is specified then a value must be specified for QualifierName and pQualifierVal.

The flag values are bit fields, and can be combined. You can combine one flag from each of the following groups with a flag from each of the other groups. Flag values within a group are mutually exclusive.

GROUP 1

WBEM_FLAG_ALWAYS
Returns all property names. QualifierName and pQualifierVal are reserved.
WBEM_FLAG_ONLY_IF_TRUE
Returns only properties that have a qualifier of the name specified by the parameter QualifierName. If you use this flag, you must specify QualifierName.
WBEM_FLAG_ONLY_IF_FALSE
Returns only properties that do not have a qualifier of the name specified by the parameter QualifierName. If you use this flag, you must specify QualifierName.
WBEM_FLAG_ONLY_IF_IDENTICAL
Returns only properties that have a qualifier of the name specified by the parameter QualifierName and have a value identical to the value specified by the VARIANT in pQualifierVal. If you use this flag, you must specify both QualifierName and pQualifierVal.

GROUP 2

WBEM_FLAG_KEYS_ONLY
Returns only the names of the property or properties that define the keys.
WBEM_FLAG_REFS_ONLY
Returns only property names that are object references.

GROUP 3

WBEM_FLAG_LOCAL_ONLY
Returns only property names that belong to the derived-most class, excluding properties from the superclass or superclasses.
WBEM_FLAG_PROPAGATED_ONLY
Returns only property names that belong to the superclass or superclasses.
WBEM_FLAG_SYSTEM_ONLY
Returns only system properties.
WBEM_FLAG_NONSYSTEM_ONLY
Returns only property names that are not system properties.

It is not an error for an empty list, that is, an array of zero elements, to be returned in situations where no properties match the specified filters.

See Also

DWbemClassObject.Get, System Properties, DWbemClassObject.BeginEnumeration


DWbemClassObject.GetObjectText

The DWbemClassObject.GetObjectText method returns a textual rendering of the object. Currently, only the Managed Object Format (MOF) syntax is supported as an output format. Notice that the MOF text returned does not contain all the information about the object, but only enough information for the MOF compiler to be able to re-create the original object. For instance, you will not find any information about the propagated qualifiers or the parent class properties.

DWbemClassObject.GetObjectText(
  [in] lFlags As Long,
  [out] strObjectText As String
) As Long

Parameters

lFlags
Reserved. It must be set to zero.
strObjectText
Output string that the output text will be placed in.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

DIWbemQualifierSet


DWbemClassObject.GetPropertyOrigin

The DWbemClassObject.GetPropertyOrigin method gets the name of the class in which a particular property was introduced. For classes with deep inheritance hierarchies, it is often desirable to know which properties were declared in which classes. If the object does not inherit from a parent class, the current class name is always returned.

DWbemClassObject.GetPropertyOrigin(
  [in] Name  As String,
  [out] strClassName  As String
) As Long

Parameters

Name
The property name for which the parent class name is desired.
ClassName
String that will contain the name of the class in which a particular property was introduced.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_NOT_FOUND | The specified property does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

DWbemClassObject.InheritsFrom


DWbemClassObject.GetPropertyQualifierSet

The DWbemClassObject.GetPropertyQualifierSet method gets the qualifier set for a particular property in the class object.

DWbemClassObject.GetPropertyQualifierSet(
  [in] pProperty As String
  [out] ppQualSet As DIWbemQualifierSet
) As Long

Parameters

pProperty
The property for which the qualifier set is requested. The property can be local or propagated from the superclass. Note that system properties have no qualifiers, so they return WBEM_E_SYSTEM_PROPERTY.
PpQualSet
Receives an Object of type DIWbemQualifierSet.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_NOT_FOUND | The specified property does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_SYSTEM_PROPERTY | An attempt was made to get qualifiers on a system property.
WBEM_NO_ERROR | Success.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.

See Also

DIWbemQualifierSet


DWbemClassObject.GetQualifierSet

The DWbemClassObject.GetQualifierSet method receives an interface that allows read and write operations on the set of qualifiers for the entire class object, whether the object is an instance or a class definition.

DWbemClassObject.GetQualifierSet(
  [out]  ppQualSet  As Object
) As Long

Parameters

ppQualSet
Object of type DIWbemQualifierSet. On error, a new object is not returned.

Return Values

WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the call.
WBEM_NO_ERROR | Success.

See Also

DIWbemQualifierSet, DWbemClassObject.GetPropertyQualifierSet


DWbemClassObject.InheritsFrom

The DWbemClassObject.InheritsFrom method determines if the current class or instance derives from a specified parent class.

DWbemClassObject.InheritsFrom(
  [in] strAncestor  As String
) As Long

Parameters

strAncestor
String containing the class name that is being tested. If the current object has this class for one of its ancestor classes, WBEM_NO_ERROR is returned.

Return Values

WBEM_NO_ERROR | The current object inherits from the specified ancestor class.
WBEM_S_FALSE | The current object does not inherit from the specified ancestor class.
WBEM_E_INVALID_PARAMETER | The strAncestor parameter is vbNullString.

See Also

DWbemClassObject.GetPropertyOrigin


DWbemClassObject.Next

The DWbemClassObject.Next method retrieves the next property in an enumeration that was started with DWbemClassObject.BeginEnumeration. This should be called repeatedly to enumerate all the properties until WBEM_S_NO_MORE_DATA is returned. If the enumeration is to be terminated early, call DWbemClassObject.EndEnumeration.

The order of the properties returned during the enumeration is not defined.

DWbemClassObject.Next(
  [in] lFlags  As Long,
  [out, OPTIONAL] pName  As String,
  [out, OPTIONAL] pVal  As VARIANT,
  [out, OPTIONAL] pvtType  As Long,
  [out, OPTIONAL] plFlavor  As Long
) As Long

Parameters

lFlags
Reserved. It must be zero.
pName
A string that will contain the property name. It can be set to vbNullString if you do not need the name.
pVal
This VARIANT is filled with the value of the qualifier. It can be set to NULL if you do not need the value. If an error code is returned, the VARIANT in pVal is left unmodified.
pvtType
Can be NULL. If not NULL, it must be a VARTYPE into which the type of the property is placed. The value of the property can be a VBNULL VARIANT, in which case this parameter would be necessary to determine the actual type of the property. plFlavor

Can be NULL. If not NULL, the Long value receives information on the origin of the property as follows:

WBEM_FLAVOR_ORIGIN_LOCAL
The property belongs to the derived-most class.
WBEM_FLAVOR_ORIGIN_PROPAGATED
The property was inherited from a parent class.
WBEM_FLAVOR_ORIGIN_SYSTEM
The property is a standard system property.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_UNEXPECTED | Did not call DWbemClassObject.BeginEnumeration.
WBEM_NO_ERROR | Success.
WBEM_S_NO_MORE_DATA | No more properties are left in the enumeration.

Sample Code

Private Sub gather_desktop_data()
' This Subroutine fills a listbox with the desktop configurations.
  Dim ppEnum As DIEnumWbemClassObject
  Dim ppObject As DWbemClassObject
  Dim pVal As Variant

  If wbem_logon <> WBEM_NO_ERROR Then   'logon Subroutine failed
     MsgBox ("Unable to log on to namespace")
     Exit Sub
  End If

' ppNamespace is a DIWbemServices type object bound to the
' specified namespace in wbem_logon
  ppNamespace.CreateInstanceEnum "Win32_desktop", WBEM_FLAG_DEEP, Nothing, ppEnum
  While ppEnum.Next(1000, ppObject) <> WBEM_S_FALSE
        ppObject.Get "__RELPATH", 0, pVal, 0, 0
        Listbox.AddItem pVal 'add to a listbox
  Wend
  Set ppEnum = Nothing     'Set the object back to nothing
End Sub

Remarks

If the underlying type of the property is an object path, a date/time, or another special type, the returned type does not contain enough information. The caller must examine the CIMTYPE qualifier for the specified property, and determine if the property is an object reference, date/time, or another special type.

This method also returns system properties.

See Also

DWbemClassObject.BeginEnumeration, DWbemClassObject.EndEnumeration, DWbemClassObject.Get, System Properties


DWbemClassObject.Put

The DWbemClassObject.Put method sets a named property to a new value. This method always overwrites the current value with the new one.

DWbemClassObject.Put(
  [in] Name  As String,
  [in] lFlags  As Long,
  [in] pVal  As VARIANT,
  [in] vtType  As Long
) As Long

Parameters

Name
String that contains the name of the property to be set. This cannot be vbNullString.
lFlags
Reserved. It must be zero.
pVal
VARIANT which becomes the new property value. If pVal is NULL, the property is set to NULL.

Note

If pVal is NULL, the type of the property is inferred from the vtType parameter.

vtType
Use this parameter only when pVal is NULL. In such a case, the vtType parameter specifies a COM type of the property. In every other case, vtType must be zero. vtType must also be zero whenever the underlying object is an instance (even if pVal is NULL), since the type of the property is fixed and cannot be changed. In other words, vtType is used only if pVal is NULL, and the underlying object is a class.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_PROPERTY_TYPE | Property type is not recognized.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TYPE_MISMATCH | For instances, this error code indicates that the pVal parameter is a VARIANT of an incorrect type for the property. For class definitions, this returns if the property already exists in the parent class, and the new COM type is different from the old COM type. Such properties are read-only for the derived class.
WBEM_NO_ERROR | Success.

Remarks

If the property exists in the superclass, its default value is changed unless it is a type mismatch. If the property does not exist and it is not a type mismatch, the property is created.

When you execute this method on an instance, there will always be an overwrite. This is because the property always exists.

When you create a new class, and the underlying type of the property is an object reference, a date/time string, or other special type, it might be necessary to modify the CIMTYPE qualifier for the property to show the special new class. When you modify properties of an instance, set the qualifiers to the correct values ahead of time.

You can only write system properties when you create a new class. In that case, the name of the class you create is designated when you write it to the system property __CLASS.

See Also

System Classes, Properties, and Qualifiers


DWbemClassObject.SpawnDerivedClass

Use the DWbemClassObject.SpawnDerivedClass method to create a new derived class object from the current object. The object must be a class definition that becomes the superclass of the spawned object.

DWbemClassObject.SpawnDerivedClass(
  [in] lFlags  As Long,
  [out] ppNewClass  As Object
) As Long

Parameters

lFlags
Reserved. It must be zero.
ppNewClass
Object of type DWbemClassObject . contains the new class definition object. On error, a new object is not returned.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_ILLEGAL_OPERATION | The user requested an illegal operation, such as spawning a class from an instance.
WBEM_E_INCOMPLETE_CLASS | The source class was not completely defined or registered with CIMOM, so a new derived class is not permitted.
WBEM_E_INVALID_PARAMETER | ppNewClass is NOTHING.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

Remarks

The new object returned in ppNewClass automatically becomes a subclass of the current object. This behavior cannot be overridden. There is no other method by which you can create derived classes.

You cannot create a derived class from a class that is local to your own client process. You must create the base class, register it with CIMOM, and retrieve it using DIWbemServices.GetObject before you can use this method to create a derived class. To create a class hierarchy, you must create the initial class with DIWbemServices.PutClass, retrieve it using DIWbemServices.GetObject, and use the retrieved object to create the newly derived class. After that, you must use DIWbemServices.PutClass to create the newly derived class. To create other derived classes, you must call DIWbemServices.GetObject, then call DWbemClassObject.SpawnDerivedClass, and so on, in a cycle for each new derivation level. In order to prevent version errors and concurrency conflicts, you need to follow this procedure. To create a class with no parent, see Class Creation.

See AlsoDIWbemServices.GetObject, DIWbemServices.PutClass


DWbemClassObject.SpawnInstance

Use the DWbemClassObject.SpawnInstance method to create a new instance of a class. The current object must be a class definition obtained from CIMOM using DIWbemServices.GetObject or DIWbemServices.CreateClassEnum. Then use this class definition to create new instances. Create each new instance locally within the process, and then call DIWbemServices.PutInstance to actually create the instance within CIMOM.

Note that spawning an instance from an instance is legal.

DWbemClassObject.SpawnInstance(
  [in] lFlags As Long,
  [out] ppNewInstance As Object
) As Long

Parameters

lFlags
Reserved. It must be zero.
ppNewInstance
DWbemClassObject type object. It receives a new instance of the class.

Return Values

WBEM_E_INCOMPLETE_CLASS | The current object is not a valid class definition, and it cannot spawn new instances. Either it is incomplete, or it has not been registered with CIMOM using PutClass.
WBEM_E_ILLEGAL_OPERATION | Returned if this method is used on an instance instead of a class
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

DIWbemServices.GetObject, DIWbemServices.PutInstance


DWbemContext

The DWbemContext interface sends additional information to providers when submitting DIWbemServices calls to CIMOM. All primary calls in DIWbemServices take an optional parameter that can be an object of this type.

In many cases, dynamic providers need more information than is specified in the normal parameters of an DIWbemServices method. For example, to manipulate any CIM schema objects it provides, a provider may need to know an Simple Network Management Protocol (SNMP) Community name or an Structured Query Language (SQL) database and table name. A client can add this information to an DWbemContext object, and send the DWbemContext object along with the call as one of the parameters.

Note It is very important that providers make as little use of this mechanism as possible. Preferably, providers would never use it. If a provider requires a large amount of highly specific context information to respond to a request, all clients must be coded to provide this information. This mechanism can break the uniform access model that is the basis of WBEM. Nevertheless, in some situations you will not be able to avoid it. Therefore, this mechanism allows you to access such providers, if necessary.

When you create an DWbemContext object, this object is a simple container of named values. You can access the methods to fill in any context information required by a dynamic provider. After you call one of the DIWbemServices methods, you can reuse the DWbemContext object for another call.

The underlying provider determines the information contained in an DWbemContext object. CIMOM makes no use of the information, but simply forwards it to the provider. Providers must publish the context information they require to service requests.

Methods

BeginEnumeration | Begins an enumeration of all context values in the DWbemContext object.
Clone | Makes a complete copy of the current DWbemContext object.
DeleteAll | Removes all context values, making the DWbemContext object empty.
DeleteValue | Removes the specified context value.
EndEnumeration | Ends an enumeration begun with BeginEnumeration and Next.
GetNames | Gets the names of all of the context values available.
GetValue | Gets the specified context value by name.
Next | Gets the next value in an enumeration of all context values beginning with BeginEnumeration.
SetValue | Sets a specific named context value.


DWbemContext.BeginEnumeration

The DWbemContext.BeginEnumeration method resets the enumeration of all the context values in the object. You must call this method before making the first call to DWbemContext.Next to enumerate all of the context values in the object.

BeginEnumeration(
  [in] lFlags As Long
) As Long

Parameters

lFlags
Reserved. It must be zero.

Return Values

WBEM_E_INVALID_PARAMETER | The lFlags parameter was not valid.
WBEM_NO_ERROR | Success.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to begin an enumeration.
WBEM_E_FAILED | Unspecified error.

See Also

DWbemContext.Next, DWbemContext.EndEnumeration


DWbemContext.Clone

The DWbemContext.Clone method makes a logical copy of the current DWbemContext object. This method can be useful when you need to make many calls that have largely identical DWbemContext objects.

Clone(
  [out] ppNewCopy  As Object
) As Long

Parameters

ppNewCopy
DWbemContext type object. It receives a new object that is a clone of the current object. On error, a new object is not returned.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | NOTHING was specified as a parameter, which is not legal.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to clone the object.
WBEM_NO_ERROR | Success.


DWbemContext.DeleteAll

The DWbemContext.DeleteAll method removes all named context values from the current object, thus emptying it.

DeleteAll( ) As Long

Parameters

None.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_NO_ERROR | Success.

See Also

DWbemContext.DeleteValue


DWbemContext.DeleteValue

The DWbemContext.DeleteValue method deletes a named context value created by DWbemContext.SetValue.

DeleteValue(
  [in] Name As String,
  [in] lFlags As Long
) As Long

Parameters

Name
String that will contain the named context value to delete.
lFlags
Reserved. It must be zero.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid Name or lFlags value was specified.
WBEM_E_NOT_FOUND | The specified named context value does not exist.
WBEM_NO_ERROR | Success.

See Also

DWbemContext.SetValue, DWbemContext.GetValue


DWbemContext.EndEnumeration

The DWbemContext.EndEnumeration method ends an enumeration sequence begun with DWbemContext.BeginEnumeration. This call is not required, but it releases as early as possible any system resources associated with the enumeration.

EndEnumeration( ) As Long

Parameters

None.

Return Values

WBEM_NO_ERROR | Success.
WBEM_E_UNEXPECTED | This call was made without a corresponding call to DWbemContext.BeginEnumeration.

See Also

DWbemContext.BeginEnumeration, DWbemContext.Next


DWbemContext.GetNames

The DWbemContext.GetNames method returns an array of strings containing all of the names of the named context values. After all the names are known, you can use GetValue can be called on each name to retrieve the value. This technique is a way of accessing the context values that is different from calling the BeginEnumeration, Next, and EndEnumeration methods.

GetNames(
  [in] lFlags  Long Long,
  [out] pNames()  As String
) As Long

Parameters

lFlags
Reserved. It must be zero.
pNames
This parameter cannot be vbNullString. If no error is returned, pNames receives an array containing all the context value names. If an error code is returned, pNames is set to vbNullString.

Note If there are no named values in the object, the call succeeds and returns an array of length zero.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

DWbemContext.GetValue, DWbemContext.BeginEnumeration


DWbemContext.GetValue

The DWbemContext.GetValue method returns the value of the named property.

GetValue(
  [in] NameIndex As String,
  [in] lFlags As Long,
  [out] pValue As VARIANT
) As Long

Parameters

NameIndex
The name of the property for which the value is to be retrieved. lFlags

Reserved. It must be zero.

pValue
This parameter cannot be NULL, and it must be of type VARIANT. If there is no error, the VARIANT is set to contain the context value. If an error code is returned, the VARIANT in pValue is left unmodified.

It is possible that an entire DWbemClassObject can be returned inside the VARIANT. If that is the case, CIM_OBJECT is the VARIANT type.

Return Values

WBEM_E_NOT_FOUND | The requested value was not found.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

DWbemContext.SetValue


DWbemContext.Next

The DWbemContext.Next method retrieves the next qualifier in an enumeration that was started with DWbemContext.BeginEnumeration

Next(
  [in] lFlags As Long,
  [out] pName As String,
  [out] pVal As VARIANT
) As Long

Parameters

lFlags
Reserved. It must be zero.
pName
String that contains the name of the qualifier returned.‹I need more information on this parameter› If WBEM_S_NO_MORE_DATA is returned, pName is set to vbNullString.
pVal
This parameter cannot be NULL, and must be of type VARIANT. If no error is returned, the VARIANT is initialized and set to contain the context value. If an error code is returned, the VARIANT in pValue is left unmodified.

If WBEM_S_NO_MORE_DATA is returned, this parameter is set to a VARIANT of type VBNULL.

It is possible that an entire DWbemClassObject is returned inside the VARIANT. If that is the case, CIM_OBJECT is the VARIANT type.

Note At the end of the enumeration, WBEM_S_NO_MORE_DATA is returned. The returned VARIANT is of type VBNULL, and the returned pName is set to vbNullString.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_UNEXPECTED | Caller did not call DWbemContext.BeginEnumeration.
WBEM_NO_ERROR | Success.
WBEM_S_NO_MORE_DATA | No more properties are left in the enumeration.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the call.

See Also

DWbemContext.BeginEnumeration, DWbemContext.EndEnumeration


DWbemContext.SetValue

The DWbemContext.SetValue method creates or overwrites a named context value.

SetValue(
  [in] NameIndex As String,
  [in] lFlags As Long,
  [in] pValue As VARIANT
) As Long

Parameters

NameIndex
Cannot be vbNullString. A string indicating the name of the context value to be changed.
lFlags
Reserved. It must be zero.
pValue
Must be a valid VARIANT, which is treated as read-only. The value in the VARIANT becomes the named context value.


DWbemLocator

Use the DWbemLocator interface to connect to a particular host machine.You can then access the CIM Object Manager (CIMOM) on this host machine by using the DIWbemServices object that is returned by the ConnectServer method on this interface.

Methods

ConnectServer Connects to CIMOM on the specified machine.


DWbemLocator.ConnectServer

The DWbemLocator.ConnectServer method connects to CIMOM on the machine specified in the NetworkResource parameter. This is typically a Microsoft® Windows NT® or Microsoft® Windows® 95/98 target machine, which must have an operational CIMOM. If method is succesfull then a DIWbemServices object will be returned that is bound to the namespace on the host machine.

DWbemLocator.ConnectServer(
  [in] NetworkResource As String,
  [in] User As String,
  [in] Password As String,
  [in] Locale As String,
  [in] lSecurityFlags As Long,
  [in] Authority As String,
  [in] pCtx As Object,
  [out] ppNamespace As Object
) As Long

Parameters

NetworkResource
A string containing the object path of the desired CIMOM and namespace. For local machine access to the default namespace, for example, use a simple object path: "root\default" or "\\.\root\default".

For access to the default namespace on a remote machine using Distributed COM (DCOM), include the machine name: "\\myserver\root\default".

See Object Paths.

User
A string that specifies the user name to use while attempting to connect. Use vbNullString to use the user name of the current logged-on user.
Password
A string that specifies the password to use when attempting to connect. Use vbNullString, but not a blank string, to use the password of the current logged-on user. A blank string is treated as a valid password.
Locale
A string that specifies the localization code. Use vbNullString to use the current locale. If not vbNullString, this parameter must be a string that indicates the desired locale in which information should be retrieved. For Microsoft locale identifiers, the format of the string is "MS\xxxx", where xxxx is a string in hexadecimal form that indicates the LCID.

For example, American English would appear as "MS\0x409"

Since WBEM accommodates other localization schemes besides Microsoft 32-bit LCIDs, you need to use this string format. Other schemes are ISO 639 and RFC 1766. See WBEM Localization.

lSecurityFlags
Must be 0.
Authority
Reserved. It should be set to vbNullString.
pCtx
DWbemContext type object required by the dynamic class provider that is producing the class instances. You must specify the values in the context object in the documentation for the provider in question. This can be NOTHING if no context is being provided.
ppNamespace
DIWbemServices type object bound to the specified namespace. On error, this is set to NOTHING.

Return Values

WBEM_E_ACCESS_DENIED | The current or specified user name and password were not valid or authorized to make the connection.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_NAMESPACE | The specified namespace did not exist on the server.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE | A networking error occurred, preventing normal operation.
WBEM_E_SERVER_NOT_FOUND | The specified server could not be located.
WBEM_NO_ERROR | Success.

Sample Code

Function Wbem_logon()
  Dim NetworkResource
  Dim ErrObj As DWbemClassObject
  Dim pLocator As New DWbemLocator
  On Error GoTo ErrorHandler
' This example attempts to log on to the root\cimv2 namespace.
' Pass vbNullstring for the username, password, locale and authority
' to use the currently logged in user password and the default locale
' and authority
' ppNamespace is a DWbemServices type object that will be bound to the
' namespace.

   pLocator.ConnectServer Me.Namespace, vbNullString, vbNullString, vbNullString, 0, vbNullString, Nothing, ppNamespace
   Wbem_logon = WBEM_NO_ERROR
Exit Function

ErrorHandler:
' Calls a custom function that converts error codes to descriptive strings.
   MsgBox "An error has occurred: " & show_wbem_error(Err.Number)
   show_wbem_error (Err.Number)
   Wbem_logon = -1 'indicate an error
   Exit Function

End Function

See Also

DIWbemServices


DIWbemObjectSink

The DIWbemObjectSink interface is a sink interface used for all types of notifications within the CIMOM programming model. Clients implement this interface to receive the results of the asynchronous methods of DIWbemServices and event notifications.

In general, call Indicate to provide objects. After that, call SetStatus to indicate the end of the notification sequence. SetStatus can also be called to indicate errors when no objects are provided to the sink.

Methods

Indicate | Provides notification objects to the implementer.
SetStatus | Provides notification status to the implementer.


DIWbemObjectSink.Indicate

To provide a notification, a source makes a call using the DIWbemObjectSink.Indicate method.

Use this interface and method with the asynchronous methods of the DIWbemServices interface.

DIWbemObjectSink.Indicate(
  [out] pIndicateObj As Object
)

Parameters

pIndicateObj
DWbemClassObject type object that is the result of a call to one of the asycronous methods.

Return Values

WBEM_E_FAILED | The receiver did not process the notification properly.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | The call succeeded; the receiver acknowledges the notification.


DIWbemObjectSink.SetStatus

Sources call the DIWbemObjectSink.SetStatus method to indicate the end of a notification sequence or the result code of an asynchronous method of DIWbemServices.

Normally, a client implements the DIWbemObjectSink interface, The client executes DIWbemServices methods, which return their results using this interface. During this operation, CIMOM calls Indicate as many times as required, followed by a final call to SetStatus.

DIWbemObjectSink.SetStatus(
  [in] lFlags As Long,
  [in] hResult As Long,
  [in] strParam As Long,
  [in] pObjParam As Object
) As Long

Parameters

lFlags
Reserved. It must be zero.
hResult
Set to the HRESULT of the asynchronous operation or notification. Typically, this is one of the WBEM_E_ error codes or WBEM_S_ status codes.
strParam
Receives a string if the original asynchronous operation returns a string. For example, when you are using PutInstanceAsync, DIWbemObjectSink.SetStatus is called with this parameter set to the object path of the newly created instance.
pObjParam
Object of type DWbemClassObject. In cases where a complex error or status object is returned, this contains an instance object that contains more information about the error.

Return Values

WBEM_E_FAILED | The receiver did not process the notification properly.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | The call succeeded; the receiver acknowledges the notification.


DIWbemQualifierSet

The object that exports the DIWbemQualifierSet interface acts as a container for the entire set of named qualifiers for a single property or for an entire object depending on how the object was obtained. If the object was obtained from DWbemClassObject.GetQualifierSet, the object consists of the set of qualifiers for an entire object (a class or instance). If the object was obtained from DWbemClassObject.GetPropertyQualifierSet, the object represents the qualifiers for a particular property.

In WBEM, this interface is always in-process. Put operations only affect the local copy of the object. Get operations retrieve values from the local copy. Perform updates only when entire objects are written using the methods DIWbemServices.PutClass or DIWbemServices.PutInstance.

Methods

BeginEnumeration | Resets prior to an enumeration of all qualifiers.
Delete | Deletes the specified named qualifier.
EndEnumeration | Ends an enumeration of qualifiers.
Get | Reads a particular named qualifier.
GetNames | Gets the names of qualifiers subject to certain filters.
Next | Gets the next qualifier during an enumeration of all qualifiers.
Put | Writes a particular named qualifier.


DIWbemQualifierSet.BeginEnumeration

The DIWbemQualifierSet.BeginEnumeration method resets before an enumeration of all the qualifiers in the object. To enumerate all of the qualifiers on an object, you must call this method before to the first call to DIWbemQualifierSet.Next.

DIWbemQualifierSet.BeginEnumeration(
  [in] lFlags As Long
) As Long

Parameters

lFlags
Specifies the qualifiers to include in the enumeration. It must be one of the following constants:
0 (Zero) | Return the names of all qualifiers.
WBEM_FLAG_LOCAL_ONLY | Return only the names of the local object. If the current qualifier set refers to a property, return only the qualifiers set on this property. Do not return those propagated from another qualifier set. If the current qualifier set refers to an instance, return only the instance-specific qualifier names. If the current qualifier set refers to a class, return only qualifiers local to the derived-most class.
WBEM_FLAG_PROPAGATED_ONLY | Return only the names of qualifiers propagated from another object. For example, if the current qualifier set refers to a property, return only the qualifiers propagated to this property from another qualifier set. Do not return those set on this property itself. If the current qualifier set refers to an instance, only return qualifiers propagated from the class definition. If the current qualifier set refers to a class, only return qualifier names inherited from the superclasses, and so on.

Return Values

WBEM_E_INVALID_PARAMETER | The lFlags parameter was not valid.
WBEM_NO_ERROR | Success.

See Also

DIWbemQualifierSet.Next


DIWbemQualifierSet.Delete

The DIWbemQualifierSet.Delete method deletes the specified qualifier by name. If the qualifier is inherited from the parent class, you can override it with a new value. In this case, you can use Delete to delete the new value. By deleting the new value, you reset the qualifier to the original inherited value.

See Qualifier Flavors.

DIWbemQualifierSet.Delete(
  [in] Name As String
) As Long

Parameters

Name
The name of the qualifier to delete.

Return Values

WBEM_E_INVALID_OPERATION | Deleting this qualifier is illegal.
WBEM_E_INVALID_PARAMETER | The Name parameter was not valid.
WBEM_E_NOT_FOUND | The specified qualifier was not found.
WBEM_NO_ERROR | Success.
WBEM_S_RESET_TO_DEFAULT | When you delete an overridden qualifier, this status code (a nonerror code) indicates that the local override was deleted and that the original qualifier from the parent object has resumed scope. A subsequent attempt to get the qualifier will succeed, returning the parent's value.

See Also

Qualifier Flavors


DIWbemQualifierSet.EndEnumeration

Call the DIWbemQualifierSet.EndEnumeration method when you want to stop an enumeration that was started with DIWbemQualifierSet.BeginEnumeration. This call immediately releases resources associated with the enumeration. We recommend this call; however, it is not a requirement.

DIWbemQualifierSet.EndEnumeration( ) As Long

Parameters

None.

Return Values

WBEM_NO_ERROR Success.

See Also

DIWbemQualifierSet.BeginEnumeration, DIWbemQualifierSet.Next


DIWbemQualifierSet.Get

The DIWbemQualifierSet.Get method gets the specified named qualifier, if found.

DIWbemQualifierSet.Get(
  [in] Name,
  [in] lFlags As Long,
  [out, OPTIONAL] pVal As VARIANT,
  [out, OPTIONAL] plFlavor As Long
) As Long

Parameters

Name
The qualifier name for which the value is being requested.
lFlags
Reserved. It must be zero.
pVal
If successful, the VARIANT is assigned to the correct type and value for the qualifier.

If an error code returns, the VARIANT in pVal is left unmodified.

If this parameter is NULL, ignore the parameter.

plFlavor
Can be NULL. If it is not NULL, this must be a Long that receives the qualifier flavor bits for the requested qualifier. See Qualifier Flavors.

Return Values

WBEM_E_INVALID_PARAMETER | One or more parameters were not found, were invalid, or the namespace could not be parsed.
WBEM_E_NOT_FOUND | The specified qualifier did not exist.
WBEM_NO_ERROR | Success.

See Also

Qualifier Flavors


DIWbemQualifierSet.GetNames

The DIWbemQualifierSet.GetNames method retrieves the names of all of the qualifiers available. Alternately, depending on the filter value of IFlags, this method retrieves the names of certain qualifiers.

You can access these qualifiers by name by using DIWbemQualifierSet.Get for each name. It is not an error for any given object to have zero qualifiers, so the number of strings in pNames on return can be zero, even though WBEM_NO_ERROR is returned.

DIWbemQualifierSet.GetNames(
  [in] lFlags As Long,
  [out] pNames As String
) As Long

Parameters

lFlags
One of the following constants:
0 (Zero) | Return the names of all qualifiers.
WBEM_FLAG_LOCAL_ONLY | Return only the names of the local object. If the current qualifiers set refers to a property, return only the qualifiers set on this property, and not those propagated from another qualifier set. If the current qualifiers set refers to an instance, return only instance-specific qualifier names. If the current qualifiers set refers to a class, return only qualifiers local to the derived-most class.
WBEM_FLAG_PROPAGATED_ONLY | Return only the names of qualifiers propagated from another object. For example, if the current qualifier set refers to a property, return only the qualifiers propagated to this property from another qualifier set, and not those set on this property itself. If the current qualifier set refers to an instance, only return qualifiers propagated from the class definition. If the current qualifier set refers to a class, only return qualifier names inherited from the superclasses.

pNames
String that that contains the requested names.

On error, no string is returned.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

DIWbemQualifierSet.Get

DIWbemQualifierSet.BeginEnumeration


DIWbemQualifierSet.Next

The DIWbemQualifierSet.Next method retrieves the next qualifier in an enumeration that started with DIWbemQualifierSet.BeginEnumeration. Call this method repeatedly to enumerate all the qualifiers until WBEM_S_NO_MORE_DATA returns. If you need to terminate the enumeration early, you should call DIWbemQualifierSet.EndEnumeration.

The order of the qualifiers returned during the enumeration is not defined.

DIWbemQualifierSet.Next(
  [in] lFlags As Long,
  [out, OPTIONAL] pName As String,
  [out, OPTIONAL] pVal As VARIANT,
  [out, OPTIONAL] plFlavor As Long
) As Long

Parameters

lFlags
Reserved. It must be zero.
pName
String containing next qualifier.
pVal
This parameter receives the value for the qualifier. If an error code is returned, the VARIANT in pVal is left unmodified.
plFlavor
If not NULL, the value is set to the qualifier flavor. See Qualifier Flavors.

Return Values

WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_UNEXPECTED | Caller did not call DIWbemQualifierSet.BeginEnumeration.
WBEM_NO_ERROR | Success.
WBEM_S_NO_MORE_DATA | No more properties are left in the enumeration.

See Also

DIWbemQualifierSet.BeginEnumeration, DIWbemQualifierSet.EndEnumeration, Qualifier Flavors


DIWbemQualifierSet.Put

The DIWbemQualifierSet.Put method writes the named qualifier and value. If the qualifier does not exist, the method creates one. When the method creates a new qualifier, it overwrites a previously existing value of the same name.

In some situations, it is not possible to write the value of a qualifier if the qualifier was propagated from another object. Propagated qualifiers are generally read-only, but can be overridden in some situations. See Qualifier Flavors.

When writing the key qualifier, it is not necessary to specify any flavors or propagation rules.

DIWbemQualifierSet.Put(
  [in] Name As String,
  [in] pVal As VARIANT ,
  [in] lFlavor As Long,
) As Long

Parameters

Name
The name of the qualifier that is being written.
pVal
Cannot be NULL. This must be a valid VARIANT that contains the qualifier value before you can write it.
Only variants of type VT_I4, VT_R8, VT_BSTR, VT_BOOL and arrays of types VT_BSTR, VT_I4, VT_R8, and VT_BOOL are supported.
lFlavor
The desired qualifier flavor for this qualifier. See Qualifier Flavors.
Not required if the qualifier is the key qualifier.

Return Values

WBEM_E_CANNOT_BE_KEY | There was an illegal attempt to specify a key qualifier on a property that cannot be a key. The class definition specifies the keys for an object. It cannot be altered on a per-instance basis.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_QUALIFIER_TYPE | The pVal parameter is not of a legal qualifier type.
WBEM_E_OVERRIDE_NOT_ALLOWED | It is not possible to perform the DIWbemQualifierSet.Put operation on this qualifier, because the owning object does not permit overrides.
WBEM_NO_ERROR | Success.

See Also

Qualifier Flavors


DIWbemServices

CIMOM exports the DIWbemServices interface. Clients use this interface to access WBEM services.

Methods

CancelAsyncCall | Cancels a currently executing asynchronous call.
CreateClassEnum | Creates a class enumerator.
CreateClassEnumAsync | Creates a class enumerator that executes asynchronously.
CreateInstanceEnum | Creates an instance enumerator.
CreateInstanceEnumAsync | Creates an asynchronous instance enumerator.
DeleteClass | Deletes a class.
DeleteClassAsync | Deletes a class and receives confirmation asynchronously.
DeleteInstance | Deletes a particular instance of a class.
DeleteInstanceAsync | Deletes an instance and provides confirmation asynchronously.
ExecMethod | Executes an object method.
ExecMethodAsync | Executes an object method asynchronously.
ExecNotificationQuery | Executes a query to receive events.
ExecNotificationQueryAsync | Executes a query and asynchronously receives the events.
ExecQuery | Executes a query to retrieve instances.
ExecQueryAsync | Executes a query and asynchronously returns the instances.
GetObject | Retrieves an object, whether an instance or class definition.
GetObjectAsync | Asynchronously retrieves an object (an instance or class definition).
OpenNamespace | Opens a particular child namespace for operations.
PutClass | Creates or updates a class definition.
PutClassAsync | Asynchronously creates or updates a class definition.
PutInstance | Creates or updates an instance of a particular class.
PutInstanceAsync | Asynchronously creates or updates an instance of a particular class.
QueryObjectSink | Allows the caller to obtain a notification handler sink.


DIWbemServices.CancelAsyncCall

The DIWbemServices.CancelAsyncCall method cancels any currently pending asynchronous call based on the DIWbemObjectSink object that was originally passed to the asynchronous method.

DIWbemServices.CancelAsyncCall(
  [in]  pSink As Object
) As Long

Parameters

pSink
DIWbemObjectSink implementation provided by the client to any of the Asynchronous Methods of DIWbemServices.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | The supplied handle in lAsyncRequestHandle did not correspond to a pending asynchronous request.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

See Also

Asynchronous Methods, DIWbemObjectSink


DIWbemServices.CreateClassEnum

The DIWbemServices.CreateClassEnum method returns an enumerator for all classes satisfying the selection criteria.

The caller must use the returned enumerator to retrieve the class definitions, calling DIEnumWbemClassObject.Next to obtain each class.

Note that it is not an error for the returned enumerator to have zero elements.

DIWbemServices.CreateClassEnum(
  [in] Superclass As String,
  [in] lFlags As Long ,
  [in] pCtx As Object,
  [out]  ppEnum As Object
) As Long

Parameters

Superclass
Object of type DWbemContext

If not NOTHING or blank, specifies a superclass name. Only classes that are subclasses of this class are returned in the enumerator. If NOTHING or blank, and if lFlags is WBEM_FLAG_SHALLOW, only the top-level classes (that is, classes that have no parent class or superclass) are returned. If NOTHING or blank and lFlags is WBEM_FLAG_DEEP, all classes within the namespace are returned.

lFlags
WBEM_FLAG_DEEP forces recursive enumeration into all subclasses derived from the specified superclass. The superclass itself is not returned in the enumeration. WBEM_FLAG_SHALLOW forces the enumeration to include only immediate subclasses of the specified superclass.
pCtx
Typically NOTHING. Otherwise, this is an DWbemContext object required by the dynamic class provider that is producing the class instances. You must specify the values in the context object in the documentation for the provider in question.
ppEnum
Object of type DIEnumWbemClassObject.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to view one or more of the classes that the call can return.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_CLASS | The specified class did not exist.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

Error Objects, DIWbemServices.CreateClassEnumAsync, DIEnumWbemClassObject


DIWbemServices.CreateClassEnumAsync

The DIWbemServices.CreateClassEnumAsync method performs the same function as DIWbemServices.CreateClassEnum, except that the objects return to the specified DIWbemObjectSink implementation instead of to an enumerator.

In cases where the call succeeds, CIMOM asynchronously calls pResponseHandler – >Notify from another thread with class definitions until the query has been satisfied.

DIWbemServices.CreateClassEnumAsync(
  [in] Superclass As String,
  [in] lFlags As Long ,
  [in] pCtx As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

Superclass
If not vbNullStringor blank, this parameter specifies a superclass name. Only classes that are subclasses of this class return in the enumerator. If vbNullStringor blank, and if lFlags is WBEM_FLAG_SHALLOW, only top-level classes, which have no parent class or superclass, return. If vbNullStringor blank, and if lFlags is WBEM_FLAG_DEEP, all classes within the namespace return.
lFlags
WBEM_FLAG_DEEP forces recursive enumeration into all subclasses derived from the specified superclass. The superclass itself does not return in the enumeration.

WBEM_FLAG_SHALLOW forces the enumeration to include only immediate subclasses of the specified superclass.

Note If Superclass is vbNullStringor blank, and WBEM_FLAG_DEEP is specified, all classes return.

pCtx
Typically NOTHING. Otherwise, this is an DWbemContext object required by the dynamic class provider that is producing the class instances. You must specify the values in the context object in the documentation for the provider in question.
PResponseHandler
Object that is the caller's implementation of DIWbemObjectSink. This handler receives the objects as they become available using the DIWbemObjectSink.Indicate method. When there are no more objects, CIMOM calls the DIWbemObjectSink.SetStatus method. For a detailed explanation of this parameter, see Asynchronous Methods.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

See Also

Asynchronous Methods, DIWbemServices.CreateClassEnum, DIWbemObjectSink


DIWbemServices.CreateInstanceEnum

The DIWbemServices.CreateInstanceEnum method creates an enumerator that returns the instances of a specified class according to user-specified selection criteria. This method implements a simple query; more complex queries may require the use of DIWbemServices.ExecQuery.

Note that it is not an error for the returned enumerator to have zero elements

DIWbemServices.CreateInstanceEnum(
  [in] Class As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [out] ppEnum  As Object
) As Long

Parameters

Class
A string containing the name of the class for which instances are desired. This parameter cannot be vbNullString.
lFlags
WBEM_FLAG_DEEP forces recursive enumeration into all subclasses derived from the specified class. Instances of Class as well as those of its derived classes return. WBEM_FLAG_SHALLOW forces the enumeration to include only the instances of the specified class.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. You must specify the values in the context object in the documentation for the provider in question.
ppEnum
Object of type DIEnumWbemClassObject that receives the enumerator.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to view instances of the specified class.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_CLASS | The specified class is invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

Sample Code

Private Sub gather_drive_data()
' This example populates a list box named List1 with instances of
' logical drives using Win32_LogicalDisk.
  Dim ppEnum As DIEnumWbemClassObject ' The enumerator
  Dim ppObject As DWbemClassObject
  Dim pVal As Variant
' Use a custom function named wbem_logon to log on to the
' namespace using Dwbemlocator.ConnectServer.

  If wbem_logon <> WBEM_NO_ERROR Then
     msgbox("Unable to log on to namespace")
     exit sub
  endif

' To create an enumeration object for Win32_LogicalDisk use
' DIWbemServices.CreateInstanceEnum.
' lFlags is set to WBEM_FLAG_DEEP to force recursive enumeration
' into all subclasses derived from the specified class.
' ppNamespace is a DIWbemServices type object bound to the
' specified namespace in wbem_logon

  ppNamespace.CreateInstanceEnum "Win32_LogicalDisk", WBEM_FLAG_DEEP, Nothing, ppEnum

' ppEnum now contains the enumerator. Next, copy all the instances of ' Win32_LogicalDisk into a listbox using the Next method.
' Pass in the name of the property we want to get the value of.
' Pass in 0 for the other arguments except pval.
' pval receives the actual value of the property

  While ppEnum.Next(100, ppObject) <> WBEM_S_FALSE
        ppObject.Get "__RELPATH", 0, pVal, 0, 0
        List1.AddItem pVal 'Add to the listbox
  Wend
  Set ppEnum = Nothing     'Set the objects back to nothing
End Sub

See Also

Error Objects, DIWbemServices.CreateInstanceEnumAsync,DWbemLocator.ConnectServer


DIWbemServices.CreateInstanceEnumAsync

The DIWbemServices.CreateInstanceEnumAsync method performs the same task as DIWbemServices.CreateInstanceEnum, except that the call returns immediately and the instances are asynchronously provided to the specified response handler.

DIWbemServices.CreateInstanceEnumAsync(
  [in] Class As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

Class
A valid BSTR containing the name of the class for which instances are desired. This parameter cannot be vbNullString.
lFlags
WBEM_FLAG_DEEP when set to zero, forces recursive enumeration into all subclasses derived from the specified class. Instances of Class as well as those of its derived classes return. WBEM_FLAG_SHALLOW forces the enumeration to include only the instances of the specified class.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. You must specify the values in the context object in the documentation for the provider in question.
pResponseHandler
The caller's implementation of DIWbemObjectSink. This handler receives the objects as they become available. For a detailed explanation of this parameter, see Asynchronous Methods.

Return Values

WBEM_E_FAILED | Unspecified error..
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_RPC_FAILURE | The RPC link between the client and CIMOM has failed.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values.

See Also

Asynchronous Methods, DIWbemServices.CreateInstanceEnum


DIWbemServices.DeleteClass

The DIWbemServices.DeleteClass method deletes the specified class from the current namespace. If there is a dynamic instance provider associated with the class, the provider is unregistered, and is no longer called for that class. Any classes that derive from the deleted class are also deleted, and their associated providers are unregistered. When the class is deleted, all outstanding static instances of the specified class and its subclasses are also deleted.

If the class is provided by a dynamic class provider, the success of the deletion depends on whether class deletion is supported by that provider.

Note You cannot delete system classes.

DIWbemServices.DeleteClass(
  [in] Class As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [out, OPTIONAL] ppCallResult As Object
) As Long

Parameters

Class
The name of the class targeted for deletion.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. You must specify the values in the context object in the documentation for the provider in question.
ppCallResultt
If NOTHING, the status of the call returns in the return code. If not NOTHING, the call becomes semisynchronous. The call returns immediately. This parameter receives a new DIWbemCallResult object that must be polled periodically by calling DIWbemCallResult.GetCallStatus to determine the final status of the operation. Using this technique, there may be many nonblocking calls to DeleteClass before you can check the status of any of them. In error cases where CIMOM cannot be reached, this parameter will be set to NOTHING.

See Error Objects.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to delete classes.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_CLASS | The specified class does not exist.
WBEM_E_INVALID_OPERATION | Deletion is not supported for the specified class. It may have been a system class or a class supplied by a dynamic provider that does not support class deletion.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values.

See Also

Error Objects, DIWbemServices.DeleteClassAsync


DIWbemServices.DeleteClassAsync

The DIWbemServices.DeleteClassAsync method deletes the specified class from the current namespace. This method is identical to DIWbemServices.DeleteClass, except that the call returns immediately. After the operation is done, you can use the DIWbemObjectSink.SetStatus method to report asynchronously to the specified object sink whether the deletion was successful or not.

DIWbemServices.DeleteClassAsync(
  [in] Class As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

Class
The name of the class targeted for deletion.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. You must specify the values in the context object in the documentation for the provider in question.
pResponseHandler
The implementation of DIWbemObjectSink implemented by the caller. The handler receives the status of the deletion request when the DIWbemObjectSink.SetStatus method makes the status available. For a detailed explanation of this parameter, see Asynchronous Methods.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

All other return codes are provided to the object sink specified by the pReponseHandler parameter through the SetStatus method. Error conditions, such as when the class does not exist or the user does not have permission to delete classes, are reported to the handler. Error conditions are not reported in the return code of this method.

Remarks

If a dynamic instance provider is associated with the class, the provider is unregistered and is no longer called for that class. Any classes that derive from the deleted class are also deleted, and their associated providers become unregistered. All outstanding static instances of the specified class and its subclasses are also deleted when the class is deleted.

If the class is provided by a dynamic class provider, the success of the deletion depends on whether that provider supports the class deletion.

Note Standard system classes cannot be deleted.

See Also

Asynchronous Methods, DIWbemServices.DeleteClass


DIWbemServices.DeleteInstance

The DIWbemServices.DeleteInstance method deletes the instance specified in the object path. You can only delete instances in the current namespace.

If a dynamic provider supplied the instance, it is sometimes not possible to delete the instance unless the provider supports instance deletion.

DIWbemServices.DeleteInstance(
  [in]  ObjectPath As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [out, OPTIONAL] ppCallResult As Object
) As Long

Parameters

ObjectPath
A string containing the object path to the object to be deleted.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. You must specify the values in the context object in the documentation for the provider in question.
ppCallResult
If NOTHING, this parameter is not used. If you specify ppCallResul,the call returns immediately with WBEM_NO_ERROR, and ppCallResult receives a new DIWbemCallResult object. This object must be polled, using the GetCallStatus method, to obtain the result.

Return Values

WBEM_E_ACCESS_DENIED | The current context does not have adequate rights to delete the object.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_CLASS | The specified class does not exist.
WBEM_E_INVALID_OPERATION | The object cannot be deleted.
WBEM_E_NOT_FOUND | The object did not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

See Also

Error Objects, DIWbemCallResult, DIWbemServices.DeleteInstanceAsync, Object Paths


DIWbemServices.DeleteInstanceAsync

The DIWbemServices.DeleteInstanceAsync method performs the same function as DIWbemServices.DeleteInstance, except that the call returns immediately. The success or failure of the operation is asynchronously reported to the supplied object sink through the DIWbemObjectSink.SetStatus method.

If a dynamic provider supplied the instance, it is sometimes not possible to delete the instance unless the provider supports instance deletion.

DIWbemServices.DeleteInstanceAsync(
  [in] ObjectPath As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

ObjectPath
A string containing the object path of the object to be deleted.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. You must specify the values in the context object in the documentation for the provider in question.
pResponseHandler
The caller's implementation of DIWbemObjectSink. This handler receives the status of the delete operation as it becomes available through the SetStatus method. For a detailed explanation of this parameter, see Asynchronous Methods.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

Other error conditions are reported asynchronously to the object sink supplied by the pResponseHandler parameter.

See Also

Asynchronous Methods, DIWbemServices.DeleteInstance, Object Paths


DIWbemServices.ExecMethod

The DIWbemServices.ExecMethod method executes a method exported by a CIM object. This method will block while the method being forwarded to the appropriate provider executes and the information and status are then returned.

CIMOM does not implement the methods directly. The method providers export the methods. For any given CIM class, the available methods and their parameters must be specified in the documentation for the provider in question.

DIWbemServices.ExecMethod(
  [in]  ObjectPath As String,
  [in]  MethodName As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [in] pInParams As Object,
  [out, OPTIONAL] ppOutParams As Object,
  [out, OPTIONAL] ppCallResult As Object
) As Long

Parameters

ObjectPath
A string containing the object path of the object for which the method is executed.
MethodName
The name of the method for the object.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pInParams
May be NOTHING if no in-parameters are required to execute the method. Otherwise, this is a DWbemClassObject that contains the properties. The properties act as inbound parameters for the method that is being executed. The contents of the object are method-specific. They are part of the specification for the provider in question.
PpOutParams

If not NOTHING, receives an object containing outbound parameters and return values for the method execution. The contents of this object are method-specific. They are part of the specification for the provider in question.

ppCallResult
If NOTHING, this is not used. otherwise the call returns immediately with WBEM_NO_ERROR, and ppCallResult receives a new DIWbemCallResult object. This object must be polled, using the GetCallStatus method, to obtain the result of the method execution. The out-parameters for the call are available by calling DIWbemCallResult.GetResultObject

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_INVALID_METHOD | The requested method was not available.
WBEM_E_ACCESS_DENIED | The current user was not authorized to execute the method.
WBEM_E_INVALID_METHOD_PARAMETERS | The provider determined the supplied pInParams object was invalid.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

See Also

DIWbemServices.ExecMethodAsync, DIWbemCallResult.GetResultObject


DIWbemServices.ExecMethodAsync

The DIWbemServices.ExecMethodAsync method asynchronously executes a method exported by a CIM object. The call immediately returns to the client. The in-parameters are forwarded to the appropriate provider where the exported method executes. Information and status return to the caller through the supplied object sink.

CIMOM does not implement the methods directly. The method providers export the methods. For any given CIM class, the available methods and their parameters are part of the documentation for the provider in question.

DIWbemServices.ExecMethodAsync(
  [in]  ObjectPath As String,
  [in]  MethodName As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [in] pInParams As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

ObjectPath
A string containing the object path of the object for which the method is to be executed.
MethodName
The name of the method for the object.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pInParamsCan be NOTHING if no in-parameters are required to execute the method. Otherwise, this is a DWbemClassObject that contains the properties. The properties act as inbound parameters for the method execution. The contents of the object are method-specific, and are part of the specification for the provider in question.
pResponseHandler
Must not be NOTHING. The object sink receives the result of the method call. The out-parameters are sent to DIWbemObjectSink.Indicate. The result of the call mechanism itself will be sent to DIWbemObjectSink.SetStatus. Notice that DIWbemObjectSink.SetStatus does not receive the return code of the CIM method, but receives the return code of the actual call-return mechanism. It is useful only when you are verifying that the call occurred or that it failed for mechanical reasons. The out-parameter object supplied to DIWbemObjectSink.Indicate returns the result code from the CIM method.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_ACCESS_DENIED | The current user was not authorized to execute the method.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

Other errors will be reported asynchronously to the object sink supplied in the pReponseHandler parameter

See Also

DIWbemServices.ExecMethod


DIWbemServices.ExecNotificationQuery

The DIWbemServices.ExecNotificationQuery method executes a query to receive events. The call returns immediately. The user can poll the returned enumerator for events as they arrive. Releasing the returned enumerator cancels the query.

DIWbemServices.ExecNotificationQuery(
  [in] QueryLanguage As String,
  [in] Query As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [out] ppEnum As Object
) As Long

Parameters

QueryLanguage
A string containing one of the query languages supported by CIMOM. This cannot be vbNullString. Currently, only the WBEM Query Language (WQL) is supported.
Query
A string containing the text of the event-related query. This cannot be vbNullString.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppEnum
If no error occurs, this parameter receives the enumerator that allows the caller to retrieve the instances in the result set of the query. The caller periodically calls DIEnumWbemClassObject.Next to see if any events are available. Notice that in this usage, Reset does not move the enumerator back to the beginning of the event sequence; thus, it has no effect.

Return Values

WBEM_E_ACCESS_DENIED | The current user is not authorized to view the result set.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_QUERY | The query was not valid syntactically.
WBEM_E_INVALID_QUERY_LANGUAGE | The requested query language is not supported.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values.

See Also

Error Objects, DIWbemServices.ExecNotificationQueryAsync, Queries


DIWbemServices.ExecNotificationQueryAsync

The DIWbemServices.ExecNotificationQueryAsync method performs the same task as DIWbemServices.ExecNotificationQuery, except that events are supplied to the specified response handler until you call CancelAsyncCall to stop the event notification.

DIWbemServices.ExecNotificationQueryAsync(
  [in] QueryLanguage As String,
  [in] Query As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

QueryLanguage
A string containing one of the query languages supported by CIMOM. This must be "WQL" for the WBEM Query Language.
Query
A string containing the text of the event-related query. This cannot be vbNullString.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
The caller's implementation of DIWbemObjectSink. This handler receives the objects in the query result set as they become available. To stop receiving events, you must call DIWbemServices.CancelAsyncCall by using the same object for pResponseHandler.

For a detailed explanation of this parameter, see Asynchronous Methods.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

Other error codes return to the object sink specified by the pResponseHandler parameter.

See Also

Asynchronous Methods, DIWbemServices.ExecQuery, Queries


DIWbemServices.ExecQuery

The DIWbemServices.ExecQuery method executes a query to retrieve objects. These objects are available through the returned enumerator. All query results return through the enumerator as DIEnumWbemClassObject.

For the valid types of queries that can be performed, see Queries.

DIWbemServices.ExecQuery(
  [in] QueryLanguage As String,
  [in] Query As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [out] ppEnum As Object
) As Long

Parameters

QueryLanguage
A string containing one of the query languages supported by CIMOM. This must be "WQL" for the WBEM Query Language.
Query
A string containing the text of the query. This cannot be vbNullString.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object in the documentation for the provider in question.

If the query is very broad and involves many instance providers, it is not practical to include enough context information for all providers. In these situations, the parameter should be set to NOTHING.

ppEnum
If no error occurs, this parameter receives the enumerator that allows the caller to retrieve the instances in the result set of the query. It is not an error for the query to have a result set with zero instances, and only by attempting to iterate through the instances can this be determined.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to view the result set.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified or the namespace could not be parsed.
WBEM_E_INVALID_QUERY | The query was not syntactically valid.
WBEM_E_INVALID_QUERY_LANGUAGE | The requested query language is not supported.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values.

See Also

Error Objects, DIWbemServices.ExecQueryAsync, Queries


DIWbemServices.ExecQueryAsync

The DIWbemServices.ExecQueryAsync method performs the same task as DIWbemServices.ExecQuery, except that the result set is supplied to the specified response handler.

For the valid types of queries that can be performed, see Queries.

DIWbemServices.ExecQueryAsync(
  [in] QueryLanguage As String,
  [in] Query As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

QueryLanguage
A string containing one of the query languages supported by CIMOM. This must be "WQL" for the WBEM Query Language.
Query
A string containing the text of the query. This cannot be vbNullString.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.

If the query is broad and involves many instance providers, it is not practical to include enough context information for all providers. In these situations, the parameter should be set to NOTHING.

pResponseHandler
The caller's implementation of DIWbemObjectSink. This handler receives the objects in the query result set as they become available. CIMOM calls DIWbemObjectSink.Indicate with the objects any number of times, followed by a single call to DIWbemObjectSink.SetStatus to indicate the final status.

For a detailed explanation of this parameter, see Asynchronous Methods.

Return Values

WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values.

Other error codes are returned to the object sink specified by the pResponseHandler parameter.

See Also

Asynchronous Methods, DIWbemServices.ExecQuery, Queries


DIWbemServices.GetObject

The DIWbemServices.GetObject method locates an object by path.

This method retrieves an object, either a class definition or an instance, based on the object's path. This method only retrieves objects from the namespace associated with the current DIWbemServices object.

DIWbemServices.GetObject(
  [in] ObjectPath As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [out, OPTIONAL] ppObject As Object,
  [out, OPTIONAL] ppCallResult As Object
) As Long

Parameters

ObjectPath
The object path of the object to retrieve. If this is set to NOTHING, an empty object is returned That object can become a new class. See Class Creation.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppObject
If not NOTHING, this parameter receives the object, if it is found. If there is an error, this parameter is set to NOTHING.
ppCallResult
If NOTHING, this is not used. Otherwise, the call returns immediately and ppCallResult receives a new DIWbemCallResult object. Periodically, this object can be polled to determine the result of the call. The caller can call DIWbemCallResult.GetResultObject to retrieve the object when the object becomes available.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to access the object.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_PATH | The specified path was invalid.
WBEM_E_NOT_FOUND | The requested object could not be found.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_RPC_FAILURE | The RPC link between the client and CIMOM has failed.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values.

See Also

Class Creation, Error Objects, DIWbemCallResult, DIWbemServices.GetObjectAsync, Object Paths


DIWbemServices.GetObjectAsync

The DIWbemServices.GetObjectAsync method asynchronously retrieves an object, either a class definition or instance, based on the object's path. This is similar to DIWbemServices.GetObject, except that the call returns immediately. and the object is provided to the supplied object sink.

Currently, this method retrieves objects only from the namespace associated with DIWbemServices .

DIWbemServices.GetObjectAsync(
  [in] ObjectPath As String,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

ObjectPath
The object path of the object to retrieve. If this is set to NOTHING, an empty object is returned. This object can become a new class. See Class Creation ,Object Paths.
lFlags
Reserved. It must be zero.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
The caller's implementation of DIWbemObjectSink. This handler receives the requested object when the object becomes available through the DIWbemObjectSink.SetStatus method. The pObjParam parameter contains the object. For a detailed explanation of this parameter, see also Asynchronous Methods.

Return Values

WBEM_E_FAILED | Other error codes return asynchronously to the DIWbemObjectSink.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_PATH | The specified object path was invalid.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

See Also

Asynchronous Methods, Class Creation, DIWbemServices.GetObject, Object Paths


DIWbemServices.OpenNamespace

The DIWbemServices.OpenNamespace method provides the caller with a new DIWbemServices object that has the specified child namespace as its operating context. All operations through the new object, such as class or instance creation, only affect that namespace. The namespace must be a child namespace of the current object through which this method is called.

DIWbemServices.OpenNamespace(
  [in]  Namespace As String,
  [in]  lFlags As Long,
  [in] pCtx As Object,
  [out, OPTIONAL] ppWorkingNamespace As Object,
  [out, OPTIONAL] ppResult As Object
) As Long

Parameters

Namespace
The object path to the target namespace. See Namespaces. This namespace can only be relative to the current namespace associated with the DIWbemServices interface object. It cannot be an absolute path. This parameter cannot be vbNullString.
lFlags
Reserved. It must be zero.
pCtx
Reserved. It must be NOTHING.
ppWorkingNamespace
Receives the object representing the new namespace context. If you specify this parameter, ppResult must be set toNOTHING.
ppResult
Typically NOTHING. If not NOTHING, ppWorkingNamespace must be NOTHING. In this case, the parameter receives a new DIWbemCallResult object, and the call returns immediately. Then, you can periodically poll the DIWbemCallResult.GetResultServices method until the requested namespace becomes available. This parameter is set to NOTHING on error and a new object is not returned.

IMPORTANT If you use this parameter, DCOM requires that ppResult must be set to NOTHING before you call the method.

Return Values

WBEM_E_ACCESS_DENIED | The user does not have permission to access the requested context.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_NAMESPACE | The specified namespace does not exist.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

For more information on return values see Visual Basic error handeling and return values

Remarks

You can also use DWbemLocator.ConnectServer to open the same namespace. The only difference is that the OpenNamespace method allows you to place relative object paths in the Namespace parameter so you can open child namespaces recursively. DWbemLocator.ConnectServer requires a full object path. See Object Paths.

For example, if Root is the current namespace associated with the DIWbemServices interface object, using Default in the Namespace parameter yields a new object bound to the \Root\Default namespace.

See Also

Error Objects, DWbemLocator.ConnectServer, Namespaces


DIWbemServices.PutClass

The DIWbemServices.PutClass method creates a new class, or it updates an existing one. The class specified by the pObject parameter must have been correctly initialized with all of the required property values.

You may not create classes with names that begin with two leading underscores because names such as this are reserved for system classes.

DIWbemServices.PutClass(
  [in] pObject As Object,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [out, OPTIONAL] ppCallResult As Object
) As Long

Parameters

pObject
Must be a valid DWbemClassObject class definition.
lFlags
If WBEM_FLAG_CREATE_OR_UPDATE, the class is created if it does not exist or overwritten if it already exists. If WBEM_FLAG_UPDATE_ONLY, the class must exist and this call constitutes an update. If WBEM_FLAG_CREATE_ONLY, this call is for creation only, and the call fails if the class already exists.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppCallResult
If not NOTHING, the call returns immediately with WBEM_NO_ERROR. Then, you must poll DIWbemCallResult for the result by using DIWbemCallResult.GetCallStatus.

Return Values

WBEM_E_ACCESS_DENIED | The current user is not permitted to create or modify classes.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INCOMPLETE_CLASS | Required properties for classes have not all been set.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.
WBEM_E_ALREADY_EXISTS | WBEM_FLAG_CREATE_ONLY flag was specified, but the class already exists.
WBEM_E_NOT_FOUND | Update flag specified, but class is not found.

For more information on return values see Visual Basic error handeling and return values.

See Also

Class Creation and Modification Rules, Error Objects, DIWbemCallResult


DIWbemServices.PutClassAsync

The DIWbemServices.PutClassAsync method creates a new class, or it updates an existing one. The class specified by the pObject parameter must be correctly initialized with all of the required property values. The call immediately returns and success or failure notification to the object sink.

DIWbemServices.PutClassAsync(
  [in] pObject As Object,
  [in] lFlags As Long ,
  [in] pCtx As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

pObject
The DWbemClassObject type object that contains the class definition.
lFlags
If WBEM_FLAG_CREATE_OR_UPDATE, the class is created if it does not exist or overwritten if it already exists. If WBEM_FLAG_UPDATE_ONLY, the class must exist and this call constitutes an update. If WBEM_FLAG_CREATE_ONLY, this call is for creation only, and the call fails if the class already exists.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
The caller's implementation of DIWbemObjectSink. This handler receives the status of the Put request when it becomes available using the SetStatus method. For a detailed explanation of this parameter, see Asynchronous Methods.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to create classes.
WBEM_E_ALREADY_EXISTS | WBEM_FLAG_CREATE_ONLY flag was specified but the class already exists.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_NOT_FOUND | WBEM_FLAG_UPDATE_ONLY flag was specified, but the class does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

Other status or error codes are reported to the object sink specified by the pReponseHandler parameter.

See Also

Asynchronous Methods, Class Creation and Modification Rules, DIWbemServices.PutClass


DIWbemServices.PutInstance

The DIWbemServices.PutInstance method creates or updates an instance of a class object to CIMOM.

DIWbemServices.PutInstance(
  [in] pInst As Object,
  [in] lFlags As Long,
  [in] pCtx As Object,
  [out, OPTIONAL] ppCallResult As Object
) As Long

Parameters

pInst
The instance to be written to the database.
lFlags
If WBEM_FLAG_CREATE_OR_UPDATE, the instance is created if it does not exist or overwritten if it already exists. If WBEM_FLAG_UPDATE_ONLY, the instance must exist and this call constitutes an update. If WBEM_FLAG_CREATE_ONLY, this call is for creation only, and the call fails if the instance already exists.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
ppCallResult
If NOTHING, this is not used. If not NOTHING, call returns immediately with WBEM_NO_ERROR. An object of type DIWbemCallResult is then returned, and you can poll for the result of the operation by using the DIWbemCallResult.GetCallStatus method. The DIWbemCallResult.GetResultString contains the object path assigned to the object.

Return Values

WBEM_E_ACCESS_DENIED | The current user does not have permission to update an instance of the specified class.
WBEM_E_ALREADY_EXISTS | WBEM_FLAG_CREATE_ONLY flag was specified but the instance already exists.
WBEM_E_FAILED | Unspecified error.
WBEM_E_ILLEGAL_NULL | A value of NOTHING was specified for a property that may not be NOTHING, such as one that is marked by a key, indexed, or not_null qualifier.
WBEM_E_INVALID_OBJECT | The specified instance is invalid (for example, PutInstance with a Class will invoke this return).
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_NOT_FOUND | WBEM_FLAG_UPDATE_ONLY flag was specified, but the instance does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_NO_ERROR | Success.

See Also

DIWbemCallResult, DIWbemServices.PutInstanceAsync, Creating and Modifying an Instance


DIWbemServices.PutInstanceAsync

The DIWbemServices.PutInstanceAsync method performs the same task as DIWbemServices.PutInstance, except that the call returns immediately. and update confirmation or error reporting is provided to the specified response handler.

DIWbemServices.PutInstanceAsync(
  [in]DWbemClassObject pInst As Object,
  [in] lFlags As Long,
  [in] pCtx  As Object,
  [in] pResponseHandler As Object
) As Long

Parameters

pInst
The instance of DWbemClassObject to be written to the repository.
lFlags
If WBEM_FLAG_CREATE_OR_UPDATE, the instance is created if it does not exist or overwritten if it already exists. If WBEM_FLAG_UPDATE_ONLY, the instance must exist and this call constitutes an update. If WBEM_FLAG_CREATE_ONLY, this call is for creation only, and the call fails if the instance already exists.
pCtx
Typically NOTHING. Otherwise, this is a DWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.
pResponseHandler
The caller's implementation of DIWbemObjectSink. This handler receives the status of theDWbemClassObject.Put operation when you use the DIWbemObjectSink.SetStatus method.

For a detailed explanation of this parameter, see Asynchronous Methods.

Return Values

WBEM_E_ALREADY_EXISTS | WBEM_FLAG_CREATE_ONLY flag was specified, but the instance already exists.
WBEM_E_FAILED | Unspecified error.
WBEM_E_ILLEGAL_NULL | A value of NULL was specified for a property that is not NULL, such as one marked by a key, indexed, or not_null qualifier.
WBEM_E_INVALID_CLASS | The specified class was invalid.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_NOT_FOUND | WBEM_FLAG_UPDATE_ONLY flag was specified, but the instance does not exist.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_RPC_FAILURE | The RPC link between the client and CIMOM has failed.
WBEM_NO_ERROR | Success.

See Also

Asynchronous Methods, DWbemContext, DIWbemServices.PutInstance, Instance Creation and Modification Rules


DIWbemServices.QueryObjectSink

The DIWbemServices.QueryObjectSink method allows you to obtain a notification handler that is exported by CIMOM. This allows you to write notifications and events directly to CIMOM. You should write Extrinsic Events only to CIMOM. See WBEM Events.

DIWbemServices.QueryObjectSink(
  [in] lFlags As Long,
  [out] DIWbemObjectSink ppResponseHandler
) As Long

Parameters

lFlags
Reserved. It must be zero.
ppResponseHandler
Receives DIWbemObjectSink type object that is the notification handler. On error, this is set to NOTHING. A value of NOTHING can be returned if no notification handler is available. This is not an error.

Return Values

WBEM_E_ACCESS_DENIED | The caller does not have permission to provide notifications to CIMOM.
WBEM_E_FAILED | Unspecified error.
WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation.
WBEM_E_RPC_FAILURE | The RPC link between the current process and CIMOM has failed.
WBEM_NO_ERROR | Success.

See Also

WBEM Events, DIWbemObjectSink


System Class Reference

The WBEM system classes are a collection of predefined classes that are included with the WBEM SDK and based on the Common Information Model (CIM). System classes are used to support the activities of the CIM Object Manager (CIMOM). For example, they describe events and event providers and consumers and objects used to implement security.

System classes are identified by a leading double underscore in their name. All system classes derive from the abstract base class __SystemClass. Because the system classes are predefined by WBEM, developers cannot create their own system classes by starting a class name with a double underscore. However, they can create classes that derive from system classes.

The following list includes all of the WBEM system classes:

__AbsoluteTimerInstruction

__AggregateEvent

__AuthenticationData

__CIMOMIdentification

__ClassCreationEvent.

__ClassDeletionEvent.

__ClassModificationEvent.

__ClassOperationEvent

__ComEventConsumer

__Event

__EventConsumer

__EventFilter

__EventGenerator

__EventProviderRegistration

__ExtendedStatus

__ExtrinsicEvent.

__FilterToConsumerBinding

__Group

__IndicationRelated.

__InstanceCreationEvent.

__InstanceDeletionEvent.

__InstanceModificationEvent.

__InstanceOperationEvent

__IntervalTimerInstruction

__Membership

__Namespace

__NamespaceCreationEvent.

__NamespaceDeletionEvent

__NamespaceModificationEvent

__NamespaceOperationEvent

__NotifyStatus

__NTLMAuthenticationData

__Provider

__SecurityRelatedClass

__Subject

__SubjectAuthenticationBinding

__SystemClass

__TimerEvent.

__TimerInstruction

__TimerNextFiring

__User

__WBEMAuthenticationData

__WBEMGroup

__Win32EventConsumerProvider

__Win32Provider


__AbsoluteTimerInstruction

The __AbsoluteTimerInstruction system class causes a timer event to be fired at a specific date and time. After the event has been fired, it is never repeated.

class __AbsoluteTimerInstruction : __TimerInstruction
{
    string EventDateTime;
};

Properties

See also the properties in __TimerInstruction.

EventDateTime
The date and time the __TimerEvent should be fired and delivered to the consumer. The format of the string is as follows:

"3/12/97 12:05:00pm"

The format is the one used when converting VT_DATE types in OLE Automation VARIANTs to strings.

Note: In subsequent releases of WBEM, the date and time will have to be specified in the DMTF Date/Time format.

See Also

__TimerEvent

Specifying Dates and Times


__AggregateEvent

The __AggregateEvent system class is an event type generated when many events are combined into a single event to avoid event flooding. Instances of this class become a summary of a series of events. WQL (WBEM Query Language) event queries enable users to control events.

For more information about using WQL for event processing, see SELECT Statements for Event Notification.

class __AggregateEvent : __IndicationRelated
{
    sint32 NumberOfEvents;
    object Representative;
};

Properties

NumberOfEvents
The number of events combined to produce this single summary event.
Representative
A copy of the typical or summary object that becomes the event. This could be a class definition or an instance of any class, but it typically is an instance.


__AuthenticationData

The __AuthenticationData system class is used to express the specific data a particular security authentication scheme, such as the Microsoft® Windows NT® LAN Manager authentication protocol.

In general, this class acts as a superclass and is not used directly. Each subclass contains data private to the particular authentication scheme, such as a password digest, a domain name, or other system-specific data. This class is only available in the Root\Security namespace.

class __AuthenticationData : __SecurityRelatedClass
{
    string Authenticator;
    [key] string GUID;
};

Properties

Authenticator
The name of the authentication system. There are two built-in names, "WBEM" and "NTLM".
GUID
A DCE-style GUID in string form that uniquely identifies the instance.


__CIMOMIdentification

The __CIMOMIdentification system class describes the particular installation of WBEM and the CIM Object Manager. This is a singleton class; there is only one instance. Users query for the instance to obtain information about the WBEM installation.

[singleton]
class __CIMOMIdentification : __SystemClass
{
    string SetupDate;
    string SetupTime;
    string VersionCurrentlyRunning;
    string VersionUsedToCreateDB;
};

Properties

SetupDate
A string indicating the date of installation. This has the form:

mm/dd/yy GMT

Currently, this is always in GMT.

Note: This will be changed to DMTF format in a future release.

SetupTime
A string indicating the time the setup occurred on the SetupDate. The format is:

HH:MM:SS xx GMT

where xx is AM or PM. The time is always in GMT.

Note: This will be changed to DMTF format in a future release.

VersionCurrentlyRunning
Indicates the version of the actual Cimom.exe image currently executing. This is of the form:

"1.00.184.0000"

where the first digit is the major version, the next two digits are minor versions, and the next three digits are the build number. The remaining digits are not used.

VersionUsedToCreateDB
Indicates the version of the actual Cimom.exe image that created the database. This is to allow future WBEM upgrades to determine whether database upgrades are required, because the database format may change between versions of WBEM. The format is:

"1.00.183.0000"

where the first digit is the major version, the next two digits are minor versions, and the next three digits are the build number. The remaining digits are not used.


__ClassCreationEvent

The __ClassCreationEvent system class is generated when a new class is created in the CIMOM database.

class __ClassCreationEvent : __ClassOperationEvent
{
    // object TargetClass; inherited from base class
};

Properties

TargetClass
Inherited from __ClassOperationEvent. Contains a copy of the class that was created.

See Also

__ClassOperationEvent


__ClassDeletionEvent

The __ClassDeletionEvent system class is generated when a class is deleted from the CIMOM database.

class __ClassDeletionEvent : __ClassOperationEvent
{
    // object TargetClass; inherited from base class
};

Properties

TargetClass
Inherited from __ClassOperationEvent. Contains a copy of the class that was deleted.

See Also

__ClassOperationEvent


__ClassModificationEvent

The __ClassModificationEvent system class is generated when a class definition is changed in the CIMOM database. The event reports both the new and old versions of the class definition.

class __ClassModificationEvent : __ClassOperationEvent
{
    // object TargetClass; inherited from base class
    object PreviousClass;
};

Properties

TargetClass
Inherited from __ClassOperationEvent. Contains a copy of the class that was deleted.
PreviousClass
Contains a copy of the previous version of the class before it was modified.

See Also

__ClassOperationEvent


__ClassOperationEvent

The __ClassOperationEvent system class is a base class for all events relating to class creation, modification, and deletion. Events of this type are not directly generated; only events of the subclass types are generated.

class __ClassOperationEvent : __Event
{
    object TargetClass;
};

Properties

TargetClass
A copy of the class definition that caused the event; for example, a copy of the deleted class, the created class, or the modified definition of a class.

See Also

__ClassCreationEvent, __ClassDeletionEvent, __ClassModificationEvent


__ComEventConsumer

The __ComEventConsumer system class is a registration class for the generic, built-in COM event consumer.

class __ComEventConsumer : __EventConsumer
{
    string ConsumerClsid;
    string ConsumerName;
    string MachineName;
};

Properties

ConsumerClsid
The COM CLSID of the event handler (implementer of IWbemUnboundObjectSink) that receives events forwarded to the consumer name specified in ConsumerName.
ConsumerName
The logical consumer name used to bind the consumer to the query filter. Any unique name string is adequate. It is recommended that the vendor or author, the name, and the version be part of the string:

"Microsoft|TestConsumer|v1.0"

MachineName
If not NULL or blank, this represents the remote machine where the consumer lives. Note that this release requires the Microsoft Networks machine name be used (IP addresses and DNS names are not supported).

If NULL or blank, it is assumed that the consumer is installed on the local machine.

See Also

__FilterToConsumerBinding


__Event

The __Event system class is an abstract base class that forms the superclass for all types of events. All new event types must ultimately derive from __Event. All built-in event types derive from this class. Note that this class has no default properties.

Note: the user may not directly derive from this class. All new user-defined event types must derive from __ExtrinsicEvent.

class __Event : __IndicationRelated
{
};

Properties

None.

See Also

__ClassOperationEvent, __ExtrinsicEvent, __InstanceOperationEvent, __NamespaceOperationEvent


__EventConsumer

The __EventConsumer system class is an abstract base class for all new event consumer types. Any new consumer type must derive from this class. Instances of this class are never created.

class __EventConsumer : __IndicationRelated
{
};

Properties

None.

See Also

__ComEventConsumer, Registering a Consumer Provider


__EventFilter

The __EventFilter system class is the primary system class used to register an interest in receiving events of various types.

class __EventFilter : __IndicationRelated
{
    string Name;
    string Query;
    string QueryLanguage;
};

Properties

Name
A unique string that identifies this filter. Typically, a DCE-style GUID in string form will serve.
Query
A WQL query that specifies the set of events that the consumer wants to receive.
QueryLanguage
Currently, this must be the string "WQL".

See Also

Creating an Event Filter


__EventGenerator

The __EventGenerator system class is TBD.

class __EventGenerator : __IndicationRelated
{
};

Properties

None.

See Also

__TimerInstruction


__EventProviderRegistration

The __EventProviderRegistration system class is a class whose instances represent registrations of the various event providers available in the system.

For each provider installed, there must be at least one instance of this class that maps the types of events provided to that provider.

class __EventProviderRegistration : __SystemClass
{
    string EventQueryList[];
    string Provider;
};

Properties

EventQueryList
A list of WQL queries that specifies the range of events supplied by this event provider. For example, if the array contains the following two strings:

"select * from WidgetEvent",

"select * from __InstanceCreationEvent where "

"TargetInstance isa Win32LogicalDisk"

the provider is supposed to provide all events of type WidgetEvent in addition to __InstanceCreationEvent instances for Win32LogicalDisk objects.

Note that the provider does not supply __InstanceChangeEvents or other kinds of events relating to Win32LogicalDisk instances.

Provider
The name of the event provider specified in an instance of __Win32Provider.

See Also

__Win32Provider, Implement an Event Provider


__ExtendedStatus

Instances of the __ExtendedStatus system class are recommended for use as a standard way to report status and error information for operations that require feedback more detailed than a simple result code. Typical uses for instances of this class are for error objects and in the SetStatus method of IWbemObjectSink.

It is typical for dynamic instance and class providers to return an instance of this class to provide detailed information about why a particular operation failed.

class __ExtendedStatus : __NotifyStatus
{
    // sint32 StatusCode; inherited from base class
    string Description;
    string Operation;
    string ParameterInfo;
    string ProviderName;
};

Properties

StatusCode
Inherited from __NotifyStatus.This field is user-defined and can be any type of result code expected by the end user.
Description
This field is user-defined and can be any string value describing the error.
Operation
This field is typically set by CIMOM to indicate which operation occurred at the time of the failure or anomaly. For example, this often contains one of the IWbemServices API names, such as "CreateInstanceEnum".
ParameterInfo
This field is typically set by CIMOM to indicate a particular parameter or parameters that appeared to cause the error. For example, if a user attempts to retrieve a class that does not exist, this field is set to the offending class name.
ProviderName
This field is typically set by CIMOM to indicate the provider name that occasioned the failure or that reported the error. If no provider is involved, this string is set to "CIMOM".

Note: When objects of this class are returned from a dynamic provider, the first two fields are set by the provider and returned unmodified to the client and the remainder are set by CIMOM.

See Also

Error Objects


__ExtrinsicEvent

The __ExtrinsicEvent system class serves as an abstract superclass for all user-defined event types. All such events are termed extrinsic events and are supplied to CIMOM by providers and clients. CIMOM never generates these events on its own.

No instances of this class are ever created. This class serves as a base for further subclasses. Note that the user is not permitted to directly derive new event types from __Event, but must derive from __ExtrinsicEvent.

class __ExtrinsicEvent : __Event
{
};

Properties

None.

See Also

__IntrinsicEvent


__FilterToConsumerBinding

The __FilterToConsumerBinding system class is an association class. The instances bind event filters to the final consumers. After the filter and consumer are bound together using this association, the event subsystem forwards the events specified by the Filter object to the consumer specified by the Consumer object.

class __FilterToConsumerBinding : __IndicationRelated
{
    [key] __EventConsumer ref Consumer;
    [key] __EventFilter ref Filter;
};

Properties

Consumer
The object path to the consumer object that expects to receive the events.
Filter
The object path to the filter object that contains the query specifying the events of interest.

See Also

Creating and Event Filter


__Group

The __Group system class is a security-related class used to specify user groups. A group is a special case of a "subject," and therefore derives from the base class __Subject and adds no new properties of its own. Creating an instance of __Group creates a new user group within WBEM.

This class is only available in the Root\Security namespace.

class __Group : __Subject
{
    // properties inherited from __Subject
};

Properties

See the properties for __Subject .

See Also

__Subject


__IndicationRelated

The __IndicationRelated system class is an abstract base class that all event-related classes derive. It contains no properties or semantics. It is a common derivation point to facilitate queries and retrieve class definitions that relate to events.

class __IndicationRelated : __SystemClass
{
};

Properties

None.


__InstanceCreationEvent

The __InstanceCreationEvent system class is generated when a new instance is created in the CIMOM database.

class __InstanceCreationEvent : __InstanceOperationEvent
{
    // object TargetInstance; inherited from __InstanceOperationEvent
};

Properties

TargetInstance
Inherited from __InstanceOperationEvent. Contains a copy of the created instance that caused the event to fire.

See Also

__InstanceOperationEvent


__InstanceDeletionEvent

The __InstanceDeletionEvent system class is generated when an instance is deleted from the CIMOM database.

class __InstanceDeletionEvent : __InstanceOperationEvent
{
    // object TargetInstance; inherited from __InstanceOperationEvent
};

Properties

TargetInstance
Inherited from __InstanceOperationEvent. Contains a copy of the created instance that caused the event to fire.

See Also

__InstanceOperationEvent


__InstanceModificationEvent

The __InstanceModificationEvent system class is generated when an instance is changed in the CIMOM database.

class __InstanceModificationEvent : __InstanceOperationEvent
{
    // object TargetInstance; inherited from __InstanceOperationEvent
    object PreviousInstance;
};

Properties

TargetInstance
Inherited from __InstanceOperationEvent. Contains a copy of the instance after it was modified.
PreviousInstance
Contains a copy of the instance prior to modification.

See Also

__InstanceOperationEvent


__InstanceOperationEvent

The __InstanceOperationEvent system class is a base class from which events derive that describe instance creation, modification, and deletion. Instances of this class never occur directly. Only instances of classes deriving from this class are actually used within WBEM.

class __InstanceOperationEvent : __Event
{
    object TargetInstance;
};

Properties

TargetInstance
The meaning and content of this instance varies, depending on the derived class. This typically contains a copy of the object that was created, modified, or deleted.

See Also

__InstanceCreationEvent, __InstanceDeletionEvent, __InstanceModificationEvent.


__IntervalTimerInstruction

The __IntervalTimerInstruction system class is used to generate events at intervals, much like a WM_TIMER message in Microsoft® Windows® programming. If an instance of this class is created and associated to a consumer, the consumer receives these events at the requested interval. Due to operating system behavior, it is not guaranteed that events will be delivered at precisely the requested interval.

class __InstanceOperationEvent : __Event
{
    sint32 IntervalBetweenEvents;
};

Properties

See also the properties in __TimerInstruction.

IntervalBetweenEvents
The number of milliseconds between event firings.

Example

The following MOF declaration can be used to configure the timer generator to issue an event named MyEvent every 10 seconds:

instance of __IntervalTimerInstruction
{
TimerId = "MyEvent"; // __TimerInstruction property
IntervalBetweenEvents = 10000;
};

Note: To actually receive such an event, a consumer must be defined and associated to this instance.

See Also

Timer Events


__Membership

The __Membership system class is a security-related association class used to express membership in a user group. By creating an instance of this class and pointing the references to the appropriate __Subject and __Group objects, membership within a __Group is expressed.

class __InstanceOperationEvent : __Event
{
    [key] __Subject ref Member;
    [key] __Group ref MemberOf;
};

Properties

Member
The path to the __Subject (a __User or __Group) whose membership is being expressed.
MemberOf
The path to the __Group object of which the Member object is a member.


__Namespace

The __Namespace system class models CIM namespaces. It provides a representation object for a real namespace. Creating a new instance of this class within any working namespace creates a new namespace within the current working namespace. Conversely, deleting an instance of __Namespace removes the requested namespace.

Enumerating instances of this class within any working namespace gives the available child namespaces.

For example, within the Root namespace are two instances of this class with the names Default and Security, that constitute the Root\Default and Root\Security namespaces, respectively.

class __Namespace : __SystemClass
{
    [key] string Name;
};

Properties

Name
The namespace name.


__NamespaceCreationEvent

An instance of the __NamespaceCreationEvent system class is generated when a new namespace is created in the CIMOM database.

class __NamespaceCreationEvent : __NamespaceOperationEvent
{
    // Namespace TargetNamespace; inherited from superclass
};

Properties

TargetNamespace
Inherited from __NamespaceOperationEvent. This contains a copy of the __Namespace instance that was created. An examination of the embedded instance's Name property indicates which namespace was created.

See Also

__NamespaceOperationEvent


__NamespaceDeletionEvent

An instance of the __NamespaceDeletionEvent system class is generated whenever a namespace is deleted.

class __NamespaceDeletionEvent : __NamespaceOperationEvent
{
    // Namespace TargetNamespace; inherited from superclass
};

Properties

TargetNamespace
Inherited from __NamespaceOperationEvent. This contains a copy of the __Namespace instance that was deleted. An examination of the embedded instance's Name property indicates which namespace was deleted.

See Also

__NamespaceOperationEvent


__NamespaceModificationEvent

An instance of the __NamespaceModificationEvent system class is generated whenever an instance of __Namespace is modified. Note that the Name property of __Namespace cannot change, since namespaces cannot be renamed, but must be deleted and re-created under a new name. Therefore, this event type is limited to indicating changes in qualifiers and properties other than Name. This event is not generated whenever any kind of change occurs within the namespace, but rather is only generated when a namespace object itself is modified.

class __NamespaceModificationEvent : __NamespaceOperationEvent
{
    // Namespace TargetNamespace; inherited from superclass
    __Namespace PreviousNamespace;
};

Note that the only differences between the two objects will be in properties other than the Name property, and in qualifiers.

Properties

TargetNamespace
Inherited from __NamespaceOperationEvent. This contains a copy of the __Namespace instance that was modified. An examination of the embedded instance's Name property indicates which namespace was modified.
PreviousNamespace
This contains a copy of the __Namespace instance prior to modification. An examination of the embedded instance's Name property indicates which namespace was modified.

See Also

__NamespaceOperationEvent


__NamespaceOperationEvent

The __NamespaceOperatonEvent system class is a base class for all namespace-related events. Instances of this event class are never directly generated.

class __NamespaceOperationEvent : __Event
{
    __Namespace TargetNamespace;
};

Properties

TargetNamespace
The meaning of this property varies, depending on the subclass.

See Also

__NamespaceModificationEvent, __NamespaceCreationEvent, __NamespaceDeletionEvent.


__NotifyStatus

The __NotifyStatus system class is a general-purpose class used to report the success or failure of an operation.

class __NotifyStatus : __Event
{
    sint32 StatusCode;
};

Whenever an asynchronous method of the IWbemServices interface is called, the client passes an IWbemObjectSink pointer to CIMOM. CIMOM uses this pointer to send results to the client using the IWbemObjectSink::Indicate method. When CIMOM finishes transmitting results back to the client, it transmits a special object, an instance of the __NotifyStatus class, to the IWbemObjectSink::SetStatus method, to indicate completion and to provide an error code if any errors occurred.

Properties

StatusCode
Contains the error code for the operation whose completion this object communicates. This can be any user-defined code, but the value zero is usually reserved to indicate a NO ERROR condition or SUCCESS.

See Also

__ExtendedStatus


__NTLMAuthenticationData

The __NTLMAuthenticationData system class is a security class that describes client authentication with Microsoft® Windows NT® LAN Manager. Briefly, all that is required to authenticate a user is the user name and domain name. Since the user name is supplied by the __Subject class and required for all types of authentication, only the domain name is specific to this authentication method. Instances of __SubjectAuthenticationBinding are needed to associate instances of this class with the user names, which are instances of class __User.

class __NTLMAuthenticationData : __AuthenticationData
{
    string Domain;
};

Properties

See the properties in the base class __AuthenticationData .

Domain
The NTLM domain name used to authenticate the user.

See Also

__AuthenticationData, __SubjectAuthenticationBinding, __User


__Provider

The __Provider system class is an abstract base class used to describe all types of providers in general, at least to the extent that they are given a name. No instance of this class can be created. It is a superclass for specific types of provider classes.

[abstract]
class __Provider : __SystemClass
{
    [key] string Provider = "<|vendor|provider|version>";
};

Properties

Provider
A unique string that identifies the provider. The following format is suggested to prevent naming conflicts:

vendor|provider|version

"Microsoft|TestProvider|V1.0"


__SecurityRelatedClass

The __SecurityRelatedClass system class is an abstract base class that describes all types of classes associated with WBEM security. No instances of this class are ever created. All security classes must derive from this base class. This class is only available in the Root\Security namespace.

[abstract]
class __SecurityRelatedClass
{
};

Properties

None.


__Subject

The __Subject system class is an abstract base class used to describe all types of users and groups. No instances of this class are ever created. Rather, instances of the subclasses __User and __Group are created to model users and groups.

[abstract]
class __Subject : __SecurityRelatedClass
{
    string Description;
    bool EditSecurity = FALSE;
    bool Enabled = FALSE;
    bool ExecuteMethods = FALSE;
    string FullName;
    [key] string Name;
    bool ReadOnly = FALSE;
    bool RemoteAccess = FALSE;
};

Properties

Description
Contains a textual description of the subject (user or group).
EditSecurity
If TRUE, the subject is permitted full access to Root\Security, that enables creation, modification, and deletion of security objects, users, groups, and so on. If FALSE, the user has no access to Root\Security.
Enabled
If TRUE, the subject is considered enabled and active. Setting this to FALSE disables the subject and does not permit a login to occur.
ExecuteMethods
If TRUE, the subject can execute object methods.
FullName
The subject's full name.
Name
The subject's name. If the subject is a user, this is the user name. If the subject is a group, this is the group name. The name must be unique. Group names and user names occupy the same scope and may not conflict.
ReadOnly
If TRUE, the user is permitted read-only access to the WBEM schema and may not create, modify, or delete objects.
RemoteAccess
If TRUE, the user is permitted to remotely access CIM Object Manager over the network. If FALSE, the user is permitted only local machine access.


__SubjectAuthenticationBinding

The __SubjectAuthenticationBinding system class is an association class used to bind to a subject the authentication data for that subject with regard to a particular security system. This class is only available in the Root\Security namespace.

For example, a user might have to be authenticated through more than one system, such as WBEM and Microsoft® Windows NT® LAN Manager. Therefore, while there is only one __Subject, there are two instances of __AuthenticationData objects that must be associated to that one subject.

[assoc]
class __SubjectAuthenticationBinding : __SecurityRelatedClass
{
    [key] __AuthenticationData ref Authentication;
    [key] __Subject ref Subject;
};

Properties

Authentication
The object path to the authentication data for the subject.
Subject
The object path to the subject being authenticated by the authentication data.

See Also

__AuthenticationData, __Subject


__SystemClass

The __SystemClass system class is the abstract base class from which all system classes derive. Instances of this class cannot be created.

[abstract]
class __SystemClass
{
};

Properties

None.


__TimerEvent

The __TimerEvent system class is generated by the CIMOM timer according to the instructions created for it. For more information, see Timer Events.

class __TimerEvent : __IndicationRelated
{
    sint32 NumFirings;
    string TimerId;
};

Properties

NumFirings
The number of times the event occurred before delivery. This can occur if the firing interval is much quicker than the ability to deliver the event. In this case, CIMOM automatically merges many timer events into the same event, in a manner similar to what occurs with WM_TIMER messages in Microsoft® Windows® programming.
TimerId
Contains the string identifier, or TimerID property of the timer instruction that caused this event.

See Also

Timer Events


__TimerInstruction

The __TimerInstruction system class is a base class used to specify instructions on how timer events should be generated for consumers. In practice, only instances of the two derived classes __AbsoluteTimerInstruction and __IntervalTimerInstruction are created.

class __TimerInstruction : __EventGenerator
{
    bool SkipIfPassed = FALSE;
    [key] string TimerId;
};class __TimerInstruction : __EventGenerator

Properties

SkipIfPassed
If the event is logically generated while the system is turned off or otherwise not available, this flag indicates whether a belated event should be generated or whether the event should simply be skipped.
TimerId
An arbitrary string identifying this particular timer. To avoid naming conflicts, the string form of a DCE-style GUID can be used.

See Also

Timer Events

__AbsoluteTimerInstruction, __IntervalTimerInstruction


__TimerNextFiring

The __TimerNextFiring system class is a reserved class and should not be manipulated by the user.


__User

The __User system class is a security-related class used to specify individual users. A user is a special case of a subject, and derives from the base class __Subject, but adds no new properties of its own. Creating an instance of __User creates a new user in WBEM.

This class is only available in the Root\Security namespace.

class __User : __Subject
{
    // Properties inherited from __Subject
};

Properties

See the properties for __Subject .

See Also

__Subject


__WBEMAuthenticationData

The __WBEMAuthenticationData system class is a security-related class used to specify the necessary information to authenticate a user through WBEM Authentication.

Instances of this class contain the password for the user. However, the password has been transformed using a one-way encryption algorithm (MD5) to protect it from being disclosed.

To completely specify a user that is authenticated through WBEM Authentication, it is necessary to create a __User or __Group and to create an instance of this class, followed by an instance of __SubjectAuthenticationBinding to associate the pair.

This class is only available in the Root\Security namespace.

class __WBEMAuthenticationData : __AuthenticationData
{
    string Authenticator = "WBEM";
    uint8 PasswordDigest[];
};

Properties

See the properties inherited from __AuthenticationData.

Authenticator
From __Subject. Must be set to "WBEM".
PasswordDigest
A byte array of the MD5 digest of the Unicode form of the user's password.

See Also

__Subject, __Group


__WbemGroup

The __WBEMGroup system class is reserved for future use.


__Win32EventConsumerProvider

The __Win32EventConsumerProvider system class describes the relationship between the logical named consumer and the consumer instrumentation (known as a consumer provider).

class __Win32EventConsumerProvider : __IndicationRelated
{
    string ConsumerClassName;
    string ConsumerProviderClsid;
    string MachineName;
};

Properties

ConsumerClassName
The name of the consumer class. Note that since all new consumers must derive from the system class __EventConsumer, each logical consumer is actually represented in the system by its own class.
ConsumerProviderClsid
The COM CLSID of the consumer implementation of IWbemEventConsumerProvider.
MachineName
If NULL, the current machine is assumed. If not NULL, this must be the machine name where the implementation of IWbemEventConsumerProvider is available.

See Also

Registering A Consumer Provider


__Win32Provider

The __Win32Provider system class is used to register dynamic providers with CIMOM.

class __Win32Provider : __SystemClass
{
    sint32 MethodSet;
    bool MustBeLoaded = FALSE;
    string ProviderClsId = "{00000000-0000-0000-0000-000000000000}";
};

You need to register every dynamic data or event provider with CIMOM by creating an instance of the __Win32Provider class in the namespace for which the data is to be provided. For more information see Implementing Dynamic Providers.

Properties

MethodSet
Contains the bitmask of the method bits for all the methods of the IWbemServices interface this provider implements. In the WBEMSVC.IDL, there are a series of bitmask definitions in the WBEM_COM_METHOD_MASK typedef. For each method implemented, the corresponding bit must be set in this mask.

Note: If the provider is an event provider, this field is set to zero.

MustBeLoaded
If TRUE, then the provider must be loaded at startup whether or not any client is requesting objects from it. If FALSE, then the provider is only loaded when absolutely required.
ProviderClsId
The class identifier of the provider's COM object. The COM object represented by this class identifier must implement the IWbemLocator interface if the provider is a dynamic class or instance provider.

If the provider is an event provider, then this CLSID refers to the IWbemEventProvider implementation.

See Also

Class and Instance Provider Models


System Property Reference

WBEM defines a set of system properties that are associated with all classes and instances of classes in addition to class-specific properties. As with system classes, system properties begin with a double underscore to differentiate them from properties created by applications or providers which may not start with a single or double underscore. Another way to identify a system property is by using the IWbemClassObject::Get method.

Not all system properties are available on all classes or instances at all times; the details of meaning and availability are specified separately for each property in the following table.

Property | Type | Description
__Class | VT_BSTR | Class name. Available on all objects at all times. Read-only for instances; read/write for classes..
__Derivation | VT_BSTR array | Class hierarchy of the current class or instance. Available on all objects at all times. The first element is the base-most class and the last element is the immediate superclass.
__Dynasty | VT_BSTR | Name of the top-level class from which this class or instance is derived. Available on all objects at all times and is read-only. When this class or instance is the top-level class, the values of __Dynasty and __Class are the same.
__Genus | VT_I4 | Used to distinguish between classes and instances. Available on all objects at all times. Read-only. Set to WBEM_GENUS_CLASS (1) for classes and WBEM_GENUS_INSTANCE (2) for instances.
__Namespace | VT_BSTR | Name of the namespace from which this class or instance came. Read-only. Available only on static objects provided by CIMOM; not available for dynamic objects such as those created through IWbemClassObject::SpawnInstance.
__Path | VT_BSTR | Full path to the class or instance, including server and namespace. Read-only. Available only on static objects provided by CIMOM; not available for dynamic objects such as those created through IWbemClassObject::SpawnInstance.
__Propertycount | VT_I4 | Number of non-system properties defined for the class or instance. Available on all objects at all times. Read-only.
__Relpath | VT_BSTR | Relative path to the class or instance. Available on all objects at all times. Read-only.
__Server | VT_BSTR | Name of the server supplying this class or instance. Read-only. Available only on static objects provided by CIMOM; not available for dynamic objects such as those created through IWbemClassObject::SpawnInstance.
__Superclass | VT_BSTR | Name of the immediate parent class of the class or instance. Available for all non-top-level classes and their instances. Read-only.


Standard Qualifier Reference

Qualifiers are used to characterize classes, instances, the properties or methods of classes and instances, and the parameters of methods. Qualifiers are optional and can be defined using the Managed Object Format (MOF) language or the Put method of the IWbemQualifierSet interface. Other methods of IWbemQualifierSet can be used to retrieve or delete existing qualifiers.

In MOF syntax, qualifiers are placed before the keyword or element that they are describing as is shown in the following class declaration:

[qualifiers...]
class StdDisk
{
  [qualifiers...]  uint32 dwNumCylinders;
  [qualifiers...]  uint32 dwNumHeads;
  [qualifiers...]  sint32 Method1();
  SINT32 Method2([qualifiers...] Parameter1);
};

All qualifier names are case-insensitive. The type of the qualifier is inferred from the declaration syntax. Some qualifiers have values; others do not. Those that do not have the implied value of TRUE. Absence of a qualifier is synonymous to a FALSE value.

There are standard qualifiers, defined by CIMOM, and user-defined qualifiers. The following list describes each of the standard qualifiers. The name of the qualifier is followed by its data type and an indicator of whether the qualifier can be attached to a class, an instance, a property, or a method.

Abstract (VT_BOOL, class)
Indicates that the class cannot be instantiated. The absence of this qualifier indicates that the class is not abstract.
Association (VT_BOOL, class)
Indicates that the class is an association class used to describe a relationship between two other classes. The absence of this qualifier indicates that the class is not an association class.
Cimtype (VT_BSTR, property)
Indicates the actual type of a property on a class and is added automatically. Because CIMOM allows more types than can be expressed by standard VT constants, the Cimtype qualifier can help interpret the values. The Cimtype qualifier is added automatically. For more information, see MOF Data Types.
ClassContext (VT_BSTR, class)
Indicates that the class has instances that are associated with additional information dynamically supplied by a provider.
Dynamic (VT_BOOL, class or property)
Indicates that instances of the class are dynamically provided.

Must be specified on all classes whose instances are provided dynamically. Only the value TRUE is allowed. When this qualifier is specified on a class declaration, the Provider qualifier must also be specified.

Must be specified on properties of instances that contain values provided by dynamic property providers. Only the value TRUE is allowed. When this qualifier is specified on a property of an instance, the PropertyContext qualifier must also be specified.

DynProps (VT_BOOL, instance)
Must be specified on instances that contain values provided by dynamic property providers. Only the value TRUE is allowed.
Implemented (VT_BOOL, method)
Indicates that a method has an implementation supplied by a provider.
In (VT_BOOL, method parameter)
Indicates that a parameter is an input parameter.
In, out (VT_BOOL, method parameter)
Indicates that a parameter is both an input and an output parameter.
Indexed (VT_BOOL, property)
Can be specified on properties of classes to request that those properties be indexed. Only the value TRUE is allowed.
InstanceContext (VT_BSTR, instance)
Can be specified on instances that contain values provided by dynamic property providers. The value is passed to the property provider as an argument to IWbemPropertyProvider::GetProperty.
Key (VT_BOOL, property)
Can be specified on properties of classes to mark those properties as keys. Only the value TRUE is allowed. A number of rules exist that determine which properties may be keys. For more information, see Key Properties.
Lexicon (VT_BSTR, class, instance, or property)
Specifies the globally unique identifier (GUID) of the instance of the __Lexicon system class to be used for localization.
Locale (VT_BSTR, class or instance)
Specifies the language of origin for the class or instance.
Max (VT_I4, property)
Ignored - is used as a hint - people can put more elements in the array than max specifies.
Not_Null (VT_BOOL, property)
Can be specified on properties of classes to indicate that those properties cannot take on a value of NULL (VT_NULL). Only the value TRUE is allowed. If specified, CIMOM does not allow creation of instances with the property set to NULL (returning WBEM_E_ILLEGAL_NULL error code). Note that key and indexed qualifiers already imply this behavior.
Out (VT_BOOL, method parameter)
Indicates that a parameter is an output parameter.
Optional (VT_BOOL, method parameter)
Indicates that a parameter is not required and has a well-behaved default value.
PropertyContext (VT_BSTR, property)
Must be specified on properties of instances that contain values provided by dynamic property providers. The value will be passed to the property provider as an argument to IWbemPropertyProvider::GetProperty.
Provider (VT_BSTR, class)
Must be specified on all classes whose instances are provided dynamically. The value of this qualifier is the name of the dynamic provider that provides the instances for this class. This name must be registered with CIMOM by creating an instance of the __Win32Provider class with the Provider property containing this name. When this qualifier is specified on a class declaration, the Dynamic qualifier must also be specified.
Singleton (VT_BOOL, class)
Designates a class that can only have one instance and does not contain key properties. Only the value TRUE is allowed.
Static (VT_BOOL, class)
Indicates that a method may be invoked against the class definition and is not bound to any instances of the class.


Appendixes


MOF Compiler

The Managed Object Format (MOF) compiler parses a file containing MOF statements and adds the classes and instances defined in the file to the CIMOM repository.

mofcomp
    [-check]
    [-N: <namespace path>]
    [-class:updateonly | -class:createonly]
    [-instance:updateonly | -instance:createonly]
    [-B:<filename>]
    [-WMI]
    [-P:<Password>]
    [-U:<UserName>]
    [-A:<Authority>]
    [-L:<FLAGS>]
    <MOF file>

Switches

-check
Requests that the compiler perform a syntax check only and print appropriate error messages. No other switch can be used with this switch. No connection to CIMOM is established and no modifications to the repository are made.
-N
Requests that the compiler load the MOF file into the specified namespace. The default namespace (Root\Default) is used unless this switch is used or a #pragma namespace ("namespace path") statement appears in the MOF file.
-class:updateonly
Requests that the compiler not create any new classes, terminating if a class specified in the MOF file does not exist.
-class:createonly
Requests that the compiler not make any changes to existing classes, terminating if a class specified in the MOF file already exists.
-instance:updateonly
Requests that the compiler not create any new instances, terminating if an instance specified in the MOF file does not exist.
-instance:createonly
Requests that the compiler not make any changes to existing instances, terminating if an instance specified in the MOF file already exists.
-B
Requests that the compiler create a binary version of the MOF file without making any modifications to the repository. The binary MOF file is created with the BMOF extension.
-WMI
Requests that the compiler perform a WMI syntax check. The -B switch must be used with this switch.
-P
Specifies a password to use when logging on.
-U
Specifies the name of the user logging on.
-A
Specifies the authority (domain name) to use when logging on.
-L
Specifies the type of authentication to use when logging on. The following values are valid:
Authentication value | Description
0 | Default authentication
1 | Windows NT LAN Manager (NTLM) authentication
2 | WBEM authentication

For a thorough description of the authentication schemes supported by WBEM, see WBEM Security.

Return Values

As its first operation, the MOF compiler performs a syntax check on the MOF file. If it finds any errors, an error message is printed and the process terminates. The following values can be returned:

Return value | Description
0 | MOF compilation was successful.
1 | MOF compiler could not connect with the CIMOM server possibly due to a semantic error such as an incompatibility with the existing repository or an actual error such as the failure of the CIMOM server to start.
2 | One or more command line switches were invalid.
3 | MOF syntax error.

Remarks

A file can be compiled with the following simple command line entries:

mofcomp <MOF filename>

When special processing is required, one or more of the switches can be used. All of the switches are optional, and any combination is allowed. However, it does not make sense to use some of the switches in combination with others. For example, to combine the -class:updateonly and -class:createonly switches results in the compiler not performing any action.

A MOF file that is using the Unicode character set contains a signature as the first two bytes of the file. This signature is either U+FFFE or U+FEFF, depending on the byte ordering of the file.

When there are no errors in the parsing process, the MOF compiler connects to the CIMOM server running on the local machine unless the -check switch is specified. Classes and instances defined in the MOF file are added to the repository.

When there is an error in updating the repository, no attempt is made to bring it back to the state it was in before the compiler began processing.

For information about how to declare classes and instances using the MOF syntax, see Using the Managed Object Format (MOF) Language.


CIMOM Command-Line Syntax

The Common Information Model Object Manager (CIMOM) can be started on Microsoft® Windows NT® installations through the Control Panel or with the net start command.

cimom
    [/kill]
    [/exe]
    [/regserver]
    [/unregserver]

Switches

/kill
Causes CIMOM to stop any running copies, even if the running copy is a Windows NT service.
/exe
Forces CIMOM to run as a standard executable file (EXE) rather than as a Windows NT service and displays CIMOM as an icon while running.
/regserver
Causes CIMOM to complete its registration process.
/unregserver
Causes CIMOM to cancel its registration by removing registry entries.

Remarks

CIMOM runs as a dual mode executable program, either as a standard .exe file or as a Windows NT service.

To connect to CIMOM
  1. Call the COM function CoCreateInstanceEx to retrieve a pointer to a locator object, which supports the IWbemLocator interface.
  2. Call IWbemLocator::ConnectServer to connect to a namespace on a server. ConnectServer returns a pointer to a WBEM services object, which supports the IWbemServices interface.


Backus Naur Form (BNF) Syntax


MOF BNF Syntax

//
// Start symbol.
//
<Parse> ::= <top_level_decl><Parse>;
<Parse> ::= <qualifier_default><Parse>;
<Parse> ::= <preprocessor_command><Parse>;
<Parse> ::= <>;

//
// Preprocessor commands
//
<preprocessor_command> ::= <pound_include>;
<preprocessor_command> ::= <pound_define>;
<preprocessor_command> ::= TOK_PRAGMA <pound_pragma>;

<pound_include> ::= TOK_INCLUDE <const_string>;

<pound_define> ::= TOK_DEFINE TOK_SIMPLE_IDENT <const_value>;

<pound_pragma> ::= TOK_NAMESPACE
                    TOK_OPEN_PAREN TOK_LPWSTR TOK_CLOSE_PAREN;

<pound_pragma> ::= TOK_CLASSFLAGS
                    TOK_OPEN_PAREN TOK_LPWSTR TOK_CLOSE_PAREN;

<pound_pragma> ::= TOK_INSTANCEFLAGS
                    TOK_OPEN_PAREN TOK_LPWSTR TOK_CLOSE_PAREN;

<top_level_decl> ::= <qualifier_decl> <decl_type>;

<decl_type> ::= <typedef>;
<decl_type> ::= <instance_decl>TOK_SEMI;
<decl_type> ::= <class_decl>;

//
//  Typedef support
//

<typedef> ::= TOK_TYPEDEF <complete_type>
                TOK_SIMPLE_IDENT <opt_subrange> TOK_SEMI;
<complete_type> ::= <type> <opt_ref>;
<complete_type> ::= <enum>;

<enum> ::= TOK_ENUM TOK_OPEN_BRACE <enum_data> TOK_CLOSE_BRACE;

<enum_data> ::= <opt_name><enum_data_rest>;

<enum_data_rest> ::= <const_int> <int_enum_data_rest>;
<enum_data_rest> ::= TOK_LPWSTR <string_enum_data_rest>;

<int_enum_data_rest> ::= <>;
<int_enum_data_rest> ::= TOK_COMMA <int_enum_datum> <int_enum_data_rest>;

<int_enum_datum> ::= <opt_name><const_int>;

<string_enum_data_rest> ::= <>;
<string_enum_data_rest> ::= TOK_COMMA <string_enum_datum>
                                <string_enum_data_rest>;

<string_enum_datum> ::= <opt_name>TOK_LPWSTR;

<opt_name> ::= <>;
<opt_name> ::= TOK_SIMPLE_IDENT TOK_EQUALS;

<opt_subrange> ::= <>;
<opt_subrange> ::= TOK_SUBRANGE TOK_OPEN_PAREN <const_value> TOK_DOT TOK_DOT
                        <const_value> TOK_CLOSE_PAREN;

//
//  Class declaration
//
<class_decl> ::=
    TOK_CLASS
    TOK_SIMPLE_IDENT        // Class name
    <class_def>;

<class_def> ::=
    <as_alias>
    <opt_parent_class>
    TOK_OPEN_BRACE
    <property_decl_list>
    TOK_CLOSE_BRACE
    TOK_SEMI;
<class_def> ::= TOK_SEMI;

<property_decl_list> ::= <PropOrMeth_decl> <property_decl_list>;
<property_decl_list> ::= <>;

<opt_parent_class> ::= TOK_COLON TOK_SIMPLE_IDENT;
<opt_parent_class> ::= <>;

//
// Property/Method declarations.
//
<PropOrMeth_decl> ::= <qualifier_decl><PropOrMeth_decl2>;

<PropOrMeth_decl2> ::= <TypeAndName> <finish_PropOrMeth>;
<PropOrMeth_decl2> ::= TOK_VOID TOK_SIMPLE_IDENT <finish_meth>;

<finish_PropOrMeth> ::= <finish_prop>;
<finish_PropOrMeth> ::= <finish_meth>;

<finish_prop> ::=
    <opt_array>
    <default_value>
    TOK_SEMI;

<finish_meth> ::=
    TOK_OPEN_PAREN
    <arg_list>
    TOK_CLOSE_PAREN
    TOK_SEMI;

<TypeAndName> ::= <type> <opt_ref> TOK_SIMPLE_IDENT;

<arg_list> ::= <arg_decl> <rest_of_args>;
<arg_list> ::= <>;

<arg_decl> ::= <qualifier_decl><TypeAndName><opt_array><default_value>;

<rest_of_args> ::= TOK_COMMA <arg_decl> <rest_of_args>;
<rest_of_args> ::= <>;

<opt_ref> ::= TOK_REF;
<opt_ref> ::= <>;

<opt_array> ::= TOK_OPEN_BRACKET <opt_array_detail>;
<opt_array> ::= <>;

<opt_array_detail> ::= TOK_UNSIGNED_NUMERIC_CONST TOK_CLOSE_BRACKET;
<opt_array_detail> ::= TOK_CLOSE_BRACKET;

<default_value> ::= <>;
<default_value> ::= TOK_EQUALS <initializer>;

//
//  Instances.
//

<instance_decl> ::=
    TOK_INSTANCE TOK_OF
    <type>
    <as_alias>
    TOK_OPEN_BRACE
    <prop_init_list>
    TOK_CLOSE_BRACE;

<prop_init_list> ::= <prop_init><prop_init_list>;
<prop_init_list> ::= <>;
<prop_init> ::= <qualifier_decl> TOK_SIMPLE_IDENT TOK_EQUALS <initializer> TOK_SEMI;

<as_alias> ::= TOK_AS <alias>;
<as_alias> ::= <>;

//
// Qualifiers
//
// This allows comma delimited identifiers, or identifiers
// in functional notation with a const parm list.
//

<qualifier_decl>   ::= TOK_OPEN_BRACKET <qualifier_list> TOK_CLOSE_BRACKET;
<qualifier_decl>   ::= <>;

<qualifier_list>   ::= <qualifier><qualifier_list_rest>;

<qualifier_list_rest> ::= TOK_COMMA <qualifier><qualifier_list_rest>;
<qualifier_list_rest> ::= <>;

<qualifier>        ::= TOK_SIMPLE_IDENT <qualifier_parm>;
<qualifier>        ::= TOK_EXTERNAL;

<qualifier_parm>  ::= TOK_OPEN_PAREN <initializer_list> TOK_CLOSE_PAREN <flavor_param>;
<qualifier_parm>  ::= <flavor_param>;

<flavor_param>    ::= TOK_COLON  <flavor_list> ;
<flavor_param>    ::= <>;

<flavor_list> ::= <flavor_value> <flavor_list_rest>;

<flavor_list_rest> ::=  <FLAVOR_VALUE> <flavor_list_rest>;
<flavor_list_rest> ::= <>;

<flavor_value> ::= TOK_TOINSTANCE;
<flavor_value> ::= TOK_NOTTOINSTANCE;
<flavor_value> ::= TOK_TOSUBCLASS;
<flavor_value> ::= TOK_NOTTOSUBCLASS;
<flavor_value> ::= TOK_ENABLEOVERRIDE;
<flavor_value> ::= TOK_DISABLEOVERRIDE;
<flavor_value> ::= TOK_RESTRICTED;

/////////////////////////////////////////////////////////////////////////////
//

<type> ::= TOK_SIMPLE_IDENT;

<const_int> ::= TOK_SIGNED_NUMERIC_CONST;
<const_int> ::= TOK_UNSIGNED_NUMERIC_CONST;
<const_int> ::= TOK_SIGNED64_NUMERIC_CONST;
<const_int> ::= TOK_UNSIGNED64_NUMERIC_CONST;

<const_string> ::= TOK_LPSTR;
<const_string> ::= TOK_LPWSTR;

<const_char> ::= TOK_CHAR;
<const_char> ::= TOK_WCHAR;

<const_value> ::= <const_string>;
<const_value> ::= <const_int>;
<const_value> ::= <const_char>;
<const_value> ::= TOK_UUID;
<const_value> ::= TOK_KEYWORD_NULL;

<initializer> ::= <simple_initializer>;
<initializer> ::= TOK_EXTERNAL;
<initializer> ::= TOK_OPEN_BRACE <initializer_list> TOK_CLOSE_BRACE;
<initializer> ::= <class_decl>;

<simple_initializer> ::= <qualifier_decl><instance_decl>;
<simple_initializer> ::= <const_value>;
<simple_initializer> ::= <alias>;

<initializer_list> ::= <simple_initializer><initializer_list>;
<initializer_list> ::= TOK_COMMA <simple_initializer><initializer_list>;
<initializer_list> ::= <>;

<alias> ::= TOK_DOLLAR_SIGN TOK_SIMPLE_IDENT;

/////////////////////////////////////////////////////////////////////////
//
//  Qualifier defaults
//

<qualifier_default> ::= TOK_QUALIFIER TOK_SIMPLE_IDENT <flavor_param>;


SQL1 BNF Syntax Description

<parse> ::= SELECT <prop_list> FROM <class_name> <opt_where>;
<parse> ::= SELECT <prop_list> FROM <class_name> <tolerance> <opt_where>
                <opt_aggregation>;

<opt_where> ::= WHERE <expr>;
<opt_where> ::= <>;

<prop_list> ::= <property_name> <prop_list_2>;
<prop_list_2> ::= COMMA <prop_list>;
<prop_list_2> ::= <>;

<property_name> ::= ASTERISK;
<property_name> ::= IDENTIFIER <property_name_2>;
<property_name_2> ::= <>;
<property_name_2> ::= DOT IDENTIFIER <property_name_2>;

<class_name> ::= IDENTIFIER;
<tolerance> ::= <>;
<tolerance> ::= WITHIN <duration>;

<duration> ::= DOUBLE;

// Subexpression nesting.  This particular sequence gives
// a series of AND clauses precedence over OR clauses.

<expr> ::= <term> <expr2>;
<expr2> ::= OR <term> <expr2>;
<expr2> ::= <>;

<term> ::= <simple_expr> <term2>;
<term2> ::= AND <simple_expr> <term2>;
<term2> ::= <>;

// Simple expression types.
// ========================

<simple_expr> ::= NOT <expr>;
<simple_expr> ::= OPEN_PAREN <expr> CLOSE_PAREN;
<simple_expr> ::= <property_name> <leading_ident_expr> <finalize>;
<simple_expr> ::= VARIANT <rel_operator> <trailing_prop_expr> <finalize>;

<trailing_prop_expr> ::=  <property_name> <trailing_prop_expr2>;
<trailing_prop_expr2> ::= OPEN_PAREN <property_name> CLOSE_PAREN;
<trailing_prop_expr2> ::= <>;

<leading_ident_expr> ::= OPEN_PAREN <unknown_func_expr>;
<leading_ident_expr> ::= <comp_operator> <trailing_const_expr>;
<leading_ident_expr> ::= <equiv_operator> <trailing_or_null>;
<leading_ident_expr> ::= <is_operator> NULL;

<unknown_func_expr> ::= <property_name> CLOSE_PAREN <rel_operator> <trailing_const_expr>;
<unknown_func_expr> ::= <typed_constant> CLOSE_PAREN <rel_operator> <trailing_prop_expr>;

<trailing_or_null> ::= NULL;
<trailing_or_null> ::= <trailing_const_expr>;

<trailing_const_expr> ::= <typed_constant>;
<trailing_const_expr> ::= <property_name> OPEN_PAREN <typed_constant> CLOSE_PAREN;

<typed_constant> ::= VARIANT; // VT_R8, VT_I4, VT_BSTR
<typed_constant> ::= TRUE;
<typed_constant> ::= FALSE;

<finalize> ::= <>;
    // This is just a semantic production in the parser to allow
    // all the important code to be located in one place.

<rel_operator> ::= <equiv_operator>;
<rel_operator> ::= <comp_operator>;

<equiv_operator> ::= EQUIVALENT_OPERATOR; // =, !=
<comp_operator> ::=  COMPARE_OPERATOR;  // <=, >=, <, >, like
<is_operator> ::=  ISNOT_OPERATOR;  // IS, IS NOT

<opt_aggregation> ::= <>;
<opt_aggregation> ::= GROUP <aggregation_params> <opt_having>;
<aggregation_params> ::= <aggregate_by> <opt_aggregate_within>;
<aggregation_params> ::= <aggregate_within> <opt_aggregate_by>;

<opt_aggregate_by> ::= <>;
<opt_aggregate_by> ::= BY <aggregate_by>;

<opt_aggregate_within> ::= <>;
<opt_aggregate_within> ::= WITHIN <aggregate_within>;

<aggregate_within> ::= <duration>;
<aggregate_by> ::= <aggregate_prop_list>;

<aggregate_prop_list> ::= <prop_list>;

<opt_having> ::= <>;
<opt_having> ::= HAVING <expr>;


Object Path BNF

// Object Path BNF
// ================

// The first part of the grammar is the namespace path.

<Parse> ::= BACKSLASH <ns_or_server>;
<Parse> ::= IDENT <ns_or_class>;    // Save initial IDENT, since we don't know what it is
<Parse> ::= COLON <objref>;

// In the case of a server or ns prefix, we allow the objref portion to be missing.

<ns_or_server> ::= BACKSLASH <dot_or_ident> BACKSLASH <ns_list> <optional_objref>;
<ns_or_server> ::= <ns_list> <optional_objref>;

<dot_or_ident> ::= IDENT;
<dot_or_ident> ::= DOT;

<optional_objref> ::= COLON <objref>;
<optional_objref> ::= <>;

<ns_or_class> ::= COLON <ident_becomes_ns> <objref>;
<ns_or_class> ::= BACKSLASH <ident_becomes_ns> <ns_list> COLON <objref>;
<ns_or_class> ::= <ident_becomes_class> <objref_rest>;

<ns_list> ::= IDENT <ns_list_rest>;

<ns_list_rest> ::= BACKSLASH <ns_list>;
<ns_list_rest> ::= <>;

<ident_becomes_ns> ::= <>;      // <initial_ident> becomes a namespace
<ident_becomes_class> ::= <>;   // <initial_ident> becomes the class

// The following portion is the object reference within the namespace.

<objref> ::= IDENT <objref_rest>;  // IDENT is classname

<objref_rest> ::= EQUALS <key_const>;
<objref_rest> ::= DOT <keyref_list>;
<objref_rest> ::= <>;

<keyref_list> ::= <keyref> <keyref_term>;

<keyref_term> ::= COMMA <keyref_list>;      // Used for compound keys
<keyref_term> ::= <>;

<keyref> ::= <propname> EQUALS <key_const>;

<propname>  ::= IDENT;

<key_const> ::= STRING_CONST;
<key_const> ::= INTEGRAL_CONST;
<key_const> ::= REAL_CONST;
<key_const> ::= IDENT;      // Where IDENT is "OBJECT"
                            // This is for singleton classes


Glossary

The Web-Based Enterprise Management (WBEM) Software Development Kit (SDK) uses its own collection of terms, or nomenclature. Many of these terms are familiar to developers, but have new or altered definitions in the WBEM SDK environment. Please read the following list of definitions carefully in order to understand what is meant when these terms occur in the WBEM SDK documentation.

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


A

abstract class
A WBEM base class used only as a template for derived classes. The __Event system class, for example, is an abstract class: Real-world events are modeled using classes derived from the __Event class, and instances are created from the __Event subclasses.
Active Directory Service Interface (ADSI)
A COM-based programming interface for accessing diverse directory services on a variety of platforms. ADSI is a dual interface in that it supports both virtual function table (VTBL) access and Automation.
aggregate event
An event type generated when many events are combined into one to avoid event flooding. Thus, an aggregate event is a summary of a series of events. Aggregate events are instances of the __AggregateEvent class.
alias
A symbolic reference in either a class or instance declaration to an object located elsewhere in a MOF file. Alias names follow the same rules as instance and class names. Aliases are typically used as shortcuts to lengthy object paths. To define an alias, add the phrase "as $AliasName" to the instance or class declaration.
association class
A class that describes a relationship between two classes or between instances of two classes. The properties of an association class include pointers, or references, to the two instances. All association classes are identified by the Association qualifier. Although inclusion is not mandatory, all WBEM classes can be included in several association classes.
ASSOCIATORS OF
A WBEM Query Language (WQL) statement that supports the traversal of associations programmatically by retrieving all endpoint instances that are associated with a particular source instance.

Also see SELECT, REFERENCES OF, and WQL and Associations.

asynchronous method
A method that allows a management application to do other tasks while requests are pending and results are delivered through another thread. This improves management application performance. Asynchronous methods have an Async suffix.
B C D E F G H I J K L M N O P Q R S T U V W X Y Z


B

Backus-Naur Form (BNF)
Backus-Naur Form. A metalanguage that specifies the syntax of programming languages.
A C D E F G H I J K L M N O P Q R S T U V W X Y Z


C

CIMOM repository
A database that contains all of the information necessary to preserve the definitions of managed objects, or classes, and support the relationships between classes.
CIM schema
A framework of organizing principles used by schema designers to understand and analyze the information requirements of management applications. Also see core model, common model, and extension schema.
class provider
One of the roles of an object provider by which it retrieves and modifies a provider-specific class. Class providers do not enumerate instances, although they can be associated with instance providers to handle the enumeration. Also see property provider.
Common Information Model (CIM)
The Common Information Model (CIM) defines the model used to represent real-world managed objects. CIM uses an object-oriented paradigm, where managed objects are modeled using the concepts of classes and objects. The logical view of CIM is similar to the view of an object-oriented database.

The CIM is divided into the metamodel and the standard schema. The metamodel describes what types of entities make up the schema. It also defines how these entities can be combined into objects that represent real-world devices.

Common Information Model Object Manager (CIMOM)
A program that handles the interaction between management applications and object providers in a manner that is transparent to each type of component.
common model
The second layer of the CIM schema, which includes a series of domain-specific but platform-independent classes. The domains are systems, networks, applications, and other management-related data. The common model is derived from the core model. Also see extension schema.
consumer-filter binding
An instance of the __FilterToConsumerBinding system class that describes a relationship between a logical consumer and an event filter. A component of the permanent consumer architecture.

Also see Binding a Logical Consumer to an Event Filter, permanent consumer, event consumer provider interface, sink, and event consumer provider object.

core model
The first layer of the CIM schema, which includes the top-level classes and their properties and associations. The core model is both domain- and platform-independent. Also see common model and extension schema.
A B D E F G H I J K L M N O P Q R S T U V W X Y Z


D

domain
The class to which a property or method belongs. For example, if status is a property of Logical Device, it is said to belong to the Logical Device domain.
dynamic class
A WBEM class whose definition is supplied by a provider at runtime as needed. Dynamic classes are not stored permanently. The provider responsible for a dynamic class stores information about its location. Whenever a dynamic class is requested, CIMOM makes a call to the appropriate provider to request it. Dynamic classes can support only dynamic instances.
dynamic instance
An instance that is supplied by a provider when the need arises and is not stored in the CIMOM repository. Requests for dynamic instances are forwarded through CIMOM to the provider for the class. Supporting instances of a class dynamically allows a provider to always supply up-to-the-minute property values.
A B C E F G H I J K L M N O P Q R S T U V W X Y Z


E

event consumer
A recipient of notifications that report the occurrence of an event. Event consumers are either temporary or permanent.

Also see Event Consumers, Temporary Event Consumers, and Permanent Event Consumers.

event consumer provider interface
An instance of the __Win32EventConsumerProvider system class that is used to locate an event consumer provider object. A component of the permanent consumer architecture.

Also see Implementing an Event Consumer Provider, permanent consumer, consumer-filter binding, event filter, sink, and logical consumer.

event consumer provider object
A COM object exposing a class identifier (CLSID) and implementing the IWbemEventConsumerProvider interface. It provides access to a sink associated with a logical consumer. A component of the permanent consumer architecture.

Also see Implementing an Event Consumer Provider, permanent consumer, event consumer provider interface, event filter, consumer-filter binding, and sink.

event filter
An instance of the __EventFilter system class that describes an event type and the conditions under which a notification is delivered. A component of the permanent consumer architecture. Also see permanent consumer, event consumer provider interface, event consumer provider object, consumer-filter binding, logical consumer, and sink.
event provider
A COM-based object that generates notifications after receiving an event from an event source. The event source can be a hardware component such as a disk drive or a software component such as a database. Event providers expose a class identifier (CLSID) and support one required interface and one optional interface. All event providers must support the IWbemEventProvider interface. The optional interface is IWbemEventProviderQuerySink. Also see Event Providers.
event query
A query created by WBEM Query Language (WQL), specified by a consumer when it registers to receive event notifications. The query defines the type of event and the conditions under which it is delivered. Also see Event Queries.
extension schema
The third layer of the CIM schema, which includes platform-specific extensions of the CIM schema such as Microsoft® Windows NT®, UNIX, and Microsoft® Exchange Server. Also see common model and core model.
A B C D F G H I J K L M N O P Q R S T U V W X Y Z


G

GROUP BY
A clause in the WQL SELECT statement used to request that multiple notifications be combined into single instances of the system class __AggregateEvent.

Also see HAVING COUNT, ISA, WHERE, WITHIN, and the SELECT Statement GROUP BY Clause.


H

HAVING COUNT
A clause in the WQL SELECT statement used to set a minimum limit on the number of discrete events that produce an aggrevate event, reducing overall event traffic.

Also see GROUP BY, ISA, WHERE, WITHIN, and the SELECT Statement HAVING COUNT Clause.

A B C D E F H I J K L M N O P Q R S T U V W X Y Z


I

indication
An operation executed as a result of some action such as the creation, modification, or deletion of an object, access to an object, or modification or access to a property. Indications can also result from the passage of a specified period of time. An indication typically results in an event.
inheritance
A relationship between two classes in which all the members of the subclass are required to be members of the superclass. Any method or property supported by the superclass must also be supported by any member of the subclass. For example, Modem is a subclass of Logical Device.
instance
An object derived from a WBEM class that contains actual data. For example, in database terms, an instance is a row of data from a table.
instance provider
One of the roles of an object provider by which it retrieves, modifies, and enumerates the instances of system and/or provider-specific classes. Instance providers may also invoke methods. Also see class provider and property provider.
interface class
The class used to access a set of objects. The interface class can be an abstract class representing the scope of an enumeration.
ISA
An operator occurring within the WQL WHERE clause, asserting that an instance is a member of a particular class hierarchy.

Also see GROUP BY, HAVING COUNT, WITHIN, and the SELECT Statement ISA Operator.

A B C D E F G H J K L M N O P Q R S T U V W X Y Z


K

Kerberos
A security mechanism that provides authentication, data integrity, data privacy, and mutual authentication.
key
A value used to identify an object within the scope of a namespace, such as a drive letter in the scope of a system. A property which is a key has the key qualifier set to true.
key property
A property that provides a unique value. Key properties are designated by the Key qualifier, a standard qualifier defined by WBEM. All classes that define multiple instances must specify a key.
key qualifier
A qualifier that must be attached to every property in a class that serves as part of the key for that class.
A B C D E F G H I J L M N O P Q R S T U V W X Y Z


L

logical consumer
An instance of a class derived from the __EventConsumer system class. The properties of the class describe the action to be taken upon receipt of a notification. A component of the permanent consumer architecture. Also see permanent consumer, event consumer provider interface, event consumer provider object, event filter, consumer-filter binding, and sink.
A B C D E F G H I J K M N O P Q R S T U V W X Y Z


M

managed object
The object in the system environment that is accessed by the provider, such as a modem.
Managed Object Format (MOF)
A compiled language for defining classes and instances. The MOF compiler offers a textual means of adding data to the CIMOM repository. MOF eliminates the need to write code, thus providing a simple and fast technique for modifying the CIMOM repository.
management application
An application or Microsoft® Windows NT® service that uses information originating from one or more objects in a managed environment. To access the information, a management application makes a request to the CIMOM.
management information base
Or MIB. A database of managed objects.
metamodel
A CIM component that describes the entities and relationships representing managed objects. For example, classes, instances, and associations are included in the metamodel.
metaschema
The schema of the metamodel.
method
A function describing the behavior of a class. Including a method in a class does not guarantee an implementation of the method. The Implemented qualifier is attached to the method to indicate that an implementation is available for the class.
model
A set of classes, properties, and associations that allow the expression of information about some specific domain. For example, a Network can consist of Network Devices and Logical Networks. The Network Devices can have attachment associations to each other, and may have member associations to Logical Networks.
MOF file
A representation of a portion of a schema, defined in terms of a given namespace. Also see MOF.
multivalued
A relationship between two classes that allows more than one object to be related to a single object. For example, a system can be made up of more than one system component (such as a modem, a hard drive, and a network card).
A B C D E F G H I J K L N O P Q R S T U V W X Y Z


N

namespace
A unit for grouping classes and instances and controlling their scope and visibility. Namespaces are not physical locations; they are more like logical databases containing specific classes and instances. Namespaces are represented by the __Namespace system class or a class derived from it.
A B C D E F G H I J K L M O P Q R S T U V W X Y Z


O

object
A unit of data that is an instance of a class; a set of property values that can be uniquely identified by a key.
object path
A formatted string used to access namespaces, classes, and instances. Each object on the system has a unique path which identifies it locally or over the network. Object paths are conceptually similar to Universal Resource Locators (URL).
object provider
A COM-based component that communicates directly with managed objects and forwards the information that it receives to CIMOM for integration and interpretation. Also see class provider, instance provider, and property provider.
operation
The name, return type, and parameters supported by a method.
optional property
A property that need not have a value.
A B C D E F G H I J K L M N P Q R S T U V W X Y Z


P

permanent consumer
An event consumer whose registration lasts until it is explicitly cancelled. Permanent consumers specify their queries in instances of the __EventFilter system class. Compare temporary consumer.

Also see Permanent Consumer Architecture, Event Consumers, Temporary Event Consumers, Permanent Event Consumers, event consumer provider interface, event consumer provider object, event filter, consumer-filter binding, sink, and logical consumer.

polymorphism
The calling of a variety of operations using the same interface.

For example, a subclass can redefine the implementation of a method or property inherited from its superclass. The property or method is thereby redefined even if the superclass is used as the interface class.

Thus, the Logical Device class can define the variable status as a string, and can return the values "on" or "off." The Modem subclass of Logical Device can redefine (override) status by returning "on," "off," and "connected." If all Logical Devices are enumerated, any Logical Device that happens to be a modem can return the value "connected" for the status property.

property
A name/value pair that describes the data of the class. Property names cannot begin with a digit and cannot contain white space. Property values must have a valid Managed Object Format (MOF) data type.
property provider
One of the roles of an object provider by which it retrieves and modifies the individual property values of system and/or provider-specific classes. Also see class provider and instance provider.
provider
A COM-based component that enables management applications to access data and event notifications from a variety of sources, such as the system registry or an SNMP device. Also see class provider, instance provider, property provider, and object provider.
A B C D E F G H I J K L M N O Q R S T U V W X Y Z


Q

qualifier
A modifier containing information that describes a class, an instance, a property, a method, or a parameter. There are three categories of qualifiers: those defined by the Common Information Model (CIM), those defined by WBEM (standard qualifiers), and those defined by developers.
qualifier flavor
A WBEM-defined flag that governs the use of a qualifier. WBEM flavors describe rules that specify whether a qualifier can be propagated to derived classes and instances and whether or not a derived class or instance can override the qualifier's original value.
A B C D E F G H I J K L M N O P R S T U V W X Y Z


R

range
The class that is referenced by a reference property.
reference
A special string property type that is marked with the reference qualifier, indicating that it is a pointer to other instances.
REFERENCES OF
A WBEM Query Language (WQL) statement that supports the traversal of associations programmatically by retrieving all association instances that refer to a particular source instance.

Also see SELECT, ASSOCIATORS OF, and WQL and Associations.

required property
A property that must have a value.
A B C D E F G H I J K L M N O P Q S T U V W X Y Z


S

schema
A subset of the information available about managed objects.
SELECT
A WBEM Query Language (WQL) statement used to retrieve properties from classes. Unlike SQL, which supports queries across multiple tables, WQL supports only single class queries.

Also see ASSOCIATORS OF, REFERENCES OF, WITHIN, GROUP BY, HAVING COUNT, ISA, and the WQL SELECT Statement topic.

singleton class
A WBEM class that supports only a single instance.
sink
A COM object implementing the IWbemUnboundObjectSink interface. Also known as a physical consumer, the sink identifies a physical destination for a particular notification. A component of the permanent consumer architecture. Also see permanent consumer, event consumer provider interface, event consumer provider object, event filter, consumer-filter binding, and logical consumer.
standard provider
An object provider that is built into the WBEM SDK, as distinguished from third-party or custom providers.
standard schema
A common conceptual framework for organizing and relating the various classes representing the current operational state of a system, network, or application. The standard schema is defined by the Desktop Management Task Force (DMTF) in the Common Information Model (CIM).
static class
A WBEM class whose definition is persistent. The definition is stored in the CIMOM repository until it is explicitly deleted. CIMOM can provide definitions of static classes without the help of a provider. Static classes can support either static or dynamic instances.
static instance
An instance that is persistently stored and remains valid until explicitly deleted, even across system reboots. Static instances are manually placed in the CIMOM repository using IWbemServices::PutInstance or IWbemServices::PutInstanceAsync.
subclass
A class that is derived from a superclass by inheritance. The subclass inherits all features of its superclass, but can add new features or redefine existing ones.
subschema
A part of a schema owned by a particular organization. The Win32 schema is an example of a subschema.
superclass
Or base class. The class from which a subclass inherits.
system class
A CIMOM-defined class that is not part of the CIM. System classes support CIMOM's core features, such as event notification, security, and localization, and are automatically defined in every namespace. As with system properties, system classes are identified by a leading double underscore in their name. All system classes derive from the abstract base class __SystemClass.
system property
One of a set of properties associated with all classes and instances of classes. System properties provide information applicable to every class, such as its name, its derivation, and its namespace. As with system classes, system properties begin with a double underscore to differentiate them from properties created by applications or providers, which cannot start with a single or double underscore. Another way to identify a system property is by using the IWbemClassObject::Get method.
A B C D E F G H I J K L M N O P Q R T U V W X Y Z


T

temporary consumer
A consumer that receives event notifications only while it is active. Thus, its registration is temporary. Temporary consumers specify their queries in the bstrQuery parameter when they call either IWbemServices::ExecNotificationQuery or IWbemServices::ExecNotificationQueryAsync. Compare permanent event consumer.

Also see Event Consumers, Temporary Event Consumers, and Permanent Event Consumers.

timer event
An event that either occurs once at a particular time of day (absolute timer event) or repeatedly at regular intervals (interval timer event). A timer event differs from other events in that it requires explicit action by the consumer in order for it to occur. Notifications of timer events are sent by CIMOM. Also see Timer Events.
type
A set of values from which a property can take its value. For example, a string property takes its value from an ordered series of data values that typically denote printable characters.
A B C D E F G H I J K L M N O P Q R S U V W X Y Z


V

virtual function table (VTBL)
A table of function pointers, such as an implementation of a class. The pointers in the VTBL point to the members of the interfaces that an object supports.
A B C D E F G H I J K L M N O P Q R S T U W X Y Z


W

WBEM class
A template for a type of managed object. WBEM classes define the basic units of management. Each class is a template for a type of managed object, and all instances of the type use the template. For example, the __Win32Provider class is a template for all object providers.
WBEM event
An instance of an event class, generated to notify a registered client of a particular occurrence.

Events arising in the real world are extrinsic events, while events that reflect changes in the CIMOM repository are intrinsic events.

After an event, an event provider generates an event notification, which is delivered by CIMOM to one or more registered recipients, known as event consumers.

WBEM Query Language (WQL)
A dialect of structured query language (SQL) with extensions to support WBEM event notification and other WBEM-specific features.

Also see REFERENCES OF, ASSOCIATORS OF, GROUP BY, HAVING COUNT, ISA, WHERE, WITHIN, and the WBEM Query Language.

WHERE
A clause in the WQL SELECT statement that constrains a query such that subsets of class instances can be selected.

Also see GROUP BY, HAVING COUNT, ISA, WHERE, WITHIN, and the WQL SELECT Statement.

Win32 schema
A Microsoft® extension to the CIM schema that contains definitions for classes and instances for objects that exist in a typical Win32 environment.
Windows Driver Model (WDM)
An important low-level component that provides access between Windows Management Instrumentation (WMI) and hardware devices.
Windows Management Instrumentation (WMI)
A set of extensions to the Windows Driver Model (WDM). WMI provides an operating system interface through which instrumented components can provide information and notification.
WITHIN
A clause in the WQL SELECT statement that constrains the granularity of event delivery time and helps CIMOM simulate events by sampling when no event provider exists for a given class.

Also see GROUP BY, HAVING COUNT, ISA, WHERE, the WQL SELECT Statement, and the SELECT Statement WITHIN Clause.

A B C D E F G H I J K L M N O P Q R S T U V X Y Z


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.


(Untitled)

Fatal Error 201

<201, Fatal>: "<fileName>:<line#>: Syntax Error in the SYNTAX clause, Last token read is <token>"
Module syntax error, OBJECT-TYPE macro invocation. There is an error in the SYNTAX clause of the MIB OBJECT-TYPE definition.


(Untitled)

Fatal Error 202

<202, Fatal>: "<fileName>:<line#>: Syntax Error in the ACCESS clause, Last token read is <token>"
Module syntax error, OBJECT-TYPE macro invocation. There is an error in the ACCESS clause of the MIB OBJECT-TYPE definition.


(Untitled)

Fatal Error 203

<203, Fatal>: "<fileName>:<line#>: Syntax Error in the STATUS clause, Last token read is <token>"
Module syntax error, OBJECT-TYPE macro invocation. There is an error in the STATUS clause of the MIB OBJECT-TYPE definition.


(Untitled)

Fatal Error 204

<204, Fatal>: "<fileName>:<line#>: Syntax Error in the DESCRIPTION clause, Last token read is <token>"
Module syntax error, OBJECT-TYPE or TRAP-TYPE macro invocation. There is an error in the DESCRIPTION clause of the MIB OBJECT-TYPE or TRAP-TYPE definition.


(Untitled)

Fatal Error 205

<205, Fatal>: "<fileName>:<line#>: Syntax Error in the REFERENCE clause, Last token read is <token>"
Module syntax error, OBJECT-TYPE or TRAP-TYPE macro invocation. There is an error in the REFERENCE clause of the MIB OBJECT-TYPE or TRAP-TYPE definition.


(Untitled)

Fatal Error 206

<206, Fatal>: "<fileName>:<line#>: Syntax Error in the INDEX clause, Last token read is <token>"
Module syntax error, OBJECT-TYPE macro invocation. There is an error in the INDEX clause of the MIB OBJECT-TYPE definition.


(Untitled)

Fatal Error 207

<207, Fatal>: "<fileName>:<line#>: Syntax Error in the DEFVAL clause, Last token read is <token>"
Module syntax error, OBJECT-TYPE macro invocation. There is an error in the DEFVAL clause of the MIB OBJECT-TYPE definition.


(Untitled)

Fatal Error 209

<209, Fatal>:"<fileName>:<line#>: Syntax Error in the ENTERPRISE clause. Last token read is <token>"
Module syntax error, TRAP-TYPE macro invocation. There is a syntax error in the ENTERPRISE clause of the MIB TRAP-TYPE definition.


(Untitled)

Fatal Error 210

<210, Fatal>:"<fileName>:<line#>: Syntax Error in the VARIABLES clause. Last token read is <token>"
Module syntax error, TRAP-TYPE macro invocation. There is a syntax error in the VARIABLES clause of the MIB TRAP-TYPE definition.


(Untitled)

Fatal Error 212

<212, Fatal>: "<fileName>:<line#>: Syntax Error in SEQUENCE definition. Last token read is <token>"
Module syntax error in type assignment. There is an error between the left and right braces of a SEQUENCE construct, which amounts to a syntax error in a MIB type assignment.


(Untitled)

Fatal Error 213

<213, Fatal>: "<fileName>:<line#>: Syntax Error in Object Identifier value. Last token read is <token>"
Module syntax error in value assignment. There is an error between the left and right braces of an object identifier value.


(Untitled)

Fatal Error 214

<214, Fatal>: "<fileName>:<line#>: Syntax Error in the list of symbols in IMPORTS. Last token read is <token>"
Module syntax error in the IMPORTS section.


(Untitled)

Fatal Error 215

<215, Fatal>: "<fileName>:<line#>: Syntax Error in IMPORTS (missing module name?). Last token read is <token>"
Module syntax error in the IMPORTS section.


(Untitled)

Fatal Error 216

<216, Fatal>: "<fileName>:<line#>: Syntax Error in the IMPORTS section. Last token read is <token>"
Module syntax error in the IMPORTS section.


(Untitled)

Fatal Error 217

<217, Fatal>: "<fileName>:<line#>: Syntax error in INTEGER Enumeration. Last token read is <token>"
Any module syntax error between the left and right braces of a MIB enumeration definition generates this message.


(Untitled)

Fatal Error 218

<218, Fatal>: "<fileName>:<line#>: Syntax Error in sub-type specification. Last token read is <token>"
Any module syntax error between the parentheses in a sub-type specification generates this message.


(Untitled)

Fatal Error 219

<219, Fatal>:"<fileName>:<line#>: Syntax Error in the SIZE specification. Last token read is <token>".
Any module syntax error in the SIZE clause between the left and right parentheses generates this message.


(Untitled)

Fatal Error 220

<220, Fatal>:"<fileName>:<line#>: OBJECT-TYPE invocation of SNMPv2SMI not allowed"
Module syntax error. You have used the SNMPv2C-specific OBJECT-TYPE invocation in the MIB, but have specified the /v1 switch, which requires strict conformance to SNMPv1 syntax.


(Untitled)

Fatal Error 222

<222, Fatal>: "<fileName>:<line#>: NOTIFICATION-TYPE not allowed in SNMPv1 SMI"
Module syntax error. You have used the SNMPv2C-specific NOTIFICATION-TYPE in the MIB, but have specified the /v1 switch, which requires strict conformance to SNMPv1 syntax.


(Untitled)

Fatal Error 223

<223, Fatal>: "<fileName>:<line#>: MODULE-IDENTITY not allowed in SNMPv1 SMI"
Module syntax error. You have used the SNMPv2C-specific MODULE IDENTITY in the MIB, but have specified the /v1 switch, which requires strict conformance to SNMPv1 syntax.


(Untitled)

Fatal Error 224

<224, Fatal>: "<fileName>:<line#>: OBJECT-IDENTITY not allowed in SNMPv1 SMI"
Module syntax error. You have used the SNMPv2C-specific OBJECT-IDENTITY in the MIB, but have specified the /v1 switch, which requires strict conformance to SNMPv1 syntax.


(Untitled)

Fatal Error 225

<225, Fatal>: "<fileName>:<line#>: TEXTUAL-CONVENTION not allowed in SNMPv1 SMI"
Module syntax error. You have used the SNMPv2C-specific TEXTUAL-CONVENTION in the MIB, but have specified the /v1 switch, which requires strict conformance to SNMPv1 syntax.


(Untitled)

Fatal Error 226

<226, Fatal>: "<fileName>:<line#>: OBJECT-GROUP not allowed in SNMPv1 SMI"
Module syntax error. You have used the SNMPv2C-specific OBJECT-GROUP in the MIB, but have specified the /v1 switch, which requires strict conformance to SNMPv1 syntax.


(Untitled)

Fatal Error 227

<227, Fatal>: "<fileName>:<line#>: NOTIFICATION-GROUP not allowed in SNMPv1 SMI"
Module syntax error. You have used the SNMPv2C-specific NOTIFICATION-GROUP in the MIB, but have specified the /v1 switch, which requires strict conformance to SNMPv1 syntax.


(Untitled)

Fatal Error 228

<228, Fatal>: "<fileName>:<line#>: MODULE-COMPLIANCE not allowed in SNMPv1 SMI"
Module syntax error. You have used the SNMPv2C-specific MODULE-COMPLIANCE in the MIB, but have specified the /v1 switch, which requires strict conformance to SNMPv1 syntax.


(Untitled)

Fatal Error 229

<229, Fatal>: "<fileName>:<line#>: AGENT-CAPABILITIES not allowed in SNMPv1 SMI"
Module syntax error. You have used the SNMPv2C-specific AGENT-CAPABILITIES in the MIB, but have specified the /v1 switch, which requires strict conformance to SNMPv1 syntax.


(Untitled)

Fatal Error 232

<232, Fatal>:"<fileName>:<line#>:Invocation of SNMPv1 SMI OBJECT-TYPE disallowed"
Module syntax error. You have used the SNMPv1-specific OBJECT-TYPE invocation in the MIB, but have specified the /v2c switch, which requires strict conformance to SNMPv2C syntax.


(Untitled)

Fatal Error 233

<233, Fatal>: "<fileName>:<line#>: Invocation of SNMPv1 SMI TRAP-TYPE disallowed"
Module syntax error. You have used the SNMPv1-specific TRAP-TYPE invocation in the MIB, but have specified the /v2c switch, which requires strict conformance to SNMPv2C syntax.


(Untitled)

Fatal Error 234

<234, Fatal>:"<fileName>:<line#>: MODULE-IDENTITY invocation is allowed only immediately after the IMPORTS section."
Module syntax error. The MODULE-IDENTITY invocation is misplaced.


(Untitled)

Fatal Error 236

<236, Fatal>: "<fileName>:<line#>: Number does not fit into the 32 bit representation used by the compiler"
Module syntax error in value assignment. There is a MIB value assignment error in which an integer value is so large that it requires more than 32 bits to represent it.


(Untitled)

Fatal Error 282

<282, Fatal>: "<fileName>:<line#>: Syntax error. Last token read is <token>"
This error occurs when the compiler knows that some syntax error has occurred, but is unable to give any more specific information on the syntax error.


(Untitled)

Fatal Error 283

<283, Fatal>: "<fileName>:<line##>: Unrecognized character <character> in input"
There is an unrecognized character in the input. Typically, unrecognized characters are ignored, and this error message reports the first unrecognized character.


(Untitled)

Warning 1004

<1004, Warning>: "<fileName>:<line#>: OBJECT-TYPE <identifier>, whose syntax resolves to one of the Counter types does not end with the letter 's' "
OBJECT-TYPE macro invocation module semantic warning. The identifier for an object of SYNTAX Counter (SNMPv1) or Counter32 and Counter64 (SNMPv2C) must be plural.

This warning can occur when compiling either an SNMPv1 or SNMPv2C MIB.


(Untitled)

Warning 1005

<1005, Warning>: "<fileName>:<line#>: OBJECT-TYPE with SYNTAX "SEQUENCE OF", should have an ACCESS clause "not-accessible."
OBJECT-TYPE macro invocation module semantic warning. A table or conceptual row (SEQUENCE OF or SEQUENCE object types, respectively) must be "not-accessible."

This warning can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Warning 1014

<1014, Warning>: "<fileName>:<line#>: Sub-identifier of value 0 not recommended in OIDs"
OBJECT-TYPE macro invocation module semantic warning. It is recommended that no object in an Internet Standard MIB use a sub-identifier of zero in its OBJECT IDENTIFIER.

This warning can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Warning 1027

<1027, Warning>: "<fileName><line#>: Imported symbol <identifier> unused"
IMPORTS section module semantic warning, specific to neither SNMPv1 nor SNMPv2C. A warning is issued for every unused imported symbol.


(Untitled)

Warning 1031

<1031, Warning>: "<fileName>:<line#>: Standard symbol <identifier> should be imported from module <identifier>. Assuming the standard definition."
IMPORTS section module semantic warning, specific to neither SNMPv1 nor SNMPv2C. If an SNMP identifier known to the compiler is in the IMPORTS section, then the module from which it is imported must be one of the standard modules.

Certain commonly used IMPORTS are "assumed knowledge" on the part of the compiler. It is unnecessary for the compiler to require access to other information modules to resolve these.

The built-in SNMPv1 and SNMPv2C IMPORTS are described in the following tables.

Built-in SNMPv1 IMPORTS

Import Class | Module | Instances
ASN.1 Value | RFC1155-SMI | internet, directory, management, experimental, private, enterprises
 | RFC1213-MIB | mib-2, ip, interfaces, transmission
ASN.1 Type | RFC1155-SMI | NetworkAddress, IpAddress, Counter, Gauge, TimeTicks, Opaque
 | RFC1213-MIB | DisplayString, PhysAddress
ASN.1 Macro | RFC-1212 | OBJECT-TYPE
 | RFC-1215 | TRAP-TYPE

Built-in SNMPv2C IMPORTS

Import Class | Module | Instances
ASN.1 Value | SNMPv2-SMI | org, dod, internet, directory, mgmt, mib-2, transmission, experimental, private, enterprises, security, snmpv2, snmpDomains, snmpProxys, snmpModules
 | SNMPv2-TM | rfc1157Proxy
Object Identity | SNMPv2-SMI | zeroDotZero
 | SNMPv2-TM | snmpUDPDomain, snmpCLNSDomain, smnpCONSDomain, snmpDDPDomain, snmpIPXDomain, rfc1157Domain
ASN.1 Type | SNMPv2-SMI | Integer32, IpAddress, Counter32, TimeTicks, Opaque, Counter64, Unsigned32, Gauge32
ASN.1 Macro | SNMPv2-SMI | MODULE-IDENTITY, OBJECT-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE
 | SNMPv2-CONF | OBJECT-GROUP, NOTIFICATION-GROUP, MODULE-COMPLIANCE, AGENT-CAPABILITIES
 | SNMPv2-TC | TEXTUAL-CONVENTION
Textual Convention | SNMPv2-TC | DisplayString, PhysAddress, MacAddress, TruthValue, TestAndIncr, AutonomousType, InstancePointer, VariablePointer, RowPointer, RowStatus, TimeStamp, TimeInterval, DateAndTime, StorageType, Tdomain, Taddress
 | SNMPv2-TM | SnmpUDPAddress, SnmpOSIAddress, SnmpNBPAddress, SnmpIPXAddress


(Untitled)

Warning 1034

<1034, Warning>: "<fileName><line#>: A value of 0 disallowed in an enumeration"
Module semantic warning in an enumeration, specific to neither SNMPv1 nor SNMPv2C. It is recommended that a named value of zero not be used in an enumeration.


(Untitled)

Warning 1036

<1036, Warning> "<fileName><line#>: Value in enumeration does not resolve to a positive integer"
Module semantic warning in an enumeration, specific to neither SNMPv1 nor SNMPv2C. A negative value is not allowed in an enumeration.


(Untitled)

Warning 1043

<1043, Warning>: "<fileName>:<line#>: OBJECT-TYPE with SYNTAX "SEQUENCE", should have an ACCESS clause "not-accessible."
OBJECT-TYPE macro invocation module semantic warning. A table or conceptual row (SEQUENCE OF or SEQUENCE object types, respectively) must be "not-accessible."

This warning can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Warning 1045

<1045, Warning>: "<fileName><lineReference to standard symbol <symbolName> assumed to be for the definition as in <moduleName>. Use the "module.symbol" notations, if you want to refer to the definition in the current module"
Module semantic warning, specific to neither SNMPv1 nor SNMPv2C. A symbol known to the compiler has been redefined, and is being referenced. The compiler assumes the standard definition of the symbol. Therefore, to use a redefinition of the standard symbol, you must use the "Module.Symbol" notation.


(Untitled)

Warning 1046

<1046, Warning>: "<fileName><line#>: <symbol> undefined. Assuming standard definition."
Module semantic warning, specific to neither SNMPv1 nor SNMPv2C. A symbol known to the compiler must not be redefined or used without being imported.


(Untitled)

Warning 1047

<1047, Warning>: "<fileName><line#>: Type definition <symbol> defined but not referenced"
Module semantic warning, specific to neither SNMPv1 nor SNMPv2C. All value assignments and type definitions must be referenced somewhere.


(Untitled)

Warning 1048

<1048, Warning>: "<fileName><line#>: Value definition <symbol< defined but not referenced"
Module semantic warning, specific to neither SNMPv1 nor SNMPv2C. All value assignments and type definitions must be referenced somewhere.


(Untitled)

Warning 1071

<1071, Warning>: "<fileName><line#>: Symbol <identifier> not present in imported module <identifier>"
Module semantic warning about cross-referencing, specific to neither SNMPv1 nor SNMPv2C. A symbol imported from a module does not resolve to anything in that module. Even though that module is specified in the input, this warning appears.


(Untitled)

Warning 1072

<1072, Warning>: "<fileName>:<line#> OBJECT-TYPE <name> is a descendant of OBJECT-TYPE <name> of module <name>"
OBJECT-TYPE macro invocation module semantic warning. A scalar object cannot have any descendant objects.

This warning can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Warning 1080

<1080, Warning>: "<fileName><line#>: MIB Module <moduleName>, from which symbol <symbolName> is imported, is not present in input"
Module semantic warning about cross-referencing, specific to neither SNMPv1 nor SNMPv2C. If one of the modules in the IMPORTS section of the main module or a subsidiary module does not exist but symbols from this module are not referenced, this warning appears.


(Untitled)

Warning 1085

<1085, Warning>: "<fileName><line#>: No groups found in module <name>. Could not fabricate MODULE-IDENTITY. Attempt to load the module into the SMIR will fail.
Module semantic SNMPv1-specific warning. This error is generated if no object groups are found in a module.


(Untitled)

Warning 1086

<1086, Warning>: "<fileName><line#>: No groups found in module <name>.
Module semantic SNMPv1-specific warning. This error is generated if no object groups are found in a module.


(Untitled)

Warning 1091

<1091, Warning>: "<fileName>:<line#> IMPLIED clause is not allowed for fixed size objects"
OBJECT-TYPE macro invocation SNMPv2C-specific module semantic warning. The IMPLIED keyword can only be present for an object having a variable-length syntax, such as an OBJECT IDENTIFIER or variable-length OCTET STRING, in the INDEX clause.


(Untitled)

Fatal Error 1001

<1001, Fatal>: "<fileName>:<line#>: SYNTAX clause of OBJECT-TYPE doesn't resolve to allowed types"
OBJECT-TYPE macro invocation module semantic error. The SYNTAX clause of the OBJECT-TYPE macro must resolve to a type or subtype, formed by using the SIZE or range specification that the SNMPv1 or SNMPv2C SMI allows. If this is not the case, fatal error 1001 is reported.

This error may occur when compiling either an SNMPv1 or SNMPv2C MIB.

Types allowed by the SNMPv1 SMI are:

  • INTEGER
  • NULL
  • OCTET STRING
  • OBJECT IDENTIFIER
  • NetworkAddress
  • IpAddress
  • Counter
  • Gauge
  • TimeTicks
  • Opaque
  • DisplayString
  • PhysAddress

    Types allowed by the SNMPv2C SMI are:

  • INTEGER
  • OCTET STRING
  • OBJECT IDENTIFIER
  • BITS
  • Integer32
  • IpAddress
  • Counter32
  • TimeTicks
  • Opaque
  • Counter64
  • Unsigned32
  • DisplayString
  • PhysAddress
  • MacAddress
  • TruthValue
  • TestAndIncr
  • AutonomousType
  • InstancePointer
  • VariablePointer
  • RowPointer
  • RowStatus
  • TimeStamp
  • TimeInterval
  • DateAndTime
  • StorageType
  • Tdomain
  • Taddress


(Untitled)

Fatal Error 1002

<1002, Fatal>: "<fileName>:<line#>: Invalid ACCESS clause <clause>"
OBJECT-TYPE macro invocation module semantic error. For SNMPv1, the ACCESS clause of the OBJECT-TYPE macro must be "read-only," "write-only," "read-write," or "not-accessible."

For SNMPv2C, the MAX-ACCESS clause must be "read-only", "read-create," "read-write," or "not-accessible."


(Untitled)

Fatal Error 1003

<1003, Fatal>: "<fileName>:<line#>: Invalid STATUS clause <clause>"
OBJECT-TYPE macro invocation module semantic error. For SNMPv1, the STATUS clause of an OBJECT-TYPE macro invocation must be "mandatory," "optional," "obsolete," or "deprecated."

For SNMPv2C, the STATUS clause of an OBJECT-TYPE macro invocation must be "current," "deprecated," or "obsolete."


(Untitled)

Fatal Error 1006

<1006, Fatal>: "<fileName>:<line#> OBJECT-TYPE <identifier>, which is of SYNTAX SEQUENCE, does not have an INDEX or AUGMENTS clause"
OBJECT-TYPE macro invocation module semantic error. For SNMPv1, the INDEX clause must be present for an OBJECT-TYPE definition whose SYNTAX resolves to a SEQUENCE type.

For SNMPv2C, either the INDEX or the AUGMENTS clause must be present for a conceptual row declaration.


(Untitled)

Fatal Error 1008

<1008, Fatal>: "<fileName>:<line#>: OBJECT-TYPE <identifier>, which is of SYNTAX "SEQUENCE" has not been referenced"
OBJECT-TYPE macro invocation module semantic error. An OBJECT-TYPE with the SYNTAX clause as a SEQUENCE type must figure in the SYNTAX clause of exactly one OBJECT-TYPE invocation that stands for a table declaration, that is, an object with the SYNTAX clause as a SEQUENCE OF type. The <line#> parameter refers to the second point of reference.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1012

<1012, Fatal>: "<fileName>:<line#> An INDEX or AUGMENTS clause is required only for SEQUENCE OBJECT-TYPES"
OBJECT-TYPE macro invocation module semantic error. An INDEX clause must only be present in an OBJECT-TYPE definition whose SYNTAX resolves to a SEQUENCE type.

This error can occur when compiling either an SNMPv1 or SNMPv2C MIB.


(Untitled)

Fatal Error 1013

<1013, Fatal>: "<fileName><line#>: <identifier> should resolve to a SEQUENCE type"
OBJECT-TYPE macro invocation module semantic error. A type used in the "SEQUENCE OF" construct must resolve to a SEQUENCE type.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1015

<1015, Fatal>: "<fileName>:<line#>: OBJECT-TYPEs <identifier> from module <identifier> and <identifier> from module <identifier> are assigned the same OID values"
OBJECT-TYPE macro invocation module semantic error. Two OBJECT-TYPE invocations (in the same or different modules) must not be assigned the same Object Identifier value.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1016

<1016, Fatal>: "<fileName>:<line#>: Value in the DEFVAL clause does not match the type in the SYNTAX clause"
OBJECT-TYPE macro invocation module semantic error. A value in a DEFVAL clause must be a value of the type mentioned in the SYNTAX clause.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1018

<1018, Fatal>: "<fileName><line#>: <symbol> in ENTERPRISE clause of TRAP-TYPE does not resolve to an OID value"
TRAP-TYPE macro invocation, SNMPv1-specific module semantic error. The symbol used in the ENTERPRISE clause of a TRAP-TYPE macro invocation must resolve to an Object Identifier value.


(Untitled)

Fatal Error 1030

<1030, Fatal>:"<fileName><line#>: Symbol <identifier> not imported from Module <identifier>"
IMPORTS section module semantic error, specific to neither SNMPv1 nor SNMPv2C. You have used the "Module.Symbol" notation, but the symbol has not been imported from the specified module in the IMPORTS section.


(Untitled)

Fatal Error 1032

<1032, Fatal>: "<fileName><line#>: Duplicate value <value> in enumeration"
Module semantic error in an enumeration, specific to neither SNMPv1 nor SNMPv2C. There must not be any duplicate values. The <line#> parameter is the position of the recurrence of the name/value.


(Untitled)

Fatal Error 1033

<1033, Fatal>: "<fileName><line#>: Duplicate name <identifier> in enumeration"
Module semantic error in an enumeration, specific to neither SNMPv1 nor SNMPv2C. There must not be any duplicate names. The <line#> parameter is the position of the recurrence of the name/value.


(Untitled)

Fatal Error 1037

<1037, Fatal>: "<fileName><line#>: Identifier <identifier> does not resolve to OCTET STRING or Opaque types"
Module semantic error in SIZE specification, specific to neither SNMPv1 nor SNMPv2C. The symbol used in a SIZE specification must resolve to OCTET STRING or Opaque.


(Untitled)

Fatal Error 1011

<1011, Fatal>: "<fileName>:<line#> the SYNTAX of member <identifier> of SEQUENCE, <identifier>, differs from the SYNTAX clause of the OBJECT-TYPE"
OBJECT-TYPE macro invocation module semantic error. An element of a SEQUENCE must be same as the type in the SYNTAX clause of the OBJECT-TYPE definition. The <line#> parameter is the line of the SYNTAX clause of the OBJECT-TYPE definition.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1020

<1020, Fatal>: "<fileName><line#>: Value assigned to TRAP-TYPE <identifier> does not resolve to a positive integer"
TRAP-TYPE macro invocation, SNMPv1-specific module semantic error. A symbol used in specifying the trap value does not resolve to a positive integer.


(Untitled)

Fatal Error 1021

<1021, Fatal>: "<fileName><line#>: Identifier <identifier> in the VARIABLES clause of TRAP-TYPE does not resolve to a scalar OBJECT-TYPE"
TRAP-TYPE macro invocation, SNMPv1-specific module semantic error. Each item in the list of variables used in the VARIABLES clause of a TRAP-TYPE macro invocation must resolve to the name of a scalar OBJECT-TYPE instance.


(Untitled)

Fatal Error 1022

<1022, Fatal>: "<fileName><line#>: Value does not resolve to type <type>"
Value assignment module semantic error, specific to neither SNMPv1 nor SNMPv2C. The value on the RHS of an INTEGER, NULL, OCTET STRING, or OBJECT IDENTIFIER value assignment is of the wrong type.


(Untitled)

Fatal Error 1023

<1023, Fatal>: "<fileName><line#>: Identifier <identifier> does not resolve to the type <identifier>"
Value assignment module semantic error, specific to neither SNMPv1 nor SNMPv2C. A symbol (value reference) on the RHS of an INTEGER, NULL, OCTET STRING, or OBJECT IDENTIFIER value assignment does not resolve to the right type.


(Untitled)

Fatal Error 1024

<1024, Fatal>: "<fileName><line#>: Negative integer in OID value definition"
Value assignment module semantic error, specific to neither SNMPv1 nor SNMPv2C. All values in an OID component list must be non-negative (preferably positive) integers.


(Untitled)

Fatal Error 1025

<1025, Fatal>: "Identifier <identifier> in OID value does not resolve to a positive integer"
Value assignment module semantic error, specific to neither SNMPv1 nor SNMPv2C. All values in an OID component list must be non-negative (preferably positive) integers.


(Untitled)

Fatal Error 1026

<1026, Fatal>: "<fileName><line#>: Identifier <identifier> in OID value neither resolves to an OID value nor a positive integer"
Value assignment module semantic error, specific to neither SNMPv1 nor SNMPv2C. The first component used in an OID value must resolve to an OID value or an INTEGER.


(Untitled)

Fatal Error 1028

<1028, Fatal>: "Module <identifier> not imported in the IMPORTS section"
IMPORTS section module semantic error, specific to neither SNMPv1 nor SNMPv2C. A module name used in referencing a symbol must either be present in the IMPORTS clause, or be the name of the current module.


(Untitled)

Fatal Error 1029

<1029, Fatal>: "<fileName><line#>: Current module <identifier> cannot be imported"
IMPORTS section module semantic error, specific to neither SNMPv1 nor SNMPv2C. The name of the current module also figures in the IMPORTS list.


(Untitled)

Fatal Error 1038

<1038, Fatal>: "<fileName><line#>: Identifier <identifier> does not resolve an INTEGER or Gauge type"
Module semantic error in range specification. This error can occur in either SNMPv1 or SNMPv2C.

In SNMPv1, the symbol used in a Range specification must resolve to INTEGER or Gauge.

In SNMPv2C, the symbol used in a Range specification must resolve to INTEGER, Gauge32, Integer32, or Unsigned32.


(Untitled)

Fatal Error 1039

<1039, Fatal>:<fileName><line#>: Negative value used in SIZE specification"
Module semantic error in SIZE specification, specific to neither SNMPv1 nor SNMPv2C. Any value used in specifying the SIZE must be non-negative.


(Untitled)

Fatal Error 1040

<1040, Fatal>: "<fileName><line#>: Identifier <identifier> in SIZE specification does not resolve to a non-negative integral value"
Module semantic error in range or size specification, specific to neither SNMPv1 nor SNMPv2C. Any symbol used in specifying a value in a SIZE specification resolves to a non-negative value.


(Untitled)

Fatal Error 1041

<1041, Fatal>: "<fileName><line#>: Identifier <identifier> in range specification does not resolve to an integral value".
Module semantic error in range or size specification, specific to neither SNMPv1 nor SNMPv2C. The symbol used in a SIZE specification must resolve to OCTET STRING or Opaque. Any value used in specifying a range must be an integer.


(Untitled)

Fatal Error 1042

<1042, Fatal>: "<fileName><line#>: Upper bound of range specification is less than the lower bound"
Module semantic error in range or size specification, specific to neither SNMPv1 nor SNMPv2C. The symbol used in a SIZE specification must resolve to OCTET STRING or Opaque. The lower bound of a range or SIZE specification must be no greater than the upper bound.


(Untitled)

Fatal Error 1044

<1044, Fatal>: "<fileName><line#>: Redefinition of symbol <identifier>"
Module semantic error, specific to neither SNMPv1 nor SNMPv2C. Redefinition of object descriptors, macro invocations, and ASN.1 types cause an error.


(Untitled)

Fatal Error 1049

<1049, Fatal>: "<fileName>:<line#>: DEFVAL clause not allowed for OBJECT-TYPE with SYNTAX NetworkAddress."
OBJECT-TYPE macro invocation SNMPv1-specific module semantic error. The DEFVAL clause is not allowed for an OBJECT-TYPE whose SYNTAX clause resolves to NetworkAddress.


(Untitled)

Fatal Error 1051

<1051, Fatal>: "<fileName>:<line#>: Ambiguous reference to symbol <identifier>"
IMPORTS section module semantic error, specific to neither SNMPv1 nor SNMPv2C. Each object descriptor corresponding to an object in an Internet Standard MIB must be unique. Since enterprise MIBs can have common object descriptors, such descriptors imported from two modules must be used unambiguously in the MIB module by using the notation "module.descriptor."


(Untitled)

Fatal Error 1054

<1054, Fatal>: "<fileName>:<line#>: <identifier> in INDEX clause does not resolve to one of the allowed types"
OBJECT-TYPE macro invocation module semantic error. The type of an object in the INDEX clause, or any type specified in the INDEX clause, must resolve to a scalar type, that is, a non-SEQUENCE or non-SEQUENCE OF type. Any type specified in the INDEX clause must also resolve to one of these.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1055

<1055, Fatal>:"<fileName>:<line#>: SYNTAX of INDEX OBJECT-TYPE <identifier>, does not resolve to one of the allowed types"
OBJECT-TYPE macro invocation module semantic error. The type of an object in the INDEX clause, or any type specified in the INDEX clause, must resolve to a scalar type, that is, a non-SEQUENCE or non-SEQUENCE OF type.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1063

<1063, Fatal<: "<fileName><line#>: Upper bound of SIZE specification is less than the lower bound"
Module semantic error in SIZE specification, specific to neither SNMPv1 nor SNMPv2C. The symbol used in a SIZE specification must resolve to OCTET STRING or Opaque. The lower bound of a range or SIZE specification must be no greater than the upper bound.


(Untitled)

Fatal Error 1064

<1064, Fatal>: "<fileName>:<line#>: SEQUENCE item <identifier> does not resolve to an OBJECT-TYPE"
Type assignment module semantic error, specific to neither SNMPv1 nor SNMPv2C. All the individual elements of a SEQUENCE declaration must resolve to an OBJECT-TYPE.


(Untitled)

Fatal Error 1070

<1070, Fatal>: "<fileName><line#>: MIB Module <moduleName>, from which symbol <symbolName> is imported, is not present in input"
Module semantic error in cross-referencing, specific to neither SNMPv1 nor SNMPv2C. If one of the modules in the IMPORTS section of the main module or a subsidiary module does not exist and one or more symbols from this module are actually referenced, this fatal error occurs.


(Untitled)

Fatal Error 1074

<1074, Fatal>: "<fileName>:<line#> SEQUENCE (Conceptual row) OBJECT-TYPE <name> does not have a SEQUENCE OF (Conceptual table) OBJECT-TYPE as its parent.
OBJECT-TYPE macro invocation module semantic error. Every row object must have a table object as its parent.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1075

<1075, Fatal>:"<fileName>:<line#>: OBJECT-TYPE <name> cannot be a child of table OBJECT-TYPE <name> of module <name> unless it is in the SEQUENCE of the latter"
OBJECT-TYPE macro invocation module semantic error. Every SEQUENCE object must have exactly the same objects that are mentioned in the SEQUENCE type definition as its children. Similarly, every SEQUENCE OF object must have exactly one child.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1077

<1077, Fatal>: "<fileName>:<line#>: The syntax of table OBJECT-TYPE <name> is not the SEQUENCE OF the syntax of the child OBJECT-TYPE <name> of module <name>.
OBJECT-TYPE macro invocation module semantic error. The syntax clause of a table object must be the "SEQUENCE OF" of the syntax of the row object.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1079

<1079, Fatal>:"fileName>:<line#>: OBJECT-TYPE <name> is an extra child of OBJECT-TYPE <name> of module <name>"
OBJECT-TYPE macro invocation module semantic error. Every SEQUENCE OF object must have exactly one child.

This error can occur in either SNMPv1 or SNMPv2C.


(Untitled)

Fatal Error 1081

<1081, Fatal>: "<fileName>line#>: Symbol <identifier> not present in imported module <identifier>"
Module semantic error in cross-referencing, specific to neither SNMPv1 nor SNMPv2C. A symbol imported from a module does not resolve to anything in that module. If that symbol is actually referenced in the MIB, this error occurs.


(Untitled)

Fatal Error 1082

<1082, Fatal>: "<fileName>:<line#>: Invalid STATUS clause <clause>"
OBJECT-IDENTITY macro invocation, SNMPv2C-specific module semantic error. The STATUS clause of an OBJECT-IDENTITY invocation must be "current," "deprecated," or "obsolete."


(Untitled)

Fatal Error 1084

<1084, Fatal>: "fileName><line#>: MODULE-IDENTITY required after the IMPORTS section for all SNMPv2 modules"
MODULE-IDENTITY macro invocation, SNMPv2C-specific module semantic error. There must be one and only one MODULE-IDENTITY invocation in an SNMPv2C MIB, immediately after the IMPORTS section.


(Untitled)

Fatal Error 1087

<1087. Fatal>: "<fileName><line#>: Invalid STATUS clause <clause> for a TEXTUAL-CONVENTION macro."
Type assignment, SNMPv2C-specific module semantic error. The status clause of a TEXTUAL-CONVENTION macro invocation must be "current," "deprecated," or "obsolete."


(Untitled)

Fatal Error 1089

<1089, Fatal>: "<fileName>:<line#>: Symbol <identifier> in AUGMENTS clause does not resolve to a row OBJECT-TYPE"
OBJECT-TYPE macro invocation SNMPv2C-specific module semantic error. If an AUGMENTS clause is present, then the identifier in the AUGMENTS clause must resolve to a table OBJECT-TYPE.


(Untitled)

Fatal Error 1090

<1090, Fatal>: "<fileName>:<line#> IMPLIED clause is useful only for the last INDEX object"
OBJECT-TYPE macro invocation SNMPv2C-specific module semantic error. The IMPLIED clause can be associated only with the last object in the INDEX clause.


(Untitled)

Fatal Error 1092

<1092, Fatal>: "<fileName>:<line#> IMPLIED clause not allowed for potentially zero-length objects"
OBJECT-TYPE macro invocation SNMPv2C-specific module semantic error. The IMPLIED clause cannot be used on a variable-length object if that object can have a zero length.


(Untitled)

Fatal Error 1093

<1093. Fatal>: "<fileName><line#>: Only the type "INTEGER" can be enumerated according to the V1 SMI."
Type assignment, SNMPv1-specific module semantic error. An SNMPv1 MIB enumeration can use only the type INTEGER.


(Untitled)

Fatal Error 1094

<1094. Fatal>: "<fileName><line#>: The type used in the enumeration does not resolve to one of the allowed types"
Type assignment, SNMPv2C-specific module semantic error. The type used in an enumeration must be INTEGER or an equivalent type, or another enumeration.


(Untitled)

Fatal Error 1095

<1095. Fatal>: "<fileName><line#>: Enumeration member is not a member of the parent enumeration"
Type assignment, SNMPv2C-specific module semantic error. If another enumeration is used, its set of items must be a subset of the parent enumeration's set of items.


(Untitled)

Fatal Error 1097

<1097, Fatal>: "<fileName><line#>: identifier <name> does not resolve to an integer value"
Type assignment, SNMPv2C-specific module semantic error. The values in the BITS type must be integer values.


(Untitled)

Fatal Error 1098

<1098, Fatal>: "<fileName><line#>: Duplicate value <value> in BITS construct"
Type assignment, SNMPv2C-specific module semantic error. There must be no duplicate names and values in a BITS construct. The <line#> parameter is the position of the recurrence of the name/value.


(Untitled)

Fatal Error 1099

<1099, Fatal>: "<fileName><line#>: Duplicate name <identifier> in BITS construct"
Type assignment, SNMPv2C-specific module semantic error. There must be no duplicate names and values in a BITS construct. The <line#> parameter is the position of the recurrence of the name/value.


(Untitled)

Fatal Error 1101

<1101, Fatal>: "<fileName><line#>: The length of the range is too long for the compiler (Does not fit into 4 bytes)"
Module semantic error in range or size specification, specific to neither SNMPv1 nor SNMPv2C. The size of a set of ranges must be less than 232. The size of a set of ranges is defined as the difference between the largest value and the smallest value in the set.


(Untitled)

Fatal Error 1451

<1451, Fatal>: "Could not connect to the SMIR"
SMIR interaction error.


(Untitled)

Fatal Error 1453

<1453, Fatal>: "Module <module> does not exist in the SMIR"
SMIR interaction error. The module that has requested deletion does not exist in the SMIR.


(Untitled)

Fatal Error 101

<101, Fatal>: "Usage:
smi2smir <DiagnosticArgs> <VersionArgs> <CommandArgs>
smi2smir <DiagnosticArgs> <RegistryArgs>
smi2smir <HelpArgs>"
Command-line syntax error. This is followed by an explanation of the switches.


(Untitled)

Fatal Error 102

<102, Fatal>:"Invalid argument on command line after <last correct argument>"
Command-line syntax error. There are some extra arguments or an invalid switch on the command line. The <last correct argument> parameter refers to the last argument that was read correctly on the command line, and can possibly be smi2smir, which is the name of the executable file for the SNMP module information compiler.


(Untitled)

Fatal Error 103

<103, Fatal>: "Diagnostic Level not specified for the /m switch"
Command-line syntax error. If you specify the /m switch, you must also specify a diagnostic level of 0, 1, or 2.


(Untitled)

Fatal Error 104

<104, Fatal>: "Diagnostic Level must be 0, 1 or 2 for the /m switch"
Command-line syntax error. If you specify the /m switch, you must also specify a diagnostic level of 0, 1, or 2.


(Untitled)

Fatal Error 105

<105, Fatal>: "Maximum diagnostic count missing after the /c switch"
Command-line syntax error. If you specify the /c switch, you must also specify a non-negative integer as the maximum count.


(Untitled)

Fatal Error 106

<106, Fatal>: "<argument> is not a valid diagnostic count"
Command-line syntax error. If you specify the /c switch, you must also specify a non-negative integer as the maximum count.


(Untitled)

Fatal Error 107

<107, Fatal>: "File Name(s) missing"
Command-line semantic error. One or more file names must be specified on the command line for the given combination of switches.


(Untitled)

Fatal Error 108

<108, Fatal>: "No command argument specified"
Command-line syntax error. Some action must be specified on the command line.


(Untitled)

Fatal Error 109

<109, Fatal>: "Module name missing"
Command-line syntax error.


(Untitled)

Warning 230

<230, Warning>: "<fileName>:<line#>: '<the wrong token>' used. Assuming '::=' "
The token ":=", "::", or "=" has been used instead of "::=".


(Untitled)

Fatal Error 1502

<1502, Fatal>: "File <file> not found, or unreadable"
Run-time error. One or more files explicitly mentioned on the command line do not exist or are unreadable.


(Untitled)

Information Message 211

<211, Information>: "Skipping TRAP-TYPE <identifier>"
Any errors in the TRAP-TYPE definition generate this message.


(Untitled)

Warning 110

<110, Warning>: "No include path specified after the /i switch"
Command-line syntax warning. If you specify the /i switch, you must also specify the path to included files.


(Untitled)

Information Message 208

<208, Information>: "Skipping OBJECT-TYPE <identifier>"
Whenever errors 201-207 occur, this message informs you that the OBJECT-TYPE invocation is being skipped.


(Untitled)

The SNMP provider returns an error for a class because some mandatory property qualifiers are not present or some qualifiers are not of the correct type and value.

[This is preliminary documentation and subject to change.]

Solution:

Make sure the qualifiers are correct for all properties of the SNMP-compatible class. See the CIM Property Qualifiers table for details.


(Untitled)

The SNMP provider returns an error for a class because some mandatory qualifiers are not present within the class definition or some qualifiers are not of the correct type and value.

[This is preliminary documentation and subject to change.]

Solution:

Make sure the qualifiers are correct for the SNMP-compatible class. See the CIM Class Qualifiers table for details.


(Untitled)

The SNMP provider returns an error for a class because some properties of a CIM MOF class definition do not contain valid values for some property qualifiers.

[This is preliminary documentation and subject to change.]

Solution:

See Mapping SNMP to the CIM Schema to make sure qualifiers are of the expected type and value.


(Untitled)

The SNMP provider returns a subset of the properties present for a class definition because the object_identifier qualifier value is incorrect with respect to the SNMP MIB definition.

[This is preliminary documentation and subject to change.]

Solution:

Check the SNMP MIB definition to make sure the object identifier is set to the correct value.


(Untitled)

The SNMP provider returns an error for a CIM MOF class because none of the properties of the class definition have read access.

[This is preliminary documentation and subject to change.]

Solution:

Check SNMP MIB definition to make sure the MOF definition is consistent with MOF class definition.


(Untitled)

The SNMP provider returns an error for a CIM MOF class because none of the properties of a given CIM MOF class definition have write access.

[This is preliminary documentation and subject to change.]

Solution:

Check SNMP MIB definition to make sure MOF definition is consistent with MOF class definition.


(Untitled)

The SNMP provider returns an error for a CIM MOF class because some properties of a given CIM MOF class definition are marked as keyed and no associated key_order qualifier is present, or the key_order values are invalid.

[This is preliminary documentation and subject to change.]

Further description:

The key_order values are invalid if they are nonconsecutive and do not begin from index value "1".

Solutions:

  • Add the correct key_order qualifier to all properties marked as being keyed.
  • Check the ordering of all properties with the key_order qualifier to make sure that the initial value of key_order is "1" and that they are monotonically incremented based on the ordering of the properties within the SNMP MIB.


(Untitled)

Dynamic class provider not registered in the SNMP device namespace.

[This is preliminary documentation and subject to change.]

Solution:

Create an instance of __WIN32Provider using the following instance template:

instance of __WIN32PROVIDER
{
    Configuration = 0;
    Provider = "MS_SNMP_CLASS_PROVIDER";
    ProviderClsId = "{3296BF00-A1FC-11cf-8C8B-00AA00A4086C}";
    MethodSet = 332817;
} ;


(Untitled)

Dynamic instance provider not registered in the SNMP device namespace.

[This is preliminary documentation and subject to change.]

Solution:

Create an instance of __WIN32Provider using the following instance template:

instance of  __WIN32PROVIDER
{
    Configuration = 0;
    Provider = "MS_SNMP_INSTANCE_PROVIDER";
    ProviderClsId = "{D45BD3C1-EF23-11cf-8CBC-00AA00A4086C}";
    MethodSet = 331793;
} ;


(Untitled)

Dynamic class provider incorrectly registered in the SNMP device namespace.

[This is preliminary documentation and subject to change.]

Solution:

Check the instance of __WIN32Provider using the following instance template:

instance of __WIN32PROVIDER
{
    Configuration = 0;
    Provider = "MS_SNMP_CLASS_PROVIDER";
    ProviderClsId = "{3296BF00-A1FC-11cf-8C8B-00AA00A4086C}";
    MethodSet = 332817;
} ;


(Untitled)

Dynamic instance provider incorrectly registered in the SNMP device namespace.

[This is preliminary documentation and subject to change.]

Solution:

Check the instance of __WIN32Provider using the following instance template:

instance of __WIN32PROVIDER
{
    Configuration = 0;
    Provider = "MS_SNMP_INSTANCE_PROVIDER";
    ProviderClsId = "{D45BD3C1-EF23-11cf-8CBC-00AA00A4086C}";
    MethodSet = 331793;
} ;


(Untitled)

No classes loaded into the SNMP device namespace.

[This is preliminary documentation and subject to change.]

Solution:

Load a static SNMP-device-compatible MOF definition into the SNMP device namespace.


(Untitled)

No classes loaded into the SMIR for an SNMP dynamic class provider-backed SNMP device namespace.

[This is preliminary documentation and subject to change.]

Solution:

Load a static SMIR SNMP-device-compatible MOF definition into the SMIR namespace.


(Untitled)

SNMP device namespace instance or SNMP-compatible class contains an illegal transport address.

[This is preliminary documentation and subject to change.]

Solutions:

  • Verify that the AgentAddress qualifier is of type string.
  • If the AgentAddress qualifier is a dotted decimal Internet Protocol (IP) address, then the address must be a valid unicast IP address.
  • If the AgentAddress qualifier is a host-name-resolvable string, verify that the host name is resolvable using the Windows executable file:

    ping.exe <hostname>

    where hostname is the host-name-resolvable string.


(Untitled)

The AgentAddress qualifier of the SNMP device namespace instance or SNMP-compatible class is correct but the operation hangs for a period of time before successfully returning.

[This is preliminary documentation and subject to change.]

Further description:

If the AgentAddress qualifier is a host-name-resolvable string, check the response time of the Windows executable file ping.exe <hostname>, where hostname is the host-name-resolvable string. Windows may be trying to resolve the host name across multiple network interface cards. In this case, Windows is performing a less-than-optimal search order.

Solution:

Try rearranging the binding order of the network interface cards.


(Untitled)

The AgentAddress qualifier of the SNMP device namespace instance or SNMP-compatible class is a resolvable host name but the operation hangs for a period of time before unsuccessfully returning.

[This is preliminary documentation and subject to change.]

Further description:

If the AgentAddress qualifier is a host-name-resolvable string, check the response time of the Windows executable file ping.exe <hostname>, where hostname is the host-name-resolvable string. Windows may be trying to resolve the host name across multiple network interface cards. In this case, Windows is performing a less-than-optimal search order.

Solution:

The marshalling interface between the WBEM client and the WBEM server may be timing out before the operation completes. Try increasing the marshalling timeout period.


(Untitled)

The AgentAddress qualifier of the SNMP device namespace instance or SNMP-compatible class is an IP address but the operation hangs for a period of time before unsuccessfully returning.

[This is preliminary documentation and subject to change.]

Further description:

If the AgentAddress qualifier has been entered incorrectly, the SNMP providers assume the value is a resolvable host name. The providers then unsuccessfully attempt to resolve the host name.

Solution:

Make sure the AgentAddress qualifier is really a dotted decimal IP address.


(Untitled)

The SNMP protocol data units generate ICMP-port-unreachable packets.

[This is preliminary documentation and subject to change.]

Further description:

The AgentAddress qualifier specified in the SNMP device namespace instance or SNMP-compatible class does not have an associated agent bound to the SNMP UDP port 161.

Solution:

Verify that the IP address is correct and that the SNMP agent is enabled on the device.


(Untitled)

The SNMP protocol data units generate ICMP-host-unreachable packets.

[This is preliminary documentation and subject to change.]

Further description:

The subnet associated with the IP transport address specified in the AgentAddress qualifier of the SNMP device namespace instance or SNMP-compatible class is known by a local router. However, the IP transport address on that subnet is not discoverable by the subnet connected router using the address resolution protocol.

Solution:

Verify that the IP address is correct and that the hardware device is switched on and connected to the network.


(Untitled)

The SNMP protocol data units generate ICMP-net-unreachable packets.

[This is preliminary documentation and subject to change.]

Further description:

The subnet associated with the IP transport address specified in the SNMP device namespace instance or SNMP-compatible class is not known by a local router.

Solution:

Check that the IP address is correct and that the routing device has the appropriate routing table entries for that subnet.


(Untitled)

The SNMP agent receives an SNMP protocol data unit but does not return a response.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP agent does not respond to an SNMP protocol operation because the SNMP protocol data unit is not a valid authenticated packet.

Solutions:

  • For the SNMPv1 protocol operations GET and GET-NEXT, make sure that the AgentReadCommunityName qualifier of the SNMP device namespace instance or SNMP-compatible class is valid for that SNMP agent device.
  • For the SNMPv1 protocol operation SET, make sure that the AgentWriteCommunityName qualifier of the SNMP device namespace instance or SNMP-compatible class is valid for that SNMP agent device.


(Untitled)

The SNMP agent does not respond to an SNMP protocol operation because the SNMP operation protocol data units are being dropped before reaching their destination.

[This is preliminary documentation and subject to change.]

Further description:

Some entity between the source and destination is dropping packets due to network saturation.

Solutions:

  • Increase the value of the AgentRetryCount qualifier of the SNMP device namespace instance or SNMP-compatible class.
  • Decrease the value of the AgentFlowControlWindowSize qualifier of the SNMP device namespace instance or SNMP-compatible class. This reduces the number of outstanding protocol data units sent to that device.


(Untitled)

The SNMP agent does not respond to an SNMP protocol operation because the SNMP response protocol data units are being dropped before reaching their destination.

[This is preliminary documentation and subject to change.]

Further description:

Some entity between the destination and source is dropping packets due to network saturation.

Solutions:

  • Increase the value of the AgentRetryCount qualifier of the SNMP device namespace instance or SNMP-compatible class.
  • Decrease the value of the AgentFlowControlWindowSize qualifier of the SNMP device namespace instance or SNMP-compatible class. This reduces the number of outstanding protocol data units sent to that device and, therefore, the number of responses being returned.


(Untitled)

The SNMP agent does not respond to an SNMP protocol operation because the SNMP agent is dropping the SNMP protocol data units.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP agent is dropping packets due to saturation.

Solutions:

  • Increase the value of the AgentRetryCount qualifier of the SNMP device namespace instance or SNMP-compatible class.
  • Decrease the value of the AgentFlowControlWindowSize qualifier of the SNMP device namespace instance or SNMP-compatible class. This reduces the number of outstanding protocol data units being sent to that device and, therefore, the number of responses being returned.
  • Decrease the value of the AgentVarBindsPerPDU qualifier of the SNMP device namespace instance or SNMP-compatible class. This reduces the number of variable binding operations the SNMP agent must process before responding with an SNMP protocol response.


(Untitled)

The SNMP agent responds to an SNMP protocol operation after the SNMP provider times out of the protocol operation response.

[This is preliminary documentation and subject to change.]

Solutions:

  • Increase the value of the AgentRetryCount qualifier of the SNMP device namespace instance or SNMP-compatible class.
  • Increase the value of the AgentRetryTimeout qualifier of the SNMP device namespace instance or SNMP-compatible class. This causes the SNMP provider to wait longer for a protocol response before timing out of the operation.


(Untitled)

The SNMP provider sends out multiple packets with the same protocol request identifier even when the agent is responding to the SNMP protocol operation.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP provider is encountering a race condition because the SNMP agent device is responding slowly to protocol requests, and the SNMP provider is timing out before receiving those responses. This causes the SNMP provider to use the retransmission policy.

Solution:

Increase the value of the AgentRetryTimeout qualifier of the SNMP device namespace instance or SNMP-compatible class. This causes the SNMP provider to wait longer for a protocol response before timing out and performing a protocol operation retransmission.


(Untitled)

The SNMP provider returns an empty result set for a given instance because the SNMP agent is expecting key information that is inconsistent with the CIM MOF definition.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP provider uses a GET operation to retrieve a particular instance of a class from a device and a SET operation to update a particular instance of a class. The device may expect keyed property information that is inconsistent with the MOF definition of the instance. The SNMP agent returns an error indicating that the instance is not available.

Solutions:

  • Check that the MOF class definition is consistent with the SNMP MIB definition used to derive it.
  • Check with the SNMP agent vendor to determine the expected typing for these properties.


(Untitled)

The SNMP provider returns an error result because the qualifier values of the SNMP device namespace instance or SNMP-compatible class do not match the expected type or values.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP provider uses a number of qualifiers to determine the transport context used to communicate with an SNMP agent device. All mandatory qualifiers must be present and all optional qualifiers that are present must be defined using the correct type and values.

Solution:

Verify that the namespace qualifier values are of the expected types and values. See Creating an SNMP Namespace for information on the qualifier values and types.


(Untitled)

The set of classes returned by the SNMP providers changes intermittently.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP class provider uses a correlation procedure to determine the set of class definitions supported by an SNMP device. The correlation process may return different results depending on the state of the network nodes connecting the SNMP providers and the SNMP agent. If additional MIBs are compiled into the SMIR, the correlation process may return additional classes that have not been available previously from the SMIR.

Solutions:

See the following topics:

  • The SNMP protocol data units generate ICMP-host-unreachable packets.
  • The SNMP protocol data units generate ICMP-net-unreachable packets.
  • The SNMP agent receives an SNMP protocol data unit but does not return a response.
  • The SNMP agent does not respond to an SNMP protocol operation because the SNMP operation protocol data units are being dropped before reaching their destination.
  • The SNMP agent does not respond to an SNMP protocol operation because the SNMP response protocol data units are being dropped before reaching their destination.
  • The SNMP agent does not respond to an SNMP protocol operation because the SNMP agent is dropping the SNMP protocol data units.


(Untitled)

The set of instances returned by the SNMP providers changes intermittently.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP instance provider may use the services of the SNMP class provider to supply class definitions that define the SNMP MIB schema definitions used to access an SNMP device. The set of classes returned by the SNMP class provider can change intermittently due to network connectivity.

Solution:

See the following topic:

The set of classes returned by the SNMP providers changes intermittently.


(Untitled)

The SNMP provider returns a subset of the properties present for a given class definition because some entity is dropping a percentage of SNMP packets between the source and destination.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP provider is returning a small percentage of NULL properties for a given instance of a class because the SNMP operation and response packets are being dropped between the source and destination.

Solutions:

See the following topics:

  • The SNMP agent does not respond to an SNMP protocol operation because the SNMP operation protocol data units are being dropped before reaching their destination.
  • The SNMP agent does not respond to an SNMP protocol operation because the SNMP response protocol data units are being dropped before reaching their destination.
  • The SNMP agent does not respond to an SNMP protocol operation because the SNMP agent is dropping the SNMP protocol data units.


(Untitled)

The SNMP provider returns a subset of the instances expected for a class definition because the SNMP agent device is returning GET-NEXT variable bindings that are not lexicographically ordered.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP provider uses a repeated GET-NEXT process to return all the instances of a Common Information Model (CIM) class definition. The SNMP provider may find that a response to an SNMP GET-NEXT operation contains a variable binding that is lexicographically previous to the requested variable binding. In this case, the SNMP provider removes the variable binding from the next SNMP GET-NEXT operation so that the provider does not cycle in an infinite loop.

Solution:

Determine if a software upgrade to the SNMP agent software fixes this ordering problem.


(Untitled)

The SNMP provider returns a subset of the properties present for a class definition because the SNMP agent does not return properties that are defined as optional.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP provider uses both GET-NEXT and GET operations to retrieve instance information from a device. The device may fail to generate responses for all properties of a given instance because the properties are defined as optional.

Solution:

This is the expected behavior.


(Untitled)

The SNMP provider returns a subset of the properties present for a class definition because the SNMP agent experiences some internal error processing those properties.

[This is preliminary documentation and subject to change.]

Solution:

Determine if a software upgrade to the SNMP agent software fixes the internal error.


(Untitled)

The SNMP provider returns a subset of the properties present within an instance of a class because the SNMP agent is returning key information that is incompatible with the CIM MOF definition.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP provider uses a GET-NEXT operation to retrieve instance information from a device. The device may return keyed property information that is inconsistent with the MOF definition of the class being retrieved. Where keyed properties are marked with the virtual_key qualifier value set to True, these properties are derived from the SNMP instance information present within the variable binding list of the non-virtual-keyed and non-keyed properties present within the class definition. These properties are not initialized because the typing information is inconsistent with the MOF class definition.

Solutions:

  • Check that the MOF class definition is consistent with the SNMP MIB definition used to derive it.
  • Check with the SNMP agent vendor to determine the expected typing for these properties.


(Untitled)

The SNMP provider returns an empty result set for a given instance because the SNMP agent is returning key information that is inconsistent with the CIM MOF definition.

[This is preliminary documentation and subject to change.]

Further description:

The SNMP provider uses a GET-NEXT operation to retrieve a particular instance of a class from a device. The device returns property information that is inconsistent with the MOF definition of the instance being retrieved. The SNMP providers drop these erroneous instances.

Solutions:

  • Check that the MOF class definition is consistent with the SNMP MIB definition used to derive it.
  • Check with the SNMP agent vendor to determine the expected typing for these properties.


(Untitled)

Displaying an Instance Table

You can open an instance table for any class in the namespace. An instance table shows all instances of the selected class in the namespace, as well as their common properties.

To display the instance table
  1. Select a class in the Class Explorer.
  2. Click the Instances button in the Class Viewer. The instance table for the selected class appears. If there are no instances of a selected class, the table displays the message "No Instances Available."

To return to the class definition display, click the Instances button again.

The following example screen shows all instances of the InterfaceDevice class:


(Untitled)

Adding Class Properties

To add a property
  1. Select the class you want to change in the Class Explorer. Click the Properties tab in the Class Viewer. The class's properties appear in the Properties page.
  2. Click the blank Name field at the bottom of the properties table. Type the new property name.
  3. Click the Type field. Click the down arrow and choose a property type from the list that appears. When you select the type, a default value may appear in the Value field.
  4. If you want a value other than the default in the Value field, click the field and enter the desired value. When you select this field and begin typing, a list box may appear from which you can choose the appropriate value.

    If the property type is an array, click the Array button in the Value field to open a dialog box in which you can enter each value in the array. When you are done entering values, click OK to return to the Properties page.

  5. To create an embedded object, do the following:
    • Select object as the property type. The Object Type dialog box appears.
    • Optionally, enter the name of the class to which the embedded object belongs, then click OK.
    • By default, the Value field is set to <empty> (which represents NULL). To change this value, right-click the field, and select Create Object from the menu. The Embedded Object dialog box appears. If you selected a class in step b, this dialog box opens the Properties page for that class.

      Otherwise, the display is blank. Enter the name of the class to which the embedded object belongs in the Class field to display that class' Properties page.

    • Edit the properties and/or qualifiers for the embedded object, if necessary, then click OK to return to the Class Viewer.
  6. Click the Save button. A confirmation message appears. Click Yes to save the new data.


Using the Go to Namespace Function

The object tree can contain objects from other namespaces. If an object is from another namespace, the object's full path appears in the tree (including the machine name if it resides on a different machine). You can display the tree for that object's namespace by using the Go to Namespace function.

To use the Go to Namespace function
  1. Right-click the object whose namespace you want to display.
  2. Select the Go to Namespace option. The object tree for the namespace appears rooted at the selected object.


(Untitled)

Displaying Class Methods

To display class methods
  1. Select the object in the Class Explorer.
  2. Click the Methods tab.

Execution of methods is not implemented in this release.


(Untitled)

Displaying Class Qualifiers

To display class qualifiers
  1. Select the class in the Class Explorer, and click the Properties tab in the Class Viewer.
  2. Right-click in the Properties page in the Class Viewer.
  3. Select Object qualifiers from the menu that appears. The Qualifiers window appears.


(Untitled)

Specifying the Namespace in the Classes in Box

The format for specifying a namespace in the Classes in box is as follows:

\\<machine>\root\<namespace>

For example, specifying \\EDKDOCS1\root\DEFAULT displays the class inheritance tree for the default namespace on the machine EDKDOCS1. If no machine is specified, the default is the local machine. You can also specify a chain of namespaces, separating each with a backslash:

\\<machine>\root\<namespace>\<namespace>\<namespace>


(Untitled)

Selecting the Namespace from the History List

The Objects in box keeps a list of previously-selected namespaces. Click the down arrow to select a namespace from this history list.


(Untitled)

Compiling a MOF File

To compile a MOF file
  1. Double-click the MOF Compiler Wizard icon. A welcome screen appears. Select Compile a .MOF file.
  2. Click the Next button. The following screen appears:

Type the path and file name for the MOF file you want to compile (or use the Browse button to select the file), and the namespace where the MOF file should be loaded.

  3. Click the Next button. The following screen appears:

Select or cancel the selection of the appropriate compiler options. You can modify classes and instances that are already in the namespace, or you can add new classes and instances to the namespace.

  4. Click Finish to compile the file. The WBEM Login dialog box appears.

    Enter the appropriate login information (see Opening the ActiveX Applications for instructions), and click OK. A message box informs you of successful compilation. Click OK to dismiss the message. The resulting database file is created in the same directory as the MOF file.


(Untitled)

Displaying Property Qualifiers

Property qualifiers can only be displayed for non-system properties.

To display property qualifiers
  1. Select the class in the Class Explorer, and click the Properties tab in the Class Viewer.
  2. Double-click the property whose qualifiers you want to display.

    —or—

    Right-click the property whose qualifiers you want to display, and select Property qualifiers from the menu that appears.

    In both cases, the Qualifiers window appears. If the class has no property qualifiers, the window is blank.

To close the Qualifiers window, click the OK or Cancel button.

The following example screen shows the property qualifiers for the UntilTime property of the Win32Printer class:


(Untitled)

Deleting Class Properties

To delete a property
  1. Select the class in the Class Explorer, and click the Properties tab in the Class Viewer.
  2. Click the blank box to the left of the property you want to delete. This selects the entire property entry.
  3. Press the Delete key. A confirmation message appears. Click OK to delete the property. This activates the Save button in the Class Viewer.
  4. Click the Save button. A confirmation message appears. Click Yes to confirm the deletion.


(Untitled)

Modifying Class Methods

[Not implemented in this release.]


(Untitled)

Creating and Using Custom Views of Instances

You can create and display custom views of class instance data. For more information, see the example screen in Displaying Custom Views of Object Data.

To create a custom view of class instance data
  1. Write an ActiveX™ control that defines the format for the data display.
  2. Associate that view with the class definition by using a new custom view instance.

After you have created a custom view and have associated it with a class instance, selecting that instance in the Class Viewer activates the Views button. Click the Views button. Choose the view you want from the list that appears, andthen click OK.

The WBEM SDK samples directory <drive>:\<Wbem-directory>\sdk\com\CustomViews contains files and instructions for creating a sample custom view.


(Untitled)

Adding Class or Property Qualifiers

To add qualifiers to a class or property
  1. Open the Qualifiers window for the desired class or property. For instructions, see Displaying Class Qualifiers or Displaying Property Qualifiers.
  2. Click the blank Name field, and enter the new qualifier name.
  3. Click the Type field, then click the down arrow and choose a type from the list that appears. When you select the type, a default value may appear in the Value field.
  4. Click the I, C, and O fields to select or cancel these settings.

    The Origin field is read-only. It indicates where the qualifier originated: local (for qualifiers defined in the current object) or propagated (for qualifiers propagated from another object).

  5. If you want a value other than the default in the Value field, click the field and enter the desired value. When you select this field and begin typing, a list box may appear from which you can choose the appropriate value.
  6. When you have finished editing, click the OK button to close the Qualifiers window.
  7. In the Class Viewer, click the Save button. A confirmation message appears. Click Yes to save the changes.


(Untitled)

Selecting the Namespace from the History List

The Classes in box keeps a list of previously-selected namespaces. Click the down arrow to select a namespace from this history list.


(Untitled)

Browsing for a Namespace

To browse for a namespace:
  1. Click the Browse for Namespace button. The Browse for Namespace dialog box appears:

  2. By default, the Machine Name box shows the local machine. To select a namespace on another machine, type that machine name in the Machine Name box and press Enter.

    —or—

    Click the Network Neighborhood button, select the remote machine from the list that appears, and then click OK.

    The WBEM Login dialog box appears.

  3. Enter the appropriate login information (see Opening the ActiveX Applications for instructions), and click OK. This returns you to the Browse for Namespace dialog box.
  4. In the Browse for Namespace dialog box, click the plus sign next to the root folder to display the namespaces on the selected machine.
  5. Click the namespace you want to use, then click OK. This returns you to the CIM Studio where the class inheritance tree for the selected namespace appears.


(Untitled)

Using Browse for Instance to Reroot the Object Tree

You can reroot the object tree from a specific instance by using the Browse for Instance function. The Browse for Instance function allows you to display all objects in the selected classes. You can then select the object you want to be the new root of the object tree.

To browse for an instance
  1. In the Object Explorer, click the Browse for Instance button. The Browse for Instance dialog box appears:

The Browse for Instance dialog box shows a list of classes in the current namespace. By default, all classes in the namespace are shown. Classes that cannot have instances (abstract classes) appear in bold type. Select Show classes which can have instances to display only those classes that can have instances. Select Associations to display association classes.

  2. For each class you want to browse, select the class name in the Available Classes list, then click the Add button. Each class selected appears in the Browse for objects in box. (For quicker selection, you can start typing the class name in the field under Available Classes to move directly to that class' location in the list.)

    You can remove selected classes from the search by clicking the class name in the Browse for objects box, then clicking the Remove button.

  3. Click OK. The Browse for Objects Results dialog box appears. The dialog box shows all objects in the selected classes. For example:

  4. Click the object you want to be the root of the object tree, then click OK. This returns you to the Object Browser. The object tree appears with the selected object as the new root.


(Untitled)

Using Make Root to Reroot the Object Tree

To change the object tree's root, right-click the object you want to be the new root. Select Make Root from the menu that appears. Because only regular objects can be made the root of the tree, the Make Root option is not available if grouping nodes are selected.

The following screens show how the tree display changes when different roots are selected:

Root = EDKDOCS1 | Root = C:


(Untitled)

Browsing for a Namespace

To browse for a namespace:
  1. Click the Browse for Namespace button. The Browse for Namespace dialog box appears:

  2. By default, the Machine Name box shows the local machine. To select a namespace on another machine, type that machine name in the Machine Name box, and press Enter.

    —or—

    Click the Network Neighborhood button, select the remote machine from the list that appears, then click OK.

    The WBEM Login dialog box appears.

  3. Enter the appropriate login information (see Opening the ActiveX Applications for instructions) and click OK. This returns you to the Browse for Namespace dialog box.
  4. In the Browse for Namespace dialog box, click the plus sign next to the root folder to display the namespaces on the selected machine.
  5. Click the namespace you want to use, then click OK. This returns you to the Object Browser where you will see the object tree for the selected namespace.


(Untitled)

Checking the Syntax of a MOF File

To check the syntax of a MOF file
  1. Double-click the MOF Compiler Wizard icon. A welcome screen appears. Select Check the syntax of a .MOF file.
  2. Click the Next button. The following screen appears:

Type the path and file name for the MOF file you want to check, or use the Browse button to select the file.

  3. Click the Finish button. The wizard checks the file's syntax, and reports the results in a message box. Click OK to dismiss the message.


(Untitled)

Specifying the Namespace in the Objects in Box

The format for specifying a namespace in the Objects in box is as follows:

\\<machine>\root\<namespace>

For example, specifying \\EDKDOCS1\root\DEFAULT displays the object tree for the default namespace on the machine EDKDOCS1. If no machine is specified, the default is the local machine. You can also specify a chain of namespaces, separating each with a backslash:

\\<machine>\root\<namespace>\<namespace>\<namespace>


(Untitled)

Displaying Class Properties

To display properties of a class
  1. Select the class in the Class Explorer.
  2. Click the Properties tab in the Class Viewer.

Properties attached to a class by the system are preceded by a double underscore (for example, __SERVER). Note that you cannot change or delete system properties. You should not create properties that begin with a double underscore. Nonsystem properties are either defined by the user or inherited from parent classes.

The following example screen shows the properties for the Win32Printer class:


(Untitled)

Editing Class Properties

To edit a property field
  1. Select the class in the Class Explorer, and click the Properties tab in the Class Viewer.
  2. Click the field you want to change.
  3. If a down arrow appears when you select the field, click the arrow and choose a value from the list that appears.
  4. —or—

    If no down arrow appears, type the new value in the field.

    When you start typing, the text turns blue, and the Save button becomes active. This indicates that the value has not been committed yet.

    If you edit a Value field that contains an array, a dialog box appears that shows each value in the array. Edit the values you want to change. Click OK to return to the Properties page.

    If the property type is an object, the Value field contains either <empty> (which represents NULL) or an Object button. To change this field, do one of the following:

    • Click the Object button to open the Embedded Object dialog box. You can edit properties and qualifiers from this box in the same way as in the Class Viewer Properties page. Click OK to return to the Class Viewer.
    • Right-click the Object button, and select Set to <empty>.
    • Right-click the <empty> value, and select Create object. This opens the Embedded Object dialog box. Enter the name of the class to which the object belongs. The Properties page for that class appears. You can edit properties and qualifiers the same way as in the Class Viewer Properties page. Click OK to return to the Class Viewer.
  5. When you have finished editing, click the Save button. A confirmation message appears. Click Yes to save the changes. After the changes are saved, the text turns black.


(Untitled)

Deleting Class or Property Qualifiers

To delete qualifiers
  1. Open the Qualifiers window for the desired class or property. For instructions, see Displaying Class Qualifiers or Displaying Property Qualifiers.
  2. Click the blank box to the left of the qualifier you want to delete. This selects the entire qualifier entry.
  3. Press the Delete key. A confirmation message appears. Click OK to delete the qualifier. This activates the Save button in the Class Viewer.
  4. Click the OK button to close the Qualifiers window.
  5. In the Class Viewer, click the Save button. A confirmation message appears. Click Yes to confirm the deletion.