KsCreateFilterFactory function (ks.h)
The** KsCreateFilterFactory** function adds a filter factory to a given device.
Syntax
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
);
Parameters
[in] DeviceObject
A pointer to a DEVICE_OBJECT structure for which to add a filter factory.
[in] Descriptor
A pointer to a KSFILTER_DESCRIPTOR that describes the characteristics of individual filters that this factory can create.
[in, optional] RefString
If this argument is provided, this string is used as the reference string for filters created by this factory. Otherwise, the reference GUID provided in the descriptor is used.
[in, optional] SecurityDescriptor
The security descriptor to use in creation of filters by this filter factory. If NULL, no descriptor is provided.
[in] CreateItemFlags
The following table lists the flags that the minidriver writer uses to specify the characteristics of filters that the new filter factory can create. Set this parameter to the bitwise OR of the flags below.
| Flag | Meaning |
|---|---|
| KSCREATE_ITEM_SECURITY_CHANGED | Indicates that the security descriptor on this object type has been changed and should be persisted. |
| KSCREATE_ITEM_WILDCARD | Indicates that this create item represents a wildcard that is used for any create requests that do not match any other create items. The ordering of the wildcard entry in the list of create items is irrelevant. Only a single wildcard entry is valid on any list of create items. |
| KSCREATE_ITEM_NOPARAMETERS | Indicates that this create item does not allow any parameters to be passed, and fails if any are found. (Normally, create parameters are passed on to the create handler.) This flag cannot be used with a wildcard flag. |
| KSCREATE_ITEM_FREEONSTOP | Indicates that the create item should be freed when the PnP manager sends IRP_MN_STOP_DEVICE. Note that AVStream automatically frees such create items when the device receives PnP stop (after the client has received the PnP stop notification). |
[in, optional] SleepCallback
A pointer to a minidriver-provided routine that receives notifications that the device associated with this filter is going to sleep. Prototype the routine as follows:
void SleepCallback (IN PKSFILTERFACTORY FilterFactory,
IN DEVICE_POWER_STATE State);
If this parameter is NULL, this filter factory is not notified that the device is going to sleep. See Device Power States.
[in, optional] WakeCallback
A pointer to a minidriver-provided routine that receives notifications that the device associated with this filter is waking up. Prototype the routine as follows:
void WakeCallback (IN PKSFILTERFACTORY FilterFactory,
IN DEVICE_POWER_STATE State);
If this parameter is NULL, this filter factory is not notified that the device is waking up. See Device Power States.
[out, optional] FilterFactory
A pointer to a KSFILTERFACTORY structure that AVStream sets to point to the newly created filter factory object. If this optional parameter is unspecified, the caller is not informed about the resulting filter factory object.
Return value
Returns STATUS_SUCCESS if the filter factory can be created. Otherwise, it returns an appropriate error code.
Remarks
If you call KsCreateFilterFactory after AVStrMiniDevicePostStart), you must then call KsFilterFactorySetDeviceClassesState to enable the device class. (Also call KsFilterFactorySetDeviceClassesState to disable a filter factory.)
If you call KsCreateFilterFactory in the context of AVStrMiniDevicePostStart or before, you do not need to do this.
Before calling this function, the minidriver must obtain the device mutex. For information about how to do this, see Device Mutex in AVStream.
This function should be used by minidrivers that either initialize themselves without a call to KsInitializeDriver or that must dynamically add and remove new filter types.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Microsoft Windows XP and later operating systems and DirectX 8.0 and later DirectX versions. |
| Target Platform | Universal |
| Header | ks.h (include Ks.h) |
| Library | Ks.lib |
| IRQL | PASSIVE_LEVEL |