Auswerten einer Steuerelementmethode, die Eingabeargumente akzeptiert

Um eine Steuerungsmethode, die Eingabeargumente akzeptiert, synchron auszuwerten, sendet ein Treiber für ein Gerät eine IOCTL_ACPI_EVAL_METHOD Anforderung oder eine IOCTL_ACPI_EVAL_METHOD_EX Anforderung an das Gerät. Das allgemeine Verfahren für die Verwendung dieser beiden Anforderungen wird unter Auswerten von ACPI-Steuerungsmethoden synchron beschrieben. Der spezifische Unterschied zwischen der Verwendung dieser beiden Anforderungen ist wie folgt:

• Wenn die Steuerungsmethode ein unmittelbar untergeordnetes Objekt des Geräts ist, sendet der Treiber eine IOCTL_ACPI_EVAL_METHOD-Anforderung und stellt eine der folgenden Eingabestrukturen bereit: ACPI_EVAL_INPUT_BUFFER_SIMPLE_INTEGER, ACPI_EVAL_INPUT_BUFFER_SIMPLE_STRING oder ACPI_EVAL_INPUT_BUFFER_COMPLEX.

• Wenn die Steuerungsmethode ein untergeordnetes Objekt im ACPI-Namespace des Geräts, aber kein unmittelbares untergeordnetes Objekt des Geräts ist, sendet der Treiber eine IOCTL_ACPI_EVAL_METHOD_EX Anforderung und stellt eine der folgenden Eingabestrukturen bereit: ACPI_EVAL_INPUT_BUFFER_SIMPLE_INTEGER_EX, ACPI_EVAL_INPUT_BUFFER_SIMPLE_STRING_EX, oder ACPI_EVAL_INPUT_BUFFER_COMPLEX_EX.

Die In diesem Thema bereitgestellte Beispielfunktion EvaluateABCDWithInputArgument zeigt, wie ein Treiber eine IOCTL_ACPI_EVAL_METHOD Anforderung verwenden kann, um eine Steuerelementmethode namens "ABCD" auszuwerten, die ein einzelnes ganzzahliges Eingabeargument verwendet.

Wenn das Eingabeargument eine Zeichenfolge oder ein Array benutzerdefinierter Daten anstelle einer ganzen Zahl war, besteht die erforderliche Änderung am Beispielcode darin, anstelle einer ganzzahligen Eingabestruktur eine Zeichenfolgeneingabestruktur oder eine komplexe Eingabestruktur anzugeben.

Wenn die "ABCD"-Steuerelementmethode kein unmittelbares untergeordnetes Objekt war, sind außerdem die erforderlichen Änderungen am Beispielcode wie folgt:

• Senden Sie eine IOCTL_ACPI_EVAL_METHOD_EX Anforderung anstelle einer IOCTL_ACPI_EVAL_METHOD Anforderung.

• Geben Sie den Typ der erweiterten Eingabestruktur an, der dem Eingabeargumenttyp (einfache ganze Zahl, einfache Zeichenfolge oder komplex) entspricht.

EvaluateABCDWithInputArgument weist zuerst eine ACPI_EVAL_INPUT_BUFFER_SIMPLE_INTEGER-Struktur inputBuffer zu, legt dann das MethodNameAsUlong-Element auf den Namen der Steuerelementmethode fest, legt den IntegerArgument-Member auf den ganzzahligen Eingabewert fest und legt das Signature-Element auf ACPI_EVAL_INPUT_BUFFER_SIMPLE_INTEGER_SIGNATURE fest.

    // Fill in the input data
    inputBuffer.MethodNameAsUlong = (ULONG) ('DCBA');
    inputBuffer.IntegerArgument  =  Argument1;
    inputBuffer.Signature = ACPI_EVAL_INPUT_BUFFER_SIMPLE_INTEGER_SIGNATURE;

EvaluateABCDWithInputArgument weist auch eine ACPI_EVAL_OUTPUT_BUFFERStrukturausgabeBuffer zu, legt aber keines der Member von outputBuffer fest.

EvaluateABCDWithInputArgument ruft dann eine vom Treiber bereitgestellte Funktion namens SendDownStreamIrp auf, die Folgendes ausführt:

1. Ruft IoBuildDeviceIoControlRequest auf, um die Anforderung zu erstellen.

2. Ruft IoCallDriver auf, um die Anforderung über den Gerätestapel zu senden.

3. Wartet, bis der E/A-Manager dem Treiber signalisiert, dass die Niedrigeren Treiber die Anforderung abgeschlossen haben.

SendDownStreamIrp wird zurückgegeben, nachdem der E/A-Manager signalisiert hat, dass die Treiber auf niedrigerer Ebene die Anforderung abgeschlossen haben.

Obwohl nicht in EvaluateABCDWithInputArgument enthalten, sollte der Treiber nach der Rückgabe von SendDownStreamIrp auch die folgenden zusätzlichen Vorgänge ausführen:

1. Überprüfen Sie die status, die SendDownStreamIrp zurückgibt. Wenn SendDownStreamIrp nicht STATUS_SUCCESS zurückgibt, sollte der Treiber ohne zusätzliche Verarbeitung zurückkehren.

2. Überprüfen Sie die Gültigkeit der Ausgabeparameter. Damit der outputBuffer gültige Ausgabedaten enthält, muss Signature auf ACPI_EVAL_OUTPUT_BUFFER_SIGNATURE und Count muss auf größer als 0 festgelegt werden.

3. Verarbeiten Sie die Ausgabeparameter, die an den Treiber zurückgegeben wurden.

4. Rufen Sie IoCompleteRequest auf, um die IOCTL_ACPI_EVAL_METHOD-Anforderung abzuschließen.

Die im folgenden Beispiel verwendeten ACPI-Datenstrukturen und Konstanten werden in Acpiioct.h definiert.

NTSTATUS
EvaluateABCDWithInputArgument(
    IN PDEVICE_OBJECT   Pdo,
    IN ULONG            Argument1,
    OUT PULONG          ReturnStatus
    )
/*
Routine Description:
    Called to evaluate the example 'ABCD' method with a single integer input argument

Parameters:
    Pdo             - For the device.
    Argument1       - Input argument.
    ReturnStatus    - Pointer to where the status data is placed.

Return Value:
    NT Status of the operation
*/
{
 ACPI_EVAL_INPUT_BUFFER_SIMPLE_INTEGER  inputBuffer;
    ACPI_EVAL_OUTPUT_BUFFER                outputBuffer; 
    NTSTATUS                               status;
    PACPI_METHOD_ARGUMENT                  argument;

    .
    .
    // Omitted: bounds checking on Argument1 value.


    ASSERT( ReturnStatus != NULL );
    *ReturnStatus = 0x0;

    // Fill in the input data
    inputBuffer.MethodNameAsUlong = (ULONG) ('DCBA');
    inputBuffer.IntegerArgument  =  Argument1;
    inputBuffer.Signature = ACPI_EVAL_INPUT_BUFFER_SIMPLE_INTEGER_SIGNATURE;

    // Send the request along
    status = SendDownStreamIrp(
       Pdo,
       IOCTL_ACPI_EVAL_METHOD,
       &inputBuffer,
       sizeof(ACPI_EVAL_INPUT_BUFFER_SIMPLE_INTEGER),
       &outputBuffer,
       sizeof(ACPI_EVAL_OUTPUT_BUFFER)
       );

    return status;
}