KsCreateFilterFactory function (ks.h)

Article
03/15/2022

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