The IWbemServices::CreateInstanceEnum method provides an instance enumeration. When invoked, the server MUST return all class instances that satisfy the selection criteria.
HRESULT CreateInstanceEnum(
[in] const BSTR strFilter,
[in] long lFlags,
[in] IWbemContext* pCtx,
[out] IEnumWbemClassObject** ppEnum
);
strFilter: MUST contain the name of the CIM class that the client wants instances of. This parameter MUST NOT be NULL.
lFlags: Flags that affect the behavior of the CreateInstanceEnum method. The flags' 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 | When this bit is not set, the server MUST consider the entire class hierarchy when returning the result.
When this bit is set, the server MUST disregard any derived class when searching the result.
|
WBEM_FLAG_SHALLOW
0x00000001 | When this bit is not set the server MUST return all classes derived from the requested class and all its subclasses.
When this bit is set, the server MUST return only classes that are directly derived from the requested class.
|
WBEM_FLAG_FORWARD_ONLY
0x00000020 | When the bit is not set the server MUST return an enumerator with reset capability.
When the bit is set, the server MUST return an enumerator without reset capability as specified in section 3.1.4.4.
|
pCtx: MUST be a pointer to an IWbemContext interface, which contains additional information the client wants to pass to the server. If pCtx is NULL, the parameter MUST be ignored.
ppEnum: MUST be an out parameter that MUST receive the pointer to the enumerator 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 making the call MUST have WBEM_ENABLE and WBEM_REMOTE_ENABLE accesses to the namespace.
In response to the IWbemServices::CreateInstanceEnum method, the server MUST evaluate the strFilter parameter (as specified in this section) and MUST return all instances for the specific class in the current namespace. The method MUST fail if strFilter 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 successful synchronous method execution MUST fill the ppEnum parameter with a new IEnumWbemClassObject after all instances are collected and MUST return WBEM_S_NO_ERROR.
The successful semisynchronous method execution MUST return immediately, it MUST fill the ppEnum parameter, and MUST return WBEM_S_NO_ERROR as specified in section 3.1.1.1.2.
The failed method execution MUST set the value referenced by the output parameters to NULL and MUST return an error in the format specified in section 2.2.11.