EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE 콜백 함수(sercx.h)

아티클
02/04/2022
읽는 데 7분 걸림

EvtSerCx2SelectNextReceiveTransactionType 이벤트 콜백 함수는 SerCx2(직렬 프레임워크 확장) 버전 2에서 호출되어 다음 읽기 작업에 사용할 데이터 전송 메커니즘을 결정합니다.

구문

EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType;

SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType(
  [in]  WDFDEVICE Device,
  [in]  PMDL Mdl,
  [in]  ULONG Offset,
  [in]  ULONG RemainingLength,
  [out] SERCX2CUSTOMRECEIVE *CustomReceive,
  [out] PULONG NextTransactionLength
)
{...}

매개 변수

[in] Device

직렬 컨트롤러를 나타내는 프레임워크 디바이스 개체에 대한 WDFDEVICE 핸들입니다. 직렬 컨트롤러 드라이버는 EvtDriverDeviceAdd 콜백 함수에서 이 개체를 만들었습니다. 자세한 내용은 SerCx2InitializeDevice를 참조하세요.

[in] Mdl

다음 수신 트랜잭션에 대한 읽기 버퍼에 의해 확장되는 메모리 페이지를 설명하는 MDL 에 대한 포인터입니다. DMA 전송에 대한 분산/수집 목록은 Offset 및 Length 매개 변수로 지정된 이 메모리의 영역을 사용합니다.

[in] Offset

다음 데이터 전송의 시작 오프셋입니다. 이 매개 변수는 MDL에서 설명하는 버퍼 영역의 시작 부분부터의 바이트 오프셋입니다. MDL에서 버퍼 공간의 총 N바이트를 지정하는 경우 오프셋 의 가능한 값은 0에서 N-1까지의 범위에 있습니다.

[in] RemainingLength

현재 읽기(IRP_MJ_READ) 요청에서 전송될 데이터의 총 바이트 수입니다. MDL이 버퍼 공간의 총 N바이트 수를 지정하는 경우 가능한 Length 값은 1에서 N-오프셋까지의 범위에 있습니다.

[out] CustomReceive

함수가 사용자 지정 수신 개체에 SERCX2CUSTOMRECEIVE 핸들을 쓰는 위치에 대한 포인터입니다. 함수가 SerCx2TransactionTypeCustom을 반환하는 경우 함수는 SerCx2CustomReceiveCreate 메서드에 대한 이전 호출에서 만든 직렬 컨트롤러 드라이버가 만든 개체 핸들을 제공해야 합니다. 반환 값이 SerCx2TransactionTypeCustom이 아닌 경우 이 출력 값은 SerCx2에서 무시됩니다.

[out] NextTransactionLength

함수가 다음 수신 트랜잭션에서 전송할 바이트 수를 쓰는 위치에 대한 포인터입니다. 반환 값이 SerCx2TransactionTypeDefault이면 이 출력 값은 SerCx2에서 무시됩니다.

반환 값

EvtSerCx2SelectNextReceiveTransactionType 함수는 드라이버에서 선택한 트랜잭션 유형(프로그래밍된 I/O(PIO), 시스템 DMA 또는 사용자 지정 데이터 전송)을 사용할지 여부를 나타내거나 SerCx2가 다음 수신 트랜잭션에 사용할 트랜잭션 유형을 선택할 수 있도록 하기 위해 SERCX2_TRANSACTION_TYPE 열거형 상수를 반환합니다.

설명

직렬 컨트롤러 드라이버는 옵션으로 이 함수를 구현할 수 있습니다. 구현된 경우 드라이버는 직렬 컨트롤러에 대한 프레임워크 디바이스 개체의 초기화를 완료하는 SerCx2InitializeDevice 메서드 호출에서 이 함수를 등록합니다.

직렬 컨트롤러 드라이버가 EvtSerCx2SelectNextReceiveTransactionType 함수를 구현하지 않는 경우 SerCx2는 항상 다음 수신 트랜잭션에 사용할 데이터 전송 메커니즘(PIO, 시스템 DMA 또는 사용자 지정) 형식을 결정합니다. SerCx2는 직렬 컨트롤러 드라이버에서 제공하는 I/O 구성 정보에 대한 결정을 기반으로 합니다. 시스템 DMA 수신 트랜잭션을 지원하는 드라이버는 이 정보를 포함하는 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG 구조를 제공합니다. 사용자 지정 수신 트랜잭션을 지원하는 드라이버는 이 정보를 포함하는 SERCX2_CUSTOM_RECEIVE_CONFIG 구조를 제공합니다.

직렬 컨트롤러 드라이버가 EvtSerCx2SelectNextReceiveTransactionType 함수를 구현하는 경우 SerCx2는 이 함수를 호출하여 다음 수신 트랜잭션에 사용할 데이터 전송 메커니즘(PIO, 시스템 DMA 또는 사용자 지정) 유형을 결정합니다. 직렬 컨트롤러에 SERCX2_XXX_RECEIVE_CONFIG 구조의 I/O 구성 정보로 적절히 설명할 수 없는 특수 하드웨어 기능이 있는 경우 이 함수를 구현할 수 있습니다.

참고 직렬 컨트롤러 드라이버가 EvtSerCx2SelectNextReceiveTransactionType 함수를 구현하더라도 SerCx2는 PIO 수신 트랜잭션을 사용하여 먼저 이 함수를 호출하지 않고 특정 유형의 데이터 전송을 수행합니다.

자세한 내용은 SerCx2 I/O 트랜잭션 개요를 참조하세요.

예

EvtSerCx2CustomReceiveSelectNextTransactionType 콜백 함수를 정의하려면 먼저 정의하려는 콜백 함수의 형식을 식별하는 함수 선언을 제공해야 합니다. Windows 드라이버에 대한 콜백 함수 형식 집합을 제공합니다. 콜백 함수 형식을 사용하여 함수를 선언하면 드라이버, SDV(정적 드라이버 검증 도구) 및 기타 확인 도구에 대한 Code Analysis 오류를 찾을 수 있으며, Windows 운영 체제용 드라이버를 작성하기 위한 요구 사항입니다.

예를 들어 이름이 지정된 MyCustomReceiveSelectNextTransactionTypeEvtSerCx2CustomReceiveSelectNextTransactionType 콜백 함수를 정의하려면 이 코드 예제와 같이 EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE 함수 형식을 사용합니다.

EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE  MyCustomReceiveTransactionStart;

그런 다음 다음과 같이 콜백 함수를 구현합니다.

_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
  EvtSerCx2SelectNextReceiveTransactionType(
    WDFDEVICE  Device,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  RemainingLength,
    SERCX2CUSTOMRECEIVE  *CustomReceive,
    PULONG  NextTransactionLength
    )
  {...}

EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE 함수 형식은 Sercx.h 헤더 파일에 정의되어 있습니다. 코드 분석 도구를 실행할 때 오류를 보다 정확하게 식별하려면 함수 정의에 Use_decl_annotations 주석을 추가해야 합니다. Use_decl_annotations 주석은 헤더 파일의 EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE 함수 형식에 적용되는 주석이 사용되는지 확인합니다. 함수 선언 요구 사항에 대한 자세한 내용은 KMDF 드라이버에 함수 역할 형식을 사용하여 함수 선언을 참조하세요. Use_decl_annotations 대한 자세한 내용은 함수 동작에 주석을 추가하세요.

요구 사항


지원되는 최소 클라이언트	Windows 8.1 시작해서 사용할 수 있습니다.
대상 플랫폼	데스크톱
헤더	sercx.h
IRQL	IRQL <= DISPATCH_LEVEL 호출합니다.