ExRegisterCallback-Funktion (wdm.h)

Artikel
02/07/2025

Die ExRegisterCallback Routine registriert eine bestimmte Rückrufroutine bei einem bestimmten Rückrufobjekt.

Syntax

PVOID ExRegisterCallback(
  [in, out]      PCALLBACK_OBJECT   CallbackObject,
  [in]           PCALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID              CallbackContext
);

Parameter

[in, out] CallbackObject

Ein Zeiger auf ein Rückrufobjekt, das aus der ExCreateCallback Routine abgerufen wurde.

[in] CallbackFunction

Ein Zeiger auf eine vom Treiber implementierte Rückrufroutine, die nicht auspagebar sein muss. Die Rückrufroutine muss dem folgenden Prototyp entsprechen:

VOID
(*PCALLBACK_FUNCTION ) (
    IN PVOID CallbackContext,
    IN PVOID Argument1,
    IN PVOID Argument2
    );

Die Rückrufroutineparameter sind wie folgt:

CallbackContext

Ein Zeiger auf einen vom Treiber bereitgestellten Kontextbereich, wie im CallbackContext Parameter von ExRegisterCallbackangegeben.

Argument1

Ein Zeiger auf einen Parameter, der vom Rückrufobjekt definiert wird.

Argument2

Ein Zeiger auf einen Parameter, der vom Rückrufobjekt definiert wird.

[in, optional] CallbackContext

Ein Zeiger auf eine aufruferdefinierte Struktur von Datenelementen, die bei jedem Aufruf als Kontextparameter der Rückrufroutine übergeben werden sollen. In der Regel ist der Kontext Teil der Geräteobjekterweiterung des Aufrufers.

Rückgabewert

ExRegisterCallback- gibt einen Zeiger auf ein Rückrufregistrierungshandle zurück, das als undurchsichtig und für die Systemverwendung reserviert werden soll. Dieser Zeiger ist NULL-, wenn ExRegisterCallback mit einem Fehler abgeschlossen ist.

Bemerkungen

Ein Treiber ruft ExRegisterCallback- auf, um eine Rückrufroutine bei einem angegebenen Rückrufobjekt zu registrieren.

Wenn das Objekt nur eine registrierte Rückrufroutine zulässt und eine solche Routine bereits registriert ist, gibt ExRegisterCallbackNULL-zurück.

Aufrufer von ExRegisterCallback- müssen den zurückgegebenen Zeiger zur späteren Verwendung in einem Aufruf von ExUnregisterCallback-speichern. Der Zeiger ist erforderlich, wenn die Rückrufroutine aus der Liste der registrierten Rückrufroutinen für das Rückrufobjekt entfernt wird.

Die Bedeutungen von Argument1 und Argument2 der registrierten Rückrufroutine hängen vom Rückrufobjekt ab und werden von der Komponente definiert, die sie erstellt hat. Im Folgenden sind die Parameter für die vom System definierten Rückrufobjekte:

\Rückruf\SetSystemTime

Argument1 (SetSystemTime)

Wird nicht verwendet.

Argument2 (SetSystemTime)

Wird nicht verwendet.

\Callback\PowerState**

Argument1 (PowerState)

Ein PO_CB_XXX Konstantenwert, der in den Typ PVOID gegossen wird.
PO_CB_AC_STATUS – Gibt an, dass sich das System von A/C in Akkuleistung geändert hat oder umgekehrt.
PO_CB_LID_SWITCH_STATE – Gibt an, dass sich der Deckelschalter geändert hat.
PO_CB_PROCESSOR_POWER_POLICY – Gibt an, dass sich die Energierichtlinie des Systemprozessors geändert hat.
PO_CB_SYSTEM_POWER_POLICY – Gibt an, dass sich die Systemstromrichtlinie geändert hat.
PO_CB_SYSTEM_STATE_LOCK – Gibt an, dass eine Systemstromzustandsänderung unmittelbar bevorsteht. Treiber im Auslagerungspfad können sich für diesen Rückruf registrieren, um eine frühzeitige Warnung zu einer solchen Änderung zu erhalten, sodass sie den Code im Arbeitsspeicher sperren können, bevor sich der Energiezustand ändert.

