Método IEnumWbemClassObject::Next (wbemcli.h)

Use o método IEnumWbemClassObject::Next para obter um ou mais objetos começando na posição atual em uma enumeração. Esse método avança a posição atual na enumeração por objetos uCount , de modo que as chamadas subsequentes retornem os objetos subsequentes.

Sintaxe

HRESULT Next(
  [in]  long             lTimeout,
  [in]  ULONG            uCount,
  [out] IWbemClassObject **apObjects,
  [out] ULONG            *puReturned
);

Parâmetros

[in] lTimeout

Especifica a quantidade máxima de tempo em milissegundos que a chamada bloqueia antes de retornar. Se você usar a constante WBEM_INFINITE (0xFFFFFFFF), a chamada bloqueará até que os objetos estejam disponíveis. Se você usar o valor 0 (WBEM_NO_WAIT), a chamada retornará imediatamente, se algum objeto estiver disponível ou não.

[in] uCount

Número de objetos solicitados.

[out] apObjects

Ponteiro para armazenamento suficiente para conter o número de ponteiros de interface IWbemClassObject especificados por uCount. Esse armazenamento deve ser fornecido pelo chamador. Esse parâmetro não pode ser NULL. O chamador deve chamar Release em cada um dos ponteiros de interface recebidos quando eles não forem mais necessários.

[out] puReturned

Ponteiro para um ULONG que recebe o número de objetos retornados. Esse número pode ser menor do que o número solicitado em uCount. Esse ponteiro não pode ser NULL.

Nota O método Next retorna WBEM_S_FALSE quando você chega ao final da enumeração, mesmo que os objetos tenham sido retornados com êxito. O valor WBEM_S_NO_ERROR retorna somente quando o número de objetos retornados corresponde ao número solicitado em uCount. O valor WBEM_S_TIMEDOUT é retornado quando o número de objetos retornados é menor que o número solicitado, mas você não está no final da enumeração. Portanto, você deve usar a lógica de encerramento de loop que examina o valor puReturned para garantir que você tenha chegado ao final da enumeração.

 

Retornar valor

O método Next retorna um HRESULT que indica o status da chamada de método. A lista a seguir lista o valor contido em um HRESULT.

Comentários

Você poderá ver códigos de erro específicos de COM retornados se problemas de rede fizerem com que você perca a conexão remota com o Gerenciamento do Windows. Em caso de erro, você pode chamar a função COM GetErrorInfo para obter mais informações de erro.

Se mais de um objeto for solicitado e se o número de objetos solicitados for retornado, a função retornará WBEM_S_NO_ERROR. Se menor que o número solicitado de objetos estiver disponível e se a enumeração tiver sido concluída, esses objetos serão retornados e a função retornará WBEM_S_FALSE.

Se a enumeração não tiver sido concluída, a chamada aguardará que os objetos fiquem disponíveis até o tempo limite especificado. Se a enumeração atingir o tempo limite antes que os objetos estejam disponíveis, a função retornará WBEM_S_TIMEDOUT.

Nota Como o retorno de chamada para o coletor pode não ser retornado no mesmo nível de autenticação exigido pelo cliente, é recomendável que você use a comunicação semissíncrona em vez de assíncrona. Para obter mais informações, confira Como chamar um método.

 

Exemplos

Para obter uma discussão estendida e um exemplo de como fazer consultas em C++ e WMI, consulte Making WMI Queries In C++ on CodeProject.

No código a seguir, mais de um objeto é solicitado:

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;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	wbemcli.h (inclua Wbemidl.h)
Biblioteca	Wbemuuid.lib
DLL	Fastprox.dll

Confira também

Enumeração do WMI

IEnumWbemClassObject