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 de DEVICE_OBJECT pour laquelle ajouter une fabrique de filtres.
[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 la valeur est NULL, aucun descripteur n’est fourni.
[in] CreateItemFlags
Le tableau suivant répertorie les indicateurs que l’enregistreur de 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 le OU 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. Le classement de l’entrée générique dans la liste des éléments de création n’est pas pertinent. Une seule entrée générique est valide sur une liste d’éléments de création. |
| KSCREATE_ITEM_NOPARAMETERS | Indique que cet élément de création n’autorise aucun paramètre à passer et échoue si des paramètres sont trouvés. (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 qu’AVStream libère automatiquement ces éléments de création lorsque l’appareil reçoit l’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 indiquant que l’appareil associé à ce filtre va être mis en veille. Prototypez la routine comme suit :
void SleepCallback (IN PKSFILTERFACTORY FilterFactory,
IN DEVICE_POWER_STATE State);
Si ce paramètre a la valeur NULL, cette fabrique de filtre n’est pas avertie que l’appareil va être en veille. Consultez État de l’alimentation de l’appareil.
[in, optional] WakeCallback
Pointeur vers une routine fournie par minidriver qui reçoit des notifications indiquant 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 a la valeur NULL, cette fabrique de filtre n’est pas avertie que l’appareil se réveille. Consultez État 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, elle retourne un code d’erreur approprié.
Remarques
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 de 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 procédure à suivre, consultez Mutex d’appareil dans AVStream.
Cette fonction doit être utilisée par les minidrivers qui s’initialisent eux-mêmes sans appel à KsInitializeDriver ou qui doivent ajouter et supprimer dynamiquement de nouveaux types de filtres.
Configuration requise
| Condition requise | Valeur |
|---|---|
| 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 |