WMI--Windows API--IEnumWbemClassObjec.Next

原文来自MSDN Library for Visual Studio 2008 SP1，翻译部分仅为个人观点，想要看更多信息请看MSDN，如有版权问题请联系QQ 643166601，邮件643166601@qq.com

 

Next Method of the IEnumWbemClassObject Interface
Use the IEnumWbemClassObject::Next method to get one or more objects starting at the current position in an enumeration.
使用IEnumWbemClassObject::Next方法获得一个或更多对象在枚举中当前位置开始。
This method advances the current position in the enumeration by uCount objects, so that subsequent calls return the subsequent objects.
这个方法在枚举中的uCount对象中增长当前位置，因此随后的调用返回随后的对象。
HRESULT Next(
  [in]                 LONG lTimeOut,
  [in]                 ULONG uCount,
  [out]                IWbemClassObject** ppObjects,
  [out]                ULONG* puReturned
);

Parameters
lTimeOut
Specifies the maximum amount of time in milliseconds that the call blocks before returning.
指定调用块返回前的最大毫秒数的时间。
If you use the constant WBEM_INFINITE (0xFFFFFFFF), the call blocks until objects are available.
如果你使用常量WBEM_INFINITE (0xFFFFFFFF)，这个调用块直达对象可用。
If you use the value 0 (WBEM_NO_WAIT), the call returns immediately, whether any objects are available or not.
如果你使用值 0 (WBEM_NO_WAIT)，这个调用立即返回，无论任何对象是可用的或不可用。
uCount
Number of requested objects.
对象请求的数量。
ppObjects
Pointer to enough storage to hold the number of IWbemClassObject interface pointers specified by uCount.
指针指向足够存储去容纳uCount指定的IWbemClassObject接口的数量。
This storage must be supplied by the caller.
这个存储必须是调用者提供。
This parameter cannot be NULL.
这个参数不能是NULL。
The caller must call Release on each of the received interface pointers when they are no longer needed.
当它们不再需要时，调用者必须调研那个在每个返回的接口至指针调用Release。
puReturned
Pointer to a ULONG that receives the number of objects returned.
这真指向ULONG取回返回对象的数量。
This number can be less than the number requested in uCount.
这个数字可以小于uCount中的数字。
This pointer cannot be NULL.
这个指针不能是NULL。

Note  The Next method returns WBEM_S_FALSE when you have reached the end of the enumeration, even if objects have been returned successfully.
注意这个Next方法当到达枚举的结束即使对象已经成功返回也返回WBEM_S_FALSE。
The WBEM_S_NO_ERROR value returns only when the number of objects returned matches the number requested in uCount.
只有当返回对象的数量和在uCount中请求的数量匹配时才返回WBEM_S_NO_ERROR。
The WBEM_S_TIMEDOUT value is returned when the number of objects returned is less than the number requested but you are not at the end of the enumeration.
当返回对象的数量少于请求的数量时除了你没有到达枚举的结尾时返回这个WBEM_S_TIMEDOUT值。
Therefore, you should use loop termination logic that examines the puReturned value to ensure that you have reached the end of the enumeration.
因此，你应该使用循环终止逻辑在仔细检查puReturned值去确保你已经到达枚举的结尾。
Return Value
The Next method returns an HRESULT indicating the status of the method call.
这个Next方法返回一个HRESULT指示方法调用的状态。
The following table lists the value contained within an HRESULT.
一个HRESULT值包含在以下列表中。
Return code Description
WBEM_E_INVALID_PARAMETER
 One or more invalid parameters were specified in the call.
 在调用中指定了一个或更多个无效的参数。
WBEM_E_OUT_OF_MEMORY
 There was not enough memory to complete the enumeration.
 没有足够的内存去完成枚举。
WBEM_E_UNEXPECTED
 An object in the enumeration has been deleted, destroying the validity of the enumeration.
 在枚举中的一个对象已经被删除，销毁枚举的有效性了。
WBEM_E_TRANSPORT_FAILURE
 This indicates the failure of the remote procedure call (RPC) link between the current process and Windows Management.
 这个指示远程程序调用(RPC)链路在当前进程和Windows管理之间失败。
WBEM_S_NO_ERROR
 The number of objects returned was the same as the number requested.
 这个返回对象的数量和请求的数量是一样的。
WBEM_S_FALSE
 The number of objects returned was less than the number requested.
 这个返回对象的数量少于请求的数量。
 WBEM_S_FALSE is also returned when this method is called with a value of 0 for the uCount parameter.
 当这个方法的uCount参数是0值时也返回WBEM_S_FALSE。
WBEM_S_TIMEDOUT
 A time-out occurred before you obtained all the objects.
 在你取回所有对象之前发生时间超时。

Remarks
You may see COM-specific error codes returned if network problems cause you to lose the remote connection to Windows Management.
如果网络问题引起你丢失远程连接到Windows管理你可以看COM-specific返回的错误代码。
On error, you can call the COM function GetErrorInfo to obtain more error information.
在上面的错误中，你可以调用COM 函数的GetErrorInfo获得更多错误信息。
If more than one object is requested, and if the number of requested objects is returned, the function returns WBEM_S_NO_ERROR.
如果请求有多于一个对象并且如果请求对象的数量是被返回的，这个函数返回WBEM_S_NO_ERROR。
If less than the requested number of objects is available, and if the enumeration has completed, those objects are returned and the function returns WBEM_S_FALSE.
如果少于请求的对象数量是可用的，并且如果这个枚举已经完成，这些对象都被返回并且函数返回WBEM_S_FALSE。
If the enumeration has not completed, the call waits for objects to be available up to the specified time-out.
如果没有完成枚举，这个调用等待对象到达可用的指定的超时。
If the enumeration times out before the objects are available, the function returns WBEM_S_TIMEDOUT.
如果枚举超时之前的对象是可用的这个函数返回WBEM_S_TIMEDOUT。

Because the call-back to the sink 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 Calling a Method.
更多信息，请看 Calling a Method。
Example Code
In the following code, more than one object is requested:
在以下的代码中，超过一个对象被请求：
HRESULT ProcessEnum( IEnumWbemClassObject*    pEnum )
{
    HRESULT    hRes = WBEM_S_NO_ERROR;

    // Final Next will return WBEM_S_FALSE
    while ( WBEM_S_NO_ERROR == hRes )
    {
        ULONG            uReturned;
        IWbemClassObject*    apObj[10];

        hRes = pEnum->Next( WBEM_INFINITE, 10, apObj, &uReturned );

        if ( SUCCEEDED( hRes ) )
        {
            // Do something with the objects.
            //ProcessObjects( uReturned,  apObj );

            for ( ULONG n = 0; n < uReturned; n++ )
            {
                apObj[n]->Release();
            }

        }    // If Enum succeeded...
    }    // While Enum is returning objects...

    return hRes;
}

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.
脚本列子，请看WMI Tasks for Scripts and Applications和 TechNet ScriptCenter脚本库。
For C++ code examples, see WMI C++ Application Examples.
C++代码例子，请看 WMI C++ Application Examples.
Requirements
Client
 Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation 4.0 SP4 and later, Windows Me, Windows 98, or Windows 95.
 
Server
 Requires Windows Server 2008, Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0 SP4 and later.
 
Header
 Declared in Wbemcli.h; include Wbemidl.h.
 
Library
 Use Wbemuuid.lib.
 
DLL
 Requires Fastprox.dll.
 

Send comments about this topic to Microsoft

Build date: 8/15/2007