IoCreateSynchronizationEvent-Funktion (wdm.h)

  • Artikel

Die IoCreateSynchronizationEvent-Routine erstellt oder öffnet ein benanntes Synchronisierungsereignis zur Verwendung bei der Serialisierung des Hardwarezugriffs zwischen zwei ansonsten nicht zusammenhängenden Treibern.

Syntax

PKEVENT IoCreateSynchronizationEvent(
  [in]  PUNICODE_STRING EventName,
  [out] PHANDLE         EventHandle
);

Parameter

[in] EventName

Zeiger auf einen Puffer, der eine Unicode-Zeichenfolge mit NULL-Beendigung enthält, die das Ereignis benennt.

[out] EventHandle

Zeiger auf eine Position, an der ein Handle für das Ereignisobjekt zurückgegeben werden soll. In Windows Server 2003 und höheren Versionen von Windows ist das zurückgegebene Handle ein Kernelhandle.

Rückgabewert

IoCreateSynchronizationEvent gibt einen Zeiger auf das erstellte oder geöffnete Ereignisobjekt oder NULL zurück, wenn das Ereignisobjekt nicht erstellt oder geöffnet werden konnte.

Hinweise

Das Ereignisobjekt wird erstellt, wenn es noch nicht vorhanden ist. IoCreateSynchronizationEvent legt den Status eines neuen Synchronisierungsereignisses auf Signaled fest. Wenn das Ereignisobjekt bereits vorhanden ist, wird es einfach geöffnet. Das Treiberpaar, das ein Synchronisierungsereignis verwendet, ruft KeWaitForSingleObject mit dem PKEVENT-Zeiger auf, der von dieser Routine zurückgegeben wird.

Wenn ein Synchronisierungsereignis auf den Signalzustand festgelegt ist, wird ein einzelner Ausführungsthread, der auf das Ereignis gewartet hat, freigegeben, und das Ereignis wird automatisch auf den Not-Signaled Zustand zurückgesetzt.

Zum Freigeben des Ereignisses ruft ein Treiber ZwClose mit dem Ereignishandle auf.

Die Freigabe von Ereignisobjekten zwischen dem Benutzermodus und dem Kernelmodus erfordert Sorgfalt. Es gibt zwei Standard Methoden zum Freigeben von Ereignisobjekten:

  • Die Anwendung im Benutzermodus erstellt das Ereignisobjekt und übergibt ein Handle an das Objekt an den Treiber, indem sie eine IOCTL an den Treiber sendet. Der Treiber muss die IOCTL im Kontext des Prozesses behandeln, der das Ereignisobjekt erstellt hat, und das Handle muss durch Aufrufen von ObReferenceObjectByHandle überprüft werden. Diese Methode ist die empfohlene Methode zum Freigeben von Ereignisobjekten zwischen Benutzer- und Kernelmodi.

  • Der Treiber erstellt ein benanntes Ereignisobjekt im globalen \BaseNamedObjects Objektverzeichnis. Verwenden Sie den Namen Global\\Xxx, um über den Benutzermodus auf ein Kernelmodusereignis zuzugreifen. Beachten Sie, dass Sicherheitseinstellungen verhindern können, dass eine Anwendung das Ereignis öffnet. Das Objektverzeichnis \BaseNamedObjects wird erst erstellt, wenn das Microsoft Win32-Subsystem initialisiert wird. Treiber, die zur Startzeit geladen werden, können daher keine Ereignisobjekte im Verzeichnis \BaseNamedObjects in ihren DriverEntry-Routinen erstellen.

Weitere Informationen zu Ereignissen finden Sie unter Ereignisobjekte.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar ab Windows 2000.
Zielplattform Universell
Header wdm.h (include Ntddk.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI-Complianceregeln HwStorPortProhibitedDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)

Weitere Informationen

IoCreateNotificationEvent

KeWaitForSingleObject

RtlInitUnicodeString

ZwClose