AllocateNtmsMedia 函数 (ntmsapi.h)

项目
08/25/2023

[从 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
);

parameters

[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媒体的媒体池。其他安全错误也可能存在，但它们表示存在安全子系统错误。 Windowsxp：拒绝NTMS_MODIFY_ACCESS媒体的媒体池。
ERROR_CANCELLED	操作员取消了对新媒体的请求。
ERROR_DATABASE_FAILURE	数据库不可访问或已损坏。
ERROR_DATABASE_FULL	数据库已满。
ERROR_DEVICE_NOT_AVAILABLE	中间资源不可用;例如，免费媒体池不可用。
ERROR_INVALID_HANDLE	会话句柄缺失或无效。
ERROR_INVALID_MEDIA	使用 NTMS_ALLOCATE_NEXT 标志时，分区 ID 或 LMID 在输入时无效。
ERROR_INVALID_MEDIA_POOL	媒体池 ID 无效。
ERROR_INVALID_PARAMETER	缺少媒体或媒体池 ID。
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 参数必须在调用时指向有效的媒体 ID。在这种情况下， lpMediaId 用作 IN 和 OUT 参数。分配 由 lpMediaId 指定的多侧媒体的下一端，并通过 lpMediaId 返回新的分区 ID， (覆盖) 中传递的原始媒体 ID。

如果指定了NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE，如果没有可用的媒体，则返回ERROR_MEDIA_ UNAVAILABLE。

必要时，RSM 会生成操作员请求来插入新的或可用的媒体。如果在处理运算符请求之前经过 dwTimeout 参数中指定的时间，RSM 将返回ERROR_TIMEOUT并删除运算符请求。

如果用户取消分配请求，RSM 将返回ERROR_CANCELLED。

如果用户指示操作员请求已得到满足，则会删除该请求，并且 RSM 会重试该进程。

当应用程序需要包含数据的新媒体时，用户或管理员会将媒体放在库或驱动器中。 RSM 标识媒体并将其置于导入池中。应用程序搜索导入池，将媒体移动到其应用程序池并分配它。通过对 AllocateNtmsMedia 的单个调用，可以简化此例程并成为原子过程。搜索导入池后，应用程序可以调用 AllocateNtmsMedia，将端的分区 ID 作为 lpPartId 参数的值传递。 RSM 然后：

将介质移动到指定的媒体池。
将媒体的状态更改为已分配。
返回 LMID。

注意对于双面媒体，另一侧仍保持“导入”状态，在导入之前无法使用。

要求


最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	ntmsapi.h
Library	Ntmsapi.lib
DLL	Ntmsapi.dll

请参阅

DeallocateNtmsMedia

媒体服务函数

NTMS_ALLOCATION_INFORMATION

通过

AllocateNtmsMedia 函数 (ntmsapi.h)

语法

parameters

返回值

注解

要求

请参阅

反馈

其他资源