Edit

Provider::EnumerateInstances method (provider.h)

  • Article

[The Provider class is part of the WMI Provider Framework which is now considered in final state, and no further development, enhancements, or updates will be available for non-security related issues affecting these libraries. The MI APIs should be used for all new development.]

The EnumerateInstances method is called by WMI to retrieve all instances of a framework provider's class.

Syntax

HRESULT EnumerateInstances(
  MethodContext *pMethodContext,
  long          lFlags
);

Parameters

pMethodContext

Pointer to the context object for this call. This value contains any IWbemContext properties specified by the client. Also, this pointer must be used as a parameter to any calls back into WMI.

lFlags

Bitmask of flags with information about the EnumerateInstances operation. This is the value specified by the client in the IWbemServices::CreateInstanceEnum method.

The following flags are handled by (and filtered out) by WMI:

  • WBEM_FLAG_DEEP
  • WBEM_FLAG_SHALLOW
  • WBEM_FLAG_RETURN_IMMEDIATELY
  • WBEM_FLAG_FORWARD_ONLY
  • WBEM_FLAG_BIDIRECTIONAL
  • WBEM_FLAG_USE_AMENDED_QUALIFIERS

Return value

The default framework provider implementation of this method returns WBEM_E_PROVIDER_NOT_CAPABLE to the calling method. The IWbemServices::CreateInstanceEnum method lists the most common return values, but you can choose to return any COM return code.

Remarks

It is not an error for EnumerateInstances to return zero instances by instantiating zero CInstance instances and setting the return value to WBEM_S_NO_ERROR.

WMI often calls EnumerateInstances when a client application calls IWbemServices::CreateInstanceEnum, although WMI may call EnumerateInstances in other situations as well. The following is a common way to override EnumerateInstances:

  1. Create an empty instance of your class using Provider::CreateNewInstance.
  2. Populate the properties of the empty instance using the Set methods of the CInstance class, such as CInstance::SetByte or CInstance::SetStringArray.
  3. Send the instance back to the client using CInstance::Commit.
If you are building a method-only provider and do not have any instances, or if enumerating instances of your class would return too many instances, you may decide to support queries that retrieve only specific instances.

Requirements

Requirement Value
Minimum supported client Windows Vista
Minimum supported server Windows Server 2008
Target Platform Windows
Header provider.h (include FwCommon.h)
Library FrameDyn.lib
DLL FrameDynOS.dll; FrameDyn.dll