Функция EnumerateNtmsObject (ntmsapi.h)

Статья
03/08/2023

[Диспетчер съемных носителей больше недоступен в Windows 7 и Windows Server 2008 R2.]

Функция EnumerateNtmsObject перечисляет объекты RSM, содержащиеся в параметре lpContainerId .

Синтаксис

DWORD EnumerateNtmsObject(
  [in]      HANDLE            hSession,
  [in]      const LPNTMS_GUID lpContainerId,
  [out]     LPNTMS_GUID       lpList,
  [in, out] LPDWORD           lpdwListSize,
  [in]      DWORD             dwType,
  [in]      DWORD             dwOptions
);

Параметры

[in] hSession

Дескриптор сеанса, возвращаемого функцией OpenNtmsSession .

[in] lpContainerId

Уникальный идентификатор контейнера объектов RSM, объекты которого необходимо перечислить. Этот параметр может быть GUID библиотеки, пула носителей, идентификатора секции, физического носителя или логического носителя. Чтобы перечислить все объекты типа, указанного параметром dwType , независимо от контейнера, присвойте этому параметру значение NULL. Дополнительные сведения о связи "объект-контейнер" см. в разделе NtmsObjectsTypes.

[out] lpList

Буфер для массива библиотек, дисков, носителей или других идентификаторов объектов RSM.

[in, out] lpdwListSize

Указатель на переменную, указывающую максимальное число идентификаторов, которые функция может возвращать с помощью параметра lpList . Во время возврата количество идентификаторов в lpList возвращается в lpdwListSize.

[in] dwType

Тип объектов для перечисления в контейнере lpContainerId . Если lpContainerId имеет значение NULL, перечисляются все объекты этого типа, поддерживаемые RSM. Этот параметр может быть одним из следующих значений из типа перечисления NtmsObjectsTypes .

Значение	Значение
NTMS_CHANGER	Смены. Параметр lpContainerId должен иметь значение NULL или GUID библиотеки.
NTMS_CHANGER_TYPE	Типы переменных. Параметр lpContainerId должен иметь значение NULL.
NTMS_COMPUTER	Текущий объект компьютера. Параметр lpContainerId должен иметь значение NULL.
NTMS_DRIVE	Диски. Параметр lpContainerId должен иметь значение NULL или GUID библиотеки.
NTMS_DRIVE_TYPE	Типы дисков. Параметр lpContainerId должен иметь значение NULL.
NTMS_IEDOOR	Двери. Параметр lpContainerId должен иметь значение NULL или GUID библиотеки.
NTMS_IEPORT	Порты вставки и извлечения, содержащиеся в библиотеке, заданной параметром lpContainerId , или все порты вставки и извлечения, поддерживаемые RSM, если указан идентификатор контейнера NULL . Параметр lpContainerId должен иметь значение NULL или GUID библиотеки.
NTMS_LIBRARY	Объекты библиотеки. К ним относятся физические единицы библиотеки и автономная библиотека. Параметр lpContainerId должен иметь значение NULL.
NTMS_LIBREQUEST	Активные запросы библиотеки (или рабочие элементы), помещенные в очередь в библиотеку, заданную параметром lpContainerId , или ко всем рабочим элементам библиотеки, помещенным в очередь в RSM, если указан идентификатор контейнера NULL . Параметр lpContainerId должен иметь значение NULL или GUID библиотеки.
NTMS_LOGICAL_MEDIA	Логический объект мультимедиа. Это среда, выделенная для приложения, которая может содержать более одной стороны или части физического носителя. Параметр lpContainerId должен иметь значение NUL, GUID пула носителей или GUID секции.
NTMS_MEDIA_POOL	Объект пула носителей, содержащий логические и (или) физические носители, а также параметры конфигурации для управления ими. Если в качестве идентификатора контейнера задано значение NULL , возвращаются только имена верхнего уровня. Параметр lpContainerId должен иметь значение NULL или GUID пула носителей.
NTMS_MEDIA_TYPE	Объект типа мультимедиа, содержащий атрибуты типа среды, поддерживаемого RSM. При перечислении со значением NULL будут предоставлены все возможные типы носителей, а не только те, которые доступны на текущем сервере. Параметр lpContainerId должен иметь значение NULL или GUID библиотеки.
NTMS_OPREQUEST	Запросы операторов, которые находятся на этом сервере RSM. Параметр lpContainerId должен иметь значение NULL.
NTMS_PARTITION	Бок на части физического носителя. Часть физического носителя может содержать несколько физических сторон (например, оптический диск содержит две стороны). Параметр lpContainerId должен иметь значение NULL, guid логического носителя, GUID физического носителя или GUID пула носителей.
NTMS_PHYSICAL_MEDIA	Элемент физического носителя (лента, оптический диск, компакт-диск или магнитный патрон). Физический носитель может содержать несколько физических сторон (например, стороны оптического диска). Параметр lpContainerId должен иметь значение NULL, GUID пула носителей или GUID библиотеки.
NTMS_STORAGESLOT	Слоты мультимедиа, содержащиеся в библиотеке, заданной параметром lpContainerId , или во всех слотах хранения, поддерживаемых RSM, если указан идентификатор контейнера NULL . Параметр lpContainerId должен иметь значение NULL или GUID библиотеки.

