IWMDMStorageControl3：：Insert3 方法 (mswmdm.h)
Insert3 方法會將內容放入記憶體旁/旁邊。 這個方法可讓應用程式明確指定所傳送物件的元數據和類型，藉此擴充 IWMDMStorageControl2：：Insert2 。
語法
HRESULT Insert3(
[in] UINT fuMode,
[in] UINT fuType,
[in] LPWSTR pwszFileSource,
[in] LPWSTR pwszFileDest,
[in] IWMDMOperation *pOperation,
[in] IWMDMProgress *pProgress,
[in] IWMDMMetaData *pMetaData,
[in] IUnknown *pUnknown,
[out] IWMDMStorage **ppNewObject
);
參數
[in] fuMode
用於 Insert3 作業的處理模式。 下表列出可在 fuMode 參數中指定的處理模式。 您必須只指定前兩種模式的其中一個、只指定其中一個 STORAGECONTROL 模式，以及其中一個 CONTENT 模式。 如果同時指定WMDM_MODE_BLOCK和WMDM_MODE_THREAD，則會使用區塊模式。 在此函式中指定WMDM_FILE_ATTR* 旗標比先呼叫此函式更有效率，然後在檔案建立或傳送之後，在檔案上設定這些屬性。
| 組合 | 模式 | Description |
|---|---|---|
| 完全是下列其中一項： | WMDM_MODE_BLOCK | 作業是使用區塊模式處理來執行。 呼叫在作業完成之前不會傳回。 |
| - | WMDM_MODE_THREAD | 作業是使用線程模式處理來執行。 呼叫會立即傳回，且作業會在背景線程中執行。 |
| 選擇性 | WMDM_MODE_QUERY | 系統會執行測試來判斷插入作業是否成功，但不會執行插入。 |
| 完全是下列其中一項： | WMDM_STORAGECONTROL_INSERTBEFORE | 物件會插入目標物件之前。 |
| - | WMDM_STORAGECONTROL_INSERTAFTER | 物件會插入目標對象之後。 |
| - | WMDM_STORAGECONTROL_INSERTINTO | 物件會插入目前的物件中。 只有在目前對像是資料夾時，才能運作。 |
| 選擇性 | WMDM_FILE_CREATE_OVERWRITE | 物件將會取代目標物件。 |
| 完全是下列其中一項： | WMDM_CONTENT_FILE | 正在插入的內容是檔案。 |
| - | WMDM_CONTENT_FOLDER | 正在插入的內容是資料夾。 這不會傳輸資料夾的內容。 |
| 選擇性 | WMDM_CONTENT_OPERATIONINTERFACE | 應用程式正在傳入 IWMDMOperation 介面，以控制數據傳輸。 |
| 零或多個： | WMDM_FILE_ATTR_READONLY | 記憶體應該設定為裝置上的唯讀。 |
| - | WMDM_FILE_ATTR_HIDDEN | 記憶體應該設定為在裝置上隱藏。 |
| - | WMDM_FILE_ATTR_SYSTEM | 存儲設備應設定為裝置上的系統。 |
| 選擇性 | WMDM_MODE_PROGRESS | 插入正在進行中。 |
| 選擇性的其中一項： | WMDM_MODE_TRANSFER_PROTECTED | 插入處於受保護的傳輸模式。 |
| - | WMDM_MODE_TRANSFER_UNPROTECTED | 插入處於未受保護的傳輸模式。 |
[in] fuType
下列其中一種類型，指定目前的記憶體。
| 值 | Description |
|---|---|
| WMDM_FILE_ATTR_FILE | 目前的記憶體是檔案。 |
| WMDM_FILE_ATTR_FOLDER | 目前的記憶體是資料夾。 |
[in] pwszFileSource
寬字元、 以 Null 結尾的字串指標，指出要在哪裡尋找插入作業的內容。 如果在 fuMode 中指定WMDM_CONTENT_OPERATIONINTERFACE，此參數必須是 NULL。 如果建立播放清單或相簿，此參數可以是 NULL 。
[in] pwszFileDest
裝置上的選擇性檔名。 如果未指定，而且應用程式會將IWMDMOperation指標傳遞給 pOperation，Windows Media 裝置管理員 會呼叫 IWMDMOperation：：GetObjectName 來要求目的地名稱。 如果未指定，且應用程式未使用 pOperation，則會使用源檔名稱和擴展名，而不需路徑) (。
[in] pOperation
IWMDMOperation 介面的選擇性指標，以控制內容傳送至媒體裝置。 如果指定， fuMode 必須包含WMDM_CONTENT_OPERATIONINTERFACE旗標。 如果在 fuMode 中指定了 WMDM_CONTENT_FILE 或 WMDM_CONTENT_FOLDER，此參數必須是 NULL。
[in] pProgress
IWMDMProgress 介面的選擇性指標，以將動作進度回報回應用程式。 此參數可以是 Null。
[in] pMetaData
元數據對象的選擇性指標。 呼叫 IWMDMStorage3：：CreateEmptyMetadataObject 來建立新的元數據物件。 此參數可讓應用程式指定元數據 (包括在裝置上建立對象期間在裝置上設定的格式) ，比之後設定元數據更有效率。 您必須設定由 g_wszWMDMFormatCode) 指定的檔案格式 (。 如果您在使用此方法時未指定檔案的格式代碼，則 MTP 裝置不會在其使用者介面中顯示檔案，而非 MTP 裝置的行為無法預期。
[in] pUnknown
要傳遞至安全內容提供者之任何自定義 COM 物件的選擇性 IUnknown 指標。 如果應用程式有足夠的安全內容提供者相關信息，這可讓您將自定義資訊傳遞至安全內容提供者。
[out] ppNewObject
將包含新內容的 IWMDMStorage 介面指標。 呼叫端必須在完成時釋放此介面。
傳回值
方法會傳回 HRESULT。 Windows Media 中的所有介面方法 裝置管理員 都可以傳回下列任何一種錯誤碼類別：
- 標準 COM 錯誤碼
- 轉換成 HRESULT 值的 Windows 錯誤碼
- Windows Media 裝置管理員 錯誤碼
備註
雖然您可以在將元數據傳送至裝置之後，在記憶體上設定元數據，但在此方法的 pMetaData 參數中設定這項資訊會更有效率。 這麼做會將其他資訊提供給裝置，讓裝置能夠適當地 (傳輸及處理檔案，例如將它儲存在正確的位置) 或顯示有用的資訊 (，例如圖片的使用者寫入描述) 。
若要設定 Windows 可攜式裝置 (WPD) 裝置的屬性，應用程式會建立 IPortableDeviceValues 物件，並將每個屬性設定為此集合。 然後，應用程式會將集合串行化為二進位大型物件， (BLOB) 。 串行化數據之後，應用程式會使用 g_wszWPDPassthroughPropertyValues 元數據常數，將它新增至 pMetadata 自變數所參考的 IWMDMMetaData。
如果指定WMDM_MODE_THREAD旗標，您應該呼叫 IWMDMProgress2：：End2 或 IWMDMProgress3：：End3 來取得完成狀態。 這些方法可確保作業已完成，也會傳回具有成功或失敗資訊的 HRESULT。
如果應用程式使用 WMDM_MODE_THREAD 並傳遞非 NullpProgress 參數，應用程式必須確保 pProgress 所屬的物件在讀取作業完成之前不會終結，因為 Windows Media 裝置管理員 會將進度通知傳送至此物件。 只有在收到結束通知之後，才能終結此物件。 若無法這麼做，將會導致存取違規。
建立播放清單或其他參考物件時，要「插入」的對象實際上不包含任何數據，但只會儲存在裝置上作為其他物件的元數據參考群組， (例如音樂檔案) 。 在播放清單上建立這類「抽象」物件，如在 裝置上建立播放清單中所述。
範例
下列 C++ 函式會將檔案傳送至裝置。 在傳輸過程中，它必須將元數據新增至記憶體，以指定新的記憶體類型。
HRESULT mySendFile(LPCWSTR pwszFileName, IWMDMStorage* pStorage, IWMDMOperation* pOperation)
{
HRESULT hr = S_OK;
// A dummy loop to handle unrecoverable errors. When we hit an error we
// can't handle or don't like, we just use a 'break' statement.
// The custom BREAK_HR macro checks for failed HRESULT values and does this.
do
{
if (pwszFileName == NULL || pStorage == NULL)
{
BREAK_HR(E_POINTER,"","Bad pointer passed in.");
return E_POINTER;
}
// Make sure the destination is a folder.
DWORD attributes = 0;
_WAVEFORMATEX format;
hr = pStorage->GetAttributes(&attributes, &format);
if (!(attributes | WMDM_FILE_ATTR_FOLDER))
{
BREAK_HR(E_FAIL, "", "Storage submitted to mySendFile is not a folder.");
return E_FAIL;
}
// Transcode the file
hr = myTranscodeMethod(pwszFileName);
BREAK_HR(hr, "Couldn't transcode the file in mySendFile.", "Transcoded the file in mySendFile.");
//
// Let's set some metadata in the storage.
//
CComPtr<IWMDMStorage3> pStorage3;
hr = pStorage->QueryInterface(__uuidof(IWMDMStorage3), (void**)(&pStorage3));
BREAK_HR(hr, "Got an IWMDMStorage3 interface in mySendFile.","Couldn't get an IWMDMStorage3 in mySendFile.");
// First create the IWMDMMetaData interface.
IWMDMMetaData* pMetadata;
hr = pStorage3->CreateEmptyMetadataObject(&pMetadata);
BREAK_HR(hr,"Created an IWMDMMetaData interface in mySendFile.","Couldn't create an IWMDMMetaData interface in mySendFile.");
//
// Set the file format.
//
WMDM_FORMATCODE fileFormat = myGetWMDM_FORMATCODE(pwszFileName);
hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMFormatCode, (BYTE*)&fileFormat, sizeof(WMDM_TYPE_DWORD));
//
// Get the proper interface and transfer the file.
//
CComPtr<IWMDMStorageControl3> pStgCtl3;
CComPtr<IWMDMStorage> pNewStorage;
hr = pStorage->QueryInterface(__uuidof(IWMDMStorageControl3),(void**)(&pStgCtl3));
// Get the simple file name to use for the destination file.
wstring destFile = pwszFileName;
destFile = destFile.substr(destFile.find_last_of(L"\\") + 1);
// Get a progress indicator.
CComQIPtr<IWMDMProgress> pProgress(this);
// Set the flags for the operation.
UINT flags = WMDM_MODE_BLOCK | // Synchronous call.
WMDM_STORAGECONTROL_INSERTINTO | // Insert it into the destination folder.
WMDM_CONTENT_FILE | // We're inserting a file.
WMDM_FILE_CREATE_OVERWRITE; // Overwrite existing files.
if (pOperation != NULL)
flags |= WMDM_CONTENT_OPERATIONINTERFACE;
// Send the file and metadata.
hr = pStgCtl3->Insert3(
flags,
WMDM_FILE_ATTR_FOLDER, // The current storage is a folder.
const_cast<WCHAR*>(pwszFileName), // Source file.
NULL, // Destination file name.
pOperation, // Null to allow Windows Media Device Manager to read
// the file; non-null to present raw data bytes to
// Windows Media Device Manager.
pProgress, // Interface to send simple progress notifications.
pMetadata, // IWMDMMetaData interface previously created and filled.
NULL,
&pNewStorage);
if (FAILED(hr))
m_pLogger->LogDword(WMDM_LOG_SEV_ERROR, NULL, "Error calling Insert3 in mySendFile: %lX", hr);
BREAK_HR(hr, "Wrote a file to the device in mySendFile", "Couldn't write to the device in mySendFile.");
} while (FALSE); // End of dummy loop
return hr;
}
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | Windows |
| 標頭 | mswmdm.h |
| 程式庫 | Mssachlp.lib |