KSIDENTIFIER 構造体 (ks.h)

[アーティクル]
02/07/2025

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	ドライバーは、クライアントに通知するのではなく、イベント通知をキューに入れます。その後、クライアントは、キューに登録されたイベント通知を受信するために、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 の値が低下を表さない部分) で表されるか、またはインターフェイスで指定されたネイティブ単位で時間の量を指定します。

Alignment

使用されません。名前のない構造体に対して適切な配置を強制するために使用される、名前のない共用体のメンバー。

筆記

セット内で ID を使用すると、1 つのセット識別子に対して 1 つの大きな比較を実行し、より小さなクイック比較を実行できます (たとえば、セット内の識別子に switch ステートメントを使用するなど)。たとえば、プロパティセット は一意の GUID 識別子によって参照され、そのセット内のプロパティは短い ID によって参照されます。

メソッド、イベント、インターフェイス、および メディアセット は、セットの "クラス" と考えることができます。

渡される出力バッファーのサイズによって、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 関数は、ミニドライバーによって提供されるハンドラーを呼び出します。シリアル化に必要なバッファーサイズは、シリアル化された未加工の要求に長さ 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 つだけである必要があります。そのため、このインスタンス識別子は常に便利な方法として使用されます。

ピンは、これらのメディア上の複数のメディアとインターフェイスをサポートする場合があります。ピンを記述する方法は、インターフェイスの一覧が、ピンに列挙されているすべてのメディアでサポートされていることを意味します。これが正しくない場合は、別のピンを使用して、特定のメディアのインターフェイスの各サブセットを記述できます。

メディアは、可能な接続の検索を高速化するためにカーネルストリーミングによってもキャッシュされます。

この構造の使用例は、チューナのサンプルで見つけることができます。このサンプルでは、KSPIN_MEDIUM は、チューナ、クロスバー、およびその他のチューナコンポーネント間の固有の接続を表します。

Flags メンバーには、クライアントが使用するシグナルの低下の種類に基づいて異なる値を含めることができます。品質管理参照してください。信号品質の低減による品質管理課題の解決に向けたさまざまな戦略の詳細を確認します。

Flags には ULONG 値が含まれているため、品質管理の問題を解決するために複数の Skip 要求が必要になる場合があります。

必要条件

要件	価値
ヘッダー	ks.h (Ks.h を含む)

次の方法で共有

KSIDENTIFIER 構造体 (ks.h)

構文

メンバーズ

備考

KSIDENTIFIER メンバーの説明

筆記

必要条件

関連項目

フィードバック

その他のリソース