EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS回呼函式 (ursdevice.h)

USB 雙重角色類別延伸模組會叫用此回呼，以允許用戶端驅動程式將資源從 resource-requirements-list 物件插入資源清單，這些資源將在每個角色的存留期間使用。

語法

EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtUrsDeviceFilterResourceRequirements;

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

參數

[in] Device

用戶端驅動程式在先前呼叫 WdfDeviceCreate 中擷取的架構裝置物件的句柄。

[in] IoResourceRequirementsList

架構 resource-requirements-list 物件的句柄，代表裝置的資源需求清單。

[in] HostRoleResources

控制器裝置在主機模式中運作時的資源清單句柄。

[in] FunctionRoleResources

控制器在函式模式中運作時的資源清單句柄。

傳回值

如果作業成功，回呼函式必須傳回STATUS_SUCCESS，或NT_SUCCESS (状态) 等於 TRUE 的另一個狀態值。 否則，它必須傳回狀態值，NT_SUCCESS (状态) 等於 FALSE。

備註

用戶端驅動程式會在呼叫 WdfDeviceCreate 之後呼叫 UrsDeviceInitialize，以使用 USB 雙重角色類別延伸模塊註冊其實作，以建立控制器的架構裝置物件。 類別延伸模組會在 EvtDevicePrepareHardware 之前叫用此回呼。 回呼會在類別延伸模組的 EvtDeviceFilterRemoveResourceRequirements 內叫用，其代表用戶端驅動程序註冊。 用戶端不得實作並註冊其 EvtDeviceFilterRemoveResourceRequirements ，因為它會覆寫類別延伸模組的實作。

每個角色都有一定數目的指派硬體資源。 這些資源可以是記憶體、中斷等等。 資源是由系統在 資源需求清單中 維護，其中包含裝置可運作的硬體資源範圍。

如需資源需求清單的詳細資訊，請參閱 處理硬體資源。

類別延伸模組會為主機和函式角色的資源 需求清單 和資源 清單 配置記憶體。 當類別延伸模組叫用用戶端驅動程式的 EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS實作時，它會將WDFIORESREQLIST 句柄傳遞給該需求清單，以及主機和函式角色 資源清單的URSIORESLIST句柄。 在實作中，用戶端驅動程式預期會透過需求清單中的邏輯組態列舉，並藉由呼叫 WdfIoResourceListGetDescriptor 來檢查每個設定的資源描述元。

如果驅動程式想要使用特定資源，它可以呼叫 UrsIoResourceListAppendDescriptor，將相關聯的資源描述元新增至個別的資源清單。

若要從需求清單中刪除資源描述元，驅動程式會呼叫 WdfIoResourceListRemove。

範例

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;
}

規格需求

另請參閱

處理硬體資源

UrsDeviceInitialize

UrsIoResourceListAppendDescriptor

WdfIoResourceListRemove