Export (0) Print
Expand All

IEnumWbemClassObject::NextAsync method

Use the NextAsync method when a controlled asynchronous retrieval of objects to a sink is required. Normal asynchronous retrieval, such as a call to IWbemServices::ExecQueryAsync, results in uncontrolled delivery of objects to the caller's implementation of IWbemObjectSink. This method is helpful for cases where a component controls object delivery.

Syntax


HRESULT NextAsync(
  [in]  ULONG uCount,
  [in]  IWbemObjectSink *pSink
);

Parameters

uCount [in]

Number of objects being requested.

pSink [in]

Sink to receive the objects. The sink must be implemented by the caller. As each batch of objects is requested, they are delivered to the pSink parameter of the Indicate method followed by a final call to the pSink parameter of the SetStatus method. If the sink is going to be used to deliver objects, this method returns WBEM_S_NO_ERROR, even if the number of objects to be delivered is less than requested. However, if there are no more objects remaining, then the pSink parameter is ignored (no calls to the pSink parameter of SetStatus are made). Instead, this method returns WBEM_S_FALSE.

Return value

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

Return codeDescription
WBEM_E_FAILED

The call failed and it is not expected to complete.

WBEM_E_INVALID_PARAMETER

A specified parameter is not valid.

WBEM_E_UNEXPECTED

An object in the enumeration has been deleted, which destroyed the validity of the enumeration.

WBEM_E_OUT_OF_MEMORY

There was not enough memory to complete the operation.

WBEM_E_TRANSPORT_FAILURE

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

WBEM_S_NO_ERROR

One or more objects successfully returned. It is not considered an error if less objects are returned than requested.

WBEM_S_FALSE

This is returned when no more objects are available. This value is also returned when this method is called with a value of 0 for the uCount parameter.

 

Remarks

A call to the COM function GetErrorInfo provides more information about the error. COM-specific error codes may also be returned if network problems cause you to lose the remote connection to Windows Management.

This call returns immediately and delivery to the sink occurs in the background. If multiple calls are made to this method from one or more threads, they are logically queued and the order of calls and object delivery is preserved. Multiple calls made to this method from one or more threads block do not return until all the sink objects related to previous calls to this method have been serviced. A call to Reset does not affect delivery of objects currently in progress as a result of previous calls. The Reset method only causes new calls to start at the beginning of the object sequence.

If the number of requested objects is immediately available, the function returns WBEM_S_NO_ERROR. If less than the number of requested objects are available, the available objects are returned and WBEM_S_NO_ERROR are returned. The remainder of the objects are delivered by the user-supplied sink.

As the objects become available, the caller's implementation of IWbemObjectSink::Indicate is called zero or more times to deliver the objects. This is followed by a call to IWbemObjectSink::SetStatus with a value of WBEM_S_NO_ERROR if uCount items are returned.

If fewer objects are available than the number requested, Indicate is called for those objects that are available. SetStatus is then called with a value of WBEM_S_FALSE, or the error code if an error occurred.

If the requested number of objects is delivered, the final object is followed by a call to SetStatus with a status code of WBEM_S_NO_ERROR. If the enumeration completes before the requested number of objects can be delivered, the SetStatus method has a status code of WBEM_S_FALSE.

If there are no available objects, Indicate is not called. However, a final call to SetStatus always occurs to indicate the status of the entire operation.

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. If you require asynchronous communication, see Calling a Method.

For more information about using methods semisynchronously, see IEnumWbemClassObject::Next 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.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Wbemcli.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

Fastprox.dll

 

 

Show:
© 2014 Microsoft