KSIDENTIFIER 構造体 (ks.h)

[アーティクル]
08/07/2023

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 要求が必要になる場合があります。