KsCreateFilterFactory, fonction (ks.h)

La fonction KsCreateFilterFactory** ajoute une fabrique de filtre à un appareil donné.

Syntaxe

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

Paramètres

[in] DeviceObject

Pointeur vers une structure DEVICE_OBJECT pour laquelle ajouter une fabrique de filtre.

[in] Descriptor

Pointeur vers un KSFILTER_DESCRIPTOR qui décrit les caractéristiques des filtres individuels que cette fabrique peut créer.

[in, optional] RefString

Si cet argument est fourni, cette chaîne est utilisée comme chaîne de référence pour les filtres créés par cette fabrique. Sinon, le GUID de référence fourni dans le descripteur est utilisé.

[in, optional] SecurityDescriptor

Descripteur de sécurité à utiliser lors de la création de filtres par cette fabrique de filtres. Si NULL, aucun descripteur n’est fourni.

[in] CreateItemFlags

Le tableau suivant répertorie les indicateurs que l’enregistreur minidriver utilise pour spécifier les caractéristiques des filtres que la nouvelle fabrique de filtres peut créer. Définissez ce paramètre sur l’OR au niveau du bit des indicateurs ci-dessous.

Indicateur Signification
KSCREATE_ITEM_SECURITY_CHANGED Indique que le descripteur de sécurité sur ce type d’objet a été modifié et doit être conservé.
KSCREATE_ITEM_WILDCARD Indique que cet élément de création représente un caractère générique utilisé pour toutes les demandes de création qui ne correspondent à aucun autre élément de création. L’ordre de l’entrée générique dans la liste des éléments de création n’est pas pertinent. Seule une seule entrée générique est valide sur n’importe quelle liste d’éléments de création.
KSCREATE_ITEM_NOPARAMETERS Indique que cet élément de création n’autorise pas l’exécution de paramètres et échoue s’il y en a un. (Normalement, les paramètres de création sont transmis au gestionnaire de création.) Cet indicateur ne peut pas être utilisé avec un indicateur générique.
KSCREATE_ITEM_FREEONSTOP Indique que l’élément de création doit être libéré lorsque le gestionnaire PnP envoie IRP_MN_STOP_DEVICE. Notez que AVStream libère automatiquement ces éléments de création lorsque l’appareil reçoit un arrêt PnP (une fois que le client a reçu la notification d’arrêt PnP).

[in, optional] SleepCallback

Pointeur vers une routine fournie par minidriver qui reçoit des notifications que l’appareil associé à ce filtre va dormir. Prototypez la routine comme suit :

void SleepCallback (IN PKSFILTERFACTORY FilterFactory,
    IN DEVICE_POWER_STATE State);

Si ce paramètre est NULL, cette fabrique de filtre n’est pas avertie que l’appareil va dormir. Consultez Les états de l’alimentation de l’appareil.

[in, optional] WakeCallback

Pointeur vers une routine fournie par minidriver qui reçoit des notifications que l’appareil associé à ce filtre se réveille. Prototypez la routine comme suit :

void WakeCallback (IN PKSFILTERFACTORY FilterFactory,
    IN DEVICE_POWER_STATE State);

Si ce paramètre est NULL, cette fabrique de filtre n’est pas avertie que l’appareil se réveille. Consultez Les états de l’alimentation de l’appareil.

[out, optional] FilterFactory

Pointeur vers une structure KSFILTERFACTORY que AVStream définit pour pointer vers l’objet de fabrique de filtre nouvellement créé. Si ce paramètre facultatif n’est pas spécifié, l’appelant n’est pas informé de l’objet de fabrique de filtre résultant.

Valeur retournée

Retourne STATUS_SUCCESS si la fabrique de filtre peut être créée. Sinon, il retourne un code d’erreur approprié.

Notes

Si vous appelez KsCreateFilterFactory après AVStrMiniDevicePostStart), vous devez ensuite appeler KsFilterFactorySetDeviceClassesState pour activer la classe d’appareil. (Appelez également KsFilterFactorySetDeviceClassesState pour désactiver une fabrique de filtre.)

Si vous appelez KsCreateFilterFactory dans le contexte d’AVStrMiniDevicePostStart ou avant, vous n’avez pas besoin de le faire.

Avant d’appeler cette fonction, le minidriver doit obtenir le mutex de l’appareil. Pour plus d’informations sur la façon de procéder, consultez Device Mutex dans AVStream.

Cette fonction doit être utilisée par les minidrivers qui s’initialisent sans appel à KsInitializeDriver ou qui doivent ajouter et supprimer dynamiquement de nouveaux types de filtres.

Spécifications

   
Client minimal pris en charge Disponible dans Microsoft Windows XP et les systèmes d’exploitation ultérieurs et DirectX 8.0 et versions ultérieures de DirectX.
Plateforme cible Universal
En-tête ks.h (inclure Ks.h)
Bibliothèque Ks.lib
IRQL PASSIVE_LEVEL

Voir aussi

KSFILTER_DESCRIPTOR

KSNODE_DESCRIPTOR

KSPIN_DESCRIPTOR_EX

KsDeleteFilterFactory