WdfIoTargetOpen 함수(wdfiotarget.h)

아티클
08/08/2023

[KMDF 및 UMDF에 적용]

WdfIoTargetOpen 메서드는 드라이버가 I/O 요청을 보낼 수 있도록 원격 I/O 대상을 엽니다.

구문

NTSTATUS WdfIoTargetOpen(
  [in] WDFIOTARGET                IoTarget,
  [in] PWDF_IO_TARGET_OPEN_PARAMS OpenParams
);

매개 변수

[in] IoTarget

WdfIoTargetCreate에 대한 이전 호출에서 가져온 I/O 대상 개체에 대한 핸들입니다.

[in] OpenParams

호출자가 할당한 WDF_IO_TARGET_OPEN_PARAMS 구조체에 대한 포인터입니다.

반환 값

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

반환 코드	설명
STATUS_INVALID_DEVICE_STATE	지정된 I/O 대상이 이미 열려 있습니다.
STATUS_INSUFFICIENT_RESOURCES	사용 가능한 시스템 리소스가 작업을 완료하기에 충분하지 않았습니다.
STATUS_INFO_LENGTH_MISMATCH	OpenParams가 지정한 WDF_IO_TARGET_OPEN_PARAMS 구조체의 크기가 잘못되었습니다.
STATUS_NO_SUCH_DEVICE	호출자의 WDF_IO_TARGET_OPEN_PARAMS 구조체의 TargetFileObject 멤버가 잘못된 파일 개체를 지정했습니다.
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 감지되었습니다.
STATUS_NOT_FOUND	OpenParams 매개 변수에서 식별된 디바이스 이름을 찾을 수 없습니다.

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

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

설명

드라이버는 개체 이름을 나타내는 유니코드 문자열을 제공하거나 WDM(Windows 드라이버 모델) DEVICE_OBJECT 구조체에 대한 포인터를 제공하여 원격 I/O 대상을 열 수 있습니다. (프레임워크 기반 드라이버에는 일반적으로 다른 드라이버의 DEVICE_OBJECT 구조에 대한 포인터가 없습니다.)

WdfIoTargetOpen을 호출하기 전에 디바이스 인터페이스 이름을 가져오려면 UMDF 드라이버가 CM_Register_Notification 호출하여 인터페이스 도착 및 제거 알림을 등록해야 합니다. 그런 다음 인터페이스 알림 콜백 루틴에서 수신하는 인터페이스 기호 이름을 사용하여 원격 대상을 열 수 있습니다. 핸들이 열려 있는 동안 드라이버는 제거 알림을 계속 수신 대기해야 합니다. 대상 드라이버가 실패하면 UMDF 드라이버는 핸들을 닫아야 합니다.

인터페이스가 이미 있는 경우 UMDF 드라이버는 CM_Get_Device_Interface_List 호출해야 하며, 필요한 버퍼 크기를 확인하기 위해 먼저 CM_Get_Device_Interface_List_Size 호출해야 합니다.

드라이버가 로컬 I/O 대상을 사용하도록 하려면 드라이버가 WdfIoTargetOpen 대신 WdfDeviceGetIoTarget을 호출해야 합니다.

WdfIoTargetOpen에 대한 호출이 실패하면 드라이버는 WdfObjectDelete를 호출하여 I/O 대상 개체를 삭제해야 합니다.

WdfIoTargetOpen에 대한 자세한 내용은 일반 I/O 대상 초기화를 참조하세요.

I/O 대상에 대한 자세한 내용은 I/O 대상 사용을 참조하세요.

예제

다음 예제에서는 I/O 대상 개체를 만들고 , WDF_IO_TARGET_OPEN_PARAMS 구조를 초기화하고, 디바이스의 기호 링크 이름을 지정하여 원격 I/O 대상을 엽니다.

WDF_OBJECT_ATTRIBUTES  ioTargetAttrib;
WDFIOTARGET  ioTarget;
WDF_IO_TARGET_OPEN_PARAMS  openParams;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ioTargetAttrib,
                                        TARGET_DEVICE_INFO
                                        );
status = WdfIoTargetCreate(
                           device,
                           &ioTargetAttrib,
                           &ioTarget
                           );
if (!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(
                                            &openParams,
                                            SymbolicLink,
                                            STANDARD_RIGHTS_ALL
                                            );
status = WdfIoTargetOpen(
                         ioTarget,
                         &openParams
                         );
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(ioTarget);
    return status;
}

요구 사항

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