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 參數會傳遞至 create handler。) 此旗標無法與通配符旗標搭配使用。 |
| 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 以停用篩選 Factory.)
如果您在AVStrMiniDevicePostStart的內容中呼叫 KsCreateFilterFactory，則不需要這麼做。
呼叫此函式之前，迷你驅動程序必須取得裝置 Mutex。 如需如何執行這項操作的詳細資訊，請參閱 AVStream中的Device Mutex。
迷你驅動程式應該使用這個函式，以在不呼叫 KsInitializeDriver 的情況下自行初始化，或是必須動態新增和移除新的篩選類型。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 適用於 Microsoft Windows XP 和更新版本的作業系統和 DirectX 8.0 和更新版本的 DirectX。 |
| 目標平台 | Universal |
| 標頭 | ks.h (包含 Ks.h) |
| 程式庫 | Ks.lib |
| IRQL | PASSIVE_LEVEL |