ExRegisterCallback-Funktion (wdm.h)

Die ExRegisterCallback-Routine registriert eine bestimmte Rückrufroutine mit 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 ausstellbar 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 ExRegisterCallback angegeben.

Argument1

Ein Zeiger auf einen vom Rückrufobjekt definierten Parameter.

Argument2

Ein Zeiger auf einen vom Rückrufobjekt definierten Parameter.

[in, optional] CallbackContext

Ein Zeiger auf eine vom Aufrufer definierte 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 wird.

Hinweise

Ein Treiber ruft ExRegisterCallback auf, um eine Rückrufroutine mit 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 speichern, damit er später in einem Aufruf von ExUnregisterCallback verwendet werden kann. 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 es erstellt hat. Im Folgenden sind die Parameter für die systemdefinierte Rückrufobjekte aufgeführt:

\Callback\SetSystemTime

Argument1 (SetSystemTime)

• Wird nicht verwendet.

Argument2 (SetSystemTime)

• Wird nicht verwendet.

\Rückruf\PowerState**

Argument1 (PowerState)

• Ein PO_CB_XXX Konstantenwert, der in den Typ PVOID umgewandelt wird.

• PO_CB_AC_STATUS – Gibt an, dass das System von A/C auf Akkuleistung oder umgekehrt umgestellt wurde.

• PO_CB_LID_SWITCH_STATE – Gibt an, dass der Deckelschalter den Status 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 Energierichtlinie des Systems geändert hat.

• PO_CB_SYSTEM_STATE_LOCK – Gibt an, dass eine Änderung des Systemstromzustands unmittelbar bevorsteht. Treiber im Auslagerungspfad können sich für diesen Rückruf registrieren, um eine frühzeitige Warnung vor einer solchen Änderung zu erhalten, sodass sie ihren Code im Arbeitsspeicher sperren können, bevor sich der Energiezustand ändert.

Argument2 (PowerState)

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

• Wenn Argument1 PO_CB_AC_STATUS ist, ist Argument2TRUE , wenn der Computer derzeit ein A/C-Netzteil verwendet, und ist FALSE , wenn der Computer mit Akkubetrieb ausgeführt wird.

• Wenn Argument1 PO_CB_LID_SWITCH_STATE ist, ist Argument2TRUE , wenn der Deckel gerade 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 beenden soll, und true , wenn der Computer soeben erneut in S0 eingestiegen ist.

\Callback\ProcessorAdd

Argument1 (ProzessorAdd)

• Ein Zeiger auf eine KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT-Struktur , die das Prozessoränderungsbenachrichtigungsereignis beschreibt. Dieser Zeiger wird in den Typ PVOID umgewandelt. Die Rückrufroutine darf den Inhalt dieser Struktur nicht ändern.

Argument2 (ProzessorAdd)

Ein Zeiger auf eine Variable, die einen NTSTATUS-Wert enthält. Dieser Zeiger wird in den Typ PVOID umgewandelt. Unter bestimmten Bedingungen kann eine Rückrufroutine einen Fehler status Wert 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 sollte, dass der neue Prozessor hinzugefügt wird.

• Der Wert des State-Mitglieds der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT Struktur, auf die Argument1 verweist, ist KeProcessorAddStartNotify.

• Die NSTATUS-Variable, auf die Argument2 verweist, enthält den Wert STATUS_SUCCESS. Das heißt, die Rückrufroutine darf keinen Fehler status Wert überschreiben, der zuvor von einem anderen Rückrufbenachrichtigungsclient geschrieben wurde.

Ab Windows Vista steht das Rückrufobjekt \Callback\ProcessorAdd zur dynamischen Nachverfolgung von Änderungen in der Prozessorpopulation zur Verfügung. Die KeRegisterProcessorChangeCallback-Routine bietet ähnliche Informationen, unterstützt aber zusätzlich ein KE_PROCESSOR_CHANGE_ADD_EXISTING Flag, das ein Treiber verwenden kann, um die Prozessoren in der anfänglichen Mehrprozessorsystemkonfiguration aufzulisten. Für Treiber, die in Windows Server 2008 und höheren Versionen von Windows ausgeführt werden, verwenden Sie nach Möglichkeit KeRegisterProcessorChangeCallback anstelle des Rückrufobjekts \Callback\ProcessorAdd .

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

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

Anforderungen

Weitere Informationen

ExCreateCallback

ExNotifyCallback

ExUnregisterCallback

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeRegisterProcessorChangeCallback