iWMDMStorageControl：：Insert 方法 (mswmdm.h)

發行項
03/05/2024

Insert 方法會將內容放入裝置上的記憶體。

語法

HRESULT Insert(
  [in]  UINT           fuMode,
  [in]  LPWSTR         pwszFile,
  [in]  IWMDMOperation *pOperation,
  [in]  IWMDMProgress  *pProgress,
  [out] IWMDMStorage   **ppNewObject
);

參數

[in] fuMode

下列值的位 OR 。下表列出可在 fuMode 參數中指定的處理模式。您必須只指定前兩種模式的其中一種、剛好其中一個 STORAGECONTROL 模式，以及其中一個 CONTENT 模式。如果同時指定WMDM_MODE_BLOCK和WMDM_MODE_THREAD，則會使用區塊模式。

組合	模式	Description
剛好是下列其中一項：	WMDM_MODE_BLOCK	作業是使用區塊模式處理來執行。在作業完成之前，呼叫將不會傳回。
	WMDM_MODE_THREAD	作業是使用線程模式處理來執行。呼叫會立即傳回，並在背景線程中執行作業。
剛好是下列其中一項：	WMDM_STORAGECONTROL_INSERTBEFORE	物件會插入目前物件之前。
	WMDM_STORAGECONTROL_INSERTAFTER	物件會在目前的物件後面插入。
	WMDM_STORAGECONTROL_INSERTINTO	物件會插入至目前的物件。只有在目前對像是資料夾時，這才能運作。
剛好是下列其中一項：	WMDM_CONTENT_FILE	正在插入的內容是檔案。
	WMDM_CONTENT_FOLDER	正在插入的內容是資料夾。這不會傳送資料夾的內容。
	WMDM_CONTENT_OPERATIONINTERFACE	正在插入的內容是作業介面。內容的數據應該寫入應用程式實作的IWMDMOperation 介面。
零或多個：	WMDM_FILE_CREATE_OVERWRITE	物件將會取代目前的物件。
	WMDM_MODE_QUERY	系統會執行測試來判斷插入作業是否成功，但不會執行插入。
	WMDM_MODE_PROGRESS	方法應該會透過 pProgress 傳回進度通知。
零或其中一個：	WMDM_MODE_TRANSFER_PROTECTED	插入處於受保護的傳輸模式。
	WMDM_MODE_TRANSFER_UNPROTECTED	插入處於未受保護的傳輸模式。

[in] pwszFile

寬字元 Null 終止字串的指標，指出要在哪裡尋找插入作業的內容。如果在 fuMode 中指定了WMDM_CONTENT_OPERATIONINTERFACE，此參數必須是 NULL。

[in] pOperation

IWMDMOperation 介面的選擇性指標，用來控制將內容傳輸到媒體裝置。如果指定， fuMode 必須包含WMDM_CONTENT_OPERATIONINTERFACE旗標。如果在 fuMode 中指定了WMDM_CONTENT_FILE或WMDM_CONTENT_FOLDER，此參數必須為 NULL。

[in] pProgress

Windows Media 所要使用的 IWMDMProgress 介面選擇性指標，裝置管理員將進度回報回應用程式。如果使用此功能， fuMode 應該包含WMDM_MODE_PROGRESS。

[out] ppNewObject

將包含新內容的 IWMDMStorage 介面指標。呼叫端必須在完成時釋放這個介面。

傳回值

方法會傳回 HRESULT。 Windows Media 中的所有介面方法裝置管理員都可以傳回下列任何錯誤碼類別：

標準 COM 錯誤碼
轉換成 HRESULT 值的 Windows 錯誤碼
Windows Media 裝置管理員錯誤碼

如需可能錯誤碼的廣泛清單，請參閱錯誤碼。

備註

如果裝置支援 IWMDMStorageControl3：：Insert3，這是要使用的慣用方法。

如果 pOperation 為 NULL () ，儲存在裝置上的物件名稱和擴展名會與來源檔案的名稱和擴展名相同。

如果指定WMDM_MODE_THREAD旗標，您應該呼叫 IWMDMProgress2：：End2 或 IWMDMProgress3：：End3 來取得完成狀態。這些方法可確保作業已完成，也會傳回具有成功或失敗資訊的 HRESULT。

Insert 方法不保證裝置支援已排序的檔案插入，但會提供旗標WMDM_STORAGECONTROL_INSERTBEFORE，並WMDM_STORAGECONTROL_INSERTAFTER。例如，如果檔系統不支援排序 (，FAT32) ，WMDM_STORAGECONTROL_INSERTBEFORE和WMDM_STORAGECONTROL_INSERTAFTER只會將新的儲存物件插入與文件系統階層中目前物件相同的層級。

如果應用程式使用 WMDM_MODE_THREAD 並傳遞非 NullpProgress 參數，則應用程式必須確定 pProgress 所屬的物件在插入作業完成之前不會終結，因為 Windows Media 裝置管理員會將進度通知傳送至此物件。只有在收到 End 通知之後，才能終結此物件。若無法這麼做，將會導致存取違規。