3.1.4.3.16 IWbemServices::CreateInstanceEnum (Opnum 18)

Article
06/24/2021

The IWbemServices::CreateInstanceEnum method provides an instance enumeration. When this method is invoked, the server MUST return all instances for the specific class in the current namespace.

 HRESULT CreateInstanceEnum(
   [in] const BSTR strSuperClass,
   [in] long lFlags,
   [in] IWbemContext* pCtx,
   [out] IEnumWbemClassObject** ppEnum
 );

strSuperClass: MUST contain the name of the CIM class for which the client wants instances. This parameter MUST NOT be NULL.

lFlags: Flags that affect the behavior of the CreateInstanceEnum method. Flag behavior MUST be interpreted as specified in the following table.

The server MUST allow any combination of zero or more flags from the following table and MUST comply with all the restrictions in a flag description. Any other DWORD value that does not match a flag condition MUST be treated as not valid.

Value	Meaning
WBEM_FLAG_USE_AMENDED_QUALIFIERS 0x00020000	If this bit is not set, the server SHOULD return no CIM localizable information. If this bit is set, the server SHOULD return CIM localizable information for the CIM object, as specified in section 2.2.6.
WBEM_FLAG_RETURN_IMMEDIATELY 0x00000010	If this bit is not set, the server MUST make the method call synchronously. If this bit is set, the server MUST make the method call semisynchronously.
WBEM_FLAG_DIRECT_READ 0x00000200	If this bit is not set, the server MUST consider the entire class hierarchy when it returns the result. If this bit is set, the server MUST disregard any derived class when it searches the result.
WBEM_FLAG_SHALLOW 0x00000001	If this bit is set, the server MUST return instances of the requested class only and MUST exclude instances of classes that are derived from the requested class. If this bit is not set, the server MUST return all instances of the requested class as well as instances of classes that are derived from the requested class.
WBEM_FLAG_FORWARD_ONLY 0x00000020	If this bit is not set, the server MUST return an enumerator that has reset capability. If this bit is set, the server MUST return an enumerator that does not have reset capability, as specified in section 3.1.4.4.

Value

Meaning

WBEM_FLAG_USE_AMENDED_QUALIFIERS

0x00020000

If this bit is not set, the server SHOULD return no CIM localizable information.

If this bit is set, the server SHOULD return CIM localizable information for the CIM object, as specified in section 2.2.6.

WBEM_FLAG_RETURN_IMMEDIATELY

0x00000010

If this bit is not set, the server MUST make the method call synchronously.

If this bit is set, the server MUST make the method call semisynchronously.

WBEM_FLAG_DIRECT_READ

0x00000200

If this bit is not set, the server MUST consider the entire class hierarchy when it returns the result.

If this bit is set, the server MUST disregard any derived class when it searches the result.

WBEM_FLAG_SHALLOW

0x00000001

If this bit is set, the server MUST return instances of the requested class only and MUST exclude instances of classes that are derived from the requested class.

If this bit is not set, the server MUST return all instances of the requested class as well as instances of classes that are derived from the requested class.

WBEM_FLAG_FORWARD_ONLY

0x00000020

If this bit is not set, the server MUST return an enumerator that has reset capability.

If this bit is set, the server MUST return an enumerator that does not have reset capability, as specified in section 3.1.4.4.

pCtx: MUST be a pointer to an IWbemContext interface, which contains additional information that the client wants to pass to the server. If pCtx is NULL, the parameter MUST be ignored.

ppEnum: MUST receive the pointer to the enumerator that is used to enumerate through the returned class instances, which implements the IEnumWbemClassObject interface. This parameter MUST NOT be NULL.

Return Values: This method MUST return an HRESULT value that MUST indicate the status of the method call. The server MUST return the following value (specified in section 2.2.11) to indicate the successful completion of the method.

WBEM_S_NO_ERROR (0x00)

The security principal that makes the call MUST have WBEM_ENABLE and WBEM_REMOTE_ENABLE accesses to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

If strSuperClass is dynamic, the server MUST obtain SupportsEnumerate for the given provider in the ProviderTable. If SupportsEnumerate is FALSE, the server MUST return WBEM_E_PROVIDER_NOT_CAPABLE.

In response to the IWbemServices::CreateInstanceEnum method, the server MUST evaluate the strSuperClass parameter (as specified in this section) and MUST return all instances for the specific class in the current namespace. The method MUST fail if the following applies: if strSuperClass does not exist; if the method parameters or their combinations are not valid, as specified in this section; or if the server is unable to execute the method.

The server SHOULD enforce a maximum length for the strSuperClass parameter, and return WBEM_E_QUOTA_VIOLATION if the limit is exceeded.<46>

The successful synchronous method execution MUST fill the ppEnum parameter with an IEnumWbemClassObject interface pointer after all instances are collected and MUST return WBEM_S_NO_ERROR.

The semisynchronous method execution MUST follow the rules as specified in section 3.1.1.1.2.

The failed method execution MUST set the value that is referenced by the output parameters to NULL and MUST return an error in the format that is specified in section 2.2.11.

3.1.4.3.16 IWbemServices::CreateInstanceEnum (Opnum 18)

Additional resources