IoCreateSynchronizationEvent-Funktion (wdm.h)

Die IoCreateSynchronizationEvent Routine erstellt oder öffnet ein benanntes Synchronisierungsereignis für die Serialisierung des Zugriffs auf Hardware zwischen zwei anderen nicht verbundenen Treibern.

Syntax

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

Parameter

[in] EventName

Zeigen Sie auf einen Puffer, der eine mit Null beendete Unicode-Zeichenfolge enthält, die das Ereignis benennt.

[out] EventHandle

Zeigen Sie 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.

Bemerkungen

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 einen Synchronisierungsereignisaufruf verwendet, KeWaitForSingleObject mit dem PKEVENT-Zeiger, der von dieser Routine zurückgegeben wird.

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

Um das Ereignis freizugeben, ruft ein Treiber ZwClose- mit dem Ereignishandle auf.

Das Freigeben von Ereignisobjekten zwischen Benutzermodus und Kernelmodus erfordert Sorgfalt. Es gibt zwei Hauptmethoden für das Freigeben von Ereignisobjekten:

• Die Benutzermodusanwendung erstellt das Ereignisobjekt und übergibt ein Handle an den Treiber, indem ein IOCTL an den Treiber gesendet wird. Der Treiber muss die IOCTL im Kontext des Prozesses behandeln, der das Ereignisobjekt erstellt hat, und muss das Handle überprüfen, indem ObReferenceObjectByHandleaufgerufen wird. 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, sodass Treiber, die zur Startzeit geladen werden, keine Ereignisobjekte im Verzeichnis \BaseNamedObjects in ihren DriverEntry- Routinen erstellen können.

Weitere Informationen zu Ereignissen finden Sie unter Event Objects.

Anforderungen

Siehe auch

IoCreateNotificationEvent-

KeWaitForSingleObject

RtlInitUnicodeString

ZwClose