Export (0) Print
Expand All
1 out of 1 rated this helpful - Rate this topic

IWbemServices::CreateInstanceEnumAsync method

The IWbemServices::CreateInstanceEnumAsync method creates an enumerator that asynchronously returns the instances of a specified class according to user-specified selection criteria. This method supports simple WMI Query Language (WQL) queries. More complex queries can be processed using the IWbemServices::ExecQueryAsync method.

Syntax


HRESULT CreateInstanceEnumAsync(
  [in]  const BSTR strClass,
  [in]  LONG lFlags,
  [in]  IWbemContext *pCtx,
  [in]  IWbemObjectSink *pResponseHandler
);

Parameters

strClass [in]

Valid BSTR containing the name of the class for which instances are desired. This parameter cannot be NULL.

lFlags [in]

This parameter can be one of the following values.

FlagMeaning
WBEM_FLAG_USE_AMENDED_QUALIFIERS

If this flag is set, Windows Management Instrumentation (WMI) retrieves the amended qualifiers stored in the localized namespace of the current connection's locale. If not set, only the qualifiers stored in the immediate namespace are retrieved.

WBEM_FLAG_DEEP

This flag forces the enumeration to include instances of this and all subclasses in the hierarchy.

WBEM_FLAG_SHALLOW

This flag forces the enumeration to include only pure instances of this class, excluding all instances of subclasses, which supply properties not found in this class.

WBEM_FLAG_SEND_STATUS

This flag registers with Windows Management a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus. Provider implementation must support intermediate status reporting for this flag to change behavior.

WBEM_FLAG_BIDIRECTIONAL

This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.

WBEM_FLAG_DIRECT_READ

This flag causes direct access to the provider for the class specified without any regard to its parent class or subclasses.

 

pCtx [in]

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is returning the requested instances. The values in the context object must be specified in the documentation for the provider in question. For more information, see Making Calls to WMI.

pResponseHandler [in]

Pointer to the caller's implementation of IWbemObjectSink. This handler receives the objects as they become available. If any error code is returned, then the supplied IWbemObjectSink pointer is not used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. Windows Management only calls AddRef on the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For more information, see Calling a Method.

Return value

This method returns an HRESULT indicating the status of the method call. The following table lists the value contained within an HRESULT.

On failure, you can obtain more information from the COM function GetErrorInfo.

COM-specific error codes also may be returned if network problems cause you to lose the remote connection to Windows Management.

An instance provider can report success or failure with either the return code from CreateInstanceEnumAsync, or through a call to SetStatus made through pResponseHandler. If you choose to call SetStatus, the return code sent through pResponseHandler takes precedence.

If CreateInstanceEnumAsync returns WBEM_S_NO_ERROR, WMI waits for a result from the SetStatus method of the response handler. WMI waits indefinitely on a local connection, or until a remote connection time-out occurs.

Return codeDescription
WBEM_E_FAILED

This indicates other unspecified errors.

WBEM_E_INVALID_PARAMETER

The specified parameter is not valid.

WBEM_E_INVALID_CLASS

The specified class does not exist or is not valid.

WBEM_E_OUT_OF_MEMORY

There was not enough memory to complete the operation.

WBEM_E_SHUTTING_DOWN

Windows Management service was probably stopped and restarted. A new call to ConnectServer is needed.

WBEM_E_TRANSPORT_FAILURE

This indicates the failure of the remote procedure call (RPC) link between the current process and Windows Management.

WBEM_E_NOT_FOUND

The provider cannot recognize the class name.

WBEM_E_PROVIDER_NOT_CAPABLE

The provider cannot enumerate instances regardless of whether it recognizes the name. Return this error code in all cases if a more specific code is not required.

WBEM_S_NO_ERROR

The call succeeded.

 

Remarks

The IWbemObjectSink::SetStatus method is called to indicate the end of the result set. It may also be called with no intervening calls to IWbemObjectSink::Indicate if error conditions occur.

Because the callback might not be returned at the same authentication level as the client requires, it is recommended that you use semisynchronous instead of asynchronous communication.

For more information, see IWbemServices::CreateInstanceEnum and Calling a Method.

Examples

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application Examples.

The following example shows you how to implement CreateInstanceEnumAsync.


#define NUM_OF_INSTANCES 3

HRESULT CStdProvider::CreateInstanceEnumAsync( 
            /* [in] */ BSTR strClass,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    IWbemClassObject *pClass = 0; 
    IWbemClassObject *pNextInst = 0;

    // Assume there is an IWbemServices pointer available to
    // retrieve the class definition.
    HRESULT hRes = m_pSvc->GetObject(strClass, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

    // Now loop through the private source and create each instance.
    for (int i = 0; i < NUM_OF_INSTANCES; i++)
    {
         // Prepare an empty object to receive the class definition.
         pClass->SpawnInstance(0, &pNextInst);

         // Create the instance.
         // For example, create the instance in a
         // FillInst method you implement:
         /*FillInst(pNextInst);*/

         // Deliver the class to WMI.
         pResponseHandler->Indicate(1, &pNextInst);
         pNextInst->Release();
    }

    // Send a finish message to WMI.
    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);

    // Free memory resources.
    SysFreeString(strClass);
    pClass->Release();
    m_pSvc->Release();

    return WBEM_S_NO_ERROR;
}

In the previous example, the instance provider acquires a thread from WMI to perform any necessary operations. You may want to call the sink AddRef method and create another thread for delivering the objects in the result set. Creating another thread allows the current thread to return to WMI without depleting the thread pool. Whether or not the provider chooses the single thread design over the dual thread design depends on how long the provider plans to use the WMI thread. There are no fixed rules. Experimentation can help you determine how your design affects WMI performance.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Wbemcli.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

Fastprox.dll;
Esscli.dll;
Framedyn.dll;
Ntevt.dll;
Stdprov.dll;
Viewprov.dll;
Wbemcomn.dll;
Wbemcore.dll;
Wbemess.dll;
Wbemsvc.dll;
Wmipicmp.dll;
Wmidcprv.dll;
Wmipjobj.dll;
Wmiprvsd.dll

See also

IWbemServices
IWbemServices::CreateInstanceEnum
Calling a Method

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.