KSFILTER_DESCRIPTOR 结构 (ks.h)

项目
02/26/2024

KSFILTER_DESCRIPTOR 结构描述由给定筛选器工厂创建的筛选器的特征。

语法

typedef struct _KSFILTER_DESCRIPTOR {
  const KSFILTER_DISPATCH     *Dispatch;
  const KSAUTOMATION_TABLE    *AutomationTable;
  ULONG                       Version;
  ULONG                       Flags;
  const GUID                  *ReferenceGuid;
  ULONG                       PinDescriptorsCount;
  ULONG                       PinDescriptorSize;
  const KSPIN_DESCRIPTOR_EX   *PinDescriptors;
  ULONG                       CategoriesCount;
  const GUID                  *Categories;
  ULONG                       NodeDescriptorsCount;
  ULONG                       NodeDescriptorSize;
  const KSNODE_DESCRIPTOR     *NodeDescriptors;
  ULONG                       ConnectionsCount;
  const KSTOPOLOGY_CONNECTION *Connections;
  const KSCOMPONENTID         *ComponentId;
} KSFILTER_DESCRIPTOR, *PKSFILTER_DESCRIPTOR;

成员

Dispatch

指向此类型筛选器 的KSFILTER_DISPATCH 结构的指针。此成员是可选的，只需要由希望接收有关筛选器创建、删除等通知的客户端提供。对处理数据 (转换) 的驱动程序通常提供此调度表和处理函数。提供筛选器处理函数而不是单个引脚处理函数，使驱动程序以筛选器为中心，而不是以引脚为中心。

AutomationTable

指向此类型筛选器 KSAUTOMATION_TABLE 结构的指针。自动化表描述了此筛选器支持的属性、方法和事件。此自动化表与 AVStream 为所有筛选器提供的自动化表合并。如果客户端提供已由 AVStream 实现的属性、方法或事件处理程序，则客户端的实现将取代 AVStream 的。

Version

此成员指定筛选器描述符的版本。此成员应设置为 KSFILTER_DESCRIPTOR_VERSION。

Flags

描述筛选器行为的标志。使用按位 OR 指定标志，KSFILTER_FLAG_CRITICAL_PROCESSING和KSFILTER_FLAG_HYPERCRITICAL_PROCESSING除外，它们互斥：

标志	描述
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING	指示 IRQL 中的筛选器进程DISPATCH_LEVEL而不是PASSIVE_LEVEL。这适用于 KSFILTER_DISPATCH中所述的筛选器进程回调。
KSFILTER_FLAG_CRITICAL_PROCESSING	如果已指定异步处理，或者系统在PASSIVE_LEVEL运行，并且进程调用在DISPATCH_LEVEL传入，则会在排队的工作项中完成处理。此标志指示应将工作项置于关键工作队列而不是延迟工作队列中。
KSFILTER_FLAG_RECEIVE_ZERO_LENGTH_SAMPLES	如果以筛选器为中心的筛选器需要接收具有标志的流标头 (零长度样本，但没有数据) ，请设置此标志。如果未设置此标志，则将零长度样本传递到下游引脚，并自动传播必要的标志。请注意，这与 DX8 和以前的默认行为相同。如果发生这种情况，这些示例将绕过微型驱动程序。在 KSPROCESSPIN 中设置 Terminate 标志以“关闭”此标志。另请参阅以筛选器为中心的处理。
KSFILTER_FLAG_DENY_USERMODE_ACCESS	此标志阻止用户模式访问特定筛选器和在此筛选器上实例化的所有引脚。
KSFILTER_FLAG_HYPERCRITICAL_PROCESSING	如果已指定异步处理，或者系统在 PASSIVE_LEVEL 运行并在DISPATCH_LEVEL传入进程调用，AVStream 将处理排队的工作项。此标志指示工作项应放置在超关键工作队列上，而不是延迟的工作队列或关键工作队列。

ReferenceGuid

