WdfUsbTargetDeviceSelectConfig 함수(wdfusb.h)

아티클
08/08/2023

[KMDF 및 UMDF에 적용]

WdfUsbTargetDeviceSelectConfig 메서드는 디바이스에 대한 USB 구성을 선택하거나 디바이스를 구성 해제합니다.

구문

NTSTATUS WdfUsbTargetDeviceSelectConfig(
  [in]           WDFUSBDEVICE                         UsbDevice,
  [in, optional] PWDF_OBJECT_ATTRIBUTES               PipeAttributes,
  [in, out]      PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);

매개 변수

[in] UsbDevice

WdfUsbTargetDeviceCreateWithParameters에 대한 이전 호출에서 가져온 USB 디바이스 개체에 대한 핸들입니다.

[in, optional] PipeAttributes

프레임워크가 디바이스 인터페이스에 대해 만드는 새 프레임워크 USB 파이프 개체에 대한 특성을 포함하는 호출자가 할당한 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. KMDF 드라이버의 경우 이 매개 변수는 선택 사항이며 WDF_NO_OBJECT_ATTRIBUTES 수 있습니다. UMDF 드라이버는 이 매개 변수를 NULL로 설정해야 합니다.

[in, out] Params

호출자와 프레임워크가 구성 매개 변수를 지정하는 데 사용하는 호출자 할당 WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 구조체에 대한 포인터입니다.

반환 값

작업이 성공하면 WdfUsbTargetDeviceSelectConfig는 I/O 대상의 완료 상태 값을 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 감지되었습니다.
STATUS_INFO_LENGTH_MISMATCH	Params가 가리키는 WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 구조체의 Size 멤버가 잘못되었습니다.
STATUS_INSUFFICIENT_RESOURCES	메모리 버퍼를 할당할 수 없습니다.
STATUS_NOT_SUPPORTED	UMDF 드라이버가 ParamsType이 다음 중 어느 것으로 설정된 WdfUsbTargetDeviceSelectConfig를 호출하면 프레임워크는 이 값을 반환합니다->. WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb 자세한 내용은 WdfUsbTargetDeviceSelectConfigType을 참조하세요.

이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.

드라이버가 잘못된 개체 핸들을 제공하는 경우 버그 검사 발생합니다.

설명

드라이버는 WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 구조를 사용하여 USB 설명자, URB 또는 프레임워크 USB 인터페이스 개체에 대한 핸들을 지정하여 디바이스 구성을 선택할 수 있습니다.

프레임워크는 프레임워크가 이전에 구성을 위해 만들었을 수 있는 파이프 개체를 삭제한 후 구성의 각 인터페이스와 연결된 각 파이프에 대해 프레임워크 USB 파이프 개체를 만듭니다. 프레임워크는 드라이버가 다른 대체 설정을 지정하지 않는 한 각 인터페이스에 대해 대체 설정 0을 사용합니다.

인터페이스의 파이프 개체에 대한 정보를 얻기 위해 드라이버는 WdfUsbInterfaceGetNumConfiguredPipes 및 WdfUsbInterfaceGetConfiguredPipe를 호출할 수 있습니다.

WdfUsbTargetDeviceSelectConfig 메서드 및 USB I/O 대상에 대한 자세한 내용은 USB I/O 대상을 참조하세요.

주의

WdfUsbTargetDeviceSelectConfig를 사용하여 설명자 목록에 나열된 첫 번째 USB 구성만 선택할 수 있지만 이 단일 구성 내에서 여러 인터페이스를 선택할 수 있습니다.

예제

다음 코드 예제에서는 지정된 단일 인터페이스가 있는 구성을 선택합니다.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
NTSTATUS  status;

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(&configParams);

status = WdfUsbTargetDeviceSelectConfig(
                                        UsbDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &configParams
                                        );

다음 코드 예제에서는 모든 인터페이스에서 대체 설정 0을 사용하여 여러 인터페이스가 있는 구성을 선택합니다. 이 예제는 KMDF 드라이버에만 적용됩니다.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
PWDF_USB_INTERFACE_SETTING_PAIR settingPairs;
UCHAR numInterfaces;
NTSTATUS  status;

numInterfaces = WdfUsbTargetDeviceGetNumInterfaces(UsbDevice);

settingPairs = ExAllocatePoolWithTag(
    PagedPool,
    sizeof(WDF_USB_INTERFACE_SETTING_PAIR) * numInterfaces,
    MY_DRIVER_TAG
);

if (settingPairs == NULL){
    return STATUS_INSUFFICIENT_RESOURCES;
}

for (interfaceIndex = 0; interfaceIndex < numInterfaces; interfaceIndex++) {
        
    settingPairs[interfaceIndex].UsbInterface = 
                                    WdfUsbTargetDeviceGetInterface(
                                        UsbDevice,
                                        interfaceIndex);

    // Select alternate setting zero on all interfaces.
       
    settingPairs[interfaceIndex].SettingIndex = 0;
}

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(
    &configParams,
    numInterfaces,
    settingPairs
);

status = WdfUsbTargetDeviceSelectConfig(
    UsbDevice,
    NULL,
    &configParams
);

if (!NT_SUCCESS(status)) {
    ExFreePoolWithTag(
        settingPairs,
        MY_DRIVER_TAG
    );
    return status;
}

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
머리글	wdfusb.h(Wdfusb.h 포함)
라이브러리	Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)