共用方式為

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媒體的媒體集區遭到拒絕。 也可能發生其他安全性錯誤，但會指出安全性子系統錯誤。

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 旗標時，資料分割識別碼或 LMID 在輸入時無效。
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_如果沒有媒體可用，則會傳回 UNAVAILABLE。

必要時，RSM 會產生操作員要求，以插入新的或可用的媒體。 如果在處理運算子要求之前， dwTimeout 參數中指定的時間經過，RSM 會傳回ERROR_TIMEOUT並刪除運算子要求。

如果使用者取消配置要求，RSM 會傳回ERROR_CANCELLED。

如果使用者指出已滿足操作員要求，則會刪除要求，RSM 會重試此程式。

當應用程式需要包含資料的新媒體時，使用者或系統管理員會將媒體放在媒體櫃或磁片磁碟機中。 RSM 會識別媒體，並將其放在匯入集區中。 應用程式會搜尋匯入集區、將媒體移至其應用程式集區，並配置它。 此常式程式可以透過單一呼叫 AllocateNtmsMedia來簡化和不可部分完成。 搜尋匯入集區之後，應用程式可以呼叫 AllocateNtmsMedia，並將側邊的資料分割識別碼當做 lpPartId 參數的值傳遞。 RSM 然後：

  1. 會將媒體移至指定的媒體集區。
  2. 將媒體的狀態變更為已配置。
  3. 會傳回 LMID。
注意 針對雙面媒體，翻轉端會維持匯入狀態，且在匯入之前無法使用。
 

需求

   
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限桌面應用程式]
目標平台 Windows
標頭 ntmsapi.h
程式庫 Ntmsapi.lib
Dll Ntmsapi.dll

另請參閱

DeallocateNtmsMedia

媒體服務函式

NTMS_ALLOCATION_INFORMATION