SerCx2CustomReceiveCreate 함수(sercx.h)

아티클
10/30/2024

SerCx2CustomReceiveCreate 메서드는 사용자 지정 수신 개체를 만듭니다. 이 개체는 SerCx2(직렬 프레임워크 확장 버전 2)가 사용자 지정 데이터 전송 메커니즘을 통해 직렬 컨트롤러에서 수신 데이터를 읽는 데 사용합니다.

통사론

NTSTATUS SerCx2CustomReceiveCreate(
  [in]  WDFDEVICE                     Device,
  [in]  PSERCX2_CUSTOM_RECEIVE_CONFIG CustomReceiveConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out] SERCX2CUSTOMRECEIVE           *CustomReceive
);

매개 변수

[in] Device

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

[in] CustomReceiveConfig

SERCX2_CUSTOM_RECEIVE_CONFIG 구조체에 대한 포인터입니다. 이 메서드를 호출하기 전에 호출자는 SERCX2_CUSTOM_RECEIVE_CONFIG_INIT 함수를 호출하여 구조를 초기화해야 합니다. 이 구조에는 직렬 컨트롤러 드라이버에서 구현하는 이벤트 콜백 루틴 집합에 대한 포인터가 포함됩니다. SerCx2는 이러한 함수를 호출하여 사용자 지정 수신 트랜잭션을 수행합니다.

[in] Attributes

새 사용자 지정 수신 개체에 할당할 특성을 설명하는 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 이 메서드를 호출하기 전에 호출자는 WDF_OBJECT_ATTRIBUTES_INIT 함수를 호출하여 구조를 초기화해야 합니다. 이 매개 변수는 선택 사항이며 직렬 컨트롤러 드라이버가 개체에 특성을 할당할 필요가 없는 경우 WDF_NO_OBJECT_ATTRIBUTES 지정할 수 있습니다. 자세한 내용은 비고를 참조하세요.

[out] CustomReceive

이 메서드가 새로 만든 사용자 지정 수신 개체에 SERCX2CUSTOMRECEIVE 핸들을 쓰는 위치에 대한 포인터입니다. SerCx2 및 직렬 컨트롤러 드라이버는 이 개체를 참조하기 위해 후속 호출에서 이 핸들을 사용합니다.

반환 값

이 메서드는 호출에 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값에는 다음 상태 코드가 포함됩니다.

반환 코드	묘사
STATUS_INVALID_DEVICE_REQUEST	이전 SerCx2CustomReceiveCreate 호출에서 사용자 지정 수신 개체가 이미 있습니다. 또는 이전 SerCx2CustomReceiveCreate 호출에서 시스템 DMA 수신 개체가 있습니다. 또는 이전 SerCx2CustomTransmitCreate 호출에서 시스템 DMA 전송 개체가 존재합니다. 또는 SerCx2PioReceiveCreate PIO 수신 개체를 만들기 위해 아직 호출되지 않았습니다.
STATUS_INVALID_PARAMETER	매개 변수 값이 잘못되었습니다.
STATUS_INFO_LENGTH_MISMATCH	구성크기 값이(SERCX2_CUSTOM_RECEIVE_CONFIG)의 크기와 같지 않습니다.
STATUS_INSUFFICIENT_RESOURCES	사용자 지정 수신 개체를 만드는 데 사용할 수 있는 리소스가 부족합니다.

발언

이 메서드는 사용자 지정 수신 개체를 만들기 위해 직렬 컨트롤러 드라이버에 의해 호출 됩니다. SerCx2는 사용자 지정 데이터 전송 메커니즘을 사용하여 직렬 컨트롤러에서 받은 데이터를 읽는 트랜잭션인 사용자 지정 수신 트랜잭션을 수행하는 데 이 개체를 사용합니다.

직렬 컨트롤러 드라이버는 SerCx2CustomReceiveCreate호출하기 전에 SerCx2InitializeDevice 및 SerCx2PioReceiveCreate 메서드를 호출해야 합니다.

SerCx2CustomReceiveCreate호출하기 전에 직렬 컨트롤러 드라이버는 SERCX2_CUSTOM_RECEIVE_CONFIG_INIT 함수를 호출하여 CustomReceiveConfig가리키는 SERCX2_CUSTOM_RECEIVE_CONFIG 구조를 초기화해야 합니다. 이 함수는 구조체의 다음 멤버를 0으로 설정합니다.

맞춤
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
배타적

필요한 경우 직렬 컨트롤러 드라이버는 초기화 함수가 반환된 후 이러한 멤버를 0이 아닌 값으로 설정할 수 있습니다. 그러나 편의상 SerCx2CustomReceiveCreate 이러한 멤버가 0인 경우 다음 기본값을 사용합니다.

맞춤 0이면 SerCx2는 데이터 맞춤 값을 1로 설정합니다. 즉, 읽기 버퍼는 메모리의 임의의 바이트 경계에서 시작할 수 있습니다.
MinimumTransactionLength 0이면 SerCx2는 최소 트랜잭션 길이를 1바이트로 설정합니다.
MaximumTransactionLength 0이면 SerCx2는 최대 트랜잭션 길이를 (ULONG)-1로 설정합니다.
MinimumTransferUnit 0이면 SerCx2는 최소 전송 단위를 1 바이트로 설정합니다.
배타적 0(FALSE)이면 배타적 모드가 비활성화됩니다.

호출 드라이버가 배타적TRUE설정하는 경우 MinimumTransferUnit, 맞춤및 MinimumTransactionLength 멤버는 0이어야 합니다. 자세한 내용은 SERCX2_CUSTOM_RECEIVE_CONFIG참조하세요.

옵션으로 직렬 컨트롤러 드라이버는 Attributes 매개 변수를 사용하여 사용자 지정 수신 개체에 대한 컨텍스트를 만들고 EvtCleanupCallback 및 EvtDestroyCallback 함수에 대한 포인터를 제공하여 삭제할 개체를 준비할 수 있습니다. 자세한 내용은 WDF_OBJECT_ATTRIBUTES참조하세요.

Attributes 매개 변수가 WDF_OBJECT_ATTRIBUTES 구조를 가리키는 경우 호출자는 WDF_OBJECT_ATTRIBUTES_INIT 초기화 함수가 ParentObject, ExecutionLevel및 SynchronizationScope 멤버에 쓰는 값을 덮어쓰지 않아야 합니다.

사용자 지정 수신 개체를 만드는 방법에 대한 자세한 내용은 SERCX2CUSTOMRECEIVE참조하세요. 사용자 지정 수신 트랜잭션에 대한 자세한 내용은 SerCx2 Custom-Receive Transactions참조하세요.

요구 사항

요구	값
지원되는 최소 클라이언트	Windows 8.1 시작해서 사용할 수 있습니다.
대상 플랫폼	보편적
헤더	sercx.h
IRQL	PASSIVE_LEVEL