为筛选器、引脚或节点指定设置属性请求的数据时,客户端经常需要了解它为属性指定的值或一组值的有效数据范围。 范围可能因设备而异,甚至可能因同一设备中的节点而异。
定义了一些属性,以允许“set-property”请求指定超出范围的值,但微型端口驱动程序会默默地将这些值限制在支持范围内(例如,请参阅KSPROPERTY_AUDIO_VOLUMELEVEL)。 对相同属性的后续获取请求,会检索驱动程序实际设置的值或值,这些值可能是客户端在设置请求中指定的值的限制版本。
但是,客户端可能需要知道属性值的范围,而不是仅仅依赖微型端口驱动程序来自动固定范围外值。 例如,为音频设备提供音量控制滑块的窗口化应用程序可能需要知道设备的音量范围,以便将该范围映射到滑块的全长。
特定属性的驱动程序处理程序例程应能够提供范围信息,以响应基本支持属性请求(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。
处理程序写入值缓冲区的属性特定信息可能包括属性值的数据范围。 MembersSize 成员在 KSPROPERTY_MEMBERSHEADER 中指示数据范围是否被包括:
如果不需要范围,则 MembersSize 为零。 例如,如果属性值的类型为 BOOL,则为这种情况。
如果 KSPROPERTY_MEMBERSHEADER 结构后面跟随一个或多个属性值的范围描述符,MembersSize 为非零。
对于 BOOL 类型的属性值,不需要范围描述符,因为范围隐式限制 为 TRUE 和FALSE 值。 但是,需要范围描述符来指定具有整数类型的属性值范围。
例如,音量节点上的 KSPROPERTY_AUDIO_VOLUMELEVEL 属性的基本支持请求(KSNODETYPE_VOLUME)检索该节点的最小和最大音量设置。 在这种情况下,客户端需要分配足够大的值缓冲区来包含以下结构:
这三个结构按前面列表中所示的顺序打包到缓冲区中的相邻位置。 处理请求时,微型端口驱动程序会将最小和最大音量级别写入 KSPROPERTY_STEPPING_LONG 结构的 Bounds 成员中。
有关包含范围描述符数组的基本支持请求的示例,请参阅 “公开多通道节点”中的图。 有关基本支持属性请求的详细信息,请参阅 KS 属性。 有关代码示例,请参阅 Microsoft Windows 驱动程序工具包(WDK)中 示例音频驱动程序 中的属性处理程序实现。