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 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 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.
| Drapeau | 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. 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 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 que AVStream libère automatiquement ces éléments de création lorsque l’appareil reçoit l’arrêt PnP (après 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 filtres n’est pas avertie que l’appareil va dormir. Consultez Device Power States .
[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 filtres n’est pas avertie que l’appareil se réveille. Consultez Device Power States .
[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 de retour
Retourne STATUS_SUCCESS si la fabrique de filtres 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 filtres.)
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 sans appel à KsInitializeDriver ou qui doivent ajouter et supprimer dynamiquement de nouveaux types de filtres.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum 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 | Universel |
| d’en-tête | ks.h (include Ks.h) |
| bibliothèque | Ks.lib |
| IRQL | PASSIVE_LEVEL |