PO_FX_POWER_CONTROL_CALLBACK Rückruffunktion (wdm.h)

Die PowerControlCallback-Rückrufroutine führt einen Energiesteuerungsvorgang durch, der vom Power Management Framework (PoFx) angefordert wird.

Syntax

PO_FX_POWER_CONTROL_CALLBACK PoFxPowerControlCallback;

NTSTATUS PoFxPowerControlCallback(
                  PVOID DeviceContext,
  [in]            LPCGUID PowerControlCode,
  [in, optional]  PVOID InBuffer,
  [in]            SIZE_T InBufferSize,
  [out, optional] PVOID OutBuffer,
  [in]            SIZE_T OutBufferSize,
  [out, optional] PSIZE_T BytesReturned
)
{...}

Parameter

DeviceContext

[in] PowerControlCode

Ein Zeiger auf den Energiesteuerungscode. Dieser Code ist ein GUID-Wert, der den angeforderten Vorgang angibt.

[in, optional] InBuffer

Ein Zeiger auf den Puffer, der die Eingabedaten für den Vorgang enthält. Das Format für die Daten in diesem Puffer hängt vom Energiesteuerungscode ab, der durch den PowerControlCode-Parameter angegeben wird. Der InBuffer-Parameter ist optional und kann als NULL angegeben werden, wenn für den angegebenen Vorgang keine Eingabedaten erforderlich sind.

[in] InBufferSize

Die Größe des Eingabepuffers in Bytes, auf den der InBuffer-Parameter verweist. Wenn InBuffer NULL ist, ist dieser Parameter 0.

[out, optional] OutBuffer

Ein Zeiger auf den Puffer, in den die Rückrufroutine die Ausgabedaten aus dem Vorgang schreibt. Das Format für die Daten in diesem Puffer hängt vom Energiesteuerungscode ab, der durch den PowerControlCode-Parameter angegeben wird. Der OutBuffer-Parameter ist optional und kann als NULL angegeben werden, wenn der angegebene Vorgang keine Ausgabedaten erzeugt.

[in] OutBufferSize

Die Größe des Ausgabepuffers in Bytes, auf den der OutBuffer-Parameter verweist. Wenn OutBuffer NULL ist, ist dieser Parameter 0.

[out, optional] BytesReturned

Ein Zeiger auf einen Speicherort, an den die Routine die Anzahl der Bytes von Daten schreibt, die in den Puffer geschrieben wurden, auf den OutBuffer verweist. Die Anzahl der geschriebenen Bytes muss kleiner oder gleich OutBufferSize sein. Dieser Parameter ist optional und kann als NULL angegeben werden, wenn der Aufrufer nicht wissen muss, wie viele Bytes in den Ausgabepuffer geschrieben wurden.

Rückgabewert

Die PowerControlCallback-Routine gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls wird ein entsprechender Fehlercode zurückgegeben.

Hinweise

PoFx ruft diese Routine auf, um eine Energiesteuerungsanforderung direkt an den Gerätetreiber zu senden. Eine Energiesteuerungsanforderung ähnelt einer E/A-Steuerungsanforderung (IOCTL). Im Gegensatz zu einem IOCTL wird eine Energiesteuerungsanforderung jedoch direkt an den Treiber gesendet und von anderen Gerätetreibern im Gerätestapel nicht beachtet. Während eines PowerControlCallback-Aufrufs führt der Treiber den angeforderten Vorgang synchron aus.

Diese Routine ist optional. Ein Gerätetreiber, der keine Energiesteuerungsvorgänge unterstützt, ist nicht erforderlich, um eine PowerControlCallback-Routine zu implementieren.

Der Gerätetreiber kann die PoFxPowerControl-Routine aufrufen, um eine Energiesteuerungsanforderung an PoFx zu senden.

Weitere Informationen zu Energiesteuerungsanforderungen finden Sie unter PoFxPowerControl.

Beispiele

Um eine PowerControlCallback-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine PowerControlCallback-Rückrufroutine mit dem Namen MyPowerControlCallbackzu definieren, verwenden Sie den typ PO_FX_POWER_CONTROL_CALLBACK, wie in diesem Codebeispiel gezeigt:

PO_FX_POWER_CONTROL_CALLBACK MyPowerControlCallback;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyPowerControlCallback(
    PVOID Context,
    LPCGUID PowerControlCode,
    PVOID InBuffer,
    SIZE_T InBufferSize,
    PVOID OutBuffer,
    SIZE_T OutBufferSize,
    PSIZE_T BytesReturned
    )
  {
      // Function body
  }

Der PO_FX_POWER_CONTROL_CALLBACK Funktionstyp ist in der Wdm.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den PO_FX_POWER_CONTROL_CALLBACK Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Wird ab Windows 8 unterstützt.
Zielplattform	Desktop
Kopfzeile	wdm.h (include Wudfwdm.h)
IRQL	Wird unter IRQL <= DISPATCH_LEVEL aufgerufen.

Weitere Informationen

PO_FX_DEVICE

PoFxPowerControl