指向 GUID 的指针，该 GUID 是标识此筛选器类型的 Unicode 引用字符串的二进制表示形式。如果存在多个筛选器工厂，则每个筛选器工厂必须具有唯一的 GUID。另请注意，提供引用字符串的其他方法需要使用 KsCreateFilterFactory 注册筛选器描述符。 ReferenceGuid 中指定的值必须与驱动程序 INF 文件中特定于筛选器的引用 GUID 匹配。请参阅初始化 AVStream 微型驱动程序。

PinDescriptorsCount

此成员指定 PinDescriptors 成员中为此筛选器类型提供的引脚描述符数。在 Windows XP 及更高版本中，如果驱动程序动态创建固定， PinDescriptorsCount 可能为零。

PinDescriptorSize

此成员指定描述符表中每个单独描述符的大小。此值必须是 8 的倍数，并且 大小必须至少 为 (KSPIN_DESCRIPTOR_EX) 。较大的值允许将特定于客户端的描述符信息追加到引脚描述符。请参阅备注中的其他信息。

PinDescriptors

指向描述此筛选器类型支持的引脚的 KSPIN_DESCRIPTOR_EX 结构数组的指针。如果 PinDescriptorsCount 为零，请将此成员设置为 NULL。

CategoriesCount

此成员指定此筛选器类型的 Categories 成员中提供的类别 GUID 的数量。零是此成员的合法值。

Categories

指向此筛选器类型的类别 GUID 数组的指针。如果需要，将为每个类别注册一个设备接口。当且仅当 CategoriesCount 为零时，此成员可能为 null。

NodeDescriptorsCount

此成员指定 NodeDescriptors 中提供的拓扑节点描述符的数量。零是此成员的合法值。

NodeDescriptorSize

此成员指定描述符表中每个单独描述符的大小（以字节为单位）。此值必须是 8 的倍数，且大小至少为 (KSNODE_DESCRIPTOR) 。较大的值允许将特定于客户端的描述符信息追加到节点描述符。请参阅备注中的其他信息。

NodeDescriptors

指向描述此筛选器类型的拓扑节点的 KSNODE_DESCRIPTOR 结构的数组的指针。当且仅当 NodeDescriptorsCount 为零时，此成员可能为 null。

ConnectionsCount

此成员指定Connections中存在的拓扑连接数。此成员可以为零，表示使用了默认连接集。使用默认连接意味着使用单个拓扑节点描述筛选器的拓扑，其中筛选器上的每个引脚都连接到拓扑节点上的相应 ID。每个连接的方向由引脚数据流确定。

Connections

指向此筛选器类型中存在的 KSTOPOLOGY_CONNECTION 结构的数组的指针。此成员是可选的;当且仅当 ConnectionsCount 为零时，它可能为 NULL (在这种情况下，默认拓扑) 使用。

ComponentId

指向此筛选器类型的 KSCOMPONENTID 结构的指针。这用于提供标识信息的组件 ID 属性。此成员是可选的。

注解

在布局筛选器描述符时，调用方可能会发现许多宏很有用。有许多有用的宏，而不是为引脚描述符、类别、节点描述符和连接指定计数、大小和表：

宏	说明
DEFINE_KSFILTER_PIN_DESCRIPTORS (表)	自动将表中的项数、表中每个项的大小以及固定描述符表本身插入筛选器描述符。
DEFINE_KSFILTER_CATEGORIES (表)	自动将表和表本身的类别数插入筛选器描述符。
DEFINE_KSFILTER_CATEGORIES_NULL	自动填充不定义任何类别的筛选器的类别成员。
DEFINE_KSFILTER_NODE_DESCRIPTORS (表)	自动将表中的项数、表中每个项的大小以及节点描述符表本身插入筛选器描述符中。
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL	自动填充不定义拓扑节点的筛选器的节点描述符成员。
DEFINE_KSFILTER_CONNECTIONS (表)	自动将表中的连接数和表本身插入筛选器描述符。
DEFINE_KSFILTER_DEFAULT_CONNECTIONS	自动填充没有显式连接的筛选器的连接表。