KSIDENTIFIER 结构（ks.h）

项目
02/07/2025

KSIDENTIFIER 结构指定唯一标识相关 GUID 集的 GUID，以及引用该集中特定成员的索引值。

KSDEGRADE、KSEVENT、KSMETHOD、KSPIN_INTERFACE、KSPIN_MEDIUM和 KSPROPERTY typedefs 是 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。大小为零表示不需要序列化属性。
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以接收排队的事件通知。
KSEVENT_TYPE_TOPOLOGY	指示传递的事件的类型为 KSE_NODE，其中 NodeId 指示拓扑节点的数字 ID。请勿自行设置此标志;而是使用此列表中的其他标志进行 OR。
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 成员是拓扑节点的标识符。请勿自行设置此标志;而是使用此列表中的其他标志进行 OR。

对于 KSDEGRADE，指定当前降级百分比（以每千部分表示（其中值 1000 表示无降级），或指定接口指定的本机单位的时间量。

Alignment

未使用。未命名联合的成员，用于强制对未命名结构进行适当的对齐。

笔记

有关用法的具体细节，请参阅 KSDEGRADE、KSEVENT、KSMETHOD、KSPIN_INTERFACE、KSPIN_MEDIUM和 KSPROPERTY typedef 主题。

使用集中的 ID 允许对集标识符执行单个大型比较，然后执行较小的快速比较（例如，使用开关语句对集中的标识符）。例如，属性集 由唯一 GUID 标识符引用，该集中的属性由短 ID 引用。

方法、事件、接口和 中等集 可视为集的“类”。

传递的输出缓冲区的大小决定了从KSPROPERTY_TYPE_BASICSUPPORT请求返回的数据。如果输出缓冲区是 ULONG 的大小，则仅返回访问标志。如果输出缓冲区是 KSPROPERTY_DESCRIPTION 结构的大小，则结构将填充访问标志、整个值信息的包含大小、属性值类型信息以及对应于结构的成员列表数。

对于KSPROPERTY_TYPE_RELATIONS请求，返回的数据也取决于输出缓冲区的大小。如果输出缓冲区大小为零，则返回相关属性所需的大小以 BytesReturned 返回，其警告状态为STATUS_BUFFER_OVERFLOW。如果缓冲区是 KSMULTIPLE_ITEM 结构的大小，则返回字节大小和关系计数。否则，缓冲区应足够长，以返回KSMULTIPLE_ITEM结构和所有相关属性标识符，该标识符作为 KSIDENTIFIER 结构的列表返回。

KSPROPERTY_TYPE_SERIALIZESET和KSPROPERTY_TYPE_UNSERIALIZESET请求允许与来自客户端的单个调用与多个属互。如果内核流式处理处理程序用于处理属性请求，KsPropertyHandler 函数将这些处理程序分解为多个调用。使用此处理程序时，属性集定义控制要序列化哪些属性。

对于序列化请求，将检查相关 KSPROPERTY_ITEM 结构的 SerializedSize 成员，以获取指示属性的大小（以字节为单位）的非零值。如果 SerializedSize 成员的值为 1，则为未知且必须查询（所有未知属性以可以单独查询KSMULTIPLE_ITEM结构开头）。若要查询序列化所需的总大小，客户端将在调用 DeviceIoControl中传递零长度缓冲区。 BytesReturned 然后返回缓冲区必须序列化集的大小以及STATUS_BUFFER_OVERFLOW的警告状态。然后，分配了该大小的缓冲区可以填充序列化的数据。

序列化缓冲区的格式是 KSPROPERTY_SERIALHDR，后跟序列化属性。后面的每个属性都包含一个标头（KSPROPERTY_SERIAL），后跟属性数据，FILE_LONG_ALIGNMENT上每个属性的开头。请注意，串行标头结构定义为FILE_LONG_ALIGNMENT。

如果存在属性项处理程序，则支持KSPROPERTY_TYPE_SERIALIZERAW和KSPROPERTY_TYPE_UNSERIALIZERAW。 KsPropertyHandler 函数调用微型驱动程序提供的处理程序。还可以通过将零长度缓冲区传递给序列化原始请求来查询序列化所需的缓冲区大小。由于处理程序附加到属性项而不是属性集，因此必须在属性参数中指定属性集中的特定项。此处理程序可以处理集中的多个属性。

Microsoft提供了多个系统定义的属性集 GUID。微型驱动程序在集成员中指定这些 GUID 之一。内核流式处理属性集通常以 KSPROPSETID 或 PROPSETID 前缀开头。内核流式处理属性集在 ks.h、ksmedia.h、bdamedia.h中定义，以及其他头文件。

有关内核流式处理属性的详细信息，请参阅 KS 属性、事件和方法。

Microsoft提供了多个系统定义的事件集 GUID。微型驱动程序在集成员中指定这些 GUID 之一。内核流式处理事件集通常以 KSEVENTSETID 前缀开头。内核流式处理事件集在 ks.h、ksmedia.h、bdamedia.h中定义，以及其他头文件。

有关内核流式处理事件的详细信息，请参阅 KS 属性、事件和方法。

Microsoft提供了多个系统定义的方法集 GUID。微型驱动程序在集成员中指定这些 GUID 之一。内核流式处理方法集通常以 KSMETHODSETID 前缀开头。内核流式处理方法集在 ks.h、ksmedia.h、bdamedia.h和可能的其他头文件中定义。

有关内核流式处理方法的详细信息，请参阅 KS 属性、事件和方法。

客户端可以使用IOCTL_KS_METHOD请求和 KSMETHOD 结构在微型驱动程序处理的内核流对象上执行方法。有关详细信息，请参阅 KS 方法。

KSPIN_MEDIUM 结构使用唯一的中等 GUID 和实例标识符（以特定于总线的方式生成）标识介质。当总线实例不关心时，可以使用保留标识符值KSMEDIUM_TYPE_ANYINSTANCE。例如，KSMEDIUMSETID_Standard是指系统总线，其中应该只有一个。因此，此实例标识符始终用作方便。

引脚可能支持这些介质上的多个介质和接口。描述引脚的方式意味着在为引脚枚举的所有介质上都支持接口列表。如果存在这种情况，则可能会使用另一个引脚来描述特定介质的每个接口子集。

该介质还通过内核流式处理进行缓存，以加快搜索可能的连接速度。

可以在优化器示例中找到使用此结构的示例，其中 KSPIN_MEDIUM 表示优化器、交叉条和其他优化器组件之间的唯一连接。

标志成员可以根据客户端使用的信号降级类型包含不同的值。请参阅质量控制。有关通过降低信号质量解决质量控制问题的不同策略的更多详细信息。

由于标志包含 ULONG 值，因此可能需要多个 Skip 请求来纠正质量控制问题。