KSPROPERTY 结构

项目
02/07/2024

KSPROPERTY 结构指定属性集中的单个内核流属性。

KSEVENT、KSMETHOD 和 KSPROPERTY 结构是 KSIDENTIFIER 结构的别名。因此，它们的定义是相同的。

语法

struct KSPROPERTY {
  GUID Set;
  ULONG Id;
  ULONG Flags;
};

成员

Set

指定标识内核流式处理属性集的 GUID。有关属性集 GUID 的详细信息，请参阅下面的 “备注 ”部分。

Id

指定属性集的成员。

Flags

指定请求类型。如果要编写流类微型驱动程序，另请参阅 KSPROPERTY_ITEM 以获取特定于类的标志信息。

标志应为下表中列出的值之一。某些标志可以使用按位 OR 运算进行组合。

值	说明
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的反函数。

注解

传递的输出缓冲区的大小决定了从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 属性、事件和方法。