EVT_WDF_USB_READER_COMPLETION_ROUTINE 콜백 함수(wdfusb.h)

  • 아티클

[KMDF 및 UMDF에 적용]

드라이버의 EvtUsbTargetPipeReadComplete 이벤트 콜백 함수는 연속 판독기가 읽기 요청을 성공적으로 완료했음을 드라이버에 알릴 수 있습니다.

구문

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

void EvtWdfUsbReaderCompletionRoutine(
  [in] WDFUSBPIPE Pipe,
  [in] WDFMEMORY Buffer,
  [in] size_t NumBytesTransferred,
  [in] WDFCONTEXT Context
)
{...}

매개 변수

[in] Pipe

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

[in] Buffer

디바이스의 데이터를 포함하는 버퍼를 나타내는 프레임워크 메모리 개체에 대한 핸들입니다.

[in] NumBytesTransferred

읽기 버퍼에 있는 데이터의 바이트 수입니다.

[in] Context

드라이버가 파이프의 WDF_USB_CONTINUOUS_READER_CONFIG 구조체의 EvtUsbTargetPipeReadCompleteContext 멤버에 지정한 드라이버 정의 컨텍스트 정보입니다.

반환 값

없음

설명

EvtUsbTargetPipeReadComplete 콜백 함수를 등록하려면 드라이버가 함수의 주소를 WDF_USB_CONTINUOUS_READER_CONFIG 구조에 배치해야 합니다.

드라이버가 USB 파이프에 대한 연속 판독기를 만든 경우 프레임워크는 드라이버의 I/O 대상이 읽기 요청을 성공적으로 완료할 때마다 드라이버의 EvtUsbTargetPipeReadComplete 콜백 함수를 호출합니다. 콜백 함수는 I/O 대상이 읽기 요청을 완료한 IRQL에서 호출됩니다. 이 요청은 일반적으로 IRQL = DISPATCH_LEVEL DISPATCH_LEVEL. (I/O 대상이 요청을 성공적으로 완료하지 못하면 프레임워크는 드라이버의 EvtUsbTargetPipeReadersFailed 콜백 함수를 호출합니다.)

디바이스에서 읽은 데이터가 포함된 버퍼에 액세스하기 위해 드라이버는 WdfMemoryGetBuffer를 호출할 수 있습니다. 프레임워크는 WDF_USB_CONTINUOUS_READER_CONFIG 구조체의 HeaderLength 멤버에 의해 정의된 헤더 다음에 데이터를 버퍼에 씁니다. WdfMemoryGetBuffer가 반환하는 포인터는 헤더의 시작을 가리키지만 EvtUsbTargetPipeReadComplete 콜백 함수의 NumBytesTransferred 매개 변수에는 헤더 길이가 포함되지 않습니다.

기본적으로 프레임워크는 EvtUsbTargetPipeReadComplete 콜백 함수가 반환된 후 버퍼의 메모리 개체를 삭제합니다. 그러나 콜백 함수가 반환된 후에도 메모리 개체가 유효한 상태로 유지되도록 할 수 있습니다. 예를 들어 드라이버가 프레임워크 파이프 개체의 컨텍스트 공간에 개체 핸들을 저장하여 콜백 함수가 반환된 후 드라이버가 메모리 개체의 내용을 처리할 수 있도록 할 수 있습니다. 메모리 개체의 수명을 연장하려면 콜백 함수가 메모리 개체의 핸들을 WdfObjectReference에 전달해야 합니다. 그런 다음, 프레임워크가 개체를 삭제할 수 있도록 드라이버가 WdfObjectDereference 를 호출해야 합니다.

프레임워크는 다음 규칙에 따라 EvtUsbTargetPipeReadComplete 및 EvtUsbTargetPipeReadersFailed 콜백 함수에 대한 호출을 동기화합니다.

  • 이러한 콜백 함수는 개별 USB 파이프에 대해 동시에 실행되지 않습니다.
  • 드라이버가 여러 개의 EvtUsbTargetPipeReadComplete 및 EvtUsbTargetPipeReadersFailed 콜백 함수를 사용하여 여러 USB 파이프에 대해 여러 연속 판독기를 만드는 경우 여러 콜백 함수를 동시에 실행할 수 있습니다.
  • 드라이버가 기본 NumPendingReads 값 또는 1보다 큰 값을 지정하고 EvtUsbTargetPipeReadComplete 콜백 함수가 실행되는 동안 읽기 요청이 완료되는 경우 프레임워크는 콜백 함수가 반환되기 전에 EvtUsbTargetPipeReadComplete 콜백 함수를 다시 호출할 수 있습니다.
  • 프레임워크는 이러한 콜백 함수를 다른 콜백 함수와 동기화하지 않습니다.
WDF_USB_CONTINUOUS_READER_CONFIG 구조체의 BufferAttributes 멤버에서 드라이버는 메모리 개체에 대해 EvtCleanupCallback 및 EvtDestroyCallback 콜백 함수를 지정할 수 있습니다. EvtCleanupCallback 콜백 함수를 지정하는 경우 프레임워크는 EvtUsbTargetPipeReadComplete 콜백 함수가 반환된 후 메모리 개체를 삭제하려고 할 때 해당 콜백 함수를 호출합니다. EvtUsbTargetPipeReadComplete 콜백 함수가 WdfObjectReference를 호출한 경우 EvtCleanupCallback 콜백 함수(제공된 경우)는 WdfObjectDereference를 호출하지 않아야 합니다.

드라이버는 메모리 개체 사용을 마쳤을 때 WdfObjectDereference 를 호출해야 합니다. 그런 다음 프레임워크는 드라이버의 EvtDestroyCallback 콜백 함수(제공된 경우)를 호출하고 메모리 개체를 삭제할 수 있습니다.

EvtUsbTargetPipeReadComplete 콜백 함수 및 USB I/O 대상에 대한 자세한 내용은 USB I/O 대상을 참조하세요.

요구 사항

요구 사항 값
대상 플랫폼 유니버설
최소 KMDF 버전 1.0
최소 UMDF 버전 2.0
머리글 wdfusb.h(Wdf.h 포함)
IRQL <=DISPATCH_LEVEL(설명 섹션 참조)

추가 정보

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer