KSPROPERTY 構造体
KSPROPERTY 構造体は、プロパティ セット内の 1 つのカーネル ストリーミング プロパティを指定します。
KSEVENT、KSMETHOD、および KSPROPERTY 構造体は、KSIDENTIFIER 構造体のエイリアスです。 そのため、それらの定義は同じです。
構文
struct KSPROPERTY {
GUID Set;
ULONG Id;
ULONG Flags;
};
メンバー
Set
カーネル ストリーミング プロパティ セットを識別する GUID を指定します。 プロパティ セット GUID の詳細については、下の「備考」セクションを参照してください。
Id
プロパティ セットのメンバーを指定します。
Flags
要求の種類を指定します。 ストリーム クラス ミニドライバーを作成する場合、クラス固有のフラグ情報については、「KSPROPERTY_ITEM」も参照してください。
Flags は、次の表に示す値のいずれかである必要があります。 一部のフラグは、ビットごとの OR 演算を使用して組み合わせることができます。
| 値 | 説明 |
|---|---|
| KSPROPERTY_TYPE_GET | 指定したプロパティ項目の値を取得します。 |
| KSPROPERTY_TYPE_SET | 指定したプロパティ項目の値を設定します。 |
| KSPROPERTY_TYPE_SETSUPPORT | ドライバーがこのプロパティ セットをサポートしているかどうかを照会します。 |
| KSPROPERTY_TYPE_BASICSUPPORT | ドライバーがこのプロパティ項目に対して処理する要求の種類を照会します。 KSPROPERTY_TYPE_GET または KSPROPERTY_TYPE_SET、あるいはその両方を返します。 すべてのプロパティ セットでこのフラグをサポートする必要があります。 |
| KSPROPERTY_TYPE_DEFAULTVALUES | 指定したプロパティ項目の既定値を照会します。 KSPROPERTY_VALUES 型の構造体を返します。 |
| KSPROPERTY_TYPE_RELATIONS | このプロパティの現在の設定に対する依存関係を持つすべてのプロパティを照会します。 プロパティ関係リストを返すか、戻りバッファーが ULONG のサイズである場合は、そのようなリストで必要なバッファー領域の量を指定します。 各要素は、FILE_QUAD_ALIGNMENT 上にあり、その前に KSMULTIPLE_ITEM 構造体が付きます。 これは、一般的にプロパティ セットのサポートに対してクエリを実行する場合は無効です。 すべてのプロパティ セットでこのフラグをサポートする必要があります。 |
| KSPROPERTY_TYPE_SERIALIZESET | 標準の KSPROPERTY_SERIALHDR および KSPROPERTY_SERIAL 構造体を使用して、プロパティ セットをシリアル化します。 |
| KSPROPERTY_TYPE_UNSERIALIZESET | 標準の KSPROPERTY_SERIALHDR および KSPROPERTY_SERIAL 構造体を使用して、プロパティ セットのシリアル化を解除します。 |
| KSPROPERTY_TYPE_SERIALIZESIZE | KSPROPERTY_TYPE_SERIALIZESET 要求の一部としてシリアル化されるときに、プロパティ データのサイズを指定する ULONG を返します。 サイズが 0 の場合は、プロパティをシリアル化する必要がないことを示します。 |
| KSPROPERTY_TYPE_SERIALIZERAW | このセット内のプロパティが存在する場合は、プロパティ セット サポート ハンドラーによってシリアル化されるように指定します。 そうでない場合、呼び出しは失敗します。 シリアル化形式はプライベートです。 この演算は、KSPROPERTY_TYPE_UNSERIALIZERAW の逆である必要があります。 |
| KSPROPERTY_TYPE_TOPOLOGY | 渡されるプロパティは KSP_NODE 型です。NodeId はトポロジ ノードの数値 ID を示します。 このフラグは単独で設定しないでください。代わりに、このテーブルの他のフラグを指定します。 |
| KSPROPERTY_TYPE_UNSERIALIZERAW | 指定されたバッファーに、このセットに属するプロパティのグループが含まれていることを指定します。このプロパティ セットのサポート ハンドラーが存在する場合は、そのプロパティ セットのサポート ハンドラーによってシリアル化を解除する必要があります。 そうでない場合、呼び出しは失敗します。 シリアル化形式はプライベートです。 この演算は、KSPROPERTY_TYPE_SERIALIZERAW の逆である必要があります。 |
備考
渡される出力バッファーのサイズによって、KSPROPERTY_TYPE_BASICSUPPORT 要求から返されるデータが決まります。 出力バッファーが ULONG のサイズである場合は、アクセス フラグのみが返されます。 出力バッファーが KSPROPERTY_DESCRIPTION 構造体のサイズである場合、構造体にはアクセス フラグ、値情報全体の包括サイズ、プロパティ値の型情報、および構造体に対応するメンバー リストの数が入力されます。
KSPROPERTY_TYPE_RELATIONS 要求の場合、返されるデータも出力バッファーのサイズによって異なります。 出力バッファー サイズが 0 である場合は、関連するプロパティを返すために必要なサイズと STATUS_BUFFER_OVERFLOW の警告状態が BytesReturned で返されます。 バッファーが KSMULTIPLE_ITEM 構造体のサイズである場合は、バイト サイズとリレーション数の両方が返されます。 それ以外の場合、バッファーは、KSMULTIPLE_ITEM 構造体と、KSIDENTIFIER 構造体のリストとして返されるすべての関連プロパティ識別子を返すのに十分な長さであることが想定されます。
KSPROPERTY_TYPE_SERIALIZESET 要求と KSPROPERTY_TYPE_UNSERIALIZESET 要求では、クライアントからの 1 回の呼び出しで複数のプロパティを操作できます。 カーネル ストリーミング ハンドラーを使用してプロパティ要求を処理する場合、これらは KsPropertyHandler 関数によって複数の呼び出しに分割されます。 このハンドラーを使用する場合、プロパティ セット定義はシリアル化するプロパティを制御します。
シリアル化要求の場合、関連する KSPROPERTY_ITEM 構造体の SerializedSize メンバーに、プロパティのサイズ (バイト単位) を示す 0 以外の値がチェックされます。 SerializedSize メンバーの値が 1 の場合は不明であり、クエリを実行する必要があります (不明なプロパティはすべて、個別にクエリできる KSMULTIPLE_ITEM 構造体で始まります)。 シリアル化に要する合計サイズを照会するために、クライアントは DeviceIoControl の呼び出しで長さ 0 のバッファーを渡します。 その後、BytesReturned は、バッファーがセットをシリアル化するために必要なサイズ (バイト単位) と、STATUS_BUFFER_OVERFLOW の警告状態を返します。 そのサイズが割り当てられたバッファーには、シリアル化されたデータを格納できます。
シリアル化バッファーの形式は、KSPROPERTY_SERIALHDR で、その後にシリアル化されたプロパティが続きます。 以降の各プロパティには、ヘッダー (KSPROPERTY_SERIAL)、その後にプロパティ データが続き、FILE_LONG_ALIGNMENT 各プロパティの先頭が含まれます。 シリアル ヘッダー構造は、FILE_LONG_ALIGNMENT 上に定義されていることに注意してください。
プロパティ項目ハンドラーが存在する場合は、KSPROPERTY_TYPE_SERIALIZERAW および KSPROPERTY_TYPE_UNSERIALIZERAW がサポートされます。 KsPropertyHandler 関数は、ミニドライバーによって提供されるハンドラーを呼び出します。 シリアル化に必要なバッファー サイズは、シリアル化された raw 要求に長さ 0 のバッファーを渡すことによっても照会できます。 ハンドラーはプロパティ セットではなくプロパティ項目にアタッチされるため、プロパティ セット内の特定の項目を Property パラメーターで指定する必要があります。 このハンドラーは、セット内の複数のプロパティを処理できます。
Microsoft は、いくつかのシステム定義プロパティ セット GUID を提供しています。 ミニドライバーは、Set メンバーでこれらの GUID のいずれかを指定します。 カーネル ストリーミング プロパティ セットは、通常、KSPROPSETID または PROPSETID プレフィックスで始まります。 カーネル ストリーミング プロパティ セットは、ks.h、ksmedia.h、bdamedia.h、および場合によっては他のヘッダー ファイルで定義されます。
カーネル ストリーミング イベントの詳細については、「KS のプロパティ、イベント、およびメソッド」を参照してください。
要件
ヘッダー: ks.h (Ks.hを含む)