ホーム › Media.DeviceManager › IWMDMStorageControl

IWMDMStorageControl

COM

IID1dcb3a08-33ed-11d3-8470-00c04f79dbc0継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IWMDMStorageControl インターフェースは、ストレージ内、デバイス内、またはデバイスとコンピューターの間でファイルを挿入、削除、移動するために使用します。

メソッド 5

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT Insert(DWORD fuMode, LPWSTR pwszFile, IWMDMOperation* pOperation, IWMDMProgress* pProgress, IWMDMStorage** ppNewObject)

Insert メソッドは、デバイス上のストレージにコンテンツを格納します。

fuMode

DWORD

次の値のビットごとの OR。次の表は、fuMode パラメーターに指定できる処理モードの一覧です。最初の 2 つのモードから 1 つ、STORAGECONTROL モードから 1 つ、CONTENT モードから 1 つを、それぞれ厳密に 1 つずつ指定する必要があります。WMDM_MODE_BLOCK と WMDM_MODE_THREAD の両方を指定した場合は、ブロックモードが使用されます。

組み合わせ	モード	説明
次のうち厳密に 1 つ:	WMDM_MODE_BLOCK	操作はブロックモード処理で実行されます。操作が完了するまで呼び出しは戻りません。
	WMDM_MODE_THREAD	操作はスレッドモード処理で実行されます。呼び出しは直ちに戻り、操作はバックグラウンドスレッドで実行されます。
次のうち厳密に 1 つ:	WMDM_STORAGECONTROL_INSERTBEFORE	オブジェクトは現在のオブジェクトの前に挿入されます。
	WMDM_STORAGECONTROL_INSERTAFTER	オブジェクトは現在のオブジェクトの後に挿入されます。
	WMDM_STORAGECONTROL_INSERTINTO	オブジェクトは現在のオブジェクトの中に挿入されます。これは現在のオブジェクトがフォルダーである場合にのみ機能します。
次のうち厳密に 1 つ:	WMDM_CONTENT_FILE	挿入されるコンテンツはファイルです。
	WMDM_CONTENT_FOLDER	挿入されるコンテンツはフォルダーです。フォルダーの中身は転送されません。
	WMDM_CONTENT_OPERATIONINTERFACE	挿入されるコンテンツは操作インターフェースです。コンテンツのデータは、アプリケーションが実装した IWMDMOperation インターフェースに書き込む必要があります。
次のうち 0 個以上:	WMDM_FILE_CREATE_OVERWRITE	オブジェクトは現在のオブジェクトを置き換えます。
	WMDM_MODE_QUERY	挿入操作が成功し得るかどうかを判定するテストが行われますが、挿入自体は実行されません。
	WMDM_MODE_PROGRESS	メソッドは pProgress を通じて進行状況の通知を返します。
次のうち 0 個または 1 つ:	WMDM_MODE_TRANSFER_PROTECTED	挿入は保護された転送モードで行われます。
	WMDM_MODE_TRANSFER_UNPROTECTED	挿入は保護されていない転送モードで行われます。

pwszFile

LPWSTR

inoptional

挿入操作の対象となるコンテンツの場所を示す、ワイド文字の null 終端文字列へのポインター。fuMode に WMDM_CONTENT_OPERATIONINTERFACE を指定した場合、このパラメーターは NULL にする必要があります。

pOperation

IWMDMOperation*

inoptional

メディアデバイスへのコンテンツ転送を制御する IWMDMOperation インターフェースへの省略可能なポインター。指定する場合、fuMode に WMDM_CONTENT_OPERATIONINTERFACE フラグを含める必要があります。fuMode に WMDM_CONTENT_FILE または WMDM_CONTENT_FOLDER を指定した場合、このパラメーターは NULL にする必要があります。

pProgress

IWMDMProgress*

inoptional

Windows Media Device Manager がアプリケーションに進行状況を報告するために使用する IWMDMProgress インターフェースへの省略可能なポインター。これを使用する場合は、fuMode に WMDM_MODE_PROGRESS を含める必要があります。

ppNewObject

IWMDMStorage**

out

新しいコンテンツを格納する IWMDMStorage インターフェースへのポインター。呼び出し元は、使用し終わったらこのインターフェースを解放する必要があります。

戻り値

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェースメソッドは、次の種類のエラーコードを返す可能性があります。

標準の COM エラーコード
HRESULT 値に変換された Windows エラーコード
Windows Media Device Manager のエラーコード

発生し得るエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

デバイスが 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 を使用し、null 以外の pProgress パラメーターを渡す場合、Windows Media Device Manager がこのオブジェクトに対して進行状況の通知を送信するため、挿入操作が完了するまで pProgress が属するオブジェクトが破棄されないようにする必要があります。このオブジェクトを破棄できるのは、End 通知を受け取った後だけです。これを守らないとアクセス違反が発生します。

