ホーム › Media.Audio › IDeviceSpecificProperty

IDeviceSpecificProperty

COM

📘 Microsoft Learn (日本語) · English

IID3b22bcbf-2586-4af0-8583-205d391b807c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IDeviceSpecificProperty インターフェイスは、デバイス固有のハードウェアコントロールのコントロール値へのアクセスを提供します。

メソッド 4

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

vtbl 3 HRESULT GetType(WORD* pVType)

GetType メソッドは、デバイス固有のプロパティ値のデータ型を取得します。

pVType

WORD*

out

デバイス固有のプロパティ値のデータ型を示す VARTYPE 列挙値を、このメソッドが書き込む VARTYPE 変数へのポインターです。VARTYPE の詳細については、Windows SDK ドキュメントを参照してください。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。

戻り値コード	説明
E_POINTER	ポインター pVType が NULL です。

vtbl 4 HRESULT GetValue(void* pvValue, DWORD* pcbValue)

GetValue メソッドは、デバイス固有のプロパティの現在の値を取得します。

pvValue	void*	out	このメソッドがプロパティ値を書き込む、呼び出し元が割り当てたバッファーへのポインターです。
pcbValue	DWORD*	inout	[inout] プロパティ値のサイズをバイト単位で指定する DWORD 変数へのポインターです。入力時、pcbValue には呼び出し元が割り当てたバッファーのサイズ(または pvValue* が NULL の場合は 0)が格納されます。戻る前に、このメソッドはバッファーに書き込まれたプロパティ値の実際のサイズ(またはバッファーが小さすぎる場合や pvValue が NULL の場合は必要なサイズ)を書き込みます。

戻り値

戻り値コード	説明
E_POINTER	ポインター pcbValue が NULL です。
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	pvValue パラメーターが指すバッファーがプロパティ値を格納するには小さすぎるか、pvValue が NULL でありプロパティ値のサイズが可変ではなく固定です。このマクロの詳細については、Windows SDK ドキュメントを参照してください。

解説(Remarks)

プロパティ値のサイズが固定ではなく可変である場合、呼び出し元は pvValue = NULL かつ *pcbValue = 0 として GetValue を呼び出すことで、必要なバッファーサイズを取得できます。このメソッドは必要なバッファーサイズを *pcbValue に書き込みます。この情報をもとに、呼び出し元は必要なサイズのバッファーを割り当て、GetValue を再度呼び出してプロパティ値を取得できます。

呼び出し元が割り当てたバッファーがプロパティ値を格納するには小さすぎる場合、GetValue は必要なバッファーサイズを *pcbValue に書き込み、エラーステータスコードを返します。この場合、pvValue が指すバッファーには何も書き込まれません。

vtbl 5 HRESULT SetValue(void* pvValue, DWORD cbValue, GUID* pguidEventContext)

SetValue メソッドは、デバイス固有のプロパティの値を設定します。

pvValue	void*	in	デバイス固有のプロパティの新しい値へのポインターです。
cbValue	DWORD	in	デバイス固有のプロパティ値のサイズ(バイト単位)です。
pguidEventContext	GUID*	inoptional	IControlChangeNotify::OnNotify メソッドのコンテキスト値です。このパラメーターはイベントコンテキスト GUID を指します。SetValue の呼び出しによってコントロールの状態が変化した場合、そのコントロールに IControlChangeNotify インターフェイスを登録しているすべてのクライアントが通知を受け取ります。OnNotify メソッドの実装において、クライアントはイベントコンテキスト GUID を検査することで、自身と他のクライアントのどちらがコントロール変更イベントの発生元であるかを判別できます。呼び出し元がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL のコンテキストポインターを受け取ります。

戻り値

戻り値コード	説明
E_POINTER	ポインター pvValue が NULL です。
E_INVALIDARG	cbValue パラメーターがプロパティ値の必要なサイズと一致しません。
E_OUTOFMEMORY	メモリ不足です。

vtbl 6 HRESULT Get4BRange(INT* plMin, INT* plMax, INT* plStepping)

Get4BRange メソッドは、デバイス固有のプロパティ値の 4 バイト範囲を取得します。

plMin	INT*	out	このメソッドが最小プロパティ値を書き込む LONG 変数へのポインターです。
plMax	INT*	out	このメソッドが最大プロパティ値を書き込む LONG 変数へのポインターです。
plStepping	INT*	out	plMin から plMax までの範囲において、連続するプロパティ値間のステップ値をこのメソッドが書き込む LONG 変数へのポインターです。最大プロパティ値と最小プロパティ値の差を d とし、範囲を n ステップ(均等なサイズの区間)に分割する場合、プロパティは n + 1 個の離散値をとることができ、連続する値の間のステップのサイズは d / n となります。

戻り値

戻り値コード	説明
E_POINTER	ポインター plMin、plMax、または plStepping が NULL です。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	プロパティ値が 32 ビットの符号付きまたは符号なし整数ではありません。このマクロの詳細については、Windows SDK ドキュメントを参照してください。

解説(Remarks)

このメソッドは、32 ビットの符号付きまたは符号なし整数であるプロパティ値の範囲とステップサイズを報告します。これら 2 つのデータ型は、それぞれ VARENUM 列挙定数 VT_I4 および VT_UI4 で表されます。プロパティ値が 32 ビット整数でない場合、このメソッドはエラーステータスコードを返します。VARENUM の詳細については、Windows SDK ドキュメントを参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IDeviceSpecificProperty "{3B22BCBF-2586-4AF0-8583-205D391B807C}"
#usecom global IDeviceSpecificProperty IID_IDeviceSpecificProperty "{}"
#comfunc global IDeviceSpecificProperty_GetType     3 var
#comfunc global IDeviceSpecificProperty_GetValue    4 sptr,var
#comfunc global IDeviceSpecificProperty_SetValue    5 sptr,int,var
#comfunc global IDeviceSpecificProperty_Get4BRange  6 var,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDeviceSpecificProperty "{3B22BCBF-2586-4AF0-8583-205D391B807C}"
#usecom global IDeviceSpecificProperty IID_IDeviceSpecificProperty "{}"
#comfunc global IDeviceSpecificProperty_GetType     3 sptr
#comfunc global IDeviceSpecificProperty_GetValue    4 sptr,sptr
#comfunc global IDeviceSpecificProperty_SetValue    5 sptr,int,sptr
#comfunc global IDeviceSpecificProperty_Get4BRange  6 sptr,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。