KsEnableEventWithAllocator, fonction (ks.h)

Article
08/07/2023

La fonction KsEnableEventWithAllocator active les événements demandés via IOCTL_KS_ENABLE_EVENT, mais permet également d’utiliser un rappel d’allocateur facultatif pour fournir une mémoire tampon pour les paramètres. Il répond à tous les identificateurs d’événements définis par les jeux. Cette fonction ne peut être appelée qu’à PASSIVE_LEVEL.

S’il est utilisé, le filtre peut avoir besoin de libérer la mémoire tampon d’une manière non conventionnelle. Notez que les indicateurs IRP_BUFFERED_IO et IRP_DEALLOCATE_BUFFER ne sont pas définis lors de l’utilisation d’un indicateur personnalisé.

Syntaxe

KSDDKAPI NTSTATUS KsEnableEventWithAllocator(
  [in]           PIRP              Irp,
  [in]           ULONG             EventSetsCount,
  [in]           const KSEVENT_SET *EventSet,
  [in, out]      PLIST_ENTRY       EventsList,
  [in, optional] KSEVENTS_LOCKTYPE EventsFlags,
  [in, optional] PVOID             EventsLock,
  [in, optional] PFNKSALLOCATOR    Allocator,
  [in, optional] ULONG             EventItemSize
);

Paramètres

[in] Irp

Spécifie l’IRP avec la demande d’activation en cours de traitement. L’objet fichier associé à l’IRP est stocké avec l’événement pour une comparaison ultérieure lors de la désactivation de l’événement.

[in] EventSetsCount

Indique le nombre de structures de jeu d’événements passées.

[in] EventSet

Spécifie un pointeur vers la liste des informations de jeu d’événements.

[in, out] EventsList

Si l’événement d’activation KSEVENT_SET. AddHandler pour le jeu d’événements a la valeur NULL. Il doit pointer vers le début de la liste des éléments KSEVENT_ENTRY auxquels l’événement doit être ajouté. Cette fonction suppose une liste unique pour au moins un sous-ensemble d’événements.

[in, optional] EventsFlags

Spécifie KSEVENTS_LOCKTYPE indicateurs spécifiant le type de verrou d’exclusion à utiliser pour accéder à la liste d’événements, le cas échéant. Si aucun indicateur n’est défini, aucun verrou n’est pris. Si un gestionnaire est déjà spécifié, ce paramètre est ignoré.

[in, optional] EventsLock

Si le KSEVENT_SET. AddHandler pour le jeu d’événements contenant l’événement activé a la valeur NULL, puis est utilisé pour synchroniser l’accès à la liste. Cette valeur peut être NULL si aucun indicateur n’est défini dans EventsFlags.

[in, optional] Allocator

Pointe éventuellement vers une fonction d’allocation qui sera utilisée pour allouer de la mémoire afin de stocker les paramètres d’événement.

[in, optional] EventItemSize

Contient éventuellement la taille de chaque structure KSEVENT_ITEM dans chaque liste d’événements. L’élément d’événement peut être étendu afin de stocker des informations privées. Si ce paramètre est égal à zéro, la taille de structure est supposée être normale. Si elle est supérieure ou égale à une structure d’élément d’événement, la macro KSEVENT_ITEM_IRP_STORAGE peut être utilisée pour retourner un pointeur vers l’élément d’événement afin que les données personnalisées puissent être récupérées. Sur les plateformes 64 bits, ce paramètre doit être un multiple de 8.

Valeur retournée

Identique à KsEnableEvent, qui retourne STATUS_SUCCESS en cas de réussite, ou une erreur spécifique à l’événement activé en cas d’échec. La fonction définit toujours le IO_STATUS_BLOCK. Champ d’informations du PIRP. Élément IoStatus dans l’IRP à zéro. Il ne définit pas le IO_STATUS_BLOCK. Le champ État ne termine pas non plus l’IRP.

Remarques

Si le rappel d’allocateur facultatif est utilisé, le filtre peut avoir besoin de libérer la mémoire tampon d’une manière non conventionnelle. Notez que les indicateurs IRP_BUFFERED_IO et IRP_DEALLOCATE_BUFFER ne sont pas définis lors de l’utilisation d’un indicateur personnalisé.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	ks.h (inclure Ks.h)
Bibliothèque	Ks.lib

Partager via