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

  • Статья

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

Функция AllocateNtmsMedia выделяет часть доступного носителя.

Синтаксис

DWORD AllocateNtmsMedia(
  [in]  HANDLE                        hSession,
  [in]  LPNTMS_GUID                   lpMediaPool,
  [in]  LPNTMS_GUID                   lpPartition,
  [out] LPNTMS_GUID                   lpMediaId,
  [in]  DWORD                         dwOptions,
  [in]  DWORD                         dwTimeout,
  [out] LPNTMS_ALLOCATION_INFORMATION lpAllocateInformation
);

Параметры

[in] hSession

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

[in] lpMediaPool

Уникальный идентификатор пула носителей, из которого будет выделен носитель. Для выделения можно указать только пулы приложений.

[in] lpPartition

Идентификатор части стороны, используемой в качестве логического идентификатора носителя (LMID). Сторона должна находиться в состоянии Доступно или Импорт. Эту функцию можно использовать для выделения определенной стороны или для импорта мультимедиа. Этот параметр является необязательным.

[out] lpMediaId

LMID выделенного носителя. Этот параметр имеет значение NULL , если среда не может быть выделена.

[in] dwOptions

Параметры. Этот параметр может иметь одно или несколько из следующих значений.

Значение Значение
NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE
 Запрещает отправку запроса оператора на новый носитель, если ни один из них не может быть выделен с указанными ограничениями.
NTMS_ALLOCATE_NEW
 Выделяет сторону указанного носителя, которая не может быть предоставлена совместно с логическим носителем другого приложения. Например, это значение резервирует вторую сторону двустороннего оптического носителя.
NTMS_ALLOCATE_NEXT
 Выделите следующую сторону ранее выделенного многостороннюю среду с помощью NTMS_ALLOCATE_NEW значения. Это позволяет одному приложению использовать обе стороны части двустороннего носителя и гарантировать, что приложение владеет всеми данными на физическом носителе.

Если все стороны среды уже выделены, запрос на выделение завершается ошибкой.

[in] dwTimeout

Максимальное время выделения указанного носителя в миллисекундах. Если этот параметр имеет значение INFINITE, время ожидания функции не будет истекает. Если этот параметр равен нулю, он будет ожидать носителя. Обратите внимание, что эта функция не помещает в очередь запрос на дополнительные носители, если параметр dwOptions указывает NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE.

[out] lpAllocateInformation

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

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

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

Значение Значение
ERROR_ACCESS_DENIED
 NTMS_CONTROL_ACCESS в пул носителей запрещено. Возможны и другие ошибки безопасности, но они указывают на ошибку подсистемы безопасности.

Windows XP: NTMS_MODIFY_ACCESS в пул мультимедиа запрещено.
ERROR_CANCELLED
 Оператор отменил запрос на новый носитель.
ERROR_DATABASE_FAILURE
 База данных недоступна или повреждена.
ERROR_DATABASE_FULL
 База данных заполнена.
ERROR_DEVICE_NOT_AVAILABLE
 Промежуточный ресурс недоступен; Например, пул свободных носителей недоступен.
ERROR_INVALID_HANDLE
 Дескриптор сеанса отсутствует или недопустим.
ERROR_INVALID_MEDIA
 Идентификатор секции или LMID был недопустимым при входе при использовании флага NTMS_ALLOCATE_NEXT.
ERROR_INVALID_MEDIA_POOL
 Недопустимый идентификатор пула носителей.
ERROR_INVALID_PARAMETER
 Отсутствует идентификатор носителя или пула носителей.
ERROR_MEDIA_OFFLINE
 Указанный носитель находится в автономном режиме и не может быть выделен.
ERROR_MEDIA_UNAVAILABLE
 Носители не выделены в течение указанного события времени ожидания.
ERROR_NOT_ENOUGH_MEMORY
 Во время обработки произошел сбой выделения ресурсов.
ERROR_SUCCESS
 Функция выполнена успешно.
ERROR_TIMEOUT
 Время ожидания истекло до того, как носитель стал доступен.

Комментарии

Функция AllocateNtmsMedia возвращает LMID. В зависимости от политики пула носителей, если указанный пул носителей не содержит доступных в Сети носителей, AllocateNtmsMedia может выполнить поиск указанного носителя в пуле свободных носителей для перемещения в указанный пул носителей. Сначала выделяется носитель из указанного пула носителей, а затем перемещается и выделяется свободный носитель.

Если пул носителей содержит любой доступный носитель в Сети, выделяется носитель из пула.

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

Windows Server 2003: Если носитель выделяется из свободного пула, требуется NTMS_USE_ACCESS в свободный пул и NTMS_CONTROL_ACCESS в целевой пул. Если свободный пул не является исходным пулом носителей, NTMS_CONTROL_ACCESS требуется как в исходном, так и в целевом пулах.

Если указано значение NTMS_ALLOCATE_NEXT, параметр lpMediaId должен указывать на допустимый идентификатор носителя во время вызова. В этом случае lpMediaId используется в качестве параметров IN и OUT. Выделяется следующая сторона многостороннюю среду, указанная lpMediaId , а новый идентификатор секции возвращается через lpMediaId (перезаписывает исходный идентификатор носителя).

Если указано NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE, возвращается ERROR_MEDIA_ НЕДОСТУПНО, если носитель недоступен.

При необходимости RSM создает запрос оператора на вставку нового или доступного носителя. Если время, указанное в параметре dwTimeout , прошло до обработки запроса оператора, RSM возвращает ERROR_TIMEOUT и удаляет запрос оператора.

Если пользователь отменяет запрос на выделение, RSM возвращает ERROR_CANCELLED.

Если пользователь указывает, что запрос оператора был удовлетворен, запрос удаляется, и RSM повторяет процесс.

Когда приложению требуется новый носитель, содержащий данные, пользователь или администратор помещает его в библиотеку или диск. RSM идентифицирует носитель и помещает его в пул импорта. Приложение выполняет поиск в пуле импорта, перемещает мультимедиа в пул приложений и выделяет его. Этот обычный процесс можно упростить и сделать атомарным с помощью одного вызова AllocateNtmsMedia. После поиска в пуле импорта приложение может вызвать AllocateNtmsMedia, передав идентификатор секции стороны в качестве значения параметра lpPartId . Затем RSM:

  1. перемещает среду в указанный пул носителей.
  2. изменяет состояние носителя на выделенный.
  3. возвращает идентификатор LMID.
Примечание Для двусторонних носителей обратная сторона остается в состоянии Импорт и недоступна для использования до импорта.
 

Требования

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

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

DeallocateNtmsMedia

Функции служб мультимедиа

NTMS_ALLOCATION_INFORMATION