ホーム › Media.DeviceManager › IMDSPDevice3

IMDSPDevice3

COM

📘 Microsoft Learn (日本語) · English

IID1a839845-fc55-487c-976f-ee38ac0e8c4e継承元IMDSPDevice2自前メソッド開始 vtbl18

公式ドキュメント

Windows Media Player との同期を想定しているデバイスでは、IMDSPDevice3 インターフェイスをサポートする必要があります。

メソッド 5

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

vtbl 18 HRESULT GetProperty(LPWSTR pwszPropName, PROPVARIANT* pValue)

GetProperty メソッドは、特定のデバイスプロパティを取得します。

pwszPropName	LPWSTR	in	デバイスから取得するプロパティの名前。
pValue	PROPVARIANT*	out	返されるプロパティの値。

戻り値

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

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

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

解説(Remarks)

pValue が指すバリアントは、空の PROPVARIANT に設定されます。つまり、その VT は VT_EMPTY に設定されます。

サービスプロバイダーは、このバリアントにプロパティ pwszPropName に対応する適切なプロパティ値を設定する必要があります。

pwszPropName が g_wszWMDMSupportedDeviceProperties の場合、サービスプロバイダーはサポートされているデバイスプロパティの配列を返す必要があります。この場合、バリアントの VT は VT_BSTR | VT_ARRAY にする必要があります。

標準的なデバイスプロパティ名の一覧については、Metadata Constants を参照してください。

このメソッドは、ストレージに対する IMDSPStorage3::GetMetadata メソッドおよび IMDSPStorage4::GetSpecifiedMetadata メソッドに似ていますが、一度に 1 つのプロパティしか取得できません。

vtbl 19 HRESULT SetProperty(LPWSTR pwszPropName, PROPVARIANT* pValue)

SetProperty メソッドは、書き込み可能な特定のデバイスプロパティを設定します。

pwszPropName	LPWSTR	in	設定するデバイスプロパティの名前。
pValue	PROPVARIANT*	in	設定するデバイスプロパティの値。

戻り値

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

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

解説(Remarks)

このメソッドは、指定されたデバイスプロパティを設定します。

デバイスプロパティ名の一覧については、Metadata Constants を参照してください。

このメソッドは、ストレージに対する SetMetadata メソッドに似ていますが、一度に 1 つのプロパティしか設定できません。

vtbl 20 HRESULT GetFormatCapability(WMDM_FORMATCODE format, WMDM_FORMAT_CAPABILITY* pFormatSupport)

GetFormatCapability メソッドは、特定のオブジェクトフォーマットの各項目についてデバイスがサポートする値または値の範囲に関する情報を、デバイスから取得します。

format

WMDM_FORMATCODE

問い合わせ対象のフォーマットを表す列挙値。

pFormatSupport

WMDM_FORMAT_CAPABILITY*

out

特定のオブジェクトフォーマットの各項目についてサポートされる値または値の範囲を格納した、返される WMDM_FORMAT_CAPABILITY 構造体。

戻り値

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

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

解説(Remarks)

このメソッドは、サポートされている任意のフォーマットに対して呼び出すことができます。サポートされているフォーマットの一覧は、g_wszWMDMFormatsSupported デバイスプロパティで表されます。

特定のフォーマットについて、このメソッドはサポートされているプロパティのすべての構成 (たとえばビットレートとサンプルレートの組み合わせ) を返す必要があります。この情報はフォーマット機能 (format capability) として表現されます。詳細については、WMDM_FORMAT_CAPABILITY を参照してください。

vtbl 21 HRESULT DeviceIoControl(DWORD dwIoControlCode, BYTE* lpInBuffer, DWORD nInBufferSize, BYTE* lpOutBuffer, DWORD* pnOutBufferSize)

DeviceIoControl メソッドは、デバイス I/O コントロールを呼び出します。

dwIoControlCode	DWORD	in	デバイスに送信する I/O コントロールコード。
lpInBuffer	BYTE*	in	呼び出し元アプリケーションが提供する入力バッファー。nInBufferSize が 0 の場合は NULL でもかまいません。
nInBufferSize	DWORD	in	lpInBuffer のサイズ (バイト単位)。
lpOutBuffer	BYTE*	out	呼び出し元アプリケーションが提供する出力バッファー。
pnOutBufferSize	DWORD*	inout	lpOutBuffer のサイズ (バイト単位)。

戻り値

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

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

解説(Remarks)

このメソッドは、アプリケーションとサービスプロバイダーの間のプライベートな通信手段を提供します。サービスプロバイダーはこの IOCTL を処理し、必要に応じて変更したうえで、カーネルモードドライバーに渡すことができます。

IMDSPDevice::SendOpaqueCommand と比べて、このメソッドは出力バッファーを呼び出し元が提供するため、Windows API の DeviceIoControl により近い形になっています。また IMDSPDevice::SendOpaqueCommand とは異なり、このメソッドは MAC チェックを伴わないため、より効率的です。

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

FindStorage メソッドは、指定された永続的な一意識別子を持つストレージを検索します。ストレージの永続的な一意識別子は、そのストレージの g_wszWMDMPersistentUniqueID プロパティで表されます。(IMDSPDevice3.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 はサービスプロバイダー (SP) 上でこのメソッドを呼び出します。

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

Windows Media Device Manager は、Windows Media Player との同期を有効にするために登録されているデバイスに対してのみ、このメソッドを呼び出します。詳細については、Enabling Synchronization with Windows Media Player を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMDSPDevice3 "{1A839845-FC55-487C-976F-EE38AC0E8C4E}"
#usecom global IMDSPDevice3 IID_IMDSPDevice3 "{}"
#comfunc global IMDSPDevice3_GetProperty          18 wstr,var
#comfunc global IMDSPDevice3_SetProperty          19 wstr,var
#comfunc global IMDSPDevice3_GetFormatCapability  20 int,var
#comfunc global IMDSPDevice3_DeviceIoControl      21 int,var,int,var,var
#comfunc global IMDSPDevice3_FindStorage          22 int,wstr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IMDSPDevice3 "{1A839845-FC55-487C-976F-EE38AC0E8C4E}"
#usecom global IMDSPDevice3 IID_IMDSPDevice3 "{}"
#comfunc global IMDSPDevice3_GetProperty          18 wstr,sptr
#comfunc global IMDSPDevice3_SetProperty          19 wstr,sptr
#comfunc global IMDSPDevice3_GetFormatCapability  20 int,sptr
#comfunc global IMDSPDevice3_DeviceIoControl      21 int,sptr,int,sptr,sptr
#comfunc global IMDSPDevice3_FindStorage          22 int,wstr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。