Scripting API

[This is preliminary documentation and subject to change.]

You can use the scripting API to interact with Windows Management using Microsoft® Visual Basic® or scripting languages.


Using the Scripting API

You can use the scripting API for Web-Based Enterprise Management (WBEM) to develop script and Visual Basic applications that can interact with the Windows Management (WinMgmt). WBEM provides scripting support for the following languages:

  • Microsoft® Visual Basic®
  • Visual Basic for Applications
  • Visual Basic, Scripting Edition
  • Microsoft® JScript®
  • Perl

The scripting interfaces differ from the COM interfaces for Windows Management in that they are adapted to the strengths and limitations of Visual Basic, Visual Basic for Applications, VBScript, and other scripting languages. WBEM includes the following features to exploit the power of scripting languages:

Object Creation | Some objects in the API are directly creatable using native mechanisms provided by each scripting language, rather than obtained via calls to other objects.
Collections | The API provides a number of standard Automation Collection interfaces. You can use each scripting language's native features to manipulate collections.
Monikers | Monikers allow you to access ISWbemObject and ISWbemServices directly without writing code to connect to CIMOM .
Direct Access | CIM Object properties and their methods can be accessed directly as Automation properties and methods of ISWbemObject
Optional Parameters | Many interface parameters in the WBEM API for Scripting are optional, and have default values. In many cases you can omit these parameters from your scripts so as to streamline development.
Error Handling | If a call to CIMOM through the WBEM API for Scripting causes an error, the error information can be accessed using the native error mechanisms of the scripting language.

For more information on scripting visit the Microsoft scripting website at: http://www.microsoft.com/scripting/. This site contains detailed information on Microsoft® Visual Basic® Scripting Edition and Microsoft® Jscript®.


Document Conventions

The Scripting API Reference uses the following document conventions:

  • Parameter types are defined using a prefix: b (Boolean), str (string), i (integer), obj (Automation object).
  • Optional parameters are placed in square brackets with their default values shown by assignment.
  • In the case of object parameters, the characters after the "obj" prefix indicate the type of object expected:
    • WbemObject for an ISWbemObject type object.
    • WbemObjectSet for an ISWbemObjectSet type object.
    • WbemPath for an ISWbemObjectPath type object.
    • WbemNamedValueSet for an ISWbemNamedValueSet type object.
    • WbemServices for an ISWbemServices type object.
    • WbemLocator for an ISWbemLocator type object.
    • WbemMethod for an ISWbemMethod type object (for example, ISWbemMethodSet.Item).
    • WbemProperty for an ISWbemProperty type object (for example, ISWbemPropertySet.Item).
    • WbemQualifier for an ISWbemQualifier type object (for example, ISWbemQualifierSet.Item).
    • WbemPropertySet for an ISWbemPropertySet type object (for example, ISWbemObject.Properties_).
    • WbemQualifierSet for an ISWbemQualifierSet type object (for example, ISWbemObject.Qualifiers_).
    • WbemMethodSet for an ISWbemMethodSet type object (for example, ISWbemObject.Methods_).
    • WbemEventSource for an ISWbemEventSource type object (for example, ISWbemServices.ExecNotificationQuery).

For Example:

objWbemObjectSet = objWbemServices.Something(
     strParam,
     [iFlags=0],
     [objWbemNamedValueSet=null]
)

Describes a Something method of an ISWbemServices object. This method returns an ISWbemObjectSet object and takes three parameters, only the first of which is mandatory. The first parameter is a string, the second is an optional integer (with a default value of zero), and the third is an optional ISWbemNamedValueSet (with a default value of null).


Object Creation

For the following interfaces of the WBEM Scripting API, direct object creation is supported using the specified ProgID.

Interface | ProgID | CLASSID
ISWbemLocator | Wbem.Locator | 76A64158-CB41-11d1-8B02-00600806D9B6
ISWbemLastError | Wbem.LastError | C2FEEEAC-CFCD-11D1-8B05-00600806D9B6
ISWbemObjectPath | Wbem.ObjectPath | 5791BC26-CE9C-11D1-97BF-0000F81E849C
ISWbemNamedValueSet | Wbem.NamedValueSet | 9AED384E-CE8B-11D1-8B05-00600806D9B6

The mechanism by which an object is created depends upon the programming language being used.

Visual Basic and VBScript Support for Object Creation

In Visual Basic or VBScript object creation is supported using the CreateObject call. For example

Set locator = CreateObject("Wbem.Locator")
JScript Support for Object Creation

In JScript object creation is supported using the ActiveXObject call. For example

var locator = new ActiveXObject("Wbem.Locator");
Perl Support for Object Creation

In Perl object creation is supported using the CreateObject call. For example:

use Win32::OLE;
$locator = Win32::OLE->CreateObject('Wbem.Locator');
ASP Example
<OBJECT RUNAT=Server PROGID=Wbem.Locator ID=MyLocator></OBJECT>

Or use the Server.CreateObject function provided by ASP, passing it the same PROGID.

HTML Example
<OBJECT ID="MyLocator" CLASSID="CLSID:76A64158-CB41-11d1-8B02-00600806D9B6"></OBJECT>


Collections

A Collection is a standard Automation concept that provides a uniform interface to a set of objects over which iteration can be performed. Manipulation of Collections using a specific programming language is usually effected using native features of that language.

This simplifies the task of dealing with objects that contain other objects, because well-known paradigms can be used to access Collections rather than each Object supporting a different interface.

The WBEM API for Scripting provides a number of interfaces which conform to the Collection paradigm. In each case the elements of the Collection can be identified (by the Item() method) using a suitable string. These are:

Collection | Element | Item() Accepts:
ISWbemObjectSet | ISWbemObject | Object Path
ISWbemPropertySet | ISWbemProperty | Property name
ISWbemQualifierSet | ISWbemQualifier | Qualifier name
ISWbemMethodSet | ISWbemMethod | Method name
ISWbemNamedValueSet | ISWbemNamedValue | Value name

Visual Basic and VBScript Support for Collections

In Visual Basic or VBScript collections are accessed using the "For Each member in collection" mechanism. For example

'Here MyDiskProperties is an ISWbemPropertySet,
'and each Property is an ISWbemProperty
For Each Property in MyDiskProperties
    WScript.Echo Property.Name
Next
JScript Support for Collections

In JScript collections are accessed using the Enumerator mechanism. For example:

// Here myDiskProperties is an ISWbemPropertySet,
// and each p is an ISWbemProperty
var e = new Enumerator (myDiskProperties);
for (;!e.atEnd();e.moveNext ())
{
    var p = e.item ();
    WScript.Echo (p.Name);
}
Perl Support for Collections

In Perl collections are accessed using the Enum mechanism. For example:

use Win32::OLE;
use Win32::OLE::Enum;

