ExCreateCallback-Funktion (wdm.h)

  • Artikel

Die ExCreateCallback-Routine erstellt entweder ein neues Rückrufobjekt oder öffnet ein vorhandenes Rückrufobjekt im Namen des Aufrufers.

Syntax

NTSTATUS ExCreateCallback(
  [out] PCALLBACK_OBJECT   *CallbackObject,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  BOOLEAN            Create,
  [in]  BOOLEAN            AllowMultipleCallbacks
);

Parameter

[out] CallbackObject

Ein Zeiger auf eine Position, die einen Zeiger auf ein Rückrufobjekt empfängt, bei dem es sich um eine undurchsichtige Systemstruktur handelt. Wenn der ExCreateCallback-Aufruf erfolgreich ist, schreibt die Routine die Adresse des neu erstellten oder geöffneten Rückrufobjekts an diesen Speicherort. Der von dieser Routine abgerufene Rückrufobjektzeiger kann als Parameter für die ExRegisterCallback - oder ExNotifyCallback-Routine bereitgestellt werden.

[in] ObjectAttributes

Ein Zeiger auf eine OBJECT_ATTRIBUTES-Struktur , die die Attribute des Rückrufobjekts enthält. Diese Struktur wurde zuvor von der InitializeObjectAttributes-Routine initialisiert.

[in] Create

Gibt an, ob ein Rückrufobjekt erstellt werden soll. Legen Sie auf TRUE fest, um ein neues Rückrufobjekt zu erstellen, wenn das angeforderte Objekt nicht geöffnet werden kann. Legen Sie andernfalls auf FALSE fest.

[in] AllowMultipleCallbacks

Gibt an, ob ein neu erstelltes Rückrufobjekt mehrere registrierte Rückrufroutinen zulassen soll. Legen Sie auf TRUE fest, um mehrere registrierte Rückrufroutinen zuzulassen. Legen Sie andernfalls auf FALSE fest. Dieser Parameter wird ignoriert, wenn Createfalse ist oder wenn ein vorhandenes Objekt geöffnet wird.

Rückgabewert

ExCreateCallback gibt STATUS_SUCCESS zurück, wenn ein Rückrufobjekt geöffnet oder erstellt wurde. Andernfalls wird ein NTSTATUS-Fehlercode zurückgegeben, um die Art des Fehlers anzugeben.

Hinweise

Ein Treiber ruft ExCreateCallback auf, um ein neues Rückrufobjekt zu erstellen oder ein vorhandenes Rückrufobjekt zu öffnen. Nachdem das Objekt erstellt oder geöffnet wurde, können andere Komponenten die ExRegisterCallback-Routine aufrufen, um Rückrufroutinen beim Rückrufobjekt zu registrieren.

Vor dem Aufrufen von ExCreateCallback muss der Treiber InitializeObjectAttributes aufrufen, um die OBJECT_ATTRIBUTES Struktur für das Rückrufobjekt zu initialisieren. Nicht benannte Rückrufobjekte sind nicht zulässig. Der Aufrufer muss einen Namen für das Objekt angeben. Andernfalls schlägt der Anruf mit STATUS_UNSUCCESSFUL fehl. Der Aufrufer sollte das attribut OBJ_PERMANENT im Rückrufobjekt angeben, um zu verhindern, dass das Objekt gelöscht wird, bevor es beim Objekt-Manager registriert werden kann. Der Aufrufer sollte auch alle anderen Attribute angeben, z. B. OBJ_CASE_INSENSITIVE, die möglicherweise benötigt werden.

Wenn alle Vorgänge mit dem Rückrufobjekt abgeschlossen wurden, muss der Treiber das Objekt löschen, um einen Speicherverlust zu verhindern. Informationen zum Löschen eines Objekts, das mit dem attribut OBJ_PERMANENT-Objekt erstellt wurde, finden Sie unter ObDereferenceObject.

Die folgende Tabelle zeigt die Rückrufobjekte, die das Betriebssystem für die Verwendung durch Treiber erstellt.

Name des Rückrufobjekts Verbrauch
\Callback\SetSystemTime Das Betriebssystem ruft alle für dieses Objekt registrierten Rückrufroutinen auf, wenn sich die Systemzeit ändert.
\Callback\PowerState Das Betriebssystem ruft alle für dieses Objekt registrierten Rückrufroutinen auf, wenn sich bestimmte Systemleistungsmerkmale ändern. Wenn sich ein Treiber für rückrufbenachrichtigungen registriert (durch Aufrufen von ExRegisterCallback), kann er die Änderungen angeben, für die er benachrichtigt werden soll.
 

Weitere Informationen zu Rückrufobjekten finden Sie unter Rückrufobjekte.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar ab Windows 2000.
Zielplattform Universell
Header wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL
DDI-Complianceregeln HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm), IrqlExPassive

Weitere Informationen

ExNotifyCallback

ExRegisterCallback

InitializeObjectAttributes

ObDereferenceObject