The KSPROPERTY structure specifies a single kernel streaming property within a property set.
The KSEVENT, KSMETHOD, and KSPROPERTY structures are aliases for the KSIDENTIFIER structure. そのため、定義は同じです。
Syntax
struct KSPROPERTY {
GUID Set;
ULONG Id;
ULONG Flags;
};
Members
Set
カーネル ストリーミング プロパティ セットを識別する GUID を指定します。 For more information about property set GUIDs, see the Remarks section below.
Id
プロパティ セットのメンバーを指定します。
Flags
要求の種類を指定します。 If you are writing a stream class minidriver, also see KSPROPERTY_ITEM for class-specific flag information.
Flags should be one of the values listed in the following table. フラグの一部は、ビットごとの OR 演算を使用して結合できます。
| Value | Description |
|---|---|
| KSPROPERTY_TYPE_GET | 指定したプロパティ項目の値を取得します。 |
| KSPROPERTY_TYPE_SET | 指定したプロパティ項目の値を設定します。 |
| KSPROPERTY_TYPE_SETSUPPORT | ドライバーがこのプロパティ セットをサポートしている場合にクエリを実行します。 |
| KSPROPERTY_TYPE_BASICSUPPORT | ドライバーがこのプロパティ項目に対して処理する要求の種類を照会します。 Returns KSPROPERTY_TYPE_GET or KSPROPERTY_TYPE_SET or both. すべてのプロパティ セットでこのフラグをサポートする必要があります。 |
| KSPROPERTY_TYPE_DEFAULTVALUES | 指定したプロパティ 項目の既定値を照会します。 Returns a structure of type KSPROPERTY_VALUES. |
| KSPROPERTY_TYPE_RELATIONS | このプロパティの現在の設定に依存するすべてのプロパティをクエリします。 プロパティリレーションリストが返されることを指定します。戻り値のバッファーが ULONG のサイズである場合は、そのようなリストに必要なバッファー領域の量を指定します。 Each element is on FILE_QUAD_ALIGNMENT, preceded by a KSMULTIPLE_ITEM structure. これは、一般的にプロパティ セットのサポートに対してクエリを実行する場合は無効です。 すべてのプロパティ セットでこのフラグをサポートする必要があります。 |
| KSPROPERTY_TYPE_SERIALIZESET | Serialize the property set, using the standard KSPROPERTY_SERIALHDR and KSPROPERTY_SERIAL structures. |
| KSPROPERTY_TYPE_UNSERIALIZESET | Unserialize the property set, using the standard KSPROPERTY_SERIALHDR and KSPROPERTY_SERIAL structures. |
| KSPROPERTY_TYPE_SERIALIZESIZE | Returns a ULONG specifying size of the property data when serialized as part of a KSPROPERTY_TYPE_SERIALIZESET request. サイズが 0 の場合は、プロパティをシリアル化する必要がないことを示します。 |
| KSPROPERTY_TYPE_SERIALIZERAW | このセット内のプロパティが存在する場合は、プロパティ セット サポート ハンドラーによってシリアル化されるように指定します。 そうでない場合、呼び出しは失敗します。 シリアル化形式はプライベートです。 This operation must be the inverse of KSPROPERTY_TYPE_UNSERIALIZERAW. |
| KSPROPERTY_TYPE_TOPOLOGY | Property passed is of type KSP_NODE, where NodeId indicates the numeric ID of the topology node. このフラグは単独で設定しないでください。代わりに、またはこのテーブル内の他のフラグを使用します。 |
| KSPROPERTY_TYPE_UNSERIALIZERAW | 指定されたバッファーに、このセットに属するプロパティのグループが含まれていることを指定します。このプロパティ セットのサポート ハンドラーが存在する場合は、そのプロパティ セットのサポート ハンドラーによって初期化されないようにする必要があります。 そうでない場合、呼び出しは失敗します。 シリアル化形式はプライベートです。 This operation must be the inverse of KSPROPERTY_TYPE_SERIALIZERAW. |
Remarks
渡される出力バッファーのサイズによって、KSPROPERTY_TYPE_BASICSUPPORT要求から返されるデータが決まります。 出力バッファーが ULONG のサイズの場合は、アクセス フラグのみが返されます。 If the output buffer is the size of the KSPROPERTY_DESCRIPTION structure, the structure is filled with the access flags, the inclusive size of the entire values information, the property value type information, and the number of member lists that correspond to the structure.
KSPROPERTY_TYPE_RELATIONS要求の場合、返されるデータも出力バッファーのサイズによって異なります。 If the output buffer size is zero, the size required to return the related properties is returned in BytesReturned with a warning status of STATUS_BUFFER_OVERFLOW. If the buffer is the size of a KSMULTIPLE_ITEM structure, both the byte size and count of relations is returned. Otherwise, the buffer is expected to be long enough to return the KSMULTIPLE_ITEM structure and all related property identifiers, which is returned as a list of KSIDENTIFIER structures.
KSPROPERTY_TYPE_SERIALIZESET and KSPROPERTY_TYPE_UNSERIALIZESET requests allow interaction with multiple properties with a single call from the client. If the kernel streaming handler is being used to process property requests, these are broken up into multiple calls by the KsPropertyHandler function. このハンドラーを使用する場合、プロパティ セット定義は、シリアル化するプロパティを制御します。
For serialization requests, the SerializedSize member of the relevant KSPROPERTY_ITEM structure is checked for a nonzero value that indicates the size, in bytes, of the property. SerializedSize メンバーの値が 1 の場合は不明であり、クエリを実行する必要があります (不明なプロパティはすべて、個別に照会できるKSMULTIPLE_ITEM構造体で始まります)。 To query for the total size a serialization would take, the client passes a zero length buffer in the call to DeviceIoControl. BytesReturned then returns the size, in bytes, that the buffer must be to serialize the set, and a warning status of STATUS_BUFFER_OVERFLOW. そのサイズに割り当てられたバッファーには、シリアル化されたデータを格納できます。
The format of the serialization buffer is a KSPROPERTY_SERIALHDR, followed by serialized properties. Each property that follows contains a header (KSPROPERTY_SERIAL), followed by the property data, with the start of each property on FILE_LONG_ALIGNMENT. Note that the serial header structure is defined to be on FILE_LONG_ALIGNMENT.
KSPROPERTY_TYPE_SERIALIZERAW and KSPROPERTY_TYPE_UNSERIALIZERAW are supported if a property item handler exists. The KsPropertyHandler function invokes the handler provided by the minidriver. シリアル化に必要なバッファー サイズは、シリアル化された未加工の要求に長さ 0 のバッファーを渡すことによっても照会できます。 Because handlers are attached to property items rather than the property set, a specific item within the property set must be specified in the Property parameter. このハンドラーは、セット内の複数のプロパティを処理できます。
Microsoft には、システム定義のプロパティ セット GUID がいくつか用意されています。 Minidrivers specify one of these GUIDs in the Set member. Kernel streaming property sets typically begin with either a KSPROPSETID or a PROPSETID prefix. Kernel streaming property sets are defined in ks.h, ksmedia.h, bdamedia.h, and possibly other header files.
カーネル ストリーミング イベントの詳細については、「KS のプロパティ、イベント、メソッドの」を参照してください。
Requirements
Header: ks.h (include Ks.h)