EVT_SERCX2_CONTROL 콜백 함수(sercx.h)
EvtSerCx2Control 이벤트 콜백 함수는 직렬 I/O 제어 요청을 처리하기 위해 SerCx2(직렬 프레임워크 확장) 버전 2에서 호출됩니다.
구문
EVT_SERCX2_CONTROL EvtSercx2Control;
NTSTATUS EvtSercx2Control(
[in] WDFDEVICE Device,
[in] WDFREQUEST Request,
[in] size_t OutputBufferLength,
[in] size_t InputBufferLength,
[in] ULONG IoControlCode
)
{...}
매개 변수
[in] Device
직렬 컨트롤러를 나타내는 프레임워크 디바이스 개체에 대한 WDFDEVICE 핸들입니다. 직렬 컨트롤러 드라이버는 EvtDriverDeviceAdd 콜백 함수에서 이 개체를 만들었습니다. 자세한 내용은 SerCx2InitializeDevice를 참조하세요.
[in] Request
직렬 I/O 컨트롤 요청을 나타내는 프레임워크 요청 개체에 대한 WDFREQUEST 핸들입니다.
[in] OutputBufferLength
Request 매개 변수로 지정된 직렬 I/O 컨트롤 요청에 대한 출력 버퍼의 길이(바이트)입니다.
[in] InputBufferLength
Request 매개 변수로 지정된 직렬 I/O 컨트롤 요청에 대한 입력 버퍼의 길이(바이트)입니다.
[in] IoControlCode
Request 매개 변수로 지정된 직렬 I/O 컨트롤 요청의 I/O 제어 코드(IOCTL)를 지정합니다. 직렬 I/O 컨트롤 요청에 대한 IOCTL은 Ntddser.h 헤더 파일에 정의됩니다. 자세한 내용은 설명 부분을 참조하세요.
반환 값
EvtSerCx2Control 함수는 호출이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 적절한 오류 상태 코드를 반환합니다.
설명
직렬 컨트롤러 드라이버는 이 함수를 구현해야 합니다. 드라이버는 직렬 컨트롤러에 대한 프레임워크 디바이스 개체의 초기화를 완료하는 SerCx2InitializeDevice 메서드 호출에서 함수를 등록합니다.
EvtSerCx2Control 함수를 사용하면 드라이버가 SerCx2에서 처리할 수 없는 특정 직렬 I/O 컨트롤 요청을 처리할 수 있습니다. SerCx2는 Ntddser.h 헤더 파일에 정의된 직렬 IOCTL의 하위 집합에 대한 모든 처리를 처리합니다. 그러나 SerCx2는 드라이버에서 직렬 I/O 제어 요청을 처리하여 하드웨어 종속 작업을 수행합니다.
SerCx2가 직렬 컨트롤러 드라이버에서만 처리할 수 있는 직렬 I/O 컨트롤 요청을 받으면 SerCx2는 EvtSerCx2Control 함수를 호출하여 I/O 컨트롤 요청을 드라이버에 전달합니다. 드라이버는 이 요청을 완료할 책임이 있습니다. 특정 I/O 컨트롤 요청에 대한 지원을 구현하지 않는 드라이버는 STATUS_NOT_SUPPORTED 오류 상태 코드로 이 I/O 컨트롤 요청을 완료해야 합니다.
I/O 컨트롤 요청을 완료하기 위해 드라이버는 일반적으로 WdfRequestComplete 메서드를 호출하고 요청 매개 변수 값과 요청이 성공했는지 여부를 나타내는 상태 값을 입력 매개 변수로 제공합니다. 이 상태 값은 요청의 상태 블록에 기록됩니다.
EvtSerCx2Control 함수의 반환 값은 이 함수가 I/O 컨트롤 요청의 상태 블록에 쓰는 상태 값과 항상 일치해야 합니다. SerCx2의 현재 구현은 이 반환 값을 무시합니다.
SerCx2는 EvtSerCx2Control 함수를 호출하여 다음 표에 표시된 IOCTL을 처리합니다. 테이블 오른쪽의 열은 특정 IOCTL에 대한 지원을 구현하기 위해 EvtSerCx2Control 함수가 필요한지 여부를 나타냅니다.
앞의 표에는 SerCx2가 EvtSerCx2Control 함수에 제공하는 모든 직렬 IOCTL이 나열됩니다. 이 목록에 없는 IOCTL의 경우 SerCx2는 IOCTL을 처리하거나 IOCTL에 즉시 실패하고 요청 상태 STATUS_NOT_SUPPORTED 설정합니다. SerCx2는 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 요청을 처리하지만 이러한 요청을 처리하는 동안 EvtSerCx2ApplyConfig 이벤트 콜백 함수를 호출합니다. SerCx2는 IOCTL_SERIAL_PURGE 요청을 처리하지만 이러한 요청을 처리하는 동안 EvtSerCx2PurgeFifos 이벤트 콜백 함수를 호출할 수 있습니다. SerCx는 IOCTL_SERIAL_SET_WAIT_MASK 요청의 예비 처리를 수행하지만, 구현된 경우 EvtSerCx2SetWaitMask 이벤트 콜백 함수를 호출하여 이러한 요청 처리를 완료합니다. 직렬 IOCTL에 대한 SerCx2 지원에 대한 자세한 내용은 직렬 I/O 요청 인터페이스를 참조하세요.
IOCTL_SERIAL_CLR_DTR 및 IOCTL_SERIAL_SET_DTR
직렬 컨트롤러 드라이버의 EvtSerCx2Control 함수가 IOCTL_SERIAL_SET_DTR 요청을 지원하는 경우 이 함수는 IOCTL_SERIAL_CLR_DTR 요청도 지원해야 하며 그 반대의 경우도 마찬가지입니다. 드라이버가 이러한 두 요청을 지원하지 않는 경우 IOCTL_SERIAL_GET_DTRRTS 요청에 대한 드라이버 처리기는 이 요청에 대한 출력 값의 SERIAL_DTR_STATE 플래그 비트를 0으로 설정해야 합니다.
IOCTL_SERIAL_GET_DTRRTS
직렬 컨트롤러 드라이버의 EvtSerCx2Control 함수는 IOCTL_SERIAL_GET_DTRRTS 요청을 지원해야 하지만 이 요청에 대한 드라이버의 처리기는 이 요청에 대한 출력 값의 SERIAL_RTS_STATE 플래그 비트만 지원해야 합니다. 옵션으로 드라이버는 SERIAL_DTR_STATE 플래그 비트를 추가로 지원할 수 있습니다. SERIAL_DTR_STATE 플래그 비트가 지원되지 않는 경우 이 비트를 0으로 설정합니다.
IOCTL_SERIAL_GET_COMMSTATUS
직렬 컨트롤러 드라이버의 EvtSerCx2Control 함수는 IOCTL_SERIAL_GET_COMMSTATUS 요청을 지원해야 하지만 이 요청에 대한 드라이버 처리기는 이 요청에 사용되는 SERIAL_STATUS 구조의 다음 멤버만 지원해야 합니다.
- Errors
- HoldReasons
IOCTL_SERIAL_GET_PROPERTIES
직렬 컨트롤러 드라이버의 EvtSerCx2Control 함수는 IOCTL_SERIAL_GET_PROPERTIES 요청을 지원해야 합니다. 이 요청에 대한 드라이버의 처리기는 이 요청에 사용되는 SERIAL_COMMPROP 구조체의 MaxBaud 멤버를 초당 비트(bps)로 표현된 지원되는 최대 전송 속도로 설정해야 합니다. 예를 들어 직렬 컨트롤러가 최대 전송 속도 115,200bps를 지원하는 경우 드라이버는 MaxBaud = 115200을 설정합니다.
IOCTL_SERIAL_GET_MODEMSTATUS
직렬 컨트롤러 드라이버의 EvtSerCx2Control 함수는 IOCTL_SERIAL_GET_MODEMSTATUS 요청을 지원해야 합니다. 이 요청에 대한 드라이버의 처리기는 직렬 컨트롤러 하드웨어에서 읽은 값을 등록하기 상태 요청의 출력 값을 원시 모뎀으로 설정해야 합니다.
IOCTL_SERIAL_GET_HANDFLOW 및 IOCTL_SERIAL_SET_HANDFLOW
직렬 컨트롤러 드라이버의 EvtSerCx2Control 함수는 IOCTL_SERIAL_GET_HANDFLOW 및 IOCTL_SERIAL_SET_HANDFLOW 요청을 지원해야 하지만 이러한 요청에 대해 정의된 플래그 비트의 하위 집합만 지원해야 합니다. 플래그 비트는 이러한 요청에 사용되는 SERIAL_HANDFLOW 구조체의 ControlHandShake 및 FlowReplace 멤버에 대해 정의됩니다.
드라이버는 ControlHandshake 멤버에서 다음 플래그 비트를 지원해야 합니다.
- SERIAL_CTS_HANDSHAKE
드라이버는 FlowReplace 멤버에서 다음 플래그 비트를 지원해야 합니다.
- SERIAL_RTS_CONTROL
- SERIAL_RTS_HANDSHAKE
ControlHandShake 또는 FlowReplace 멤버에서 특정 플래그 비트를 지원하지 않는 드라이버는 IOCTL_SERIAL_GET_HANDFLOW 요청에 대한 출력 값에서 이 플래그 비트를 0으로 설정해야 합니다. IOCTL_SERIAL_SET_HANDFLOW 요청이 드라이버에서 지원하지 않는 ControlHandshake 또는 FlowReplace 플래그 비트를 지정하는 경우 EvtSerCx2Control 함수는 요청에 실패하고 STATUS_INVALID_PARAMETER 반환해야 합니다.
옵션으로 드라이버는 SERIAL_HANDFLOW 구조체의 XonLimit 및 XoffLimit 멤버를 지원할 수 있습니다. 그러나 이러한 멤버는 필요한 경우 거의 없으며 Microsoft는 해당 구성원을 지원하지 않는 것이 좋습니다. XonLimit 및 XoffLimit 멤버를 지원하지 않는 드라이버는 이러한 멤버를 IOCTL_SERIAL_GET_HANDFLOW 요청에 대한 출력 값에서 0으로 설정해야 합니다. IOCTL_SERIAL_SET_HANDFLOW 요청이 0이 아닌 XonLimit 또는 XoffLimit 멤버를 지정하고 드라이버가 이러한 멤버를 지원하지 않는 경우 EvtSerCx2Control 함수는 요청에 실패하고 STATUS_NOT_IMPLEMENTED 반환해야 합니다.
예제
EvtSerCx2Control 콜백 함수를 정의하려면 먼저 정의 중인 콜백 함수의 형식을 식별하는 함수 선언을 제공해야 합니다. Windows는 드라이버에 대한 콜백 함수 형식 집합을 제공합니다. 콜백 함수 형식을 사용하여 함수를 선언하면 드라이버에 대한 코드 분석, SDV( 정적 드라이버 검증 도구 ) 및 기타 확인 도구에서 오류를 찾을 수 있으며 Windows 운영 체제용 드라이버를 작성하기 위한 요구 사항입니다.
예를 들어 라는 MyControlEvtSerCx2Control 콜백 함수를 정의하려면 다음 코드 예제와 같이 EVT_SERCX2_CONTROL 함수 형식을 사용합니다.
EVT_SERCX2_CONTROL MyControl;
그런 다음, 다음과 같이 콜백 함수를 구현합니다.
_Use_decl_annotations_
NTSTATUS
MyControl(
WDFDEVICE Device,
WDFREQUEST Request,
size_t OutputBufferLength,
size_t InputBufferLength,
ULONG IoControlCode
)
{...}
EVT_SERCX2_CONTROL 함수 형식은 Sercx.h 헤더 파일에 정의되어 있습니다. 코드 분석 도구를 실행할 때 오류를 보다 정확하게 식별하려면 함수 정의에 Use_decl_annotations 주석을 추가해야 합니다. Use_decl_annotations 주석은 헤더 파일의 EVT_SERCX2_CONTROL 함수 형식에 적용되는 주석이 사용되도록 합니다. 함수 선언에 대한 요구 사항에 대한 자세한 내용은 KMDF 드라이버에 함수 역할 형식을 사용하여 함수 선언을 참조하세요. Use_decl_annotations 대한 자세한 내용은 함수 동작 주석 지정을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8.1 시작해서 사용할 수 있습니다. |
| 대상 플랫폼 | 데스크톱 |
| 머리글 | sercx.h |
| IRQL | IRQL <= DISPATCH_LEVEL 호출합니다. |
추가 정보
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기