IWbemHiPerfProvider::CreateRefreshableEnum method

The IWbemHiPerfProvider::CreateRefreshableEnum method creates a new refreshable enumeration. The WMI Refresher calls this method in response to a client request to IWbemConfigureRefresher::AddEnum. The provider associates the supplied IWbemHiPerfEnum object with the supplied refresher. On each call to the supplied refresher's Refresh method, the provider ensures that the enumerator contains a set of all the instances of the class listed in the wszClass parameter and that these instances contain updated information. One possible way to do this would be to keep an array of refreshable enumerators in the refresher.

Note  If a provider does not implement this method, it must return WBEM_E_PROVIDER_NOT_CAPABLE.
 

Syntax


HRESULT CreateRefreshableEnum(
  [in]  IWbemServices   *pNamespace,
  [in]  LPCWSTR         wszClass,
  [in]  IWbemRefresher  *pRefresher,
  [in]  long            lFlags,
  [in]  IWbemContext    *pCtx,
  [in]  IWbemHiPerfEnum *pHiPerfEnum,
  [out] long            *plId
);

Parameters

pNamespace [in]

An IWbemServices pointer back into Windows Management, which can service any requests made by the provider. If pNamespace must call back into Windows Management during its execution, the provider calls AddRef on this pointer.

wszClass [in]

Constant, null-terminated string of 16-bit, Unicode characters that contains the name of the class, whose instances are refreshed in the pHiPerfEnum parameter.

pRefresher [in]

Pointer to a IWbemRefresher object that contains a refresher obtained by calling IWbemHiPerfProvider::CreateRefresher.

lFlags [in]

Reserved. This parameter must be 0 (zero).

pCtx [in]

Typically NULL; otherwise, a pointer to an IWbemContext object required by one or more dynamic class providers. The values in the context object must be specified in the specific provider's documentation. For more information about this parameter, see Making Calls to WMI.

pHiPerfEnum [in]

Pointer to a IWbemHiPerfEnum object that contains the high-performance enumeration.

plId [out]

Pointer to an integer returned by the provider that uniquely identifies the refreshable enumeration.

Return value

This method returns an HRESULT that indicates the status of the method call. The following list lists the value contained within an HRESULT.

WBEM_S_NO_ERROR

The method was successful.

WBEM_E_PROVIDER_NOT_CAPABLE

The provider does not implement this method.

WBEM_E_INVALID_CLASS

The provider does not support the requested class.

WBEM_E_ACCESS_DENIED

The current user does not have permission to retrieve instances of the specified class.

WBEM_E_NOT_FOUND

The requested instance could not be found.

WBEM_E_INVALID_OBJECT_PATH

The specified path was not valid.

WBEM_E_INVALID_PARAMETER

The parameter specified is not valid.

WBEM_E_OUT_OF_MEMORY

Memory could not be allocated.

WBEM_E_FAILED

This indicates other unspecified errors.

WBEM_E_NOT_FOUND

The provider cannot enumerate the requested class.

WBEM_E_PROVIDER_NOT_CAPABLE

The provider does not support refreshing instance objects. Unless a more specific error code is required, return this error code in all cases if a more specific code is not required.

Remarks

The provider must not modify the refreshable enumerator except during a refresh operation. The enumeration is shallow, so all instances placed in the enumerator should be of the class specified by wszClass.

The provider must not access the enumerator unless WMI calls the IWbemRefresher::Refresh method of the owner. As with refreshable objects, the provider must not update the enumerator unless the object owning the enumerator refreshes the enumerator.

Examples

The following code example describes how to implement CreateRefreshableEnum.


HRESULT CHiPerfProvider::CreateRefreshableEnum(
  /* [in] */IWbemServices *pNamespace,
  /* [in] */LPCWSTR wszClass,
  /* [in] */IWbemRefresher *pRefresher,
  /* [in] */long lFlags,
  /* [in] */IWbemContext *pCtx,
  /* [in] */IWbemHiPerfEnum *pEnum,
  /* [out] */ long *plId
)
{
  // Use a private interface defined
  // to talk with the refresher.
  IMyRefresher* pMyRefr = NULL;

  HRESULT hres = pRefresher->QueryInterface(
    IID_IMyRefresher,
    (void**) &pMyRefr );

  if ( SUCCEEDED( hres ) )
  {
  LPLONG plLastId;
    // Generates a unique identifier
    *plId = InterlockedIncrement( &plLastId );

    // Use an internal method to add the
    // enumerator to an array.
    pMyRefr->AddEnum( wszClass, *plId, pEnum );

    pMyRefr->Release();
  }

  return hres;
}

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2008

Header

Wbemprov.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

Wmiprvsd.dll

See also

IWbemHiPerfProvider
Developing a WMI Provider
Writing an Instance Provider
Making an Instance Provider into a High-Performance Provider
Performance Counter Provider

 

 

Show: