KSPROPERTY 结构

KSPROPERTY结构指定属性集内的单个内核流式处理属性。

KSEVENTKSMETHODKSPROPERTY结构是KSIDENTIFIER结构的别名。 因此,它们的定义是相同的。

语法

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

成员

Set

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

Id

指定属性集的成员。

Flags

指定请求类型。 如果要编写 stream 类微型驱动程序,请参阅类特定标志信息的 KSPROPERTY_ITEM

Flags 应为下表中列出的值之一。 某些标志可以使用按位 "或" 运算组合在一起。

说明
KSPROPERTY_TYPE_GET 检索指定属性项的值。
KSPROPERTY_TYPE_SET 设置指定属性项的值。
KSPROPERTY_TYPE_SETSUPPORT 查询驱动程序是否支持此属性集。
KSPROPERTY_TYPE_BASICSUPPORT 查询驱动程序为此属性项处理的请求类型。 返回 KSPROPERTY_TYPE_GETKSPROPERTY_TYPE_SET 。 所有属性集都必须支持此标志。
KSPROPERTY_TYPE_DEFAULTVALUES 查询指定属性项的默认值。 返回 KSPROPERTY_VALUES类型的结构。
KSPROPERTY_TYPE_RELATIONS 查询具有此属性的当前设置的依赖项的所有属性。 指定要返回的属性关系列表,或此类列表(如果返回缓冲区为 ULONG 的大小)所需的缓冲区空间量。 每个元素都位于 FILE_QUAD_ALIGNMENT上, KSMULTIPLE_ITEM 结构之前。 通常,在查询对属性集的支持时,这是无效的。 所有属性集都必须支持此标志。
KSPROPERTY_TYPE_SERIALIZESET 使用标准 KSPROPERTY_SERIALHDRKSPROPERTY_SERIAL 结构序列化属性集。
KSPROPERTY_TYPE_UNSERIALIZESET 使用标准 KSPROPERTY_SERIALHDRKSPROPERTY_SERIAL 结构 Unserialize 属性集。
KSPROPERTY_TYPE_SERIALIZESIZE 当序列化为 KSPROPERTY_TYPE_SERIALIZESET 请求的一部分时,返回指定属性数据大小的 ULONG。 如果大小为零,则表示属性不需要进行序列化。
KSPROPERTY_TYPE_SERIALIZERAW 指定属性集支持处理程序(如果存在)应序列化此集中的属性。 否则,调用将失败。 序列化格式是私有的。 此操作必须是 KSPROPERTY_TYPE_UNSERIALIZERAW的反向操作。
KSPROPERTY_TYPE_TOPOLOGY 传递的属性的类型为 KSP_NODE,其中节点 ID 指示拓扑节点的数值 ID。 请勿自行设置此标志;而应为此表中的其他标志。
KSPROPERTY_TYPE_UNSERIALIZERAW 指定所提供的缓冲区包含属于此集的一组属性,这些属性应由属性集支持处理程序 unserialized (如果存在)。 否则,调用将失败。 序列化格式是私有的。 此操作必须是 KSPROPERTY_TYPE_SERIALIZERAW的反向操作。

备注

传递的输出缓冲区的大小决定 KSPROPERTY_TYPE_BASICSUPPORT 请求返回的数据。 如果输出缓冲区的大小为 ULONG,则仅返回访问标志。 如果输出缓冲区是 KSPROPERTY_DESCRIPTION 结构的大小,则将使用访问标志、整个值信息的非独占大小、属性值类型信息和与结构相对应的成员列表来填充结构。

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

KSPROPERTY_TYPE_SERIALIZESETKSPROPERTY_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_SERIALIZERAWKSPROPERTY_TYPE_UNSERIALIZERAWKsPropertyHandler函数调用微型驱动程序提供的处理程序。 还可以通过将长度为零的缓冲区传递到序列化的原始请求来查询序列化所需的缓冲区大小。 由于处理程序附加到属性项而不是属性集,因此属性集内的特定项必须在 属性 参数中指定。 此处理程序可以处理集内的多个属性。

Microsoft 提供了多个系统定义的属性集 Guid。 微型驱动程序在 成员中指定这些 guid 之一。 内核流式处理属性集通常以 KSPROPSETIDPROPSETID 前缀开头。 在 ksksmediabdamedia和可能的其他头文件中定义内核流属性集。

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

要求

标头: ks .h (包含 ks .h)

另请参阅

KSEVENT

KSMETHOD

KSIDENTIFIER

KSMETHOD_ITEM

KSE_NODE

KSPROPERTY_DESCRIPTION

KSPROPERTY_ITEM

KSMULTIPLE_ITEM

KsPropertyHandler

KSPROPERTY_SERIALHDR

KSPROPERTY_SERIAL