Argument2 (PowerState)

Ein Wert von TRUE oder FALSE, der in den Typ PVOID gegossen wird.

Wenn Argument1 PO_CB_AC_STATUS ist, ist Argument2TRUE, wenn der Computer derzeit eine A/C-Stromversorgung verwendet und FALSE ist, wenn der Computer mit Akkubetrieb ausgeführt wird.
Wenn Argument1 PO_CB_LID_SWITCH_STATE ist, ist Argument2TRUE, wenn der Deckel aktuell geöffnet ist, und FALSE, wenn der Deckel geschlossen ist.
Wenn Argument1 PO_CB_PROCESSOR_POWER_POLICY ist, wird Argument2- nicht verwendet.
Wenn Argument1 PO_CB_SYSTEM_POWER_POLICY ist, wird Argument2- nicht verwendet.
Wenn Argument1 PO_CB_SYSTEM_STATE_LOCK ist, ist Argument2FALSE, wenn der Computer den Systemstromzustand S0 beendet, und ist TRUE, wenn der Computer gerade erneut S0 eingibt.

\Rückruf\ProcessorAdd

Argument1 (ProcessorAdd)

Ein Zeiger auf eine KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT Struktur, die das Ereignis für die Prozessoränderungsbenachrichtigung beschreibt. Dieser Zeiger wird in den Typ PVOID gegossen. Die Rückrufroutine darf den Inhalt dieser Struktur nicht ändern.

Argument2 (ProcessorAdd)

Ein Zeiger auf eine Variable, die einen NTSTATUS-Wert enthält. Dieser Zeiger wird in den Typ PVOID gegossen. Unter bestimmten Bedingungen kann eine Rückrufroutine einen Fehlerstatuswert in diese Variable schreiben, um anzugeben, warum der neue Prozessor nicht hinzugefügt werden soll. Ein Gerätetreiber darf den Wert dieser Variablen nur ändern, wenn alle drei der folgenden Bedingungen erfüllt sind:

Während der Verarbeitung der Rückrufroutine tritt ein Fehler auf, der verhindern soll, dass der neue Prozessor hinzugefügt wird.
Der Wert des State Member der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT Struktur, auf die Argument1 verweist, ist KeProcessorAddStartNotify.
Die NSTATUS-Variable, die Argument2 verweist, um den Wert STATUS_SUCCESS. Das heißt, die Rückrufroutine darf keinen Fehlerstatuswert überschreiben, der zuvor von einem anderen Rückrufbenachrichtigungsclient geschrieben wurde.

Ab Windows Vista ist das \Callback\ProcessorAdd Callbackobjekt verfügbar, um Änderungen in der Prozessorpopulation dynamisch nachzuverfolgen. Die KeRegisterProcessorChangeCallback- Routine stellt ähnliche Informationen bereit, unterstützt aber zusätzlich ein KE_PROCESSOR_CHANGE_ADD_EXISTING Flag, das ein Treiber verwenden kann, um die Prozessoren in der anfänglichen Multiprozessorsystemkonfiguration auflisten zu können. Verwenden Sie für Treiber, die in Windows Server 2008 und höheren Versionen von Windows ausgeführt werden, KeRegisterProcessorChangeCallback- anstelle des \Callback\ProcessorAdd Rückrufobjekts, falls möglich.

Weitere Informationen zu Rückrufobjekten finden Sie unter Callback Objects.

Das Betriebssystem ruft registrierte Rückrufroutinen an der gleichen IRQL auf, bei der der Treiber, der den Rückruf erstellt hat, die ExNotifyCallback Routine aufgerufen hat.

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	IRQL-<= APC_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)