IWDFUsbTargetPipe2::ConfigureContinuousReader 메서드(wudfusb.h)

아티클
08/08/2023

[경고: 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 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_STATE)	드라이버는 이미 USB 파이프에 대한 연속 판독기를 구성했습니다. USB 파이프는 대량 또는 인터럽트 입력 전송을 위해 설정되지 않았습니다.
E_OUTOFMEMORY	버퍼를 할당하려는 프레임워크의 시도가 실패했습니다.
ERROR_ARITHMETIC_OVERFLOW	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 구성을 포함한 다양한 하드웨어 구성이 포함되어야 합니다. 그런 다음 동일한 테스트를 사용하여 더 높은 값으로 실험할 수 있습니다. 더 높은 값이 필요할 수 있는 드라이버는 인터럽트 속도가 높은 디바이스에 대한 드라이버로, 인터럽트 서비스가 신속하게 수행되지 않으면 데이터가 손실될 수 있습니다.

NumPendingReads 값이 너무 크면 시스템 성능이 저하될 수 있습니다. 성능 요구 사항을 충족하는 가장 낮은 값을 사용해야 합니다. 일반적으로 3~4보다 높은 값은 데이터 처리량을 개선하지 않습니다. 그러나 값이 높을수록 고주파 파이프에서 대기 시간 또는 데이터 누락 가능성을 줄일 수 있습니다.

드라이버가 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