音频属性的基本支持查询
为筛选器、引脚或节点指定 set-property 请求的数据时,客户端经常需要知道它为属性指定的一个或多个值的有效数据范围。 范围可能因设备而异,甚至可能因同一设备中的节点而异。
定义了一些属性以允许 set-property 请求指定超出范围的值,但微型端口驱动程序以无提示方式将这些值固定到受支持的范围(例如,请参阅 KSPROPERTY_AUDIO_VOLUMELEVEL)。 对同一属性的后续 get 请求会检索驱动程序的一个或多个值的实际设置,这个/这些值这可能是客户端在 set 请求中指定的值的固定版本。
但是,客户端可能需要知道属性值的范围,而不是仅仅依赖微型端口驱动程序自动固定超出范围的值。 例如,为音频设备提供音量控件滑块的窗口化应用程序可能需要知道设备的音量范围,以便将该范围映射到滑块的全长。
驱动程序为特定属性指定的处理程序例程应该能够提供范围信息,以响应基本支持属性请求 (KSPROPERTY_TYPE_BASICSUPPORT)。 向驱动程序发送基本支持属性请求时,客户端会提供一个值缓冲区,属性处理程序将基本支持信息写入其中,该信息由可能后跟属性特定数据的 KSPROPERTY_DESCRIPTION 结构组成。 此数据通常由一个或多个参数范围的规范组成,具体取决于属性。
通常,客户端事先不知道此值缓冲区的大小,必须向属性处理程序发送一两个初步请求以确定值大小。 这些初步请求的格式定义良好。 客户端期望驱动程序在处理基本支持请求时遵循以下约定:
如果该请求将值大小指定为 sizeof (ULONG),则属性处理程序应将 KSPROPERTY_DESCRIPTION 结构的 AccessFlags 成员的值写入 ULONG 大小的值缓冲区中。 如果处理程序为基本支持属性请求提供进一步的支持,则会设置 KSPROPERTY_TYPE_BASICSUPPORT 标志位。
如果该请求将值大小指定为 sizeof (KSPROPERTY_DESCRIPTION),处理程序应将 KSPROPERTY_DESCRIPTION 结构写入数据缓冲区。 处理程序将结构的 DescriptionSize 字段设置为等于该结构的大小加上处理程序在结构后面加载到数据缓冲区中的所有附加属性特定信息的大小。 这是客户端需要分配的值缓冲区的大小,以包含属性的基本支持信息。
如果请求指定了足够大的值大小来包含 KSPROPERTY_DESCRIPTION 结构和属性特定信息,则处理程序应将 KSPROPERTY_DESCRIPTION 结构写入缓冲区的开头,并将特定于属性的信息写入 KSPROPERTY_DESCRIPTION 结构末尾之后的数据缓冲区部分。 编写 KSPROPERTY_DESCRIPTION 结构时,处理程序应将 DescriptionSize 字段设置为该结构的大小加上该结构后面属性特定信息的大小。
如果请求指定的值大小与这三种情况之一不匹配,则属性处理程序将拒绝请求并返回状态代码 STATUS_BUFFER_TOO_SMALL。
处理程序写入值缓冲区的属性特定信息可能包括属性值的数据范围。 KSPROPERTY_MEMBERSHEADER 的 MembersSize 成员会指示是否包含数据范围:
如果不需要任何范围,则 MembersSize 为零。 例如,如果属性值的类型为 BOOL,则为这种情况。
如果 KSPROPERTY_MEMBERSHEADER 结构后跟一个或多个属性值的范围描述符,则 MembersSize 为非零。
对于 BOOL 类型的属性值,不需要范围描述符,因为范围隐式限制为 TRUE 和 FALSE 值。 但是,需要范围描述符来指定具有整数类型的属性值范围。
例如,音量节点 (KSNODETYPE_VOLUME) 上 KSPROPERTY_AUDIO_VOLUMELEVEL 属性的基本支持请求会检索该节点的最小和最大音量设置。 在这种情况下,客户端需要分配足够大的值缓冲区来包含以下结构:
这三个结构按前面列表中所示的顺序打包到缓冲区中的相邻位置。 处理请求时,微型端口驱动程序会将最小和最大音量级别写入 KSPROPERTY_STEPPING_LONG 结构的 Bounds 成员。
有关包含范围描述符数组的基本支持请求的示例,请参阅公开多声道节点中的图。 有关基本支持属性请求的详细信息,请参阅 KS 属性。 有关代码示例,请参阅 Microsoft Windows 驱动程序工具包 (WDK) 中示例音频驱动程序中的属性处理程序实现。