EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS fungsi panggilan balik (ursdevice.h)

Ekstensi kelas peran ganda USB memanggil panggilan balik ini untuk memungkinkan driver klien memasukkan sumber daya dari objek daftar persyaratan sumber daya ke daftar sumber daya yang akan digunakan selama masa pakai setiap peran.

Sintaks

EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtUrsDeviceFilterResourceRequirements;

NTSTATUS EvtUrsDeviceFilterResourceRequirements(
  [in] WDFDEVICE Device,
  [in] WDFIORESREQLIST IoResourceRequirementsList,
  [in] URSIORESLIST HostRoleResources,
  [in] URSIORESLIST FunctionRoleResources
)
{...}

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja yang diambil driver klien dalam panggilan sebelumnya ke WdfDeviceCreate.

[in] IoResourceRequirementsList

Handel ke objek daftar persyaratan sumber daya kerangka kerja yang mewakili daftar persyaratan sumber daya perangkat.

[in] HostRoleResources

Handel ke daftar sumber daya untuk perangkat pengontrol saat beroperasi dalam mode host.

[in] FunctionRoleResources

Handel ke daftar sumber daya untuk pengontrol saat beroperasi dalam mode fungsi.

Nilai kembali

Jika operasi berhasil, fungsi panggilan balik harus mengembalikan STATUS_SUCCESS, atau nilai status lain yang NT_SUCCESS(status) sama dengan TRUE. Jika tidak, itu harus mengembalikan nilai status yang NT_SUCCESS(status) sama dengan FALSE.

Keterangan

Driver klien mendaftarkan implementasinya dengan ekstensi kelas peran ganda USB dengan memanggil UrsDeviceInitialize setelah memanggil WdfDeviceCreate untuk membuat objek perangkat kerangka kerja untuk pengontrol. Ekstensi kelas memanggil panggilan balik ini sebelum EvtDevicePrepareHardware. Panggilan balik dipanggil dalam ekstensi kelas EvtDeviceFilterRemoveResourceRequirements, yang terdaftar atas nama driver klien. Klien tidak boleh menerapkan dan mendaftarkan EvtDeviceFilterRemoveResourceRequirements karena akan mengambil alih implementasi ekstensi kelas.

Setiap peran memiliki sejumlah sumber daya perangkat keras yang ditetapkan. Sumber daya tersebut bisa berupa memori, gangguan, dan sebagainya. Sumber daya dikelola oleh sistem dalam daftar persyaratan sumber daya yang berisi berbagai sumber daya perangkat keras tempat perangkat dapat beroperasi.

Untuk informasi selengkapnya tentang daftar persyaratan sumber daya, lihat Menangani Sumber Daya Perangkat Keras.

Ekstensi kelas mengalokasikan memori untuk daftar persyaratan sumber daya dan daftar sumber daya untuk peran host dan fungsi. Ketika ekstensi kelas memanggil implementasi EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS driver klien, ekstensi ini meneruskan handel WDFIORESREQLIST ke daftar persyaratan tersebut bersama dengan handel URSIORESLIST untuk daftar sumber daya peran host dan fungsi. Dalam implementasi, driver klien diharapkan untuk menghitung melalui konfigurasi logis dalam daftar persyaratan dan memeriksa deskriptor sumber daya untuk setiap konfigurasi dengan memanggil WdfIoResourceListGetDescriptor.

Jika driver ingin menggunakan sumber daya tertentu, driver dapat menambahkan deskriptor sumber daya terkait ke daftar sumber daya masing-masing dengan memanggil UrsIoResourceListAppendDescriptor.

Untuk menghapus deskriptor sumber daya dari daftar persyaratan, driver memanggil WdfIoResourceListRemove.

Contoh

EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtUrsFilterRemoveResourceRequirements;


_Function_class_(EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS)
_IRQL_requires_same_
_IRQL_requires_max_(PASSIVE_LEVEL)
NTSTATUS
EvtUrsFilterRemoveResourceRequirements (
    _In_ WDFDEVICE Device,
    _In_ WDFIORESREQLIST IoResourceRequirementsList,
    _In_ URSIORESLIST HostRoleResources,
    _In_ URSIORESLIST FunctionRoleResources
    )
{
    NTSTATUS status;
    WDFIORESLIST resList;
    ULONG resListCount;
    ULONG resCount;
    ULONG currentResourceIndex;
    PIO_RESOURCE_DESCRIPTOR descriptor;
    BOOLEAN assignToHost;
    BOOLEAN assignToFunction;
    BOOLEAN keepAssigned;

    TRY {

        status = STATUS_SUCCESS;

        //
        // Currently does not support multiple logical configurations. Only the first one
        // is considered.
        //

        resListCount = WdfIoResourceRequirementsListGetCount(IoResourceRequirementsList);
        if (resListCount == 0) {
            // No logical resource configurations found.
            LEAVE;
        }

        // Enumerate through logical resource configurations.

        resList = WdfIoResourceRequirementsListGetIoResList(IoResourceRequirementsList, 0);
        resCount = WdfIoResourceListGetCount(resList);


        for (currentResourceIndex = 0; currentResourceIndex < resCount; ++currentResourceIndex) {

            descriptor = WdfIoResourceListGetDescriptor(resList, currentResourceIndex);

            if (descriptor->Type == CmResourceTypeConfigData) {

                //
                // This indicates the priority of this logical configuration.
                // This descriptor can be ignored.
                //

                keepAssigned = TRUE;
                assignToFunction = FALSE;
                assignToHost = FALSE;

            } else if ((descriptor->Type == CmResourceTypeMemory) ||
                       (descriptor->Type == CmResourceTypeMemoryLarge)) {

                //
                // This example client driver keeps the memory resources here. 
                //

                keepAssigned = TRUE;
                assignToFunction = TRUE;
                assignToHost = TRUE;

            } else {

                //
                // For all other resources, pass it to the child device nodes for host and function.
                //

                keepAssigned = FALSE;
                assignToHost = TRUE;
                assignToFunction = TRUE;
            }

            if (assignToHost != FALSE) {
                status = UrsIoResourceListAppendDescriptor(HostRoleResources, descriptor);
                if (!NT_SUCCESS(status)) {
                    // UrsIoResourceListAppendDescriptor for HostRoleResources failed.
                    LEAVE;
                }
            }

            if (assignToFunction != FALSE) {
                status = UrsIoResourceListAppendDescriptor(FunctionRoleResources, descriptor);
                if (!NT_SUCCESS(status)) {
                    // UrsIoResourceListAppendDescriptor for FunctionRoleResources failed.
                    LEAVE;
                }
            }

            if (keepAssigned == FALSE) {
                WdfIoResourceListRemove(resList, currentResourceIndex);
                --currentResourceIndex;
                --resCount;
            }
        }

    } FINALLY {
    }

    return status;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 10
Server minimum yang didukung	Server Windows 2016
Target Platform	Windows
Versi KMDF minimum	1.15
Header	ursdevice.h (termasuk Urscx.h)
IRQL	PASSIVE_LEVEL

Lihat juga

Menangani Sumber Daya Perangkat Keras

UrsDeviceInitialize

UrsIoResourceListAppendDescriptor

WdfIoResourceListRemove