ホーム › Media.DeviceManager › IMDSPStorage4

IMDSPStorage4

COM

IID3133b2c4-515c-481b-b1ce-39327ecb4f74継承元IMDSPStorage3自前メソッド開始 vtbl19

公式ドキュメント

IMDSPStorage4 インターフェイスは、仮想ストレージ(プレイリストやアルバムなど)とメタデータをサポートするために IMDSPStorage3 を拡張します。注意サービスプロバイダーがデバイスパラメーター UseExtendedWmdm を値 1 で追加していない限り、Windows Media Device Manager はこのインターフェイスを呼び出しません。詳細については「Device Parameters」を参照してください。。

メソッド 6

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

vtbl 19 HRESULT SetReferences(DWORD dwRefs, IMDSPStorage** ppISPStorage)

SetReferences メソッドは、参照を保持するストレージ(プレイリストやアルバムなど)に含まれる参照を設定します。このストレージに既に存在していた参照は上書きされます。

dwRefs	DWORD	in	渡された配列に含まれる IMDSPStorage インターフェイスポインターの数。0 も有効な値であり、その場合ストレージは参照を 1 つも持たない状態にリセットされます。このときストレージ自体は削除されません。
ppISPStorage	IMDSPStorage**	inoptional	ストレージ内の参照を設定するために使用する IMDSPStorage インターフェイスポインターの配列へのポインター。参照の順序は、この配列内の対応する IWMDMStorage インターフェイスポインターの順序と一致します。dwRefs も 0 の場合は NULL も有効な値です。

戻り値

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

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

返される可能性のあるエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

ppIMDSPStorage 配列には、有効な IMDSPStorage オブジェクトであればどれでも格納できます。これには、フォルダーや、それ自体が参照を含むストレージ(たとえばプレイリストのプレイリストを作成する場合)も含まれます。

サービスプロバイダーは、デバイスのサポートレベル(プレイリストや入れ子のプレイリストをサポートするかどうか)に応じて、このメソッドを適切に処理する必要があります。渡された参照配列に必要なサポートレベルをデバイスが備えていない場合、サービスプロバイダーは WMDM_E_NOTSUPPORTED を返す必要があります。

参照に削除済みのストレージが含まれている場合は、WMDM_E_INTERFACEDEAD を返す必要があります。

SetReferences メソッドは、全消去して読み込み直す(wipe-and-load)モデルに従います。渡される参照は完全な一式であり、ストレージオブジェクト上の既存の参照を完全に置き換える必要があります。

vtbl 20 HRESULT GetReferences(DWORD* pdwRefs, IMDSPStorage*** pppISPStorage)

GetReferences メソッドは、プレイリストやアルバムのオブジェクトを表すような関連付けストレージに含まれる参照を構成する、IMDSPStorage オブジェクトへのポインターの配列を返します。

pdwRefs	DWORD*	out	pppIWMDMStorage で返される IWMDMStorage インターフェイスポインターの数へのポインター。
pppISPStorage	IMDSPStorage***	out	ストレージ上の参照を表す IWMDMStorage インターフェイスポインターの配列へのポインターへのポインター。このような参照は、たとえばプレイリストやアルバム内の項目を表すことができます。参照の順序はこの配列内の順序と一致します。この配列のメモリはサービスプロバイダーが割り当てる必要があります。

戻り値

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

返される可能性のあるエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

Windows Media Device Manager は、プレイリストやアルバムなどの関連付けストレージ上の参照を取得するために、このメソッドを使用します。

ストレージがデバイスから削除済みの項目への参照を 1 つ以上保持している場合、SP は返す参照にそれらを含めないでください。SP は S_FALSE を返すことでこの状況を示す必要があります。アプリケーションは、ここで返された有効な参照を使用して、関連付けストレージオブジェクトを更新することを選択できます。SP 自身が参照を更新することもできます。

参照の数が 0 の場合、サービスプロバイダーは要素数 0 の参照配列を返す必要があります。

