EVT_ACX_CIRCUIT_PREPARE_HARDWARE Rückruffunktion (acxcircuit.h)

Der EVT_ACX_CIRCUIT_PREPARE_HARDWARE Rückruf wird vom Treiber verwendet, um Funktionen hinzuzufügen, wenn sich ein ACXCIRCUIT in der Vorbereitungsphase befindet.

Syntax

EVT_ACX_CIRCUIT_PREPARE_HARDWARE EvtAcxCircuitPrepareHardware;

NTSTATUS EvtAcxCircuitPrepareHardware(
  WDFDEVICE Device,
  ACXCIRCUIT Circuit,
  WDFCMRESLIST ResourcesRaw,
  WDFCMRESLIST ResourcesTranslated
)
{...}

Parameter

Device

Ein WDFDEVICE-Objekt (beschrieben in WDF - Zusammenfassung von Framework-Objekten), das dem angegebenen ACXCIRCUIT zugeordnet ist.

Circuit

Das ACXCIRCUIT -Objekt (in Zusammenfassung von ACX Objects) in der Vorbereitungsphase.

ResourcesRaw

Ein Handle zu einem Framework-Ressourcenlistenobjekt, das die rohen Hardwareressourcen identifiziert, die der Plug- und Play-Manager dem Gerät zugewiesen hat. Weitere Informationen zu Rohressourcen finden Sie unter raw and Translated Resources.

ResourcesTranslated

Ein Handle zu einem Framework-Ressourcenlistenobjekt, das die übersetzten Hardwareressourcen identifiziert, die der Plug- und Play-Manager dem Gerät zugewiesen hat.

Rückgabewert

Gibt STATUS_SUCCESS zurück, wenn der Anruf erfolgreich war. Andernfalls wird ein entsprechender Fehlercode zurückgegeben. Weitere Informationen finden Sie unter Verwenden von NTSTATUS-Werten.

Bemerkungen

Um eine EvtAcxCircuitPrepareHardware-Rückruffunktion zu registrieren, muss ein Treiber die AcxCircuitInitSetAcxCircuitPnpPowerCallbacks-Methodeaufrufen.

Wenn der Treiber eine EvtAcxCircuitPrepareHardware-Rückruffunktion für eine ACXCIRCUIT registriert hat, ruft das ACX-Framework die Funktion auf, nachdem das WDF-Framework die EvtDevicePrepareHardware-Rückruffunktion des Treibers aufruft.

Die Rückruffunktion EvtAcxCircuitPrepareHardware greift mithilfe der empfangenen Handles "ResourcesRaw" und "ResourcesTranslated" auf die rohen und übersetzten Hardwareressourcen des Geräts zu. Die Rückruffunktion kann WdfCmResourceListGetCount- und WdfCmResourceListGetDescriptor- aufrufen, um die Ressourcenlisten zu durchlaufen. Diese Rückruffunktion kann die Ressourcenlisten nicht ändern.

Weitere Informationen zu Ressourcenlisten und der Reihenfolge, in der die Ressourcen angezeigt werden, finden Sie unter Raw and Translated Resources.

In der Regel führt die EvtAcxCircuitPrepareHardware-Rückruffunktion des Treibers bei Bedarf die folgenden Aktionen aus:

• Ordnet physische Speicheradressen virtuellen Adressen des ACXCIRCUIT zu, damit der Treiber auf arbeitsspeicher zugreifen kann, der dem Gerät zugewiesen ist.
• Optional kann die Rückruffunktion EvtAcxCircuitPrepareHardware des Treibers eine Arbeitsaufgabe in die Warteschlange stellen, um andere zeitintensive Konfigurationsaufgaben auszuführen. Die Verwendung einer Arbeitsaufgabe für solche Vorgänge kann dazu beitragen, dass die Startzeit Ihres Geräts die Startzeit des Systems nicht erhöht. Weitere Informationen finden Sie unter Verwenden von Framework-Arbeitselementen.
• In der Regel sollten alle anderen Hardwareinitialisierungsvorgänge, einschließlich des Ladens der Firmware, jedes Mal ausgeführt werden, wenn das Gerät in den Arbeitszustand (D0) wechselt und daher in der EvtDeviceD0Entry-Rückruffunktion des Treibers ausgeführt werden soll.

The ResourcesRaw and ResourcesTranslated handles that the EvtAcxCircuitPrepareHardware/EvtDevicePrepareHardware callback function receives valid until the driver's EvtDeviceReleaseHardware callback function returns.

Wenn der Treiber den EvtAcxCircuitPrepareHardware-Rückruf fehlschlägt, wird das ACXCIRCUIT-Objekt in den zustand "delete-pending" gesetzt, und zugeordnete ACXSTREAMS werden heruntergefahren.

Weitere Informationen zu Hardwareressourcen finden Sie unter Einführung in Hardwareressourcen.

Weitere Informationen dazu, wann das ACX- und WDF-Framework diese Rückruffunktionen aufruft, finden Sie unter PnP- und Power Management-Szenarien.

Weitere Informationen zu Treibern, die diese Rückruffunktion bereitstellen, finden Sie unter Unterstützen von PnP und Power Management im Funktionstreiber-.

Beispiel

Die Beispielverwendung wird unten gezeigt.

NTSTATUS
EvtCircuitPrepareHardware(
    _In_ WDFDEVICE      Device,
    _In_ ACXCIRCUIT     Circuit,
    _In_ WDFCMRESLIST   ResourcesRaw,
    _In_ WDFCMRESLIST   ResourcesTranslated
    )
{
    NTSTATUS            status      = STATUS_SUCCESS;
    PCIRCUIT_CONTEXT    circuitCtx  = GetCircuitContext(Circuit);
    CIpcEventReader *   eventReader = circuitCtx->EventReader;

    PASSIVE_CODE();

    UNREFERENCED_PARAMETER(Device);
    UNREFERENCED_PARAMETER(ResourcesRaw);
    UNREFERENCED_PARAMETER(ResourcesTranslated);

    //
    // Enable 'remote' circuit notifications.
    //
    ASSERT(eventReader);
    status = eventReader->EnableEvents();
    if (!NT_SUCCESS(status))
    {
        DrvLogError(g_RecorderLog, FLAG_INIT,
                    "ACXCIRCUIT %p, CIpcEventReader::EnableEvents failed, %!STATUS!",
                    Circuit, status);
        goto exit;
    }

    status = STATUS_SUCCESS;

exit:
    return status;
}

ACX-Anforderungen

Mindestens ACX-Version: 1.0

Weitere Informationen zu ACX-Versionen finden Sie unter ACX-Versionsübersicht.

Anforderungen

Anforderung	Wert
Header-	acxcircuit.h
IRQL-	PASSIVE_LEVEL

Siehe auch

• acxcircuit.h header