KSIDENTIFIER 構造体 (ks.h)
KSIDENTIFIER 構造体は、関連する GUID のセットを一意に識別する GUID と、そのセット内の特定のメンバーを参照するインデックス値を指定します。
KSDEGRADE、KSEVENT、KSMETHOD、KSPIN_INTERFACE、KSPIN_MEDIUM、KSPROPERTY typedef は、KSIDENTIFIER 構造体のエイリアスです。 そのため、それらの定義は同じです。 使用法の詳細については、個々の typedef トピックを参照してください。
構文
typedef struct {
union {
struct {
GUID Set;
ULONG Id;
ULONG Flags;
} _IDENTIFIER;
struct {
GUID Set;
ULONG Id;
ULONG Flags;
};
LONGLONG Alignment;
};
} KSIDENTIFIER, *PKSIDENTIFIER;
メンバー
_IDENTIFIER
以下の解説を参照してください。
_IDENTIFIER.Set
以下の解説を参照してください。
_IDENTIFIER.Id
以下の解説を参照してください。
_IDENTIFIER.Flags
以下の解説を参照してください。
Set
以下の解説を参照してください。
Id
以下の解説を参照してください。
Flags
以下の解説を参照してください。
Alignment
以下の解説を参照してください。
注釈
KSIDENTIFIER メンバーの説明
Set
カーネル ストリーミング プロパティ、イベント、メソッド、通信バス セットを識別する GUID を指定します。 KSPIN_INTERFACE構造体は、インターフェイス セット内の特定のインターフェイスを記述します。 KSDEGRADE 構造体には、分解戦略の詳細が含まれています。 詳細については、以下の 「解説 」セクションを参照してください。
Id
プロパティ、イベント、メソッド セットのメンバーを指定します。 KSPIN_MEDIUMの場合は、バス上の一意の接続を識別します。 KSPIN_INTERFACEの場合は、インターフェイス セット内のこの特定のインターフェイスの ID 番号を指定します。 KSDEGRADE の場合は、セット内の項目のセット固有の識別子を指定します。
Flags
要求の種類を指定します。 ストリーム クラス ミニドライバーを作成する場合は、「クラス固有のフラグ情報の KSPROPERTY_ITEM 」も参照してください。 フラグ は、次の表に示す値のいずれかである必要があります。 一部のフラグは、ビットごとの OR 演算を使用して組み合わせることができます。
使用法の詳細については、 KSDEGRADE、 KSEVENT、 KSMETHOD、 KSPIN_INTERFACE、 KSPIN_MEDIUM、 KSPROPERTY typedef の各トピックを参照してください。
KSPROPERTY 要求の種類を指定します。
| KSPROPERTY フラグ値 | 説明 |
|---|---|
| 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の逆である必要があります。 |
KSEVENT 要求の種類を指定します。 このフラグは、次の表に示す値のいずれかである必要があります。
| KSEVENT フラグ値 | 説明 |
|---|---|
| KSEVENT_TYPE_ENABLE | このイベントの種類のイベント通知を有効にします。 ドライバーは、クライアントが明示的に無効になるまでイベント通知を続行します。 |
| KSEVENT_TYPE_ONESHOT | このイベントが次に発生した場合にのみイベント通知を有効にします。 発生したイベントをクライアントが無効にする必要はありません (無効にする必要はありません)。 |
| KSEVENT_TYPE_SETSUPPORT | イベント セットの一覧、または特定のイベント セットのサポートを照会します。 |
| KSEVENT_TYPE_BASICSUPPORT | 特定のイベントの種類をサポートするためのクエリ。 |
| KSEVENT_TYPE_ENABLEBUFFERED | ドライバーは、クライアントに通知する代わりに、イベント通知をキューに入れます。 その後、クライアントは、キューに入IOCTL_KS_ENABLE_EVENTイベント通知を受信するために、KSEVENT_TYPE_QUERYBUFFERに対して 2 つ目のIOCTL_KS_ENABLE_EVENT要求を発行します。 |
| KSEVENT_TYPE_TOPOLOGY | 渡されたイベントの種類が KSE_NODE であることを示します。 NodeId はトポロジ ノードの数値 ID を示します。 このフラグは単独で設定しないでください。代わりに、この一覧の他のフラグと共に指定します。 |
| KSEVENT_TYPE_QUERYBUFFER | バッファーに格納された次のイベント通知を取得します。 |
KSMETHOD 要求の種類を指定します。 また、KSMETHOD_ITEMのKSMETHOD_TYPE_Xxx フラグも参照してください。 要求には、次の表に示す値の組み合わせを含めることができます。
| KSMETHOD フラグ値 | 説明 |
|---|---|
| KSMETHOD_TYPE_BASICSUPPORT | ミニドライバーに対してクエリを実行して、メソッド セットの指定されたメソッドがサポートされているかどうかを判断することを示します。 |
| KSMETHOD_TYPE_SEND | ミニドライバーが指定したメソッドを実行する必要があることを示します。 指定されたパラメーターに対する メソッドの効果は、クライアントに認識されている必要があります。つまり、パラメーターの読み取り元、書き込み元、両方、またはどちらも認識できません。 ミニドライバーは、KSMETHOD_ITEM構造体を使用して、パラメーターに対するメソッドの効果を指定します。 |
| KSMETHOD_TYPE_SETSUPPORT | ミニドライバーに対してクエリを実行して、指定したメソッド セットがサポートされているかどうかを判断することを示します。 |
| KSMETHOD_TYPE_TOPOLOGY | 指定したメソッドの型が KSM_NODE であることを示します。 ここで、NodeId メンバーはトポロジ ノードの識別子です。 このフラグは単独で設定しないでください。代わりに、この一覧の他のフラグと共に指定します。 |
KSDEGRADE の場合は、現在の低下の割合 (1000 分の 1 で表される値が 1000 の場合は低下なし) を指定するか、インターフェイスで指定されたネイティブ 単位の時間を指定します。
Alignment
使用されていません。 名前のない構造体に対して適切なアラインメントを強制するために使用される、名前のない共用体のメンバー。
メモ
使用法の詳細については、 KSDEGRADE、 KSEVENT、 KSMETHOD、 KSPIN_INTERFACE、 KSPIN_MEDIUM、 KSPROPERTY typedef の各トピックを参照してください。
セット内で ID を使用すると、セット識別子に対して 1 つの大きな比較を実行し、より小さなクイック比較を実行できます (たとえば、セット内の識別子に switch ステートメントを使用します)。 たとえば、 プロパティ セット は一意の GUID 識別子によって参照され、そのセット内のプロパティは短い ID で参照されます。
メソッド、 イベント、 インターフェイス、 およびメディア セット は、セットの "クラス" と考えることができます。
渡される出力バッファーのサイズによって、KSPROPERTY_TYPE_BASICSUPPORT要求から返されるデータが決まります。 出力バッファーが ULONG のサイズの場合は、アクセス フラグのみが返されます。 出力バッファーが KSPROPERTY_DESCRIPTION 構造体のサイズの場合、構造体にはアクセス フラグ、値情報全体の包括サイズ、プロパティ値の型情報、構造体に対応するメンバー リストの数が入力されます。
KSPROPERTY_TYPE_RELATIONS要求の場合、返されるデータも出力バッファーのサイズによって異なります。 出力バッファー サイズが 0 の場合、関連プロパティを返すために必要なサイズは BytesReturned で返され、警告の状態は STATUS_BUFFER_OVERFLOW。 バッファーが 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 関数は、ミニドライバーによって提供されるハンドラーを呼び出します。 シリアル化に必要なバッファー サイズは、シリアル化された未加工の要求に長さ 0 のバッファーを渡すことによっても照会できます。 ハンドラーはプロパティ セットではなくプロパティ項目にアタッチされるため、プロパティ セット内の特定の項目を Property パラメーターで指定する必要があります。 このハンドラーは、セット内の複数のプロパティを処理できます。
Microsoft には、システム定義のプロパティ セット GUID がいくつか用意されています。 ミニドライバーは 、Set メンバーでこれらの GUID のいずれかを指定します。 カーネル ストリーミング プロパティ セットは、通常、 KSPROPSETID または PROPSETID プレフィックスで始まります。 カーネル ストリーミング プロパティ セットは、ks.h、ksmedia.h、bdamedia.h、および場合によっては他のヘッダー ファイルで定義されます。
カーネル ストリーミング プロパティの詳細については、「 KS のプロパティ、イベント、およびメソッド」を参照してください。
Microsoft では、システム定義のイベント セット GUID がいくつか用意されています。 ミニドライバーは 、Set メンバーでこれらの GUID のいずれかを指定します。 カーネル ストリーミング イベント セットは、通常 、KSEVENTSETID プレフィックスで始まります。 カーネル ストリーミング イベント セットは、ks.h、ksmedia.h、bdamedia.h、および場合によっては他のヘッダー ファイルで定義されます。
カーネル ストリーミング イベントの詳細については、「 KS のプロパティ、イベント、およびメソッド」を参照してください。
Microsoft では、システム定義のメソッド セット GUID がいくつか用意されています。 ミニドライバーは 、Set メンバーでこれらの GUID のいずれかを指定します。 カーネル ストリーミング メソッド セットは、通常 、KSMETHODSETID プレフィックスで始まります。 カーネル ストリーミング メソッド セットは、ks.h、ksmedia.h、bdamedia.h、および場合によっては他のヘッダー ファイルで定義されます。
カーネル ストリーミング メソッドの詳細については、「 KS のプロパティ、イベント、およびメソッド」を参照してください。
クライアントは、IOCTL_KS_METHOD要求と KSMETHOD 構造体を使用して、ミニドライバーが処理するカーネル ストリーミング オブジェクトに対してメソッドを実行できます。 詳細については、「 KS メソッド」を参照してください。
KSPIN_MEDIUM構造体は、バス固有の方法で生成される一意の中 GUID とインスタンス識別子を使用して、メディアを識別します。 バス インスタンスに問題がない場合に使用される予約済み識別子値KSMEDIUM_TYPE_ANYINSTANCEがあります。 たとえば、KSMEDIUMSETID_Standardはシステム バスを参照します。このバスは 1 つだけである必要があります。 そのため、このインスタンス識別子は常に利便性のためだけに使用されます。
ピンは、これらのメディア上の複数のメディアとインターフェイスをサポートする場合があります。 ピンを記述する方法は、1 つのピンに対して列挙されたすべてのメディアでインターフェイスの一覧がサポートされていることを意味します。 これが当てはまらない場合は、特定のメディアのインターフェイスの各サブセットを記述するために別のピンを使用できます。
メディアは、可能な接続の検索を高速化するために、カーネル ストリーミングによってキャッシュされます。
この構造の使用例は、チューナ、クロスバー、およびその他のチューナコンポーネント間の一意の接続 を表KSPIN_MEDIUM チューナサンプルにあります。
Flags メンバーには、クライアントが使用するシグナルの低下の種類に基づいて異なる値を含めることができます。 「品質管理」を参照してください。 信号品質を下げることで品質管理の問題を解決するためのさまざまな戦略について詳しく説明します。
Flags には ULONG 値が含まれているため、品質管理の問題を解決するには、複数の Skip 要求が必要になる場合があります。
要件
| 要件 | 値 |
|---|---|
| Header | ks.h (Ks.h を含む) |