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 パラメーターで指定できる処理モードを示します。 最初の 2 つのモードのうちの 1 つ、STORAGECONTROL モードの 1 つ、および CONTENT モードの 1 つを正確に指定する必要があります。 WMDM_MODE_BLOCKとWMDM_MODE_THREADの両方が指定されている場合は、ブロック モードが使用されます。 この関数でWMDM_FILE_ATTR* フラグを指定する方が、最初にこの関数を呼び出してから、作成または送信後にファイルにこれらの属性を設定するよりも効率的です。
| 組み合わせ | モード | 説明 |
|---|---|---|
| 次のいずれかです。 | 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 インターフェイスを渡しています。 |
| 次の 0 個以上: | WMDM_FILE_ATTR_READONLY | ストレージは、デバイスで読み取り専用に設定する必要があります。 |
| - | WMDM_FILE_ATTR_HIDDEN | ストレージは、デバイスで非表示に設定する必要があります。 |
| - | WMDM_FILE_ATTR_SYSTEM | ストレージは、デバイス上のシステムに設定する必要があります。 |
| オプション | WMDM_MODE_PROGRESS | 挿入が進行中です。 |
| オプションの 1 つ: | WMDM_MODE_TRANSFER_PROTECTED | 挿入は保護転送モードです。 |
| - | WMDM_MODE_TRANSFER_UNPROTECTED | 挿入は保護されていない転送モードです。 |
[in] fuType
現在のストレージを指定する、次のいずれかの種類。
| 値 | 説明 |
|---|---|
| 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を使用し、null 以外の pProgress パラメーターを渡す場合、Windows Media デバイス マネージャーはこのオブジェクトに進行状況通知を送信するため、pProgress が属するオブジェクトが読み取り操作が完了するまで破棄されないようにする必要があります。 このオブジェクトは、終了通知を受信した後にのみ破棄できます。 これを行わないと、アクセス違反が発生します。
プレイリストやその他の参照オブジェクトを作成する場合、"挿入" されるオブジェクトには実際にはデータは含まれないが、単に他のオブジェクト (音楽ファイルなど) へのメタデータ参照のグループとしてデバイスに格納されます。 このような "抽象" オブジェクトをプレイリストに作成する方法については、「 デバイスでのプレイリストの作成」を参照してください。
例
次の 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 |
| Library | Mssachlp.lib |