KsCreateFilterFactory 函数 (ks.h)

KsCreateFilterFactory** 函数将筛选器工厂添加到给定设备。

语法

KSDDKAPI NTSTATUS KsCreateFilterFactory(
  [in]            PDEVICE_OBJECT            DeviceObject,
  [in]            const KSFILTER_DESCRIPTOR *Descriptor,
  [in, optional]  PWSTR                     RefString,
  [in, optional]  PSECURITY_DESCRIPTOR      SecurityDescriptor,
  [in]            ULONG                     CreateItemFlags,
  [in, optional]  PFNKSFILTERFACTORYPOWER   SleepCallback,
  [in, optional]  PFNKSFILTERFACTORYPOWER   WakeCallback,
  [out, optional] PKSFILTERFACTORY          *FilterFactory
);

参数

[in] DeviceObject

指向要为其添加筛选器工厂的 DEVICE_OBJECT 结构的指针。

[in] Descriptor

指向描述此工厂可以创建的单个筛选器特征的 KSFILTER_DESCRIPTOR 的指针。

[in, optional] RefString

如果提供了此参数,此字符串将用作此工厂创建的筛选器的引用字符串。 否则,将使用描述符中提供的引用 GUID。

[in, optional] SecurityDescriptor

此筛选器工厂在创建筛选器时要使用的安全描述符。 如果 NULL,则不提供描述符。

[in] CreateItemFlags

下表列出了微型驱动程序编写器用来指定新筛选器工厂可以创建的筛选器的特征的标志。 将此参数设置为下面的标志的按位 OR。

意义
KSCREATE_ITEM_SECURITY_CHANGED 指示此对象类型的安全描述符已更改,应保留。
KSCREATE_ITEM_WILDCARD 指示此创建项表示用于与任何其他创建项不匹配的任何创建请求的通配符。 创建项列表中的通配符项的排序无关紧要。 在任何创建项列表中,只有一个通配符条目有效。
KSCREATE_ITEM_NOPARAMETERS 指示此创建项不允许传递任何参数,如果找到任何参数,则失败。 (通常,创建参数将传递给创建处理程序。此标志不能与通配符标志一起使用。
KSCREATE_ITEM_FREEONSTOP 指示当 PnP 管理器发送 IRP_MN_STOP_DEVICE时,应释放创建项。 请注意,当设备收到 PnP 停止时,AVStream 会自动释放此类创建项( 客户端收到 PnP 停止通知后)。

[in, optional] SleepCallback

指向微型驱动程序提供的例程的指针,该例程接收与此筛选器关联的设备将进入睡眠状态的通知。 对例程进行原型,如下所示:

void SleepCallback (IN PKSFILTERFACTORY FilterFactory,
    IN DEVICE_POWER_STATE State);

如果此参数 NULL,则不会通知此筛选器工厂设备进入睡眠状态。 请参阅 设备电源状态

[in, optional] WakeCallback

指向微型驱动程序提供的例程的指针,该例程接收与此筛选器关联的设备的通知正在唤醒。 对例程进行原型,如下所示:

void WakeCallback (IN PKSFILTERFACTORY FilterFactory,
    IN DEVICE_POWER_STATE State);

如果此参数 NULL,则不会通知此筛选器工厂设备正在唤醒。 请参阅 设备电源状态

[out, optional] FilterFactory

指向 AVStream 设置为指向新创建的筛选器工厂对象的 KSFILTERFACTORY 结构的指针。 如果未指定此可选参数,则调用方不会通知生成的筛选器工厂对象。

返回值

如果可以创建筛选器工厂,则返回STATUS_SUCCESS。 否则,它将返回适当的错误代码。

言论

如果在 AVStrMiniDevicePostStart后调用 KsCreateFilterFactory,则必须调用 KsFilterFactorySetDeviceClassesState 才能启用设备类。 (还调用 KsFilterFactorySetDeviceClassesState 禁用筛选器工厂。

如果在 AVStrMiniDevicePostStart 或之前上下文中调用 KsCreateFilterFactory,则无需执行此作。

在调用此函数之前,微型驱动程序必须获取设备互斥体。 有关如何执行此作的信息,请参阅 AVStream 中的设备互斥体。

此函数应由初始化自己的微型驱动程序使用,而无需调用 KsInitializeDriver,或者必须动态添加和删除新的筛选器类型。

要求

要求 价值
最低支持的客户端 Microsoft Windows XP 及更高版本的作系统以及 DirectX 8.0 及更高版本的 DirectX 版本中提供。
目标平台 普遍
标头 ks.h (包括 Ks.h)
Ks.lib
IRQL PASSIVE_LEVEL

另请参阅

KSFILTER_DESCRIPTOR

KSNODE_DESCRIPTOR

KSPIN_DESCRIPTOR_EX

KsDeleteFilterFactory