WdfUsbTargetDeviceCreateWithParameters 함수(wdfusb.h)

아티클
08/08/2023

[KMDF 및 UMDF에 적용]

WdfUsbTargetDeviceCreateWithParameters 메서드는 지정된 프레임워크 디바이스 개체에 대한 프레임워크 USB 디바이스 개체를 만들고 I/O 작업을 위한 USB 디바이스를 엽니다. 메서드는 프레임워크 USB 디바이스 개체에 대한 구성 정보도 지정합니다.

구문

NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
  [in]           WDFDEVICE                     Device,
  [in]           PWDF_USB_DEVICE_CREATE_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out]          WDFUSBDEVICE                  *UsbDevice
);

매개 변수

[in] Device

프레임워크 디바이스 개체에 대한 핸들입니다.

[in] Config

프레임워크 USB 디바이스 개체에 대한 구성 정보를 포함하는 WDF_USB_DEVICE_CREATE_CONFIG 구조체에 대한 포인터입니다.

[in, optional] Attributes

새 프레임워크 USB 디바이스 개체에 대한 특성을 포함하는 호출자가 제공하는 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 구조체의 ParentObject 멤버는 NULL이어야 합니다. 이 매개 변수는 선택 사항이며 WDF_NO_OBJECT_ATTRIBUTES 수 있습니다.

[out] UsbDevice

새 프레임워크 USB 디바이스 개체에 대한 핸들을 수신하는 위치에 대한 포인터입니다.

반환 값

WdfUsbTargetDeviceCreateWithParameters는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_INFO_LENGTH_MISMATCH	Config 매개 변수가 올바른 크기가 아닙니다.
STATUS_INSUFFICIENT_RESOURCES	새 프레임워크 USB 디바이스 개체를 만들기 위한 메모리가 부족했습니다.
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 감지되었습니다. 자세한 내용은 설명 부분을 참조하세요.
STATUS_UNSUCCESSFUL	USB 구성 정보를 가져오는 데 실패했습니다.

WdfUsbTargetDeviceCreateWithParameters 메서드가 반환할 수 있는 다른 반환 값 목록은 프레임워크 개체 만들기 오류를 참조하세요.

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

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

설명

Windows 8 USB 3.0 디바이스를 지원하는 새 USB 드라이버 스택이 포함되어 있습니다.

프레임워크 기반 클라이언트 드라이버가 Windows 8 USB 드라이버 스택의 새로운 기능을 사용하려면 먼저 드라이버가 디바이스용 Windows에서 로드하는 기본 USB 드라이버 스택에 등록해야 합니다. 클라이언트 드라이버를 등록하려면 WdfUsbTargetDeviceCreateWithParameters 를 호출하고 WDF_USB_DEVICE_CREATE_CONFIG 구조에서 계약 버전을 지정합니다.

클라이언트 드라이버가 Windows 8 향상된 기능과 새로운 기능을 빌드, 실행 및 사용하려는 경우 클라이언트 계약 버전이 USBD_CLIENT_CONTRACT_VERSION_602.

일반적으로 드라이버는 EvtDevicePrepareHardware 콜백 함수 내에서 WdfUsbTargetDeviceCreateWithParameters를 호출합니다. 드라이버는 EvtDriverDeviceAdd 콜백 함수 내에서 WdfUsbTargetDeviceCreateWithParameters를 호출할 수도 있습니다.

WDM USB 클라이언트 드라이버가 USB 3.0 드라이버 스택과 상호 작용하는 방법에 대한 자세한 내용은 모범 사례: URL 사용을 참조하세요.

드라이버가 WdfUsbTargetDeviceCreateWithParameters 를 호출하여 프레임워크 USB 디바이스 개체를 만드는 경우 드라이버는 WdfUsbTargetDeviceCreateUrb 또는 WdfUsbTargetDeviceCreateIsochUrb를 호출해야만 URL을 만들어야 합니다.

UMDF 드라이버에서 이 메서드를 호출하는 경우 드라이버의 INF 파일에서 UmdfDispatcher 지시문을 지정해야 합니다. 그렇지 않으면 이 메서드가 STATUS_INVALID_PARAMETER 반환할 수 있습니다. 이 지시문에 대한 자세한 내용은 INF 파일에서 WDF 지시문 지정을 참조하세요.

예제

다음 코드 예제는 WdfUsbTargetDeviceCreateWithParameters를 호출하는 EvtDevicePrepareHardware 콜백 함수의 일부입니다. 이 예제에서는 드라이버 정의 컨텍스트 공간에서 프레임워크 USB 디바이스 개체에 핸들을 저장합니다.

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;
    WDF_USB_DEVICE_CREATE_CONFIG  Config;

    pMyDeviceContext = GetDeviceContext(Device);

    // If object handle is not NULL, MyEvtDevicePrepareHardware
    // was called previously and the handle is still valid.
    if (pMyDeviceContext->UsbDevice != NULL) {
        return STATUS_SUCCESS;
    }

    WDF_USB_DEVICE_CREATE_CONFIG_INIT(
                                      &Config,
                                      USBD_CLIENT_CONTRACT_VERSION_602
                                      );

    status = WdfUsbTargetDeviceCreateWithParameters(
                                      Device,
                                      &Config,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

요구 사항

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