KsCreateFilterFactory function

The KsCreateFilterFactory function adds a filter factory to a given device.

Syntax


NTSTATUS KsCreateFilterFactory(
  _In_            PDEVICE_OBJECT          DeviceObject,
  _In_      const KSFILTER_DESCRIPTOR     *Descriptor,
  _In_opt_        PWSTR                   RefString,
  _In_opt_        PSECURITY_DESCRIPTOR    SecurityDescriptor,
  _In_            ULONG                   CreateItemFlags,
  _In_opt_        PFNKSFILTERFACTORYPOWER SleepCallback,
  _In_opt_        PFNKSFILTERFACTORYPOWER WakeCallback,
  _Out_opt_       PKSFILTERFACTORY        *FilterFactory
);

Parameters

DeviceObject [in]

A pointer to a DEVICE_OBJECT structure for which to add a filter factory.

Descriptor [in]

A pointer to a KSFILTER_DESCRIPTOR that describes the characteristics of individual filters that this factory can create.

RefString [in, optional]

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.

SecurityDescriptor [in, optional]

The security descriptor to use in creation of filters by this filter factory. If NULL, no descriptor is provided.

CreateItemFlags [in]

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.

FlagMeaning

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).

 

SleepCallback [in, optional]

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.

WakeCallback [in, optional]

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.

FilterFactory [out, optional]

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

Target platform

Universal

Version

Available in Microsoft Windows XP and later operating systems and DirectX 8.0 and later DirectX versions.

Header

Ks.h (include Ks.h)

Library

Ks.lib

IRQL

PASSIVE_LEVEL

See also

KsDeleteFilterFactory
KSFILTER_DESCRIPTOR
KSPIN_DESCRIPTOR_EX
KSNODE_DESCRIPTOR

 

 

Send comments about this topic to Microsoft

Show: