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