vtbl 4 HRESULT Delete(DWORD fuMode, IWMDMProgress* pProgress)

Delete メソッドは、このストレージを完全に削除します。

fuMode

DWORD

次のフラグのうち 1 つまたは 2 つを、ビットごとの OR で組み合わせた値。最初の 2 つのモードから厳密に 1 つを指定します。3 番目のモードは省略可能です。

モード	説明
WMDM_MODE_BLOCK	操作はブロックモード (同期) 処理で実行されます。操作が完了するまで呼び出しは戻りません。
WMDM_MODE_THREAD	操作はスレッドモード (非同期) 処理で実行されます。呼び出しは直ちに戻り、操作はバックグラウンドスレッドで実行されます。
WMDM_MODE_RECURSIVE	ストレージオブジェクトがフォルダーの場合、そのフォルダーと中身、およびすべてのサブフォルダーとその中身が削除されます。

pProgress

IWMDMProgress*

inoptional

Windows Media Device Manager がアプリケーションに進行状況を報告するために使用する IWMDMProgress インターフェースへの省略可能なポインター。

戻り値

標準の COM エラーコード
HRESULT 値に変換された Windows エラーコード
Windows Media Device Manager のエラーコード

発生し得るエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

Delete 操作が完了すると、削除されたオブジェクトへのすべての参照は無効になります。アプリケーションは、これらのインターフェース、およびそのオブジェクトに関連付けられたその他のインターフェースやリソースを解放する必要があります。

アプリケーションが WMDM_MODE_THREAD を使用し、null 以外の pProgress パラメーターを渡す場合、Windows Media Device Manager がこのオブジェクトに対して進行状況の通知を送信するため、削除操作が完了するまで pProgress が属するオブジェクトが破棄されないようにする必要があります。このオブジェクトを破棄できるのは、End 通知を受け取った後だけです。これを守らないとアクセス違反が発生します。

vtbl 5 HRESULT Rename(DWORD fuMode, LPWSTR pwszNewName, IWMDMProgress* pProgress)

Rename メソッドは、現在のストレージの名前を変更します。

fuMode

DWORD

Rename 操作に使用する処理モード。次の 2 つのモードから厳密に 1 つを指定します。両方のモードを指定した場合は、ブロックモードが使用されます。

モード	説明
WMDM_MODE_BLOCK	操作はブロックモード処理で実行されます。操作が完了するまで呼び出しは戻りません。
WMDM_MODE_THREAD	操作はスレッドモード処理で実行されます。呼び出しは直ちに戻り、操作はバックグラウンドスレッドで実行されます。

pwszNewName

LPWSTR

新しい名前を指定する、ワイド文字の null 終端文字列へのポインター。

pProgress

IWMDMProgress*

inoptional

処理の進行状況を追跡するためにアプリケーションが実装した IWMDMProgress インターフェースへの省略可能なポインター。

戻り値

標準の COM エラーコード
HRESULT 値に変換された Windows エラーコード
Windows Media Device Manager のエラーコード

発生し得るエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

アプリケーションが WMDM_MODE_THREAD を使用し、null 以外の pProgress パラメーターを渡す場合、Windows Media Device Manager がこのオブジェクトに対して進行状況の通知を送信するため、読み取り操作が完了するまで pProgress が属するオブジェクトが破棄されないようにする必要があります。このオブジェクトを破棄できるのは、End 通知を受け取った後だけです。これを守らないとアクセス違反が発生します。

vtbl 6 HRESULT Read(DWORD fuMode, LPWSTR pwszFile, IWMDMProgress* pProgress, IWMDMOperation* pOperation)

Read メソッドは、現在のストレージをコンピューターにコピーします。

fuMode

DWORD

Read 操作に使用する処理モード。次の表は、fuMode パラメーターに指定できる処理モードの一覧です。最初の 2 つのモードから厳密に 1 つ、および最後の 3 つ (WMDM_CONTENT) のモードから厳密に 1 つを指定する必要があります。WMDM_MODE_BLOCK と WMDM_MODE_THREAD の両方を指定した場合は、ブロックモードが使用されます。

モード	説明
WMDM_MODE_BLOCK	操作はブロックモード処理で実行されます。操作が完了するまで呼び出しは戻りません。
WMDM_MODE_THREAD	操作はスレッドモード処理で実行されます。呼び出しは直ちに戻り、操作はバックグラウンドスレッドで実行されます。
WMDM_CONTENT_FILE	呼び出し元は、ポータブルデバイス上のファイルをハードディスク上のファイルに読み取るよう Windows Media Device Manager に要求します。呼び出し元は、pwszFileName パラメーターにファイルの完全なパスと名前を指定する必要があります。
WMDM_CONTENT_FOLDER	呼び出し元は、指定したフォルダー、その中身、およびすべてのサブフォルダーの中身を、ポータブルデバイスからハードディスクに読み取るよう Windows Media Device Manager に要求します。呼び出し元は、pwszFileName パラメーターにハードディスク上の対象ディレクトリの完全なパスを指定する必要があります。これは現在、Microsoft が提供するサービスプロバイダーではサポートされていません。
WMDM_CONTENT_OPERATIONINTERFACE	ファイル名を渡す代わりに、アプリケーションが実装した IWMDMOperation インターフェースを使用してデータを読み取ります。