# Here myPSet is an ISWbemPropertySet and each prop
# is an ISWbemProperty
foreach $prop (Win32::OLE::Enum->new(myPSet->All) {
        print "$prop->{Name}\n";
}


Object Creation and Monikers

In COM, a Moniker is standard mechanism for encapsulating the location and binding of another COM object. The textual representation of a Moniker is called a Display Name.

The WBEM API for Scripting allows you to create ISWbemObject and ISWbemServices in a concise manner using the concept of Moniker Display Names. This is provided as a cheaper alternative to the mechanism of first creating an ISWbemLocator and explicitly connecting to CIMOM using further method calls to obtain the interface that you need.

The Moniker Display Name is simply a human-readable string that acts as a name for a WBEM Namespace, or a WBEM Class or Instance. The format of this string is very similar to that of a standard WBEM Object Path (need reference here), with the following differences:

  • The string must begin with the characters "WinMgmts:" (these are case-insensitive), followed by a WBEM object path that identifies either a namespace or a WBEM class or instance.
  • The server may be omitted from the object path, in which the local server is assumed.
  • The namespace may be omitted from the object path, in which case the default namespace is assumed (this is determined by the value of the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\WBEM\Scripting\Default Namespace the default value of which is root\cimv2.

Note It is not permissible to omit the namespace but specify the server, if a class or instance is also specified.

You can use the ISWbemObjectPath as an alternative means of constructing a Display Name without recourse to typing long WBEM object paths. The DisplayName Automation property of this interface returns a string suitable for use as a Display Name.

The following table gives examples of valid Moniker Display Names.

WinMgmts: | This identifies the default namespace on the local machine; an ISWbemServices object is returned.
WinMgmts://myServer | This identifies the default namespace on the server an ISWbemServices object is returned.
WinMgmts://myServer/root/cimv2 | This identifies the root/cimv2 namespace on the server myServer; an ISWbemServices object is returned.
WinMgmts:root/cimv2 | This identifies the root/cimv2 namespace on the local server; an ISWbemServices object is returned.
WinMgmts://myServer/root/cimv2:Win32_logicalDisk | This identifies the class Win32_logicalDisk in the namespace root/cimv2 on the server myServer; an ISWbemObject object is returned.
WinMgmts:root/cimv2:Win32_logicalDisk | This identifies the class Win32_logicalDisk in the namespace root/cimv2 on the local server; an ISWbemObject object is returned.
WinMgmts:Win32_logicalDisk | This identifies the class Win32_logicalDisk in the default namespace on the local server; an ISWbemObject object is returned.
WinMgmts://myServer/root/cimv2:Win32_LogicalDisk="C:" | This identifies the instance of Win32_logicalDisk corresponding to drive C: in the namespace root/cimv2 on the server myServer; an ISWbemObject object is returned.
WinMgmts:root/cimv2:Win32_LogicalDisk="C:" | This identifies the instance of Win32_logicalDisk corresponding to drive C: in the namespace root/cimv2 on the local server; an ISWbemObject object is returned.
WinMgmts:Win32_LogicalDisk="C:" | This identifies the instance of Win32_logicalDisk corresponding to drive C: in the default namespace on the local server; an ISWbemObject object is returned.

Visual Basic and VBScript Support for Display Names

In Visual Basic or VBScript objects can be created using Moniker Display Names using the GetObject mechanism. For example:

Set AlerterService = GetObject("WinMgmts:Win32_Service=""ALERTER""")

uses Monikers as a concise alternative to:

Set Locator = CreateObject("Wbem.Locator")
Set Service = Locator.ConnectServer
Set AlerterService = Service.Get("Win32_Service=""ALERTER""")
JScript Support for Display Names

In JScript objects can be created using Moniker Display Names using the GetObject mechanism. For example:

var AlerterService = GetObject("WinMgmts:Win32_Service=""ALERTER""");

uses Monikers as a concise alternative to:

var Locator = CreateObject("Wbem.Locator");
var Service = Locator.ConnectServer ();
var AlerterService = Service.Get("Win32_Service=""ALERTER""");
Perl Support for Display Names

In Perl objects can be created using Moniker Display Names using the GetObject mechanism. For example:

use Win32::OLE;
use Win32::OLE::Variant;
$alerter = Win32::OLE->GetObject(WinMgmts:Win32_Service="ALERTER"');

uses Monikers as a concise alternative to:

use Win32::OLE;
use Win32::OLE::Variant;
$locator = Win32::OLE->CreateObject('Wbem.Locator');
$service = $locator->ConnectServer ();
$slerterService = $service->Get('Win32_Service="ALERTER"');

Note Although Monikers provide more direct access to objects, in certain circumstances repeated use of Monikers may be less efficient than the equivalent code that explicitly connects to CIMOM. If application performance is a consideration you may wish to consider using the alternative mechanisms.

It is not possible to use the GetObject function provided by VBScript and JScript when running scripts embedded within an HTML page, as Internet Explorer disallows the use of this call for security reasons.


Direct Access

Direct Access allows you to access the CIM properties of a CIM/WBEM class or instance directly on an ISWbemObject, rather than through the Property collection of that object. It also allows you to execute methods on that object in the native style of the programming language, rather than using the ISWbemServices.ExecMethod call.

Visual Basic and VBScript Support for Direct Property Access

Using dot notation you can get the VolumeName property of an instance Win32_LogicalDisk by the following means:

VolumeName = MyDisk.VolumeName

instead of

VolumeName = MyDisk.Properties_("VolumeName")

Chaining of objects is also acceptable. To access a property of an object that is embedded in another object you can use the syntax:

value = MyComputer.MyDisk.VolumeName

For properties which have array values, the array subscript notation is also supported:

valueOfElement = MyDisk.MyArrayProperty(3)
JScript Support for Direct Property Access

Using dot notation you can get the VolumeName property of an instance Win32_LogicalDisk by the following means:

var VolumeName = MyDisk.VolumeName;

instead of

var VolumeName = MyDisk.Properties_("VolumeName");

Chaining of objects is also acceptable. To access a property of an object that is embedded in another object you can use the syntax:

var value = MyComputer.MyDisk.VolumeName;

For properties which have array values, the array subscript notation is also supported:

var valueOfElement = MyDisk.MyArrayProperty[3];
Perl Support for Direct Property Access

Using dot notation you can get the VolumeName property of an instance Win32_LogicalDisk by the following means:

$volumeName = MyDisk->{VolumeName};

instead of

$volumeName = MyDisk->{Properties_}->(VolumeName)->{Value};

Chaining of objects is also acceptable. To access a property of an object that is embedded in another object you can use the syntax:

$value = MyComputer->{MyDisk}->{VolumeName};

For properties which have array values, the array subscript notation is also supported:

$valueOfElement = MyDisk->{MyArrayProperty}[3];
Visual Basic and VBScript Support for Direct Method Invocation

To directly invoke a method that starts a backup on a method provider on a remote computer, use the following syntax:

Set Instance =   GetObject("CIM: Win32_NTEventlogFile.Name=""C:\\WINNT351\\system32\\config\\AppEvent.Evt""")
Instance.BackupEventLog("c:\appevt.bak")
JScript Support for Direct Method Invocation

To directly invoke a method that starts a backup on a method provider on a remote computer, use the following syntax:

instance = GetObject("CIM: Win32_NTEventlogFile.Name=""C:\\WINNT351\\system32\\config\\AppEvent.Evt""");
instance.BackupEventLog("c:\appevt.bak");
Perl Support for Direct Method Invocation

To directly invoke a method that starts a backup on a method provider on a remote computer, use the following syntax:

use Win32::OLE;
use Win32::OLE::Variant;
$instance = Win32::OLE->GetObject("CIM: Win32_NTEventlogFile.Name=""C:\\WINNT351\\system32\\config\\AppEvent.Evt""");
$instance->BackupEventLog("c:\appevt.bak");

Note If you use this approach to execute a WBEM method that requires output parameters, you need to be aware that JScript does not support the use of output parameters in method calls. If your WBEM method uses output parameters, then you will need to invoke the method using the using ExecMethod on a ISWbemServices object instead.


Error Handling

If a call to CIMOM through the WBEM API for Scripting causes an error, the error information can be accessed using the native error mechanisms of the scripting language.

Visual Basic and VBScript Support for Error Handling

In Visual Basic or VBScript error handling is supported using the Err object. The Description property of this object will contain a human-readable description of the error. The Number property is set to the HRESULT returned by the Scripting API. The Source property is set to a string that identifies the object that raised the error.

JScript Support for Error Handling

Currently there are no error handling mechanisms defined in JScript (this should change for JScript 5.0).

Perl Support for Error Handling

TBD.


Using the WbemScripting Type Library

You can use the WBEM Scripting API from Microsoft® Visual Basic®. First, you need to use the following procedure to make the Visual Basic integrated development environment (IDE) aware of the WbemScripting type library by adding it to the project references.

To add the WbemScripting type library to the project references:

  1. Select References from the Project menu.
  2. In the Available References dialog box, check WBEM Scripting API V1.0.
  3. If WBEM Scripting API V1.0 does not appear in the Available References list, add it by using the Browse button in the References dialog box. The Browse button opens an Add Reference dialog box that enables you to locate the WbemScripting type library. The WbemScripting type library resides in the file Wbemscrp.tlb in the \Wbem directory.
  4. Select the file and click Open; WBEM Scripting API V1.0 appears on the references list. Make sure you check the box next to this item in the list.


Security Issues When Writing Scripts For WBEM

There are several security issues that need to be considered when developing scripts for WBEM.

  • Access Denied Error when Connecting
  • GetObject and HTML


Access Denied Error When Connecting

Windows Management may have difficulty connecting to a name space when running a script from an Active Server Pages (ASP) page. This is because IIS configures ASP pages to run in the context of a special account with a name derived from your machine name. The user accounts set up by IIS are not always recognized by Windows Management. There are several solutions to this problem.

  1. To grant access to Windows Management, you can use the WBEM User Manager (wbemuser.exe) on the user account created by IIS.
  2. You can change the security configuration in IIS to use Microsoft® Window NT® Challenge/Response rather than Anonymous Access. The identity of the client running the browser will then be passed through to Windows Management.
  3. You can change the IIS account used for anonymous access to another account that is recognized by Windows Management.


GetObject and HTML

You cannot use the GetObject function provided by VBScript and JScript when running scripts embedded within an HTML page. Internet Explorer disallows the use of this call because of security reasons.


Scripting API Reference

The Windows Management (WinMgmt) programmer's reference for scripting provides the application programming interface (API) definitions for the Web-Based Enterprise Management (WBEM) scripting API. This reference provides information for developers who are writing applications using Microsoft® Visual Basic®, Microsoft® Visual Basic for Applications, Microsoft® Visual Basic® Scripting Edition, Microsoft® JScript®, and Perl.

The following table describes WBEM objects and how they are used.

Object | Description
ISWbemLocator | Used to obtain an ISWbemServices object that can access Windows Management on a particular host machine.
ISWbemServices | Used to create, update, and retrieve instances or classes.
ISWbemObjectSet | Used to access a collection of objects of type ISWbemObject.
ISWbemObject | Used to contain and manipulate a single Common Information Model (CIM) object class or instance.
ISWbemNamedValue | Used to contain a single named value.
ISWbemNamedValueSet | Used to access a collection of objects of type ISWbemNamedValue items.
ISWbemObjectPath | Used to generate and validate an object path.
ISWbemLastError | Used to provide extended error information when there is an error.
ISWbemPropertySet | Used to access a collection of objects of type ISWbemProperty.
ISWbemProperty | Used to contain a single CIM property.
ISWbemQualifierSet | Used to access a collection of objects of type ISWbemQualifier .
ISWbemQualifier | Used to contain a single CIM qualifier.
ISWbemMethod | Used to contain a single CIM Method definition.
ISWbemMethodSet | Used to access a collection of objects of type ISWbemMethod.
ISWbemEventSource | Used to retrieve events in conjunction with ISWbemServices.ExecNotificationQuery


ISWbemServices

You can use the methods of an ISWbemServices object to perform operations against a namespace on a local or remote host.

Methods

AssociatorsOf | Returns a collection of objects (classes or instances) that are associated with a specified object. This method performs the same function that the WBEM Query Language (WQL) "Associators Of" query performs.
Delete | Deletes an instance or class.
ExecMethod | Executes an object method.
ExecNotificationQuery | Executes a query to receive events.
ExecQuery | Executes a query to retrieve a collection of objects (classes or instances).
Get | Retrieves a class or instance.
InstancesOf | Returns a collection of instances of a specified class.
ReferencesTo | Returns a collection of objects (classes or instances) that refer to a single object. This method performs the same function that the WQL "References Of" query performs.
SubclassesOf | Returns a collection of subclasses of a specified class.


ISWbemServices.AssociatorsOf

The AssociatorsOf method of the ISWbemServices object returns a collection of objects (classes or instances) that are associated with a specified object. These returned objects are called endpoints. This method performs the same function that the WQL "Associators Of" query performs.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemServices.AssociatorsOf(
strObjectPath,
[strAssocClass=""],
[strResultClass=""],
[strResultRole=""],
[strRole=""],
[bClassesOnly=FALSE],
[bSchemaOnly=FALSE],
[strRequiredAssocQualifier=""],
[strRequiredQualifier=""],
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

strObjectPath
Required. This is a string containing the object path of the source class or instance.
strAssocClass
Optional. This is a string that contains an association class. If specified, this parameter indicates that the returned endpoints must be associated with the source through the specified association class or a class derived from this association class.
strResultClass
Optional. This is a string that contains a class name. If specified, this optional parameter indicates that the returned endpoints must belong to or be derived from the class specified in this parameter.
strResultRole
Optional. This is a string that contains a property name. If specified, this parameter indicates that the returned endpoints must play a particular role in their association with the source object. The role is defined by the name of a specified property—which must be a reference property—of an association.
strRole
Optional. This is a string that contains a property name. If specified, this parameter indicates that the returned endpoints must participate in an association with the source object in which the source object plays a particular role. The role is defined by the name of a specified property—which must be a reference property—of an association.
bClassesOnly
Optional. This is a Boolean value that indicates whether a list of class names should be returned rather than actual instances of the classes. These are the classes to which the endpoint instances belong. The default value for this parameter is FALSE.
bSchemaOnly
Optional. This is a Boolean value that indicates whether the query applies to schema rather than data. The default value for this parameter is FALSE. It can only be set to TRUE if the strObjectPath parameter specifies the object path of a class. When set to TRUE, the set of returned endpoints represent classes that are suitably associated with the source class in schema.
strRequiredAssocQualifier
Optional. This is a string that contains a qualifier name. This parameter, if specified, indicates that the returned endpoints must be associated with the source object through an association class that includes the specified qualifier.
strRequiredQualifier
Optional. This is a string that contains a qualifier name. This parameter, if specified, indicates that the returned endpoints must include the specified qualifier.
iFlags
Optional. This is an integer specifying additional flags to the operation. The default for this parameter is wbemFlagReturnImmediately, which directs the call to return immediately rather than wait until the query has completed. This parameter can return the following values.
Value Meaning
wbemFlagForwardOnly
0x20 		This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but do not allow calls to Clone or Reset.
wbemFlagBidirectional
0 		This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectSet will be returned.

Error Codes

The AssociatorsOf method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed 0x80041001 | There is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

It is not an error for the returned collection to have zero elements.

For information about the associated WQL query "Associators Of", source instances and endpoints see "Data Queries" in the "WBEM Query Language" section of the Web-Based Enterprise Management (WBEM) software development kit (SDK) reference.

See Also

ISWbemServices.ReferencesTo, ISWbemObject.References_, ISWbemObject.Associators_


ISWbemServices.ReferencesTo

The ReferencesTo method of the ISWbemServices object returns a collection of all association classes or instances that refer to a particular source class or instance.

This method performs the same function that the WQL "References Of" query performs.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemServices.ReferencesTo(
strObjectPath,
[strResultClass=""],
[strRole=""],
[bClassesOnly=FALSE],
[bSchemaOnly=FALSE],
[strRequiredQualifier=""],
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

strObjectPath
Required. This is a string containing the object path of the source for this method.
strResultClass
Optional. This is a string that contains a class name. This parameter, if specified, indicates that the returned association objects must belong to or be derived from the class specified in this parameter.
strRole
Optional. This is a string that contains a property name. If specified, this parameter indicates that the returned association objects must be limited to those in which the source object plays a particular role. The role is defined by the name of a specified property—which must be a reference property—of an association.
bClassesOnly
Optional. This is a Boolean value that indicates whether a list of class names should be returned rather than actual instances of the classes. These are the classes to which the association objects belong. The default value for this parameter is FALSE.
bSchemaOnly
Optional. This is a Boolean value that indicates whether the query applies to schema rather than data. The default value for this parameter is FALSE. It can only be set to TRUE if the strObjectPath parameter specifies the object path of a class. When set to TRUE, the set of returned endpoints represent classes that are suitably associated with the source class in schema.
strRequiredQualifier
Optional. This is a string that contains a qualifier name. This parameter, if specified, indicates that the returned association objects must include the specified qualifier.
iFlags
Optional. This is an integer specifying additional flags to the operation. The default for this parameter is wbemFlagReturnImmediately, which directs the call to return immediately rather than wait until the query has completed. This parameter can return the following values.
Value Meaning
wbemFlagForwardOnly
0x20 		This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but do not allow calls to Clone or Reset.
wbemFlagBidirectional
0 		This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectSet will be returned.

Error Codes

The ReferencesTo method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed 0x80041001 | There is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

It is not an error for the returned collection to have zero elements.

For information about the associated WQL query "References Of", source instances, and association objects, see "Data Queries" in the "WBEM Query Language" section of the WBEM SDK reference.

See Also

ISWbemServices.AssociatorsOf, ISWbemObject.References_, ISWbemObject.Associators_


ISWbemServices.SubclassesOf

The SubclassesOf method of the ISWbemServices object returns an object of type ISWbemObjectSet. This object is a collection of subclasses of a specified class. Items in the returned collection can be obtained by way of standard collection methods. See Collections for information on using collections.

Note This method only works for class objects.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemServices.SubclassesOf(
[strSuperclass=""],
[iFlags=wbemFlagReturnImmediately|wbemQueryFlagDeep],
[objwbemNamedValueSet=null]
)

Parameters

strSuperclass
Optional. This parameter, if not blank, specifies a superclass name. Only the classes that are subclasses of this class return in the enumerator. If it is blank, and if iFlags is wbemQueryFlagShallow, only the top-level classes (that is, classes that have no parent class or superclass) are returned. If it is blank, and iFlags is wbemQueryFlagDeep, all classes within the namespace are returned.
iFlags
Optional. This determines how deep the enumeration will be. See the flags section below for more details. The default value for this parameter is wbemFlagReturnImmediately|wbemQueryFlagDeep. This parameter can return the following values.
Value Meaning
wbemQueryFlagShallow
1 		This value forces recursive enumeration into all subclasses derived from the specified superclass. The superclass itself is not returned in the enumeration.
WbemQueryFlagDeep
0 		This is the default for this parameter. It forces the enumeration to include only immediate subclasses of the specified superclass.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectSet will be returned.

Error Codes

The SubclassesOf method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed 0x80041001 | There is an unspecified error.
wbemErrInvalidClass 0x80041010 | The specified class did not exist.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

It is not an error for the returned collection to have zero elements.

See Also

ISWbemObjectSet


ISWbemServices.InstancesOf

The InstancesOf method of the ISWbemServices object 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 ISWbemServices.ExecQuery.

Note This method only works for class objects. It is not an error for the returned enumerator to have zero elements.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemServices.InstancesOf(
strClass,
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

strClass
Required. This is a string containing the name of the class for which instances are desired. This parameter cannot be blank.
iFlags
Optional. This parameter determines how deep the call will enumerate and if this call will return immediately or wait until the call is complete before returning. The default value for this parameter is wbemFlagReturnImmediately. This parameter can return the following values.
Value Meaning
wbemFlagForwardOnly
0x20 		This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but do not allow calls to Clone or Reset.
wbemFlagBidirectional
0 		This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately
0x10 		This is the default value for this parameter. This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.
WbemQueryFlagShallow
1 		This flag forces the enumeration to include only immediate subclasses of the specified superclass.
WbemQueryFlagDeep
0 		This is the default for this parameter. This value forces the enumeration to include all of class in the hierarchy.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If successful, an object of type ISWbemObjectSet is returned.

Error Codes

The InstancesOf method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view instances of the specified class.
wbemErrFailed 0x80041001 | An unspecified error occurred.
wbemErrInvalidClass 0x80041010 | The specified class is invalid.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObjectSet


ISWbemServices.Delete

The Delete method of the ISWbemServices object deletes the class or instance specified in the object path. You can only delete objects in the current namespace.

If a dynamic provider supplied the class or instance, it is sometimes not possible to delete this object unless the provider supports class or instance deletion.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemServices.Delete(
strObjectPath,
[iFlags=0],
[objwbemNamedValueSet=null]
)

Parameters

strObjectPath
Required. This is a string containing the object path to the object that you want to delete. Object paths can be constructed by hand, or built using the ISWbemObjectPath interface, or from the Path_ property of an instance of ISWbemObject.
iFlags
Reserved. It must be zero.
objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

None

Error Codes

The Delete method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current context does not have adequate security rights to delete the object.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidClass 0x80041010 | The specified class does not exist.
wbemErrInvalidOperation 0x80041016 | The object cannot be deleted.
wbemErrNotFound 0x80041002 | The object did not exist.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObjectPath


ISWbemServices.ExecMethod

The ExecMethod method of the ISWbemServices object executes a method exported by a method provider. This method can be used as an alternate way to execute a method in cases where it is not possible to execute a method directly. For example, you would need to use it with a scripting language such as Microsoft® JScript® that does not support output parameters, if your method has out parameters. Otherwise, the recommended means of invoking a method is to use direct method invocation. Direct method invocation is executing a method by using object.method syntax. For example, to execute a method called "get" on an object called "myobject" you could use the syntax: myobject.get. For more information on direct method invocation, see Direct Access.

This method will block while the method that is forwarded to the appropriate provider executes. The information and status are then returned.

Windows Management does not implement the methods directly. The method providers export the methods.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objOutParams = objwbemServices.ExecMethod(
strObjectPath,
strMethodName,
[objwbemInParams=null],
[iFlags=0],
[objwbemNamedValueSet=null]
)

Parameters

strObjectPath
Required. This is a string containing the object path of the object for which the method is executed. Object paths can be constructed by hand, or built using the ISWbemObjectPath object or from the Path_ property of an instance of ISWbemObject.
strMethodName
Required. It is the name of the method for the object.
objwbemInParams
Optional. This is an ISWbemObject object that contains the input parameters for the method being executed. The following procedure describes the four steps in constructing this parameter:

To construct the objwbemInParams parameter

  1. Call ISWbemObject.Methods_.Item("MethodName") to get an ISWbemMethod object that contains the properties that describe the method, where "MethodName" is the name of the method to retrieve.
  2. Use the ISWbemMethod.InParameters property of the ISWbemMethod object to get an InParameters object.
  3. Call SpawnInstance_ on the InParameters object to create an instance.
  4. Set the properties of the instance to whatever values are appropriate. For example, If you want to set an input parameter named myinputparam to the value "whatever" in an instance of InParameters called "INST", the code would look like this: INST.Properties_.Add("myinputparam").Value = "Whatever"

    By default, this parameter is undefined.

iFlags
Optional. This parameter is reserved, and must be zero.
objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

An object of type ISWbemObject is returned if this call is successful. The returned object contains the out parameters and return value for the method being executed.

Error Codes

The ExecMethod method can return the error codes listed in the following table.

Error | Description
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidClass 0x80041010 | The specified class was invalid.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.
wbemErrInvalidMethod 0x8004102E | The requested method was not available.
wbemErrAccessDenied 0x80041003 | The current user was not authorized to execute the method.

See Also

ISWbemObject.ExecMethod_


ISWbemServices.ExecNotificationQuery

The ExecNotificationQuery method of the ISWbemServices object executes a query to receive events. The call returns immediately. The user can poll the returned enumerator for events as they arrive.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemServices.ExecNotificationQuery(
strQuery,
[strQueryLanguage="WQL"],
[iFlags=(wbemFlagReturnImmediately|wbemFlagForwardOnly)],
[objwbemNamedValueSet=null]
)

Parameters

strQuery
Required. This is a string containing the text of the event-related query. This cannot be blank.
strQueryLanguage
Optional. This is a string containing one of the query languages supported by Windows Management. This must be "WQL".
iFlags
Optional. This is an integer parameter that determines the behavior of the query. The default value is wbemFlagForwardOnly combined with wbemFlagReturnImmediately. This parameter can return the following values.
Value Meaning
wbemFlagForwardOnly
0x20 		This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but do not allow calls to Clone or Reset.
wbemFlagBidirectional
0 		This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If no error occurs, this method returns an object that is of type ISWbemEventSource. You can call the ISWbemEventSource.NextEvent method to retrieve events as they arrive.

Error Codes

The ExecNotificationQuery method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user is not authorized to view the result set.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrInvalidQuery 0x80041017 | The query was not valid syntactically.
wbemErrInvalidQueryType 0x80041018 | The requested query language is not supported.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemServices.ExecQuery


ISWbemServices.ExecQuery

The ExecQuery method of the ISWbemServices object executes a query to retrieve objects. These objects are available through the returned ISWbemObjectSet collection.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemServices.ExecQuery(
strQuery,
[strQueryLanguage="WQL"],
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

strQuery
Required. This is a string containing the text of the query. This parameter cannot be blank.
strQueryLanguage
Optional. This parameter is a string containing one of the query languages supported by Windows Management. If it is supplied, it must be "WQL".
iFlags
Optional. This is an integer parameter that determines the behavior of the query and determines if this call will wait for all results or return immediately. The default value for this parameter is wbemFlagReturnImmediately. This parameter can return the following values.
Value Meaning
wbemFlagForwardOnly
0x20 		This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but do not allow calls to Clone or Reset.
wbemFlagBidirectional
0 		This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If no error occurs, this method returns an object that is of type ISWbemObjectSet. This is an object collection that contains the result set of the query. The caller can examine the collection using the implementation of collections for the programming language you are using. For more information on collections, see Collections.

Error Codes

The ExecQuery method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view the result set.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrInvalidQuery 0x80041017 | The query was not syntactically valid.
wbemErrInvalidQueryType 0x80041018 | The requested query language is not supported.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

It is not an error for the query to return an empty result set

See Also

ISWbemServices.Get


ISWbemServices.Get

The Get method of the ISWbemServices object 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 ISWbemServices object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objObject = objwbemServices.Get(
[strObjectPath=""],
[ilFlags=0],
[objwbemNamedValueSet=null]
)

Parameters

strObjectPath
Optional. The object path of the object you want to retrieve. If this is empty, an empty object is returned that can become a new class. Object paths can be constructed by hand, or built using the ISWbemObjectPath interface or from the Path_ property of an instance of ISWbemObject. This parameter is optional.
iFlags
Optional. This parameter is reserved and must be zero if specified.
objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If successful, this method returns an ISWbemObject representing the requested object.

Error Codes

The Get method can return the error codes listed in the following table.

wbemErrAccessDenied 0x80041003 | The current user does not have permission to access the object.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrInvalidObjectPath 0xH8004103A | The specified path was invalid.
wbemErrNotFound 0x80041002 | The requested object could not be found.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObject


ISWbemObjectSet

An ISWbemObjectSet object is a collection of objects of type ISWbemObject. For information on using collections, see Collections.

An ISWbemObjectSet object can be obtained by calling any of the following methods:

ISWbemServices.InstancesOf

ISWbemServices.SubclassesOf

ISWbemServices.ExecNotificationQuery

ISWbemServices.ExecQuery

ISWbemServices.AssociatorsOf

ISWbemServices.ReferencesTo

ISWbemObject.Associators_

ISWbemObject.References_

Note ISWbemObjectSet does not support the optional Add and Remove collection methods.

Methods

Method | Description
Item | Retrieves an ISWbemObject from the collection. This is the default method of the object.

Properties

Property | Description
Count | The number of items in the collection.


ISWbemObjectSet.Item

The Item method of the ISWbemObjectSet object gets an ISWbemObject from the collection.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objObject = objwbemObjectSet.Item(
strObjectPath,
[iFlags=0]
)

Parameters

strObjectPath
Required. The relative path of the object you want to retrieve from the collection (for example, Win32_LogicalDisk="C:").
iFlags
Optional. This parameter is reserved and the default value is 0.

Return Value

If successful, the requested ISWbemObject is returned.

Error Codes

The Item method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.
wbemErrNotFound 0x80041002 | The requested item was not found.

Remarks

This method may be expensive (require a lot of processor time) as complete enumeration by the provider of the elements of the set is required to return the result


ISWbemObjectSet.Count

Use the Count property of the ISWbemObjectSet object to determine how many items are in the context collection. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

iCount = objWbemObjectSet.Count

Remarks

This method may be expensive (require a lot of processor time) as complete enumeration by the provider of the elements of the set is required to return the result.


ISWbemNamedValueSet

An ISWbemNamedValueSet object is a collection of objects of type ISWbemNamedValue. The methods and properties of ISWbemNamedValueSet are used principally to send additional information to providers when submitting certain calls to Windows Management. All calls in ISWbemServices, and some calls in ISWbemObject, take an optional parameter that is an object of this type. A client can add information to an ISWbemNamedValueSet object, and send the ISWbemNamedValueSet object along with the call as one of the parameters.

For information on using collections, see Collections.

Note It is very important that providers make as little use of this mechanism as possible. It is recommended that providers 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 the Web-Based Enterprise Management (WBEM). Nevertheless, in some situations you will not be able to avoid it. Therefore, this mechanism allows you to access such providers, if necessary.

An ISWbemNamedValueSet object is a collection of ISWbemNamedValue elements. These Items are added to the collection using the ISWbemNamedValueSet.Add method. They are removed using the ISWbemNamedValueSet.Remove method and retrieved using the ISWbemNamedValueSet.Item method. You can access the methods to fill in any context information required by a dynamic provider. After you call one of the ISWbemServices methods, you can reuse the ISWbemNamedValueSet object for another call.

The underlying provider determines the information contained in an ISWbemNamedValueSet object. Windows Management 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

Method | Description
Add | Adds an ISWbemNamedValue object to the collection.
DeleteAll | Removes all items from the collection, making the ISWbemNamedValueSet object empty.
Item | Retrieves an ISWbemNamedValue from the collection. This is the default method of the object.
Remove | Removes an ISWbemNamedValue object from the collection.

Properties

Property | Description
Count | The number of items in the collection.


ISWbemNamedValueSet.Add

The Add method of the ISWbemNamedValueSet object adds an ISWbemNamedValue object to the collection. If an element already exists in the collection with the same name, the new element replaces it.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objNamedValue = objwbemNamedValueSet.Add(
strName,
varVal,
[iFlags=0]
)

Parameters

strName
Required. This is the name of the new value.
varVal
Required. This is a variant representing the new value.
iFlags
Optional. This parameter is reserved and must be set to zero if specified.

Return Value

If successful, this method returns the newly modified or created ISWbemNamedValue.

Remarks

For examples of adding and retrieving named values, see ISWbemNamedValue.Value.


ISWbemNamedValueSet.Count

Use the Count property of the ISWbemNamedValueSet object to determine how many items are in the collection. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

iCount = objwbemNamedValueSet.Count


ISWbemNamedValueSet.DeleteAll

The DeleteAll method of the ISWbemNamedValueSet object removes all named values from the collection, thus emptying it.

Syntax

objwbemNamedValueSet.DeleteAll

Return Value

None.

Error Codes

The DeleteAll method can return the error code listed in the following table.

Error | Description
wbemErrFailed 0x80041001 | This is an unspecified error.

See Also

ISWbemNamedValueSet.Remove


ISWbemNamedValueSet.Item

The Item method of the ISWbemNamedValueSet object gets an ISWbemNamedValue from the collection.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objNamedValue = objwbemNamedValueSet.Item(
strName,
[iFlags=0]
)

Parameters

strName
Required. This is the name of the value to retrieve.
iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

If successful, the requested ISWbemNamedValue is returned.

Error Codes

The Item method can return the error codes listed in the following table.

Error | Description
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified, or the namespace could not be parsed.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.
wbemErrNotFound 0x80041002 | The requested item was not found.

Remarks

For examples of adding and retrieving named values, see ISWbemNamedValue.Value.


ISWbemNamedValueSet.Remove

The Remove method of the ISWbemNamedValueSet object deletes a named value from the context.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objwbemNamedValueSet.Remove(
strName,
[iFlags=0]
)

Parameters

strName
Required. This is the name of the value to remove.
iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

None.

Error Codes

The Remove method can return the error codes listed in the following table.

Error | Description
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified, or the namespace could not be parsed.
wbemErrNotFound 0x80041002 | The requested item was not found.


ISWbemLocator

You can use the methods of the ISWbemLocator object to obtain an ISWbemServices object that represents a connection to a namespace on a local or remote host machine. You can then use the methods on the ISWbemServices object to access Windows Management (WinMgmt).

Methods

ConnectServer Connects to Windows Management on the specified machine.


ISWbemLocator.ConnectServer

The ConnectServer method of the ISWbemLocator object connects to the namespace on the machine specified in the Server parameter. This can be either a local or remote target machine, typically with a Microsoft® Windows NT® or Microsoft® Windows® 95/98 operating system, which must have an operational Windows Management. If the method is successful, a ISWbemServices object will be returned that is bound to the namespace on the host machine.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objwbemServices = objwbemLocator.ConnectServer(
[strServer=""],
[strNameSpace=""],
[strUser=""],
[strPassword=""],
[strLocale=""],
[strAuthority=""],
[iSecurityFlags=0],
[objwbemNamedValueSet=null]
)

Parameters

strServer
Optional. For access to a remote machine using Distributed Component Object Model (DCOM), this parameter specifies the machine name. One example would be "myserver". If you do not provide this parameter, the call will default to the local machine.
strNameSpace
Optional. This is a string that specifies the namespace to which you log on. For example, to log on to the root\default namespace, use "root\default". If you do not specify this parameter, it will default to the namespace that has been configured as the default name space for scripting. For more information on the default value for this parameter, see Object Creation and Monikers.
strUser
Optional. This is a string that specifies the user name to use while attempting to connect. This can be in the form of a user name or domain\username. Leave it blank to use the current logged-on user name .
strPassword
Optional. This is a string that specifies the password to use when attempting to connect. Leave it blank to use the password of the current logged-on user.
strLocale
Optional. This is a string that specifies the localization code. If you want to use the current locale, leave it blank. If not blank, 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.

strAuthority
Optional. It can be a NT LAN Manager (NTLM) domain name. Otherwise, it should be left blank.
iSecurityFlags
Optional. This parameter reserved and must be zero if specified.
objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If successful, an object of type ISWbemServices that is bound to the specified namespace is returned.

Error Codes

The ConnectServer method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current or specified user name and password were not valid or authorized to make the connection.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidNamespace 0x80041013 | The specified namespace did not exist on the server.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified, or the namespace could not be parsed.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.
wbemErrTransportFailure 0x80041015 | A networking error occurred, preventing normal operation.

Remarks

An error code of Hex 0x80070005 indicates a DCOM access-denied error.

See Also

ISWbemServices


ISWbemNamedValue

The ISWbemNamedValue object represents a single named value that belongs to the ISWbemNamedValueSet collection object.

Properties

Property | Description
Name | Name of the ISWbemNamedValue item.
Value | Value of the ISWbemNamedValue item. This is the default property of this object.


ISWbemNamedValue.Name

The Name property of the ISWbemNamedValue object is a unique case-insensitive string that is used when retrieving or setting an ISWbemNamedValue item. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strName = objwbemNamedValue.Name


ISWbemNamedValue.Value

The Value property of the ISWbemNamedValue object returns the variant value of an ISWbemNamedValue item. This is the default property for ISWbemNamedValue objects. Changes made to the value property are reflected automatically in the ISWbemNamedValueSet collection to which the ISWbemNamedValue belongs.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

varValue = objwbemNamedValue.Value


ISWbemObjectPath

Use the methods and properties of the ISWbemObjectPath object to construct and validate an object path.

Methods

Method | Description
SetAsClass | Forces the path to address a Common Information Model (CIM) class.
SetAsSingleton | Forces the path to address a singleton CIM instance.

Properties

Property | Description
Keys | This property is a ISWbemNamedValueSet that contains the key value bindings.
Class | The name of the class that will be part of the object path.
DisplayName | A string that contains the path in a form that can be used as a moniker display name. See Object Creation and Monikers.
IsClass | Boolean value that indicates if this path represents a class. This is analogous to the __GENUS property in the Component Object Model (COM) application programming interface (API).
IsSingleton | Boolean value that indicates if this path represents a singleton instance.
Namespace | The name of the namespace that is part of the object path. This is the same as the __NAMESPACE property in the COM API.
ParentNamespace | The name of the parent of the namespace that is part of the object path.
Path | Contains the absolute path. This is the same as the __PATH system property in the COM API. This is the default property of this object.
Relpath | Contains the relative path. This is the same as the __RELPATH system property in the COM API.
Server | The name of the server. This is the same as the __SERVER system property in the COM API.


ISWbemObjectPath.SetAsClass

The SetAsClass method of the ISWbemObjectPath object forces the path to address a CIM class.

Syntax

objwbemObjectPath.SetAsClass

Return Value

None.

Error Codes

The SetAsClass method can return the following error code.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.


ISWbemObjectPath.SetAsSingleton

The SetAsSingleton method of the ISWbemObjectPath object forces the path to address a singleton CIM instance. A singleton class is a class that can never have more than one instance.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objwbemObjectPath.SetAsSingleton()

Return Value

None.

Error Codes

The SetAsSingleton method can return the following error code.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.


ISWbemObjectPath.Keys

The Keys property of the ISWbemObjectPath object is an object of type ISWbemNamedValueSet that contains the key value bindings.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objNamedValueSet = objwbemObjectPath.Keys


ISWbemObjectPath.Class

The Class property of the ISWbemObjectPath object is the name of the class that is part of the object path.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strClass = objwbemObjectPath.Class
objwbemObjectPath.Class = strClass


ISWbemObjectPath.DisplayName

The DisplayName property of the ISWbemObjectPath object is a string that contains the path in a form that can be used as a moniker display name.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strDisplayName = objwbemObjectPath.DisplayName
objwbemObjectPath.DisplayName = strDisplayName


ISWbemObjectPath.IsClass

The IsClass property of the ISWbemObjectPath object is a Boolean value that indicates if this path represents a class. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bIsClass = objwbemObjectPath.IsClass


ISWbemObjectPath.IsSingleton

The IsSingleton property of the ISWbemObjectPath object is a Boolean value that indicates if this path represents a singleton instance. A singleton instance is an instance of a class that can never have more than one instance. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bIsSingleton = objwbemObjectPath.IsSingleton
objwbemObjectPath.IsSingleton = bIsSingleton


ISWbemObjectPath.Namespace

The Namespace property of the ISWbemObjectPath object contains the name of the namespace that is part of the object path.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strNamespace = objwbemObjectPath.Namespace
objwbemObjectPath.Namespace = strNamespace


ISWbemObjectPath.ParentNamespace

The ParentNamespace property of the ISWbemObjectPath object contains the name of the parent namespace that is part of the object path. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strParentNamespace = objwbemObjectPath.ParentNamespace


ISWbemObjectPath.Path

The Path property of the ISWbemObjectPath object contains the absolute path. This is the same as the __PATH property in the COM API. This is the default property of this object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strPath = objwbemObjectPath.Path
objwbemObjectPath.Path = strPath


ISWbemObjectPath.Relpath

The Relpath property of the ISWbemObjectPath object contains the relative path.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strRelPath = objwbemObjectPath.RelPath
objwbemObjectPath.RelPath = strRelPath


ISWbemObjectPath.Server

The Server property of the ISWbemObjectPath object contains the name of the server that is be part of the object path.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strServer = objwbemObjectPath.Server
objwbemObjectPath. Server = strServer


ISWbemObject

You can use the methods and properties of the ISWbemObject object to represent a single Component Object Model (CIM) class definition or CIM object instance.

This object supports two types of properties and methods. Those defined in this section are generic properties and methods that apply to all CIM objects. In addition, this object exposes the CIM Properties (respectively, Methods) of the object as dynamic Automation Properties (respectively, Methods) of this object. These names and types of these properties and methods depend on the underlying CIM Object. For more information on how these dynamic properties and methods are exposed, refer to Direct Access.

From the Web-Based Enterprise Management (WBEM) client perspective, this object is always in-process. Write operations only affect the local copy of the object, and read operations always retrieve values from the local copy. Updates to Windows Management are performed only when entire objects are written using a call to the ISWbemObject.Put_ method. If you modify the properties or methods in an ISWbemObject, your changes will be not written to Windows Management until you call ISWbemObject.Put_.

The generic method and property names defined in this section always end with a trailing underscore ("_") to differentiate them from the dynamic CIM methods and properties of the underlying CIM object.

Methods

Method | Description
Associators_ | Retrieves the Associators of the object.
Clone_ | Makes a copy of the current object.
CompareTo_ | Tests two objects for equality.
Delete_ | Deletes the object from Windows Management.
GetObjectText_ | Retrieves the textual representation of the object (MOF syntax).
Instances_ | Returns a collection of instances of the object (which must be a CIM class).
Put_ | Creates or updates the object in Windows Management.
References_ | Returns References to the object.
SpawnDerivedClass_ | Creates a new derived class from the current object (which must be a CIM class).
SpawnInstance_ | Creates a new instance from the current object.
Subclasses_ | Returns a collection of subclasses of the object (which must be a CIM class).
ExecMethod_ | Executes a method on the object.

Properties

Property | Description
Properties_ | This is an ISWbemPropertySet object. It is the collection of properties for this object.
Qualifiers_ | This is an ISWbemQualifierSet object. It is the collection of qualifiers for this object.
Methods_ | This is an ISWbemMethodSet object. It is the collection of methods for this object.
Derivation_ | Contains an array of strings describing the derivation hierarchy for the class.
Path_ | Contains a ISWbemObjectPath object that represents the object path of the current class or instance.


ISWbemObject.Clone_

The Clone_ method of the ISWbemObject object returns a new object that is a clone of the current object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objObject = objwbemObject.Clone_()

Return Value

If successful, a new ISWbemObject is returned.

Error Codes

The Clone_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | Nothing was specified as a parameter, and it is not acceptable in this usage.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to clone the object.

Remarks

Use this method to duplicate a class definition or 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 ISWbemObject.SpawnInstance_ to create a single starting instance, and use ISWbemObject.Clone_ to produce 100 copies of the instance quickly. Subsequently, you can modify the objects, giving each one specific values.

It is not possible to use this method to convert a class definition to an instance, or to convert an instance to a class definition.


ISWbemObject.CompareTo_

The CompareTo_ method of the ISWbemObject object compares two ISWbemObject type objects. This comparison is subject to certain constraints based on the values specified in the iFlags parameter.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bAreEqual = objwbemObject.CompareTo_(
objwbemObject,
[iFlags= wbemComparisonFlagIncludeAll]
)

Parameters

objwbemObject
Required. An Object of class ISWbemObject. This is the object with which the first object is compared. The object must be a valid ISWbemObject instance, and it cannot be undefined.
iFlags
Optional. It specifies the object characteristics to consider when comparing an object with other objects. You can use wbemComparisonFlagIncludeAll to consider all features (this is the default), or any combination of the following values.
Value Meaning
wbemComparisonFlagIncludeAll
0 		Use this flag to compare all properties, qualifiers, and flavors, or use one of the other flags listed below to ignore any of these items.
WbemComparisonFlagIgnoreObjectSource
2 		The source of the objects, namely the server and the namespace they came from, are ignored in comparison to other objects.
wbemComparisonFlagIgnoreQualifiers
1 		All qualifiers (including "key" and "dynamic") should be ignored in comparison.
WbemComparisonFlagIgnoreDefaultValues
4 		Default values of properties should be ignored. This flag is only meaningful when comparing classes.
wbemComparisonFlagIgnoreFlavor
0x20 		Ignore qualifier flavors. This flag still takes qualifier values into account, but ignores flavor distinctions such as propagation rules and override restrictions.
wbemComparisonFlagIgnoreCase
0x10 		Compares string values 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 whether this flag is specified or not.
WbemComparisonFlagIgnoreClass
8 		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 will be undefined.

Return Value

This method returns the Boolean value TRUE if the objects match or FALSE if they do not.

Error Codes

The CompareTo_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObject


ISWbemObject.Associators_

The Associators_ method of the ISWbemObject object returns a collection of objects (classes or instances) that are associated with the current object. These returned objects are called endpoints. This method performs the same function that the WBEM Query Language (WQL) "Associators Of" query performs.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemObject.Associators_(
[strAssocClass=""],
[strResultClass=""],
[strResultRole=""],
[strRole=""],
[bClassesOnly=FALSE],
[bSchemaOnly=FALSE],
[strRequiredAssocQualifier=""],
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

strAssocClass
Optional. This is a string that contains an association class. If specified, this parameter indicates that the returned endpoints must be associated with the source through the specified association class or a class derived from this association class.
strResultClass
Optional. This is a string that contains a class name. If specified, this parameter indicates that the returned endpoints must belong to or be derived from the class specified in this parameter.
strResultRole
Optional. This is a string that contains a property name. If specified, this parameter indicates that the returned endpoints must play a particular role in their association with the source object. The role is defined by the name of a specified property—which must be a reference property—of an association.
strRole
Optional. This is a string that contains a property name. If specified, this parameter indicates that the returned endpoints must participate in an association with the source object in which the source object plays a particular role. The role is defined by the name of a specified property—which must be a reference property—of an association.
bClassesOnly
Optional. This is a Boolean value that indicates whether a list of classnames should be returned rather than actual instances of the classes. These are the classes to which the endpoint instances belong. The default value for this parameter is FALSE.
bSchemaOnly
Optional. This is a Boolean value that indicates whether the query applies to schema rather than data. The default value for this parameter is FALSE. It can only be set to TRUE if the strObjectPath parameter specifies the object path of a class. When set to TRUE, the set of returned endpoints represent classes that are suitably associated with the source class in schema.
strRequiredAssocQualifier
Optional. This is a string that contains a qualifier name. This parameter, if specified, indicates that the returned endpoints must be associated with the source object through an association class that includes the specified qualifier.
strRequiredQualifier
Optional. This is a string that contains a qualifier name. This parameter, if specified, indicates that the returned endpoints must include the specified qualifier.
iFlags
Optional. This is an integer specifying additional flags to the operation. The default for this parameter is wbemFlagReturnImmediately, which directs the call to return immediately rather than wait until the query has completed. This parameter can return the following values.
Value Meaning
wbemFlagForwardOnly
0x20 		This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but do not allow calls to Clone or Reset.
wbemFlagBidirectional
0 		This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectSet will be returned.

Error Codes

The Associators_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed 0x80041001 | There is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

For information about the associated WQL query "Associators Of", source instances and endpoints see "Data Queries" in the "WBEM Query Language" section of the WBEM software development kit (SDK) reference.

See Also

ISWbemServices.AssociatorsOf, ISWbemServices.ReferencesTo, ISWbemObject.References_


ISWbemObject.References_

The References_ method of the ISWbemObject object returns a collection of all association classes or instances that refer to the current object.

This method performs the same function that the WQL "References Of" query performs.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemObject.References_(
[strResultClass=""],
[strRole=""],
[bClassesOnly=FALSE],
[bSchemaOnly=FALSE],
[strRequiredQualifier=""],
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

strResultClass
Optional. This is a string that contains a class name. This parameter, if specified, indicates that the returned association objects must belong to or be derived from the class specified in this parameter.
strRole
Optional. This is a string that contains a property name. If specified, this parameter indicates that the returned association objects must be limited to those in which the source object plays a particular role. The role is defined by the name of a specified property—which must be a reference property—of an association.
bClassesOnly
Optional. This is a Boolean value that indicates whether a list of classnames should be returned rather than actual instances of the classes. These are the classes to which the association objects belong. The default value for this parameter is FALSE.
bSchemaOnly
Optional. This is a Boolean value that indicates whether the query applies to schema rather than data. The default value for this parameter is FALSE. It can only be set to TRUE if the strObjectPath parameter specifies the object path of a class. When set to TRUE, the set of returned endpoints represent classes that are suitably associated with the source class in schema.
strRequiredQualifier
Optional. This is a string that contains a qualifier name. This parameter, if specified, indicates that the returned association objects must include the specified qualifier.
iFlags
Optional. This is an integer specifying additional flags to the operation. The default for this parameter is wbemFlagReturnImmediately, which directs the call to return immediately rather than wait until the query has completed. This parameter can return the following values.
Value Meaning
wbemFlagForwardOnly
0x20 		This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but do not allow calls to Clone or Reset.
wbemFlagBidirectional
0 		This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectSet will be returned.

Error Codes

The References_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed 0x80041001 | There is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

For information about the associated WQL query "References Of", source instances, and association objects, see "Data Queries" in the "WBEM Query Language" section of the WBEM SDK reference.

See Also

ISWbemServices.ReferencesTo, ISWbemServices.AssociatorsOf, ISWbemObject.Associators_


ISWbemObject.GetObjectText_

The GetObjectText_ method of the ISWbemObject object returns a textual rendering of the object. This interface can be used to display an object's contents. 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.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strMofText = objwbemObject.GetObjectText_(
[iFlags=0]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

If successful, this method will return a string that contains the output text.

Error Codes

The GetObjectText_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.


ISWbemObject.Put_

The Put_ method of the ISWbemObject object creates or updates an instance or class object to Windows Management. You can use this method after you have modified any properties or methods in an ISWbemObject object and your changes will be written to Windows Management.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objObjectPath = objwbemObject.Put_(
[iFlags= wbemChangeFlagCreateOrUpdate],
[objwbemNamedValueSet=null]
)

Parameters

iFlags
Optional. This parameter determines if the call will create or update the class or instance and if the call will return right away or not. This parameter can return the following values.
Value Meaning
wbemChangeFlagCreateOrUpdate
0 		This flag causes the class or instance to be created if it does not exist or overwritten if it exists already.
WbemChangeFlagCreateOnly
2 		This flag is used for creation only. The call will fail if the class or instance already exists.
WbemChangeFlagUpdateOnly
1 		This flag causes this call to update. The class or instance must exist for the call to be successful.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectPath will be returned. This will contain the object path of the instance or class that has been successfully committed to Windows Management.

Error Codes

The Put_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to update an instance of the specified class.
wbemErrAlreadyExists 0x80041002 | wbemChangeFlagCreateOnly flag was specified, but the instance already exists.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrIllegalNull 0x8004100A | 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.
wbemErrInvalidObject 0x80041014 | The specified instance is invalid.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrNotFound 0x80041002 | wbemChangeFlagUpdateOnly flag was specified, but the instance or class does not exist.
wbemErrIncompleteClass 0x8004100C | Required properties for classes have not all been set.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObjectPath.Class, ISWbemQualifier, ISWbemProperty


ISWbemObject.SpawnDerivedClass_

Use the SpawnDerivedClass_ method of the ISWbemObject object to create a derived class object from the current object. The object must be a class definition that becomes the superclass of the spawned object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objNewClass = objwbemObject.SpawnDerivedClass_(
[iFlags=0]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

If the call is successful, an object of type ISWbemObject is returned that contains the new class definition object. No object is returned when there is an error.

Error Codes

The SpawnDerivedClass_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x8004100 | This is an unspecified error.
wbemErrIllegalOperation 0x8004101E | The user requested an illegal operation, such as spawning a class from an instance.
wbemErrIncompleteClass 0x8004100C | The source class was not completely defined or registered with Windows Management, so a new derived class is not permitted.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

The object returned 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. Before you can use this method to create a derived class, you must create the base class. To create the base class, call ISWbemObject.Put_, and retrieve it using ISWbemServices.Get.


ISWbemObject.SpawnInstance_

Use the SpawnInstance_ method of the ISWbemObject object to create a new instance of a class. The current object must be a class definition obtained from Windows Management via a method such as ISWbemServices.Get or ISWbemServices.ExecQuery. Then use this class definition to create new instances. Create each new instance locally within the process, and then call ISWbemObject.Put_ to actually create the instance within Windows Management.

Note Spawning an instance from an instance is acceptable.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objNewInstance = objwbemObject.SpawnInstance_(
[iFlags=0]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

If successful, this call returns an object of type ISWbemObject that contains a new instance of the class.

Error Codes

The SpawnInstance_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrIncompleteClass 0xH80041020 | 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 Windows Management using ISWbemObject.Put_.
wbemErrIllegalOperation 0xH8004101E | Returned if this method is used on an instance instead of a class.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemServices.Get, ISWbemObject.Put_


ISWbemObject.ExecMethod_

The ExecMethod_ method of the ISWbemObject object executes a method exported by a method provider. This method is similar to ISWbemServices.ExecMethod, but it operates directly on the object whose method is to be executed.

Use ISWbemObject.ExecMethod_ as an alternate way to execute a method in cases where it is not possible to execute a method directly. For example, you would need to use it with a scripting language such as Microsoft® JScript® that does not support output parameters, if your method has out parameters. Otherwise, the recommended means of invoking a method is to use direct method invocation. Direct method invocation is executing a method by using object.method syntax. For more information on direct method invocation, see Direct Access.

This method will block while the method that is forwarded to the appropriate provider executes. The information and status are then returned.

Windows Management does not implement the methods directly. The method providers export the methods.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objOutParams = objwbemObject.ExecMethod_(
strMethodName,
[objwbemInParams=null],
[iFlags=0],
[objwbemNamedValueSet=null]
)

Parameters

strMethodName
Required. This is the name of the method for the object.
objwbemInParams
Optional. This is an ISWbemObject object that contains the input parameters for the method being executed.

To construct the objwbemInParams parameter

  1. Call ISWbemObject.Methods_.Item("MethodName") to get an ISWbemMethod object that contains the properties that describe the method, where "MethodName" is the name of the method to retrieve.
  2. Use the ISWbemMethod.InParameters property of the ISWbemMethod object to get an InParameters object.
  3. Call SpawnInstance_ on the InParameters object to create an instance.
  4. Set the properties of the instance to whatever values are appropriate. For example, If you want to set an input parameter named myinputparam to the value "whatever" in an instance of InParameters called "INST", the code would look like this: INST.Properties_.Add ("myinputparam").Value = "Whatever"

    The default value for this parameter is undefined.

iFlags
Optional. This parameter is reserved and must be set to zero if specified.
objwbemNamedValueSet
Optional. Typically, it is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

A object of ISWbemObject is returned if this call is successful. The returned object contains the out parameters and return value for the method being executed.

Error Codes

The ExecMethod_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidClass 0x80041010 | The specified class was invalid.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.
wbemErrInvalidMethod 0x8004102E | The requested method was not available.
wbemErrAccessDenied 0x80041003 | The current user was not authorized to execute the method.

See Also

ISWbemServices.ExecMethod


ISWbemObject.Subclasses_

The Subclasses_ method of the ISWbemObject object returns an object of type ISWbemObjectSet. This object is a collection of subclasses of the current object, which must be a class. Items in the returned collection can be obtained by way of standard collection methods. See Collections for information on using collections.

Note It is not an error for the returned collection to have zero elements if there are no subclasses of the current object.

This method only works for class objects.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemObject.Subclasses_(
[iFlags= wbemFlagReturnImmediately|wbemQueryFlagDeep],
[objwbemNamedValueSet=null]
)

Parameters

iFlags
Optional. This determines how deep the enumeration will be. This parameter can return the following values.
Value Meaning
wbemQueryFlagShallow
1 		This value forces recursive enumeration into all subclasses derived from the specified superclass. The superclass itself is not returned in the enumeration.
wbemQueryFlagDeep
0 		This is the default for this parameter. It forces the enumeration to include only immediate subclasses of the specified superclass.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectSet will be returned.

Error Codes

The Subclasses_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed 0x80041001 | There is an unspecified error.
wbemErrInvalidClass 0x80041010 | The specified class did not exist.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObjectSet


ISWbemObject.Instances_

The Instances_ method of the ISWbemObject object creates an enumerator that returns the instances of the current class object. This method implements a simple query. More complex queries may require the use of ISWbemServices.ExecQuery.

Note This method only works for class objects. It is not an error for the returned collection to have zero elements.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemObject.Instances_(
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.
objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics. This parameter is optional.

Return Value

If successful, an object of type an object of type ISWbemObjectSet is returned.

Error Codes

The Instances_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view instances of the specified class.
wbemErrFailed 0x80041001 | An unspecified error occurred.
wbemErrInvalidClass 0x80041010 | The specified class is invalid.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObjectSet


ISWbemObject.Delete_

The Delete_ method of the ISWbemObject object deletes the current class or instance.

If a dynamic provider supplied the class or instance, it is sometimes not possible to delete this object unless the provider supports class or instance deletion.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objwbemObject.Delete_(
[iFlags=0],
[objwbemNamedValueSet=null]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.
objwbemNamedValueSet
Optional. Typically undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

None.

Error Codes

The Delete_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current context does not have adequate security rights to delete the object.
wbemErrFailed 0x8004100 | This is an unspecified error.
wbemErrInvalidClass 0x80041010 | The specified class does not exist.
wbemErrInvalidOperation 0x80041016 | The object cannot be deleted.
wbemErrNotFound 0x80041002 | The object did not exist.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.


ISWbemObject.Derivation_

The Derivation_ property of the ISWbemObject object contains an array of strings that describe the class derivation hierarchy for the instance being referenced. The contents are in most-derived-from order. That is, the first element in the array defines the superclass and the last element defines the dynasty class. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strClassArray = objwbemObject.Derivation_


ISWbemObject.Methods_

The Methods_ property of the ISWbemObject object returns an ISWbemMethodSet object that is a collection of the CIM methods for the current class or instance. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objMethodSet = objwbemObject.Methods_


ISWbemObject.Path_

The Path_ property of the ISWbemObjectPath object returns an ISWbemObjectPath object that represents the object path of the current class or instance This property can be passed as a parameter to methods that require an object path.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objObjectPath = objwbemObject.Path_

Remarks

Only the Class property of the returned ISWbemObjectPath instance can be modified. Attempts to modify any other property, or to call the methods SetAsClass or SetAsSingleton, will return an error of wbemErrReadOnly.

As a consequence of this, the ISWbemNamedValueSet that is the value of the Keys property of the returned ISWbemObjectPath instance cannot be modified. Attempts to call the methods Add, Remove, or DeleteAll on this value will return an error of wbemErrReadOnly. Furthermore any ISWbemNamedValue obtained from this collection is not modifiable, and attempts to modify the Value property will return the same error code.

However, if you call ISWbemObject.Clone_ to create a copy, the Path_ property of the copy is fully modifiable.


ISWbemObject.Properties_

The Properties_ property of the ISWbemObject object returns an ISWbemPropertySet object that is a collection of the CIM properties for the current class or instance. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objPropertySet = objwbemObject.Properties_


ISWbemObject.Qualifiers_

The Qualifiers_ property of the ISWbemObject object returns an ISWbemQualifierSet object that is a collection of the CIM qualifiers for the current class or instance. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objQualifierSet = objwbemObject.Qualifiers_


ISWbemLastError

You can use the methods and properties of the ISWbemLastError object to contain and manipulate error objects. You can create an ISWbemLastError error object to inspect the extended error information associated with a previous method call. If there is no error information available, an attempt to create an error object will fail. If the call succeeds and an error object is returned the status of the object is reset. Further attempts to retrieve a error object will fail until a new error takes place.

The methods and properties of this interface are exactly the same as those of the ISWbemObject..

Methods

Method | Description
Associators_ | Retrieves the Associators of the object.
Clone_ | Makes a copy of the current object.
CompareTo_ | Tests two objects for equality.
Delete_ | Deletes the object from Windows Management.
GetObjectText_ | Retrieves the textual representation of the object (MOF syntax).
Instances_ | Returns a collection of instances of the object (which must be a CIM class).
Put_ | Creates or updates the object in Windows Management.
References_ | Returns References to the object.
SpawnDerivedClass_ | Creates a new derived class from the current object (which must be a CIM class).
SpawnInstance_ | Creates a new instance from the current object.
Subclasses_ | Returns a collection of subclasses of the object (which must be a CIM class).
ExecMethod_ | Executes a method on the object.

Properties

Property | Description
Properties_ | This is an ISWbemPropertySet object. It is the collection of properties for this object.
Qualifiers_ | This is an ISWbemQualifierSet object. It is the collection of qualifiers for this object.
Methods_ | This is an ISWbemMethodSet object. It is the collection of methods for this object.
Derivation_ | Contains an array of strings describing the derivation hierarchy for the class.
Path_ | Contains a ISWbemObjectPath object that represents the object path of the current class or instance.


ISWbemLastError.Clone_

The Clone_ method of the ISWbemLastError object returns a new object that is a clone of the current object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objObject = objwbemLastError.Clone_()

Return Value

If successful, a new ISWbemLastError object is returned.

Error Codes

The Clone_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | Nothing was specified as a parameter, and it is not acceptable in this usage.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to clone the object.

Remarks

Use this method to duplicate a class definition or 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 ISWbemLastError.SpawnInstance_ to create a single starting instance, and use ISWbemLastError.Clone_ to produce 100 copies of the instance quickly. Subsequently, you can modify the objects, giving each one specific values.

It is not possible to use this method to convert a class definition to an instance, or to convert an instance to a class definition.


ISWbemLastError.CompareTo_

The CompareTo_ method of the ISWbemLastError object compares two ISWbemLastError type objects. This comparison is subject to certain constraints based on the values specified in the iFlags parameter.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bAreEqual = objwbemLastError.CompareTo_(
objwbemObject,
[iFlags= wbemComparisonFlagIncludeAll]
)

Parameters

objwbemObject
Required. An object of class ISWbemLastError. This is the object with which the first object is compared. The object must be a valid ISWbemLastError instance, and it cannot be undefined.
iFlags
Optional. It specifies the object characteristics to consider when comparing an object with other objects. You can use wbemComparisonFlagIncludeAll to consider all features (this is the default), or any combination of the following values.
Value Meaning
wbemComparisonFlagIncludeAll
0 		Use this flag to compare all properties, qualifiers, and flavors, or use one of the other flags listed below to ignore any of these items.
WbemComparisonFlagIgnoreObjectSource
2 		The source of the objects, namely the server and the namespace they came from, are ignored in comparison to other objects.
wbemComparisonFlagIgnoreQualifiers
1 		All qualifiers (including "key" and "dynamic") should be ignored in comparison.
WbemComparisonFlagIgnoreDefaultValues
4 		Default values of properties should be ignored. This flag is only meaningful when comparing classes.
wbemComparisonFlagIgnoreFlavor
0x20 		Ignore qualifier flavors. This flag still takes qualifier values into account, but ignores flavor distinctions such as propagation rules and override restrictions.
wbemComparisonFlagIgnoreCase
0x10 		Compares string values 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 whether this flag is specified or not.
WbemComparisonFlagIgnoreClass
8 		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 will be undefined.

Return Value

This method returns the Boolean value TRUE if the objects match or FALSE if they do not.

Error Codes

The CompareTo_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemLastError


ISWbemLastError.Associators_

The Associators_ method of the ISWbemLastError object returns a collection of objects (classes or instances) that are associated with the current object. These returned objects are called endpoints. This method performs the same function that the WBEM Query Language (WQL) "Associators Of" query performs.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Snytax

objWbemObjectSet = objwbemLastError.Associators_(
[strAssocClass=""],
[strResultClass=""],
[strResultRole=""],
[strRole=""],
[bClassesOnly=FALSE],
[bSchemaOnly=FALSE],
[strRequiredAssocQualifier=""],
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

strAssocClass
Optional. This is a string that contains an association class. If specified, this parameter indicates that the returned endpoints must be associated with the source through the specified association class or a class derived from this association class.
strResultClass
Optional. This is a string that contains a class name. If specified, this parameter indicates that the returned endpoints must belong to or be derived from the class specified in this parameter.
strResultRole
Optional. This is a string that contains a property name. If specified, this parameter indicates that the returned endpoints must play a particular role in their association with the source object. The role is defined by the name of a specified property—which must be a reference property—of an association.
strRole
Optional. This is a string that contains a property name. If specified, this parameter indicates that the returned endpoints must participate in an association with the source object in which the source object plays a particular role. The role is defined by the name of a specified property—which must be a reference property—of an association.
bClassesOnly
Optional. This is a Boolean value that indicates whether a list of classnames should be returned rather than actual instances of the classes. These are the classes to which the endpoint instances belong. The default value for this parameter is FALSE.
bSchemaOnly
Optional. This is a Boolean value that indicates whether the query applies to schema rather than data. The default value for this parameter is FALSE. It can only be set to TRUE if the strObjectPath parameter specifies the object path of a class. When set to TRUE, the set of returned endpoints represent classes that are suitably associated with the source class in schema.
strRequiredAssocQualifier
Optional. This is a string that contains a qualifier name. This parameter, if specified, indicates that the returned endpoints must be associated with the source object through an association class that includes the specified qualifier.
strRequiredQualifier
Optional. This is a string that contains a qualifier name. This parameter, if specified, indicates that the returned endpoints must include the specified qualifier.
iFlags
Optional. This is an integer specifying additional flags to the operation. The default for this parameter is wbemFlagReturnImmediately, which directs the call to return immediately rather than wait until the query has completed. This parameter can return the following values.
Value Meaning
wbemFlagForwardOnly
0x20 		This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but do not allow calls to Clone or Reset.
wbemFlagBidirectional
0 		This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectSet will be returned.

Error Codes

The Associators_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed 0x80041001 | There is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

For information about the associated WQL query "Associators Of", source instances and endpoints see "Data Queries" in the "WBEM Query Language" section of the WBEM software development kit (SDK) reference.

See Also

ISWbemServices.AssociatorsOf, ISWbemServices.ReferencesTo, ISWbemLastError.References_


ISWbemLastError.References_

The References_ method of the ISWbemLastError object returns a collection of all association classes or instances that refer to the current object.

This method performs the same function that the WQL "References Of" query performs.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemLastError.References_(
[strResultClass=""],
[strRole=""],
[bClassesOnly=FALSE],
[bSchemaOnly=FALSE],
[strRequiredQualifier=""],
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

strResultClass
Optional. This is a string that contains a class name. This parameter, if specified, indicates that the returned association objects must belong to or be derived from the class specified in this parameter.
strRole
Optional. This is a string that contains a property name. If specified, this parameter indicates that the returned association objects must be limited to those in which the source object plays a particular role. The role is defined by the name of a specified property—which must be a reference property—of an association.
bClassesOnly
Optional. This is a Boolean value that indicates whether a list of classnames should be returned rather than actual instances of the classes. These are the classes to which the association objects belong. The default value for this parameter is FALSE.
bSchemaOnly
Optional. This is a Boolean value that indicates whether the query applies to schema rather than data. The default value for this parameter is FALSE. It can only be set to TRUE if the strObjectPath parameter specifies the object path of a class. When set to TRUE, the set of returned endpoints represent classes that are suitably associated with the source class in schema.
strRequiredQualifier
Optional. This is a string that contains a qualifier name. This parameter, if specified, indicates that the returned association objects must include the specified qualifier.
iFlags
Optional. This is an integer specifying additional flags to the operation. The default for this parameter is wbemFlagReturnImmediately, which directs the call to return immediately rather than wait until the query has completed. This parameter can return the following values.
Value Meaning
wbemFlagForwardOnly
0x20 		This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but do not allow calls to Clone or Reset.
wbemFlagBidirectional
0 		This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectSet will be returned.

Error Codes

The References_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed 0x80041001 | There is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

For information about the associated WQL query "References Of", source instances, and association objects, see "Data Queries" in the "WBEM Query Language" section of the WBEM SDK reference.

See Also

ISWbemServices.ReferencesTo, ISWbemServices.AssociatorsOf, ISWbemLastError.Associators_


ISWbemLastError.GetObjectText_

The GetObjectText_ method of the ISWbemLastError object returns a textual rendering of the object. This interface can be used to display an object's contents. 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.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strMofText = objwbemLastError.GetObjectText_(
[iFlags=0]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

If successful, this method will return a string that contains the output text.

Error Codes

The GetObjectText_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.


ISWbemLastError.Put_

The Put_ method of the ISWbemLastError object creates or updates an instance or class object to Windows Management. You can use this method after you have modified any properties or methods in an ISWbemLastError object and your changes will be written to Windows Management.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objObjectPath = objwbemLastError.Put_(
[iFlags= wbemChangeFlagCreateOrUpdate],
[objwbemNamedValueSet=null]
)

Parameters

iFlags
Optional. This parameter determines if the call will create or update the class or instance and if the call will return right away or not. This parameter can return the following values.
Value Meaning
wbemChangeFlagCreateOrUpdate
0 		This flag causes the class or instance to be created if it does not exist or overwritten if it exists already.
WbemChangeFlagCreateOnly
2 		This flag is used for creation only. The call will fail if the class or instance already exists.
WbemChangeFlagUpdateOnly
1 		This flag causes this call to update. The class or instance must exist for the call to be successful.
wbemFlagReturnImmediately
0x10 		This flag causes the call to return immediately.
wbemFlagReturnWhenComplete
0 		This flag causes this call to block until the query has completed.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectPath will be returned. This will contain the object path of the instance or class that has been successfully committed to Windows Management.

Error Codes

The Put_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to update an instance of the specified class.
wbemErrAlreadyExists 0x80041002 | wbemChangeFlagCreateOnly flag was specified, but the instance already exists.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrIllegalNull 0x8004100A | 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.
wbemErrInvalidObject 0x80041014 | The specified instance is invalid.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrNotFound 0x80041002 | wbemChangeFlagUpdateOnly flag was specified, but the instance or class does not exist.
wbemErrIncompleteClass 0x8004100C | Required properties for classes have not all been set.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObjectPath.Class, ISWbemQualifier, ISWbemProperty


ISWbemLastError.SpawnDerivedClass_

Use the SpawnDerivedClass_ method of the ISWbemLastError object to create a derived class object from the current object. The object must be a class definition that becomes the superclass of the spawned object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objNewClass = objwbemLastError.SpawnDerivedClass_(
[iFlags=0]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Values

If the call is successful, an Object of type ISWbemLastError is returned that contains the new class definition object. No object is returned when there is an error.

Error Codes

The SpawnDerivedClass_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x8004100 | This is an unspecified error.
wbemErrIllegalOperation 0x8004101E | The user requested an illegal operation, such as spawning a class from an instance.
wbemErrIncompleteClass 0x8004100C | The source class was not completely defined or registered with Windows Management, so a new derived class is not permitted.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

Remarks

The object returned 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. Before you can use this method to create a derived class, you must create the base class. To create the base class, call ISWbemLastError.Put_, and retrieve it using ISWbemServices.Get.


ISWbemLastError.SpawnInstance_

Use the SpawnInstance_ method of the ISWbemLastError object to create a new instance of a class. The current object must be a class definition obtained from Windows Management via a method such as ISWbemServices.Get or ISWbemServices.ExecQuery. Then use this class definition to create new instances. Create each new instance locally within the process, and then call ISWbemLastError.Put_ to actually create the instance within Windows Management.

Note Spawning an instance from an instance is acceptable.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objNewInstance = objwbemLastError.SpawnInstance_(
[iFlags=0]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

If successful, this call returns an object of type ISWbemLastError that contains a new instance of the class.

Error Codes

The SpawnInstance_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrIncompleteClass 0xH80041020 | 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 Windows Management using ISWbemLastError.Put_.
wbemErrIllegalOperation 0xH8004101E | Returned if this method is used on an instance instead of a class.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemServices.Get, ISWbemLastError.Put_


ISWbemLastError.ExecMethod_

The ExecMethod_ method of the ISWbemLastError object executes a method exported by a method provider. This method is similar to ISWbemServices.ExecMethod, but it operates directly on the object whose method is to be executed.

Use ISWbemLastError.ExecMethod_ as an alternate way to execute a method in cases where it is not possible to execute a method directly. For example, you would need to use it with a scripting language such as Microsoft® JScript® that does not support output parameters, if your method has out parameters. Otherwise, the recommended means of invoking a method is to use direct method invocation. Direct method invocation is executing a method by using object.method syntax. For more information on direct method invocation, see Direct Access.

This method will block while the method that is forwarded to the appropriate provider executes. The information and status are then returned.

Windows Management does not implement the methods directly. The method providers export the methods.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objOutParams = objwbemLastError.ExecMethod_(
strMethodName,
[objwbemInParams=null],
[iFlags=0],
[objwbemNamedValueSet=null]
)

Parameters

strMethodName
Required. This is the name of the method for the object.
objwbemInParams
Optional. This is an ISWbemLastError object that contains the input parameters for the method being executed.

To construct the objInParams parameter

  1. Call ISWbemLastError.Methods_.Item("MethodName") to get an ISWbemMethod object that contains the properties that describe the method, where "MethodName" is the name of the method to retrieve.
  2. Use the ISWbemMethod.InParameters property of the ISWbemMethod object to get an InParameters object.
  3. Call SpawnInstance_ on the InParameters object to create an instance.
  4. Set the properties of the instance to whatever values are appropriate. For example, If you want to set an input parameter named myinputparam to the value "whatever" in an instance of InParameters called "INST", the code would look like this: INST.Properties_.Add ("myinputparam").Value = "Whatever"

    The default value for this parameter is undefined.

iFlags
Optional. This parameter is reserved and must be zero if specified.
objwbemNamedValueSet
Optional. Typically, it is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

A object of ISWbemLastError is returned if this call is successful. The returned object contains the out parameters and return value for the method being executed.

Error Codes

The ExecMethod_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrInvalidClass 0x80041010 | The specified class was invalid.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.
wbemErrInvalidMethod 0x8004102E | The requested method was not available.
wbemErrAccessDenied 0x80041003 | The current user was not authorized to execute the method.

See Also

ISWbemServices.ExecMethod


ISWbemLastError.Subclasses_

The Subclasses_ method of the ISWbemLastError object returns an object of type ISWbemObjectSet. This object is a collection of subclasses of the current object, which must be a class. Items in the returned collection can be obtained by way of standard collection methods. See Collections for information on using collections.

Note It is not an error for the returned collection to have zero elements if there are no subclasses of the current object.

This method only works for class objects.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemLastError.Subclasses_(
[iFlags= wbemFlagReturnImmediately|wbemQueryFlagDeep],
[objwbemNamedValueSet=null]
)

Parameters

iFlags
Optional. This determines how deep the enumeration will be. This parameter can return the following values.
Value Meaning
wbemQueryFlagShallow
1 		This value forces recursive enumeration into all subclasses derived from the specified superclass. The superclass itself is not returned in the enumeration.
wbemQueryFlagDeep
0 		This is the default for this parameter. It forces the enumeration to include only immediate subclasses of the specified superclass.

objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

If the call is successful, an object of type ISWbemObjectSet will be returned.

Error Codes

The Subclasses_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed 0x80041001 | There is an unspecified error.
wbemErrInvalidClass 0x80041010 | The specified class did not exist.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObjectSet


ISWbemLastError.Instances_

The Instances_ method of the ISWbemLastError object creates an enumerator that returns the instances of the current class object. This method implements a simple query. More complex queries may require the use of ISWbemServices.ExecQuery.

Note This method only works for class objects. It is not an error for the returned collection to have zero elements.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objWbemObjectSet = objwbemLastError.Instances_(
[iFlags=wbemFlagReturnImmediately],
[objwbemNamedValueSet=null]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.
objwbemNamedValueSet
Optional. Typically, this is undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics. This parameter is optional.

Return Value

If successful, an object of type an object of type ISWbemObjectSet is returned.

Error Codes

The Instances_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current user does not have permission to view instances of the specified class.
wbemErrFailed 0x80041001 | An unspecified error occurred.
wbemErrInvalidClass 0x80041010 | The specified class is invalid.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.

See Also

ISWbemObjectSet


ISWbemLastError.Delete_

The Delete_ method of the ISWbemLastError object deletes the current class or instance.

If a dynamic provider supplied the class or instance, it is sometimes not possible to delete this object unless the provider supports class or instance deletion.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objwbemLastError.Delete_(
[iFlags=0],
[objwbemNamedValueSet=null]
)

Parameters

iFlags
Optional. This parameter is reserved and must be zero if specified.
objwbemNamedValueSet
Optional. Typically undefined. Otherwise, this is an ISWbemNamedValueSet object whose elements represent the context information that may be used by the provider that is servicing the request. A provider that supports or requires such information must document the value names that it recognizes, their types, allowed values, and semantics.

Return Value

None.

Error Codes

The Delete_ method can return the error codes listed in the following table.

Error | Meaning
wbemErrAccessDenied 0x80041003 | The current context does not have adequate security rights to delete the object.
wbemErrFailed 0x8004100 | This is an unspecified error.
wbemErrInvalidClass 0x80041010 | The specified class does not exist.
wbemErrInvalidOperation 0x80041016 | The object cannot be deleted.
wbemErrNotFound 0x80041002 | The object did not exist.
wbemErrOutOfMemory 0x80041006 | There was not enough memory to complete the operation.


ISWbemLastError.Derivation_

The Derivation_ property of the ISWbemLastError object contains an array of strings that describe the class derivation hierarchy for the instance being referenced. The contents are in most-derived-from order. That is, the first element in the array defines the superclass and the last element defines the dynasty class. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strClassArray = objwbemLastError.Derivation_


ISWbemLastError.Methods_

The Methods_ property of the ISWbemLastError object returns an ISWbemMethodSet object that is a collection of the CIM methods for the current class or instance. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objMethodSet = objwbemLastError.Methods_


ISWbemLastError.Path_

The Path_ property of the ISWbemLastError object returns an ISWbemObjectPath object that represents the object path of the current class or instance This property can be passed as a parameter to methods that require an object path.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objObjectPath = objwbemLastError.Path_

Remarks

Only the Class property of the returned ISWbemObjectPath instance can be modified. Attempts to modify any other property, or to call the methods SetAsClass or SetAsSingleton, will return an error of wbemErrReadOnly.

As a consequence of this, the ISWbemNamedValueSet that is the value of the Keys property of the returned ISWbemObjectPath instance cannot be modified. Attempts to call the methods Add, Remove, or DeleteAll on this value will return an error of wbemErrReadOnly. Furthermore any ISWbemNamedValue obtained from this collection is not modifiable, and attempts to modify the Value property will return the same error code.

However, if you call ISWbemObject.Clone_ to create a copy, the Path_ property of the copy is fully modifiable.


ISWbemLastError.Properties_

The Properties_ property of the ISWbemLastError object returns an ISWbemPropertySet object that is a collection of the CIM properties for the current class or instance. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objPropertySet = objwbemLastError.Properties_


ISWbemLastError.Qualifiers_

The Qualifiers_ property of the ISWbemLastError object returns an ISWbemQualifierSet object that is a collection of the CIM qualifiers for the current class or instance. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objQualifierSet = objwbemLastError.Qualifiers_


ISWbemPropertySet

An ISWbemPropertySet object is a collection of objects of type ISWbemProperty. You can add items to the collection using the Add method, retrieve items using the Item method, and remove items from the collection using the Remove method. For information on using collections, see Collections.

The ISWbemProperty objects that make up a ISWbemPropertySet collection are used to describe the properties of a single CIM class or instance.

Methods

Method | Description
Add | Adds an ISWbemProperty object to the ISWbemPropertySet collection.
Item | Retrieves an ISWbemProperty from the collection. This is the default method of this object.
Remove | Removes an ISWbemProperty object from the collection.

Property

Property | Description
Count | The number of items in the collection.


ISWbemPropertySet.Add

The Add method of the ISWbemPropertySet object adds an ISWbemProperty object to the ISWbemPropertySet collection. If a property with the same name already exists in the collection, its contents are replaced with the new definition.

Note The value of the property is NULL (unassigned) after this operation. To set or change the value of a Common Information Model (CIM) property, you must set the Value property of the returned ISWbemProperty.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objProperty = objwbemPropertySet.Add(
strName,
iCIMType,
[bIsArray=FALSE],
[iFlags=0]
)

Parameters

strName
Required. This is the name of the new property.
iCIMType
Required. This is the CIMType of the new property. See CIMTypes for the table with the CIMTypes and their values.
bIsArray
Optional. This specifies whether the property is an array type. The default value for this parameter is FALSE.
iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

This method returns an ISWbemProperty object that represents the new property, if successful. Otherwise, a null object is returned.

Error Codes

The Add method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified failure.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory for this method to execute.
wbemErrInvalidPropertyType 0x8004102A | The CIM type is not recognized.

See Also

ISWbemProperty.Value, ISWbemPropertySet.Remove


ISWbemPropertySet.Item

The Item method of the ISWbemPropertySet object gets a named ISWbemProperty from the collection. This is the default method for this object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objProperty = objwbemPropertySet.Item(
strName,
[iFlags=0]
)

Parameters

strName
Required. This is the name of the property to retrieve.
iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

If successful, the requested ISWbemProperty is returned.

Error Codes

The Item method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified failure.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrOutOfMemory 0x80041006 | There was not enough memory for this method to execute.


ISWbemPropertySet.Remove

The Remove method of the ISWbemPropertySet object deletes a property from the ISWbemPropertySet collection.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objwbemPropertySet.Remove(
strName,
[iFlags=0]
)

Parameters

strName

Required. This is the name of the item to remove.

iFlags
Optional. This parameter is reserved and must be zero if specified.

Return Value

None.

Error Codes

The Remove method can return the error codes listed in the following table.

Error | Meaning
wbemErrFailed 0x80041001 | This is an unspecified failure.
wbemErrInvalidOperation 0x80041016 | The user attempted to delete a property that cannot be deleted.
wbemErrInvalidParameter 0x80041008 | An invalid parameter was specified.
wbemErrNotFound 0x80041002 | The specified property does not exist.
wbemErrOutOfMemory 0x80041006 | There was not enough memory for this method to execute.
wbemErrPropagatedProperty 0x2147217380 | The user attempted to delete a property that was not owned. The property was inherited from a parent class.

See Also

ISWbemPropertySet.Add


ISWbemPropertySet.Count

Use the Count automation property of the ISWbemPropertySet object to determine how many items are in the ISWbemPropertySet collection. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

iCount = objwbemPropertySet.Count


ISWbemProperty

The ISWbemProperty object represents a single Common Information Model (CIM) property of a managed object.

Methods

None.

Properties

Property | Description
CIMType | The CIM Type of this property.
IsArray | Boolean value that indicates if this property has an array type.
IsLocal | Boolean value that indicates if this is a local property.
Name | Name of this property.
Origin | Contains the originating class of this property.
Qualifiers_ | This is a ISWbemQualifierSet, which is the collection of qualifiers for this property.
Value | The actual value of this property. This is the default automation property of this object.


ISWbemProperty.CIMType

Use the CIMType property of the ISWbemProperty object to determine the CIM type of this property. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

iCIMType = objwbemProperty.CIMType

Remarks

See CIMTypes for the table of CIMTypes and their values.


ISWbemProperty.IsArray

The IsArray property of the ISWbemProperty object is a Boolean value used to determine if this property has an array type. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bIsArray = objwbemProperty.IsArray


ISWbemProperty.IsLocal

The IsLocal property of the ISWbemProperty object is a Boolean value used to determine if this property is local. A value of FALSE indicates that this property has been inherited from another class. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bIsLocal = objwbemProperty.IsLocal


ISWbemProperty.Name

The Name property of the ISWbemProperty object returns the name of this CIM property. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strName = objwbemProperty.Name


ISWbemProperty.Origin

The Origin property of the ISWbemProperty object retrieves the name of the CIM class in which this CIM property was introduced. For classes with deep inheritance hierarchies, it is often desirable to know which properties were declared in which classes.

If the property is local (see ISWbemQualifier.IsLocal), this will be same as the owning class. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strOriginClassName = objwbemProperty.Origin


ISWbemProperty.Qualifiers_

The Qualifiers_ property of the ISWbemProperty object returns an object of type ISWbemQualifierSet that is the collection of qualifiers for this CIM property. This property is read-only.

Syntax

objQualifierSet = objwbemProperty.Qualifiers_


ISWbemProperty.Value

The Value property of the ISWbemProperty object defines the variant value of the CIM property. This is the default automation property of this object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

varValue = objwbemProperty.Value
objwbemProperty.Value = varValue


ISWbemQualifierSet

An ISWbemQualifierSet object is a collection of objects of type ISWbemQualifier. Items are added to the collection using the Add method, retrieved using the Item method, and removed from the collection using the Remove method.

For information on using collections, see Collections.

The ISWbemQualifier objects that make up a ISWbemQualifierSet collection describe the Common Information Model (CIM) qualifiers attached to a CIM Class, CIM Instance, CIM Method, or CIM Method Parameter.

Methods

Method | Description
Add | Adds an ISWbemQualifier object to the ISWbemQualifierSet collection.
Item | Retrieves an ISWbemQualifier from the collection. This is the default method of this object.
Remove | Removes an ISWbemQualifier object from the collection.

Properties

Property | Description
Count | The number of items in the collection.


ISWbemQualifierSet.Add

The Add method of the ISWbemQualifierSet object adds an ISWbemQualifier object to the ISWbemQualifierSet collection. If a qualifier with the same name already exists in the collection, it is replaced.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objQualifier = objwbemQualifierSet.Add(
strName,
varVal,
[bPropagatesToSubclasses=TRUE],
[bPropagatesToInstances=TRUE],
[bOverridable=TRUE],
[iFlags=0]
)

Parameters

strName
Required. The name of the new qualifier.
varVal
Required. The variant value of the new qualifier.
bPropagatesToSubclasses
Optional. A Boolean value that indicates if this new qualifier will be propagated to subclasses. The default value is TRUE.
bPropagatesToInstances
Optional. A Boolean value that indicates if this new qualifier will be propagated to instances. The default value is TRUE.
strOverridable
Optional. A Boolean value that indicates if this qualifier can be overridden when propagated. The default value is TRUE.
iFlags
Optional. This parameter is reserved and the default value is 0.

Return Value

This method returns an ISWbemQualifier object that represents the new qualifier, if successful. Otherwise, a null object is returned.

Error Codes

The Add method can return the error codes listed in the following table.

Error | Meaning
wbemErrInvalidParameter 0x80041008 | The iFlags parameter was not valid.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrCannotBeKey 0x8004101F | 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.
wbemErrInvalidQualifierType 0x80041029 | The varVal parameter is not of a legal qualifier type.
wbemErrOverrideNotAllowed 0x8004101A | It is not possible to perform the ISWbemQualifierSet.Add operation on this qualifier because the owning object does not permit overrides.

See Also

ISWbemQualifierSet.Remove


ISWbemQualifierSet.Item

The Item method of the ISWbemQualifierSet object returns a named ISWbemQualifier from the collection. It is the default method of this object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objQualifier= objwbemQualifierSet.Item(
strName,
[iFlags=0]
)

Parameters

strName
Required. The name of the qualifier to retrieve.
iFlags
Optional. This parameter is reserved and the default value is 0.

Return Value

If successful, the requested ISWbemQualifier is returned.

Error Codes

The Item method can return the error codes listed in the following table.

Error | Description
wbemErrInvalidParameter 0x80041008 | The iFlags parameter was not valid.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrNotFound 0x80041002 | The specified qualifier does not exist.

See Also

ISWbemQualifier


ISWbemQualifierSet.Remove

The Remove method of the ISWbemQualifierSet object deletes a named qualifier from the collection.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objwbemQualifierSet.Remove(
strName,
[iFlags=0]
)

Parameters

strName

Required. The name of the qualifier to remove.

iFlags
Optional. This parameter is reserved and the default value is 0.

Return Value

None.

Error Codes

The Remove method can return the error codes listed in the following table.

Error | Meaning
wbemErrInvalidParameter 0x80041008 | The iFlags parameter was not valid.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrNotFound 0x80041002 | The specified qualifier does not exist.
wbemErrInvalidOperation 0x80041016 | Removing this qualifier is illegal.

See Also

ISWbemQualifierSet.Add


ISWbemQualifierSet.Count

The Count property of the ISWbemQualifier object contains the number of items in a ISWbemQualifierSet collection. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

iCount = objwbemQualifierSet.Count


ISWbemQualifier

You can use the properties of the ISWbemQualifier object to represent a single Common Information Model (CIM) qualifier of a CIM Class, CIM Instance, CIM property, CIM method, or CIM method parameter.

Methods

None.

Properties

Property | Description
IsLocal | Boolean value that indicates if this is a local qualifier.
IsOverridable | Boolean value that indicates if this qualifier can be overridden when propagated.
Name | Name of this qualifier.
PropagatesToInstance | Boolean value that indicates if this qualifier can be propagated to an instance.
PropagatesToSubclass | Boolean value that indicates if this qualifier can be propagated to a subclass.
Value | The actual value of this qualifier. This is the default property of this object.


ISWbemQualifier.IsLocal

The IsLocal property of the ISWbemQualifier object is a Boolean value that indicates if the qualifier is local. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bIsLocal = objwbemQualifier.IsLocal


ISWbemQualifier.PropagatesToInstance

The PropagatesToInstance property of the ISWbemQualifier object is a Boolean value that indicates if this qualifier can be propagated to an instance.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bPropagatesToInstance = objwbemQualifier.PropagatesToInstance
objwbemQualifier.PropagatesToInstance = bPropagatesToInstance


ISWbemQualifier.PropagatesToSubClass

The PropagatesToSubClass property of the ISWbemQualifier object is a Boolean value that indicates if this qualifier can be propagated to an subclass.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bPropagatesToSubclass = objwbemQualifier.PropagatesToSubclass
objwbemQualifier.PropagatesToSubclass = bPropagatesToSubclass


ISWbemQualifier.Value

The Value property of the ISWbemQualifier object contains the variant value of the CIM qualifier. This is the default property of this object.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

varValue = objwbemQualifier.Value
objwbemQualifier.Value = varValue


ISWbemQualifier.Name

The Value property of the ISWbemQualifier object defines the name of this qualifier. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strQualifierName = objwbemQualifier.Name


ISWbemQualifier.IsOverridable

The IsLocal property of the ISWbemQualifier object is a Boolean value that indicates if the qualifier can be overridden when propagated.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

bIsOverridable = objwbemQualifier.IsOverridable
objwbemQualifier.IsOverridable = bIsOverridable


ISWbemMethod

You can use the properties of the ISWbemMethod object to represent a single Common Information Model (CIM) method of a CIM object.

This object can be used to inspect the definitions of methods. In order to invoke the methods, you should use either direct access (see Direct Access ) on an ISWbemObject (which is the recommended mechanism), or the ISWbemServices.ExecMethod call.

Note In this version of the application programming interface (API), write access to method information is not supported. If you want to define methods, or modify existing method definitions, you may use the Web-Based Enterprise Management (WBEM) Component Object Model (COM) API or, preferably, you should define the method changes in a Managed Object Format (MOF), and then submit that using the MOF Compiler.

Methods

None.

Properties

Property | Description
InParameters | This is an object of type ISWbemObject, whose properties define the input parameters for this method.
Name | This is the name of the method.
Origin | This is the originating class of the method.
OutParameters | This is an object of type ISWbemObject whose properties define the out parameters and return type of this method.
Qualifiers_ | This is an object of type ISWbemQualifierSet that contains the qualifiers for this method.


ISWbemMethod.InParameters

The InParameters property of the ISWbemMethod object is an object of type ISWbemObject whose CIM properties define the input parameters for this method. This property is read-only. Note that any changes made to this object will not be reflected in the underlying method definition.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objInParameters = objwbemMethod.InParameters


ISWbemMethod.Name

The Name property of the ISWbemMethod object is a string that describes the name of this method. This property is read-only.

Syntax

strMethodName = objwbemMethod.Name


ISWbemMethod.Origin

The Origin property of the ISWbemMethod object returns the name of the CIM class in which this method was introduced. For classes with deep inheritance hierarchies, it is often desirable to know which methods were declared in which classes. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

strClassOriginName = objwbemMethod.Origin


ISWbemMethod.OutParameters

The OutParameters property of the ISWbemMethod object is an object of type ISWbemObject whose CIM properties define the out parameters and return type of this method. This property is read-only. Note that any changes made to this object will not be reflected in the underlying method definition.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objOutParameters = objwbemMethod.OutParameters


ISWbemMethod.Qualifiers_

The Qualifiers_ property of the ISWbemMethod object returns an object of type ISWbemQualifierSet that is the collection of qualifiers for this CIM method. This property is read-only.

Syntax

objQualifierSet = objwbemMethod.Qualifiers_


ISWbemMethodSet

An ISWbemMethodSet object is a collection of objects of type ISWbemMethod. Items are retrieved using the Item method. For information on using collections, see Collections.

Note In this version of the application programming interface (API), write access to method information is not supported. If you want to define methods, or modify existing method definitions, you may use the Web-Based Enterprise Management (WBEM) Component Object Model (COM) API, or, preferably, you should define the method changes in a Managed Object Format (MOF), and then submit that using the MOF Compiler.

Method

Method | Description
Item | Retrieves an ISWbemMethod from the collection. This is the default automation method of this object.

Property

Property | Description
Count | The number of items in the collection.


ISWbemMethodSet.Item

The Item method of the ISWbemMethodSet object returns a named ISWbemMethod from the collection.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objMethod= objwbemMethodSet.Item(
strName,
[iFlags=0]
)

Parameters

strName
Required. The name of the method to retrieve.
iFlags
Optional. This parameter is reserved and the default value is 0.

Return Value

If successful, the requested ISWbemMethod is returned.

Error Codes

The Item method can return the error codes listed in the following table.

Error | Meaning
wbemErrInvalidParameter 0x80041008 | The iFlags parameter was not valid.
wbemErrFailed 0x80041001 | This is an unspecified error.
wbemErrNotFound 0x80041002 | The specified method does not exist.

See Also

ISWbemMethod


ISWbemMethodSet.Count

The Count property of the ISWbemMethodSet object defines the number of items in the collection. This property is read-only.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

iCount = objwbemMethodSet.Count


ISWbemEventSource

You can use the method of the ISWbemEventSource object to retrieve events from an event query. You will get an ISWbemEventSource object if you make a call to ISWbemServices.ExecNotificationQuery to make an event query. You can then use the NextEvent method to retrieve events as they arrive.

Methods

Method | Description
NextEvent | Used to retrieve an event in conjunction with ISWbemServices.ExecNotificationQuery.

Properties

None.


ISWbemEventSource.NextEvent

The NextEvent method of the ISWbemEventSource object retrieves an event, if available, from an event query.

The following syntax is language neutral. For an explanation of this syntax, see Document Conventions.

Syntax

objObject = objwbemEventsource.NextEvent(
[iTimeoutMs = wbemTimeoutInfinite]
)

Parameters

iTimeoutMs
Optional. The number of milliseconds the call will wait for an event before returning a timeout error. The default value for this parameter is wbemTimeoutInfinite (-1) which directs this call to wait indefinitely.

Return Value

If successful, an object of type ISWbemObject containing the requested event is returned. If the call times out, the returned object will be NULL and an error code 0x80043001 will be returned.

Error Codes

The NextEvent method can return the following error code.

Error | Meaning
wbemErrTimedOut 0x80043001 | The requested event did not arrive in the amount of time that was specified in the iTimeoutMs parameter.


WBEM Scripting Object Model

Objects represented by boxes with a heavy border can be created directly. Shaded boxes represent collections. An arrow from one box to another indicates that an API call on the object from which the arrow points returns an object of the type to which it points.


CIMTypes

Some of the WBEM interfaces accept or return an argument called the CIMType that describes what type of data is stored in a variant. Below is a table that describes the name of the CIMTypes defined for Windows Management and the value associated with each constant.

CIMType | Value (Decimal)
wbemCimtypeSint16 | 2
wbemCimtypeSint32 | 3
wbemCimtypeReal32 | 4
wbemCimtypeReal64 | 5
wbemCimtypeString | 8
wbemCimtypeBoolean | 11
wbemCimtypeObject | 13
wbemCimtypeSint8 | 16
wbemCimtypeUint16 | 17
wbemCimtypeUint16 | 18
wbemCimtypeUint32 | 19
wbemCimtypeSint64 | 20
wbemCimtypeUint64 | 21
wbemCimtypeDatetime | 101
wbemCimtypeReference | 102
wbemCimtypeChar | 103


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.