vtbl 21 HRESULT CreateStorageWithMetadata(DWORD dwAttributes, LPWSTR pwszName, IWMDMMetaData* pMetadata, ULONGLONG qwFileSize, IMDSPStorage** ppNewStorage)

CreateStorageWithMetadata メソッドは、指定されたメタデータを適用して新しいストレージを作成し、新しく作成されたストレージの IMDSPStorage インターフェイスへのポインターを返します。

dwAttributes

DWORD

新しいストレージの属性を格納する DWORD。次の表に、使用できるストレージ属性を示します。

属性	説明
WMDM_STORAGECONTROL_INSERTBEFORE	新しいストレージオブジェクトは、対象オブジェクトの前に作成されます。
WMDM_STORAGECONTROL_INSERTAFTER	新しいストレージオブジェクトは、対象オブジェクトの後に作成されます。
WMDM_STORAGECONTROL_INSERTINTO	新しいストレージオブジェクトは、対象オブジェクトのフォルダー内に作成されます。
WMDM_STORAGECONTROL_OVERWRITE	同じ名前のストレージが既に存在する場合は、それが破棄されて新しいストレージが作成されます。
WMDM_STORAGE_ATTR_FILESYSTEM	このオブジェクトは最上位のストレージメディアです(ストレージカードやその他のオンボードストレージなど)。
WMDM_STORAGE_ATTR_REMOVABLE	このストレージメディアはリムーバブルです。
WMDM_STORAGE_ATTR_CANEDITMETADATA	このストレージはメタデータを編集できます。
WMDM_STORAGE_ATTR_FOLDERS	このストレージメディアはフォルダーとファイル階層をサポートします。
WMDM_FILE_ATTR_FOLDER	これはストレージメディア上のフォルダーです。
WMDM_FILE_ATTR_LINK	これは複数のファイルの間に関連付けを作成するリンクです。
WMDM_FILE_ATTR_FILE	これはストレージメディア上のファイルです。
WMDM_FILE_ATTR_AUDIO	このファイルはオーディオデータです。
WMDM_FILE_ATTR_DATA	このファイルはオーディオ以外のデータです。
WMDM_FILE_ATTR_CANPLAY	このオーディオファイルはデバイスで再生できます。
WMDM_FILE_ATTR_CANDELETE	このファイルは削除できます。
WMDM_FILE_ATTR_CANMOVE	このファイルまたはフォルダーはストレージメディア上で移動できます。
WMDM_FILE_ATTR_CANRENAME	このファイルまたはフォルダーは名前を変更できます。
WMDM_FILE_ATTR_CANREAD	このファイルはホストコンピューターから読み取ることができます。
WMDM_FILE_ATTR_MUSIC	このオーディオファイルは音楽です。
WMDM_FILE_ATTR_PLAYLIST	これはプレイリストオブジェクトです。
WMDM_FILE_ATTR_VIDEO	このファイルはビデオデータを含みます。
WMDM_FILE_ATTR_HIDDEN	このファイルはファイルシステム上で隠しファイルになっています。
WMDM_FILE_ATTR_SYSTEM	これはシステムファイルです。
WMDM_FILE_ATTR_READONLY	これは読み取り専用ファイルです。
WMDM_STORAGE_IS_DEFAULT	このストレージは、新しいメディアを配置する既定のストレージです。
WMDM_STORAGE_CONTAINS_DEFAULT	このストレージは、新しいメディアを配置する既定のストレージを含んでいます。

pwszName

LPWSTR

新しいストレージの名前を格納する、ワイド文字の null 終端文字列へのポインター。

pMetadata

IWMDMMetaData*

inoptional

IWMDMMetaData インターフェイスへのポインター。

qwFileSize

ULONGLONG

ファイルサイズを格納する Qword。

ppNewStorage

IMDSPStorage**

out

