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 | 指示此创建项不允许传递任何参数，如果找到任何参数，则失败。 (通常，创建参数将传递给 create handler。) 此标志不能与通配符标志一起使用。 |
| KSCREATE_ITEM_FREEONSTOP | 指示在 PnP 管理器发送 IRP_MN_STOP_DEVICE时应释放创建项。 请注意，在客户端收到 PnP 停止通知) 后，当设备收到 PnP 停止 (时 ，AVStream 会自动释放此类创建项。 |
[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
指向 KSFILTERFACTORY 结构的指针，AVStream 将其设置为指向新创建的筛选器工厂对象。 如果未指定此可选参数，则不会通知调用方生成的筛选器工厂对象。
返回值
如果可以创建筛选器工厂，则返回STATUS_SUCCESS。 否则，它将返回相应的错误代码。
注解
如果在 AVStrMiniDevicePostStart) 之后调用 KsCreateFilterFactory，则必须调用 KsFilterFactorySetDeviceClassesState 以启用设备类。 (还调用 KsFilterFactorySetDeviceClassesState 以禁用筛选器工厂。)
如果在 AVStrMiniDevicePostStart 或之前调用 KsCreateFilterFactory，则无需执行此操作。
在调用此函数之前，微型驱动程序必须获取设备互斥体。 有关如何执行此操作的信息，请参阅 AVStream 中的设备互斥。
此函数应由无需调用 KsInitializeDriver 或必须动态添加和删除新筛选器类型的微型驱动程序使用。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | 在 Microsoft Windows XP 及更高版本的操作系统以及 DirectX 8.0 及更高版本的 DirectX 中可用。 |
| 目标平台 | 通用 |
| 标头 | ks.h (包括 Ks.h) |
| Library | Ks.lib |
| IRQL | PASSIVE_LEVEL |