[in] dwOptions

Параметры перечисления. Это применимо, только если dwType имеет NTMS_MEDIA_POOL.

Значение	Значение
NTMS_ENUM_ROOTPOOL	Это перечисляет корневой пул в дополнение ко всем другим пулам мультимедиа верхнего уровня; он всегда возвращается в качестве первого GUID в списке. Перечисление корневого пула требуется только для получения или задания атрибутов безопасности объекта . Значение dwType должно быть NTMS_MEDIA_POOL, а значение lpContainerId должно иметь значение NULL.
NTMS_ENUM_DEFAULT	Не включает перечисление корневого пула при перечислении пулов носителей.

Значение

NTMS_ENUM_ROOTPOOL

Это перечисляет корневой пул в дополнение ко всем другим пулам мультимедиа верхнего уровня; он всегда возвращается в качестве первого GUID в списке. Перечисление корневого пула требуется только для получения или задания атрибутов безопасности объекта . Значение dwType должно быть NTMS_MEDIA_POOL, а значение lpContainerId должно иметь значение NULL.

NTMS_ENUM_DEFAULT

Не включает перечисление корневого пула при перечислении пулов носителей.

Windows XP: Этот параметр зарезервирован и должен иметь нулевое значение.

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

Эта функция возвращает одно из следующих значений.

Значение	Значение
ERROR_INVALID_PARAMETER	Отсутствует указатель lpdwListSize или lpContainerId не является допустимым контейнером для типа объекта, заданного dwType.
ERROR_INSUFFICIENT_BUFFER	Размер буфера, заданный lpdwListSize , слишком мал для всех найденных объектов. Функция усекает список и возвращает фактический размер в lpdwListSize.
ERROR_INVALID_HANDLE	Дескриптор сеанса отсутствует или недопустим.
ERROR_NOT_ENOUGH_MEMORY	Во время обработки произошел сбой выделения.
ERROR_OBJECT_NOT_FOUND	Идентификатор GUID, заданный lpContainerId , не является ИДЕНТИФИКАТОРом GUID объекта контейнера в базе данных.
ERROR_SUCCESS	Функция выполнена успешно. Если lpContainerId не содержит объектов типа, заданного dwType, функция возвращает ERROR_SUCCESS и lpdwListSize , равный нулю.

Если доступное число идентификаторов, указанное в параметре lpdwListSize , больше текущего размера буфера, lpdwListSize возвращает требуемое число идентификаторов. Затем приложение должно выделить буфер большего размера и повторить попытку.

Так как идентификаторы могут быть добавлены другим процессом, последующие функции с измененным размером списка могут получить ошибку, указывающую на то, что список слишком мал.

Если параметр lpContainerId имеет значение NULL, RSM перечисляет объекты верхнего уровня (например, библиотеки).

Если в списке указано несколько объектов, объект может быть перечислен из нескольких контейнеров. Контейнер NULL является контейнером самого высокого уровня и перечисляет все объекты в системе. Например, можно перечислить носители в определенной библиотеке или все носители в системе.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	ntmsapi.h
Библиотека	Ntmsapi.lib
DLL	Ntmsapi.dll