KSIDENTIFIER 结构 (ks.h)

项目
08/07/2023

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	返回一个 ULONG，指定作为KSPROPERTY_TYPE_SERIALIZESET请求的一部分进行序列化时的属性数据的大小。如果大小为零，则表示不需要序列化属性。
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发出第二个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

未使用。未命名联合的成员，用于在未命名的结构上强制正确对齐。

备注

有关使用情况的详细信息，请参阅 KSDEGRADE、 KSEVENT、 KSMETHOD、 KSPIN_INTERFACE、 KSPIN_MEDIUM 和 KSPROPERTY typedef 主题。

在集中使用 ID 允许对集标识符执行单个大型比较，然后较小的快速比较 (例如，对集) 中的标识符使用 switch 语句。例如， 属性集 由唯一 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 函数调用微型驱动程序提供的处理程序。还可以通过将零长度缓冲区传递给序列化原始请求来查询序列化所需的缓冲区大小。由于处理程序附加到属性项而不是属性集，因此必须在 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是指系统总线，其中应只有一个。因此，为了方便起见，始终使用此实例标识符。

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

媒体还通过内核流式处理缓存，以加快搜索可能的连接的速度。

可以在调谐器示例中找到此结构的示例，其中 KSPIN_MEDIUM 表示调谐器、横梁和其他调谐器组件之间的唯一连接。

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

由于 Flags 包含 ULONG 值，因此可能需要多个 Skip 请求来修复质量管理问题。