IWDFUsbTargetPipe2::ConfigureContinuousReader 메서드(wudfusb.h)
[경고: UMDF 2는 UMDF의 최신 버전이며 UMDF 1을 대체합니다. 모든 새 UMDF 드라이버는 UMDF 2를 사용하여 작성해야 합니다. UMDF 1에는 새로운 기능이 추가되지 않으며 최신 버전의 Windows 10에서는 UMDF 1에 대한 지원이 제한되어 있습니다. 유니버설 Windows 드라이버는 UMDF 2를 사용해야 합니다. 자세한 내용은 UMDF시작 .]을 참조하세요.
ConfigureContinuousReader 메서드는 USB 파이프에서 지속적으로 읽도록 프레임워크를 구성합니다.
통사론
HRESULT ConfigureContinuousReader(
[in] SIZE_T TransferLength,
[in] SIZE_T HeaderLength,
[in] SIZE_T TrailerLength,
[in] UCHAR NumPendingReads,
[in, optional] IUnknown *pMemoryCleanupCallbackInterface,
[in] IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletion,
[in, optional] PVOID pCompletionContext,
[in, optional] IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailure
);
매개 변수
[in] TransferLength
디바이스에서 수신할 수 있는 데이터의 최대 길이(바이트)입니다.
[in] HeaderLength
디바이스에서 데이터를 수신하는 버퍼에 대한 오프셋(바이트)입니다. 프레임워크는 오프셋 값부터 시작하여 디바이스의 데이터를 읽기 버퍼에 저장합니다. 즉, 이 공간은 프레임워크가 디바이스의 데이터를 저장하는 TransferLength크기 공간 앞에 섰습니다.
[in] TrailerLength
후행 버퍼 공간의 길이(바이트)입니다. 이 공간은 프레임워크가 디바이스에서 데이터를 저장하는 TransferLength크기 공간을 따릅니다.
[in] NumPendingReads
I/O 대상에서 데이터를 수신하기 위해 프레임워크에서 큐에 대기하는 읽기 요청 수입니다. 이 값이 0이면 프레임워크는 기본 읽기 요청 수를 사용합니다. 지정된 값이 허용되는 최대값보다 큰 경우 프레임워크는 허용되는 최대값을 사용합니다. NumPendingReads 매개 변수에 대한 자세한 내용은 다음 설명 섹션을 참조하세요.
[in, optional] pMemoryCleanupCallbackInterface
프레임워크가 선택적 IObjectCleanup::OnCleanup 콜백 함수에 액세스하는 데 사용하는 드라이버 제공 IUnkown 인터페이스에 대한 포인터입니다. 프레임워크는 연속 읽기 작업을 처리하기 위해 만든 읽기 버퍼의 할당을 취소할 때 콜백 함수를 호출합니다. 이 매개 변수는 선택 사항이며 NULL 수 있습니다.
[in] pOnCompletion
OnReaderCompletion 콜백 함수를 제공하는 드라이버 제공 IUsbTargetPipeContinuousReaderCallbackReadComplete 인터페이스에 대한 포인터입니다.
[in, optional] pCompletionContext
프레임워크가 드라이버의 IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion 콜백 함수에 전달하는 드라이버 정의 컨텍스트 정보에 대한 형식화되지 않은 포인터입니다.
[in, optional] pOnFailure
OnReaderFailure 콜백 함수를 제공하는 드라이버 제공 IUsbTargetPipeContinuousReaderCallbackReadersFailed 인터페이스에 대한 포인터입니다.
반환 값
ConfigureContinuousReader 작업이 성공하면 S_OK 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.
| 반환 코드 | 묘사 |
|---|---|
|
드라이버가 USB 파이프에 대한 연속 판독기를 이미 구성했습니다.
USB 파이프가 대량 또는 인터럽트 입력 전송에 대해 설정되지 않았습니다. |
|
버퍼를 할당하려는 프레임워크의 시도가 실패했습니다. |
|
TransferLength, HeaderLength또는 TrailerLength 매개 변수가 너무 크거나 유효하지 않은 크기를 지정했습니다. |
이 메서드는 Winerror.h에 포함된 다른 값 중 하나를 반환할 수 있습니다.
발언
대량 파이프 또는 인터럽트 파이프에 대한 연속 판독기를 구성할 수 있습니다. 파이프에는 입력 엔드포인트가 있어야 합니다.
ConfigureContinuousReader 호출하여 연속 판독기를 구성한 후 드라이버는 IWDFIoTargetStateManagement::Start 호출하여 판독기를 시작해야 합니다. 판독기를 중지하려면 드라이버가 IWDFIoTargetStateManagement::stop호출해야 합니다.
일반적으로 드라이버는 IPnpCallbackHardware::OnPrepareHardware 콜백 함수 내에서 ConfigureContinuousReader를 호출합니다. 드라이버는 IPnpCallback::OnD0Entry 콜백 함수 내에서 IWDFIoTargetStateManagement::Start 호출해야 하며 IPnpCallback::OnD0Exit 콜백 함수 내에서 IWDFIoTargetStateManagement::Stop 호출해야 합니다.
파이프의 I/O 대상이 읽기 요청을 성공적으로 완료할 때마다 프레임워크는 드라이버의 IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion 콜백 함수를 호출합니다. I/O 대상이 요청을 처리하는 동안 오류를 보고하는 경우 프레임워크는 모든 읽기 요청이 완료된 후 드라이버의 IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure 콜백 함수를 호출합니다. 따라서 OnReaderFailure 콜백 함수가 실행되는 동안에는 OnReaderCompletion 콜백 함수가 호출되지 않습니다.
다음 지침을 사용하여 NumPendingReads 매개 변수에 대한 값을 선택합니다.
-
드라이버가 프레임워크의 기본값을 사용하도록 하려면 NumPendingReads 0으로 설정합니다.
기본값은 1보다 크며 많은 프로세서 구성에서 많은 디바이스에 대해 합리적으로 좋은 성능을 제공합니다.
-
드라이버가 디바이스에서 데이터를 제공하는 정확한 순서로 데이터 버퍼를 수신하는 것이 중요한 경우 NumPendingReads 1로 설정합니다.
프레임워크가 둘 이상의 읽기 요청을 큐에 대기하는 경우 드라이버는 디바이스가 데이터를 제공하는 순서와 동일한 순서로 데이터 버퍼를 수신하지 못할 수 있습니다.
-
NumPendingReads 철저한 성능 측정에 따라 디바이스의 성능 요구 사항을 충족하는 숫자로 설정합니다.
먼저 numPendingReads 기본값(0)으로 디바이스를 테스트합니다. 테스트에는 다양한 형식 및 프로세서 수, 다양한 USB 호스트 컨트롤러 및 USB 구성을 비롯한 다양한 하드웨어 구성이 포함되어야 합니다. 그런 다음 동일한 테스트를 사용하여 더 높은 값을 실험할 수 있습니다. 더 높은 값이 필요할 수 있는 드라이버는 인터럽트 속도가 높은 디바이스에 대한 드라이버로, 인터럽트를 신속하게 서비스하지 않으면 데이터가 손실될 수 있습니다.
드라이버가 ConfigureContinuousReader호출한 후에는 드라이버의 IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure 콜백 함수가 호출되고 FALSE반환하지 않는 한 드라이버는 IWDFIoRequest::Send 사용하여 I/O 요청을 파이프에 보낼 수 없습니다.
ConfigureContinuousReader 메서드 및 USB I/O 대상에 대한 자세한 내용은 UMDF-USB 파이프 읽기를 참조하세요.
예제
다음 코드 예제에서는 연속 판독기를 구성합니다. 이 예제에서 최대 버퍼 크기는 드라이버 정의 버퍼의 크기입니다. 헤더 및 트레일러 버퍼 오프셋은 0으로 설정되고 보류 중인 읽기 작업의 수는 2로 설정됩니다. 이 예제에서는 pCompletionContext 매개 변수에 대상 파이프의 인터페이스 포인터를 사용하므로 OnReaderCompletion 콜백 함수는 읽기 작업이 완료된 파이프를 확인할 수 있습니다.
HRESULT hr, hrQI;
IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletionCallback = NULL;
IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailureCallback= NULL;
IWDFUsbTargetPipe2 * pIUsbInterruptPipe2;
//
// Obtain interfaces.
//
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnFailureCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = m_pIUsbInterruptPipe->QueryInterface(IID_PPV_ARGS(&pIUsbInterruptPipe2));
if (!SUCCEEDED(hrQI)) goto Error;
//
// Configure the reader.
//
hr = pIUsbInterruptPipe2->ConfigureContinuousReader(
sizeof(m_MyBuffer),
0,
0,
2,
NULL,
pOnCompletionCallback,
m_pIUsbTargetPipe,
pOnFailureCallback
);
...
요구 사항
| 요구 | 값 |
|---|---|
| 지원 종료 | UMDF 2.0 이상에서는 사용할 수 없습니다. |
| 대상 플랫폼 | 바탕 화면 |
| 최소 UMDF 버전 | 1.9 |
| 헤더 | wudfusb.h(Wudfusb.h 포함) |
| DLL | WUDFx.dll |
참고 항목
IPnpCallbackHardware::OnPrepareHardware
IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion
IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure
IWDFIoTargetStateManagement::start