IWMDMStorageControl3::Insert3 メソッド (mswmdm.h)

[アーティクル]
08/25/2023

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;
}