KsEnableEventWithAllocator-Funktion (ks.h)

Artikel
08/07/2023

Die KsEnableEventWithAllocator-Funktion aktiviert Ereignisse, die über IOCTL_KS_ENABLE_EVENT angefordert werden, ermöglicht aber auch die Verwendung eines optionalen Zuordnungsrückrufs, um einen Puffer für die Parameter bereitzustellen. Es reagiert auf alle Ereignisbezeichner, die von den Sätzen definiert werden. Diese Funktion kann nur bei PASSIVE_LEVEL aufgerufen werden.

Bei Verwendung muss der Filter den Puffer möglicherweise auf nichtkonventionale Weise freigeben. Beachten Sie, dass die Flags IRP_BUFFERED_IO und IRP_DEALLOCATE_BUFFER nicht festgelegt werden, wenn sie einen benutzerdefinierten Zuteilungsgeber verwenden.

Syntax

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

Parameter

[in] Irp

Gibt die IRP an, bei der die Aktivierungsanforderung verarbeitet wird. Das dem IRP zugeordnete Dateiobjekt wird mit dem Ereignis für einen späteren Vergleich beim Deaktivieren des Ereignisses gespeichert.

[in] EventSetsCount

Gibt die Anzahl der übergebenen Ereignissatzstrukturen an.

[in] EventSet

Gibt einen Zeiger auf die Liste der Ereignissatzinformationen an.

[in, out] EventsList

Wenn das aktivierend-Ereignis KSEVENT_SET. AddHandler für den Ereignissatz ist NULL. Er muss auf den Kopf der Liste der KSEVENT_ENTRY Elemente verweisen, zu denen das Ereignis hinzugefügt werden soll. Diese Funktion setzt eine einzelne Liste für mindestens eine Teilmenge von Ereignissen voraus.

[in, optional] EventsFlags

Gibt KSEVENTS_LOCKTYPE Flags an, die den Typ der Ausschlusssperre angeben, die beim Zugriff auf die Ereignisliste verwendet werden soll, falls vorhanden. Wenn kein Flag festgelegt ist, wird keine Sperre genommen. Wenn bereits ein Handler angegeben ist, wird dieser Parameter ignoriert.

[in, optional] EventsLock

Wenn der KSEVENT_SET. AddHandler für den Ereignissatz, der das aktivierte Ereignis enthält, ist NULL. Anschließend wird der Zugriff auf die Liste synchronisiert. Dieser Wert kann NULL sein, wenn in EventsFlags kein Flag festgelegt ist.

[in, optional] Allocator

Zeigt optional auf eine Zuordnungsfunktion, die zum Zuweisen von Arbeitsspeicher zum Speichern der Ereignisparameter verwendet wird.

[in, optional] EventItemSize

Enthält optional die Größe jeder KSEVENT_ITEM Struktur in jeder Ereignisliste. Das Ereigniselement kann erweitert werden, um private Informationen zu speichern. Wenn dieser Parameter 0 ist, wird davon ausgegangen, dass die Strukturgröße normal ist. Wenn es größer oder gleich einer Ereigniselementstruktur ist, kann das KSEVENT_ITEM_IRP_STORAGE Makros verwendet werden, um einen Zeiger auf das Ereigniselement zurückzugeben, damit die benutzerdefinierten Daten abgerufen werden können. Auf 64-Bit-Plattformen muss dieser Parameter ein Vielfaches von 8 sein.

Rückgabewert

Identisch mit KsEnableEvent, das bei erfolgreicher Ausführung STATUS_SUCCESS oder einen fehlerspezifischen Fehler für das aktivierte Ereignis zurückgibt, wenn der Fehler nicht erfolgreich ist. Die Funktion legt immer die IO_STATUS_BLOCK fest. Informationsfeld des PIRP. IoStatus-Element innerhalb des IRP auf Null. Die IO_STATUS_BLOCK wird nicht festgelegt. Statusfeld, noch wird die IRP abgeschlossen.

Hinweise

Wenn der optionale Zuteilungsrückruf verwendet wird, muss der Filter den Puffer möglicherweise auf nichtkonventionale Weise freigeben. Beachten Sie, dass die Flags IRP_BUFFERED_IO und IRP_DEALLOCATE_BUFFER nicht festgelegt werden, wenn sie einen benutzerdefinierten Zuteilungsgeber verwenden.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	ks.h (einschließlich Ks.h)
Bibliothek	Ks.lib

Freigeben über