Метод IEnumPortableDeviceObjectIDs::Next (portabledeviceapi.h)

Статья
08/25/2023

Метод Next извлекает следующий идентификатор объекта или несколько в последовательности перечисления.

Синтаксис

HRESULT Next(
  [in]      ULONG  cObjects,
  [in, out] LPWSTR *pObjIDs,
  [in, out] ULONG  *pcFetched
);

Параметры

[in] cObjects

Количество запрошенных объектов.

[in, out] pObjIDs

Массив указателей LPWSTR , каждый из которых указывает полученный идентификатор объекта. Вызывающий объект должен выделить массив элементов cObjects LPWSTR. Вызывающий объект должен освободить как массив, так и возвращаемые строки. Строки освобождаются путем вызова CoTaskMemFree.

[in, out] pcFetched

Во входных данных этот параметр игнорируется. Количество фактически извлеченных идентификаторов в выходных данных. Если идентификаторы объектов не освобождаются и возвращаемое значение S_FALSE, перечислять больше не нужно.

Возвращаемое значение

Метод возвращает HRESULT. Допустимые значения включают, но не ограничиваются, значения, приведенные в следующей таблице.

Код возврата	Описание
S_OK	Метод выполнен успешно.
S_FALSE	Больше нет объектов для перечисления.

Если в последовательности остается меньше запрошенного числа элементов, этот метод извлекает оставшиеся элементы. Количество фактически извлеченных элементов возвращается через pcFetched (если вызывающий объект не передал значение NULL для этого параметра). Перечислимые объекты являются одноранговым элементом, то есть перечисление дочерних объектов объекта будет перечислять только прямые дочерние объекты, а не объекты внучки или более глубокие объекты.

Примеры


// This number controls how many object identifiers are requested during each call
// to IEnumPortableDeviceObjectIDs::Next()
#define NUM_OBJECTS_TO_REQUEST  10

// Recursively called function which enumerates using the specified
// object identifier as the parent.
void RecursiveEnumerate(LPCWSTR wszParentObjectID, IPortableDeviceContent* pContent)
{
    HRESULT                       hr             = S_OK;
    IEnumPortableDeviceObjectIDs* pEnumObjectIDs = NULL;

    if ((wszParentObjectID == NULL) ||
        (pContent          == NULL))
    {
        return;
    }

    // wszParentObjectID is the object identifier of the parent being used for enumeration

    // Get an IEnumPortableDeviceObjectIDs interface by calling EnumObjects with the
    // specified parent object identifier.
    hr = pContent->EnumObjects(0, wszParentObjectID, NULL, &pEnumObjectIDs);
    if (FAILED(hr))
    {
        // Failed to get IEnumPortableDeviceObjectIDs from IPortableDeviceContent
    }

    // Loop calling Next() while S_OK is being returned.
    while(hr == S_OK)
    {
        DWORD  cFetched = 0;
        LPWSTR szObjectIDArray[NUM_OBJECTS_TO_REQUEST] = {0};
        hr = pEnumObjectIDs->Next(NUM_OBJECTS_TO_REQUEST, // Number of objects to request on each NEXT call
                                  szObjectIDArray,        // Array of LPWSTR array which will be populated on each NEXT call
                                  &cFetched);             // Number of objects written to the LPWSTR array
        if (SUCCEEDED(hr))
        {
            // Traverse the results of the Next() operation and recursively enumerate
            // Remember to free all returned object identifiers using CoTaskMemFree()
            for (DWORD dwIndex = 0; dwIndex < cFetched; dwIndex++)
            {
                RecursiveEnumerate(szObjectIDArray[dwIndex],pContent);

                // Free allocated LPWSTRs after the recursive enumeration call has completed.
                CoTaskMemFree(szObjectIDArray[dwIndex]);
                szObjectIDArray[dwIndex] = NULL;
            }
        }
    }

    // Release the IEnumPortableDeviceObjectIDs when finished
    if (pEnumObjectIDs != NULL)
    {
        pEnumObjectIDs->Release();
        pEnumObjectIDs = NULL;
    }
}

Требования

Требование	Значение
Целевая платформа	Windows
Header	portabledeviceapi.h
Библиотека	PortableDeviceGUIDs.lib

См. также раздел

Перечисление содержимого

Интерфейс IEnumPortableDeviceObjectIDs

Поделиться через