KsEnableEventWithAllocator, fonction (ks.h)

Article
02/07/2025

La fonction KsEnableEventWithAllocator active les événements demandés via IOCTL_KS_ENABLE_EVENT, mais permet également l’utilisation d’un rappel d’allocateur facultatif pour fournir une mémoire tampon pour les paramètres. Elle répond à tous les identificateurs d’événement 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 de 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 allocateur 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 gérée. L’objet de 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 du jeu d’événements.

[in, out] EventsList

Si le KSEVENT_SET de l’événement d’activation. AddHandler pour le jeu d’événements est NULL , il doit pointer vers la tête de la liste des éléments KSEVENT_ENTRY sur lesquels l’événement doit être ajouté. Cette fonction suppose une seule liste 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 des é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é est NULL, puis il 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

Si vous le souhaitez, il pointe vers une fonction d’allocation qui sera utilisée pour allouer de la mémoire pour stocker les paramètres d’événement.

[in, optional] EventItemSize

Contient éventuellement la taille de chaque structure de KSEVENT_ITEM dans chaque liste d’événements. L’élément d’événement peut être étendu pour stocker des informations privées. Si ce paramètre est égal à zéro, la taille de la structure est supposée être normale. S’il est supérieur ou égal à une structure d’élément d’événement, la macro KSEVENT_ITEM_IRP_STORAGE peut être utilisée pour renvoyer 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 de retour

Identique à KsEnableEvent, qui retourne STATUS_SUCCESS en cas de réussite, ou une erreur spécifique à l’événement en cours d’activation en cas d’échec. La fonction définit toujours la IO_STATUS_BLOCK. Champ d’informations du PIRP. Élément IoStatus au sein de l’IRP à zéro. Elle ne définit pas le IO_STATUS_BLOCK. Champ d’état, pas plus qu’il ne termine l’IRP.

Remarques

Si le rappel d’allocateur facultatif est utilisé, le filtre peut avoir besoin de libérer la mémoire tampon de 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 allocateur personnalisé.

Exigences

Exigence	Valeur
plateforme cible	Universel
d’en-tête	ks.h (include Ks.h)
bibliothèque	Ks.lib

Partager via