新しく作成されたストレージの IMDSPStorage インターフェイスを受け取る、IMDSPStorage ポインターへのポインター。

戻り値

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

返される可能性のあるエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

このメソッドは、ストレージの作成時にメタデータを適用する必要がある場合に役立ちます。これに対し、IMDSPStorage2::CreateStorage2 メソッドおよび IMDSPStorage::CreateStorage メソッドには、作成時にメタデータを指定する手段がありません。

Windows Media Player と同期できるデバイスのサービスプロバイダーがこのインターフェイスをサポートしている場合、Windows Media Device Manager は Insert/2/3 の操作中にこのメソッドを呼び出します。

WMDM_FILE_ATTR_FOLDER 属性と WMDM_FILE_ATTR_FILE 属性の両方が設定されている場合は、フォルダー属性がファイル属性より優先され、新しいストレージはフォルダーとして作成されます。

クライアントが指定できるのは、WMDM_STORAGECONTROL_INSERTBEFORE、WMDM_STORAGECONTROL_INSERTAFTER、WMDM_STORAGECONTROL_INSERTINTO のうちいずれか 1 つだけです。

新しいストレージは同じ階層に作成することも、現在のストレージがフォルダーであればその中に挿入することもできます。これは dwAttributes パラメーターの値によって制御されます。WMDM_STORAGECONTROL_INSERTBEFORE または WMDM_STORAGECONTROL_INSERTAFTER を指定した場合、新しいストレージは現在のストレージと同じ階層に作成されます。WMDM_STORAGECONTROL_INSERTINTO を指定した場合、新しいストレージは現在のストレージの中に挿入されます。

WMDM_STORAGECONTROL_INSERTBEFORE と WMDM_STORAGECONTROL_INSERAFTER は、ファイルシステム上のコンテンツの順序付けを前提としています。ファイルシステムが順序付けをサポートしていない場合(FAT32 ファイルシステムなど)、どちらのフラグも、新しいストレージを現在のストレージと同じ階層に挿入するという同一の効果になります。現在のストレージがストレージメディアのルートを表しているときにこれら 2 つのフラグのいずれかを指定すると、操作は失敗します。

WMDM_STORAGECONTROL_INSERTINTO は、現在のストレージがフォルダーである場合にのみ有効です。現在のストレージがファイルであるときにこのフラグを指定すると、操作は失敗します。

vtbl 22 HRESULT GetSpecifiedMetadata(DWORD cProperties, LPWSTR* ppwszPropNames, IWMDMMetaData* pMetadata)

GetSpecifiedMetadata メソッドは、ストレージについて指定されたメタデータオブジェクトのみを取得します。

cProperties	DWORD	in	取得するプロパティの数。
ppwszPropNames	LPWSTR*	in	取得するプロパティ名を格納した配列。この配列のサイズは cProperties と等しくする必要があります。
pMetadata	IWMDMMetaData*	inoptional	返される IWMDMMetaData インターフェイスポインターへのポインター。

戻り値

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

返される可能性のあるエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

このメソッドを使うと、クライアントはどのプロパティを取得するかを制御できます。クライアントは、取得したいプロパティのプロパティ名を指定できます。

これに対し、GetMetadata メソッドはストレージのすべてのメタデータ(プロパティ)を取得します。

指定されたプロパティをいずれも返せない場合、サービスプロバイダーは WMDM_E_NOTSUPPORTED または適切なエラーコードを返す必要があります。

少なくとも 1 つのプロパティを取得できる場合、サービスプロバイダーはそのプロパティを返し、戻り値として成功コード WMDM_S_NOT_ALL_PROPERTIES_RETRIEVED を設定する必要があります。

vtbl 23 HRESULT FindStorage(WMDM_FIND_SCOPE findScope, LPWSTR pwszUniqueID, IMDSPStorage** ppStorage)

FindStorage メソッドは、指定された永続的な一意識別子を持つストレージを検索します。ストレージの永続的な一意識別子は、そのストレージの g_wszWMDMPersistentUniqueID プロパティによって表されます。(IMDSPStorage4.FindStorage)