pwszFile

LPWSTR

inoptional

ポータブルデバイスのコンテンツのコピー先となる、コンピューター上の完全修飾ファイル名へのポインター。ファイル名には拡張子を含める必要があります。デバイス上の現在のストレージの拡張子は使用されません。fuMode に WMDM_CONTENT_OPERATIONINTERFACE を指定した場合、このパラメーターは無視されます。

pProgress

IWMDMProgress*

inoptional

実行中の操作の進行状況を追跡するためにアプリケーションが実装した IWMDMProgress インターフェースへの省略可能なポインター。

pOperation

IWMDMOperation*

inoptional

メディアデバイスからのコンテンツ転送を強化するために使用する省略可能なメソッド群である IWMDMOperation インターフェースへの省略可能なポインター。fuMode に WMDM_CONTENT_FILE または WMDM_CONTENT_FOLDER を指定した場合、このパラメーターは NULL にする必要があります。

戻り値

標準の COM エラーコード
HRESULT 値に変換された Windows エラーコード
Windows Media Device Manager のエラーコード

発生し得るエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

このメソッドは、pwszFilename で指定された既存のファイルを自動的に上書きします。次の場合でも成功することがあります

アプリケーションが WMDM_MODE_THREAD を使用し、null 以外の pProgress パラメーターを渡す場合、Windows Media Device Manager がこのオブジェクトに対して進行状況の通知を送信するため、読み取り操作が完了するまで pProgress が属するオブジェクトが破棄されないようにする必要があります。このオブジェクトを破棄できるのは、End 通知を受け取った後だけです。これを守らないとアクセス違反が発生します。

vtbl 7 HRESULT Move(DWORD fuMode, IWMDMStorage* pTargetObject, IWMDMProgress* pProgress)

Move メソッドは、現在のストレージをデバイス上の新しい場所に移動します。

fuMode

DWORD

Move 操作を呼び出す処理モードと、実行する移動の種類。次の 2 つのモードから厳密に 1 つを指定します。両方のモードを指定した場合は、ブロックモードが使用されます。

モード	説明
WMDM_MODE_BLOCK	操作はブロックモード処理で実行されます。操作が完了するまで呼び出しは戻りません。
WMDM_MODE_THREAD	操作はスレッドモード処理で実行されます。呼び出しは直ちに戻り、操作はバックグラウンドスレッドで実行されます。

次の表は、オブジェクトの移動先を示すフラグの一覧です。この表の値 1 つを、前述のモードの表の値 1 つとビットごとの OR で組み合わせます。

フラグ	説明
WMDM_STORAGECONTROL_INSERTBEFORE	オブジェクトは対象オブジェクトの前に挿入されます。
WMDM_STORAGECONTROL_INSERTINTO	オブジェクトは対象オブジェクトの中に挿入されます。
WMDM_STORAGECONTROL_INSERTAFTER	オブジェクトは対象オブジェクトの後に挿入されます。

pTargetObject

IWMDMStorage*

inoptional

現在のオブジェクトを配置する位置の基準となる、前または後ろのオブジェクトへのポインター。

pProgress

IWMDMProgress*

inoptional

実行中の操作の進行状況を追跡するためにアプリケーションが実装した IWMDMProgress インターフェースへの省略可能なポインター。

戻り値

標準の COM エラーコード
HRESULT 値に変換された Windows エラーコード
Windows Media Device Manager のエラーコード

発生し得るエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

ファイルまたはディレクトリを移動できるのは、同じルートストレージ内に限られます。

アプリケーションが WMDM_MODE_THREAD を使用し、null 以外の pProgress パラメーターを渡す場合、Windows Media Device Manager がこのオブジェクトに対して進行状況の通知を送信するため、移動操作が完了するまで pProgress が属するオブジェクトが破棄されないようにする必要があります。このオブジェクトを破棄できるのは、End 通知を受け取った後だけです。これを守らないとアクセス違反が発生します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

#define global IID_IWMDMStorageControl "{1DCB3A08-33ED-11D3-8470-00C04F79DBC0}"
#usecom global IWMDMStorageControl IID_IWMDMStorageControl "{}"
#comfunc global IWMDMStorageControl_Insert  3 int,wstr,sptr,sptr,sptr
#comfunc global IWMDMStorageControl_Delete  4 int,sptr
#comfunc global IWMDMStorageControl_Rename  5 int,wstr,sptr
#comfunc global IWMDMStorageControl_Read    6 int,wstr,sptr,sptr
#comfunc global IWMDMStorageControl_Move    7 int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。