KSPROPERTY_ITEM 结构 (ks.h)

项目
06/01/2023

驱动程序使用 KSPROPERTY_ITEM 结构来描述它们如何支持属性集中的属性。

语法

typedef struct {
  ULONG                   PropertyId;
  union {
    PFNKSHANDLER GetPropertyHandler;
    BOOLEAN      GetSupported;
  };
  ULONG                   MinProperty;
  ULONG                   MinData;
  union {
    PFNKSHANDLER SetPropertyHandler;
    BOOLEAN      SetSupported;
  };
  const KSPROPERTY_VALUES *Values;
  ULONG                   RelationsCount;
  const KSPROPERTY        *Relations;
  PFNKSHANDLER            SupportHandler;
  ULONG                   SerializedSize;
} KSPROPERTY_ITEM, *PKSPROPERTY_ITEM;

成员

PropertyId

指定要描述的属性的 ID。

GetPropertyHandler

指向微型驱动程序提供的 KStrGetPropertyHandler 的指针。如果 为 NULL，则无法读取属性。此成员仅由使用 AVStream 或 Stream 类接口的驱动程序使用。

GetSupported

如果此属性支持获取请求，则设置为 TRUE ;如果不支持，则设置为 FALSE 。 (类驱动程序通过SRB_GET_DEVICE_PROPERTY或SRB_GET_STREAM_PROPERTY requests 满足请求。) 此成员仅由在流类下运行的微型驱动程序使用。

MinProperty

指定用于保存属性标识符的最小缓冲区长度。此大小必须至少为 (KSPROPERTY) 。

MinData

指定用于保存从此属性读取或写入到此属性的数据的最小缓冲区长度。

SetPropertyHandler

指向微型驱动程序提供的 KStrSetPropertyHandler 的指针。如果 为 NULL，则无法设置属性。此成员仅由使用 AVStream 或 Stream 类接口的驱动程序使用。

SetSupported

如果此属性支持设置的请求，则设置为 TRUE ;如果不支持，则设置为 FALSE 。 (类驱动程序通过SRB_SET_DEVICE_PROPERTY或SRB_SET_STREAM_PROPERTY请求满足请求。)

Values

指向 KSPROPERTY_VALUES 类型的结构的指针。指定属性的可接受和/或默认值。这些值与驱动程序为响应IOCTL_KS_PROPERTY请求而报告的值相同，并设置了KSPROPERTY_TYPE_BASICSUPPORT和KSPROPERTY_TYPE_DEFAULTVALUES标志。

RelationsCount

指定 Relations 成员指向的数组中的条目数。

Relations

指向表示与此相关的属性的 KSPROPERTY 结构的数组。如果更改一个属性可能会影响另一个属性的值，则两个属性被视为相关属性。每个条目的 Flags 成员未使用。

SupportHandler

仅当为原始序列化或原始非序列化实现自己的格式时，才提供此成员。基本支持查询、范围查询和关系查询由 AVStream 自动处理，这将从此KSPROPERTY_ITEM结构的其他成员返回相关值。

SerializedSize

指定在KSPROPERTY_TYPE_SERIALIZESET请求中序列化时属性的大小。如果无法序列化属性，则此值应为零。有关详细信息，请参阅 KSPROPERTY 。

注解

Stream类微型驱动程序使用 KSPROPERTY_ITEM 向客户端描述如何对集内每个属性执行属性请求。在包含指向KSPROPERTY_ITEM结构数组的指针的 KSPROPERTY_SET 结构中指定了对属性集整体的处理。

流类驱动程序代表微型驱动程序处理属性请求。当流类驱动程序需要微型驱动程序提供更多信息时，它将SRB_XXX请求传递给微型驱动程序的 StrMiniReceiveXXXRequest 例程之一。流类驱动程序处理下表中列出的不同请求类型。

属性请求标志值	响应
KSPROPERTY_TYPE_GET	如果 GetSupported 为 TRUE，则流类驱动程序会将 SRB_GET_DEVICE_PROPERTY 或 SRB_GET_STREAM_PROPERTY 请求提交到相应的微型驱动程序 StrMiniReceiveXXXRequest 例程。
KSPROPERTY_TYPE_SET	如果 SetSupported 为 TRUE，则流类驱动程序会将 SRB_SET_DEVICE_PROPERTY 或 SRB_SET_STREAM_PROPERTY 请求提交到相应的微型驱动程序 StrMiniReceiveXXXRequest 例程。
KSPROPERTY_TYPE_BASICSUPPORT	流类驱动程序使用 KSPROPERTY_ITEM 获取满足此请求所需的信息。例如，若要指定属性数据的数据类型和允许的范围，它们都使用此结构的 Values 成员。
KSPROPERTY_TYPE_SETSUPPORT	仅当流类驱动程序为其KSPROPERTY_SET结构中设置的属性提供条目时，流类驱动程序才会以 STATUS_SUCCESS 的形式完成属性请求 IRP。
KSPROPERTY_TYPE_DEFAULTVALUES	流类驱动程序使用此结构的 Values 成员来确定属性数据的默认值。
KSPROPERTY_TYPE_RELATIONS	流类驱动程序使用 Relations 成员来确定哪些属性与此属性相关。

如果客户端指定KSPROPERTY_TYPE_DEFAULTVALUES，则驱动程序使用数据缓冲区返回其值类型的说明，包括可能允许的范围和默认值。此标志的结果与KSPROPERTY_TYPE_BASICSUPPORT类似，只不过返回的任何值都是在结构KSPROPERTY_MEMBERSHEADER的 Flags 成员中用KSPROPERTY_MEMBER_FLAG_DEFAULT标记的值。

有关详细信息，请参阅 KS 属性。