findScope

WMDM_FIND_SCOPE

検索操作のスコープ。次のいずれかの値である必要があります。

値	説明
WMDM_FIND_SCOPE_GLOBAL	デバイス全体を検索します。
WMDM_FIND_SCOPE_IMMEDIATE_CHILDREN	現在のストレージの直下の子のみを検索します。

pwszUniqueID

LPWSTR

ストレージの永続的な一意識別子。

ppStorage

IMDSPStorage**

out

pwszUniqueID パラメーターで指定された、返されるストレージへのポインター。

戻り値

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

返される可能性のあるエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

サービスプロバイダーは、ストレージの g_wszWMDMPersistentUniqueID プロパティを通じて永続的な一意識別子を返します。特定のストレージについて、サービスプロバイダーが提供する永続的な一意識別子は、デバイス接続セッションが異なっても同一である必要があります。

アプリケーションは、後からこの永続的な一意識別子を指定して FindStorage を呼び出すことがあります。これに応じて、Windows Media Device Manager はサービスプロバイダーのこのメソッドを呼び出します。

永続的な一意識別子は、特定のデバイスに保存されたコンテンツを一意に識別するために使用されます。これは、すべてのデバイスにわたって同一のままとなるコンテンツ固有のグローバル一意識別子を表すものではありません。したがって、同じコンテンツであっても異なるストレージに保存されていれば、永続的な一意識別子は異なります。

このメソッドでは永続的な一意識別子に基づいてストレージを検索できるのに対し、IMDSPStorage2::GetStorage では名前に基づいてストレージを検索できます。

Windows Media Device Manager がこのメソッドを呼び出すのは、Windows Media Player と同期できるデバイスの場合のみです。詳細については、Enabling Synchronization with Windows Media Player を参照してください。

vtbl 24 HRESULT GetParent(IMDSPStorage** ppStorage)

GetParent メソッドは、現在のストレージの親を取得します。

ppStorage

IMDSPStorage**

out

返される親ストレージオブジェクトへのポインター。

戻り値

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

返される可能性のあるエラーコードの詳細な一覧については、Error Codes を参照してください。

解説(Remarks)

このメソッドを再帰的に使用すると、現在のストレージの階層全体をたどることができます。

ルートストレージに対してこのメソッドが呼び出された場合、このメソッドは S_FALSE を返し、ppStorage に NULL を設定する必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMDSPStorage4 "{3133B2C4-515C-481B-B1CE-39327ECB4F74}"
#usecom global IMDSPStorage4 IID_IMDSPStorage4 "{}"
#comfunc global IMDSPStorage4_SetReferences              19 int,sptr
#comfunc global IMDSPStorage4_GetReferences              20 var,sptr
#comfunc global IMDSPStorage4_CreateStorageWithMetadata  21 int,wstr,sptr,int64,sptr
#comfunc global IMDSPStorage4_GetSpecifiedMetadata       22 int,var,sptr
#comfunc global IMDSPStorage4_FindStorage                23 int,wstr,sptr
#comfunc global IMDSPStorage4_GetParent                  24 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IMDSPStorage4 "{3133B2C4-515C-481B-B1CE-39327ECB4F74}"
#usecom global IMDSPStorage4 IID_IMDSPStorage4 "{}"
#comfunc global IMDSPStorage4_SetReferences              19 int,sptr
#comfunc global IMDSPStorage4_GetReferences              20 sptr,sptr
#comfunc global IMDSPStorage4_CreateStorageWithMetadata  21 int,wstr,sptr,int64,sptr
#comfunc global IMDSPStorage4_GetSpecifiedMetadata       22 int,sptr,sptr
#comfunc global IMDSPStorage4_FindStorage                23 int,wstr,sptr
#comfunc global IMDSPStorage4_GetParent                  24 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。