EVT_SERCX2_SET_WAIT_MASK 콜백 함수(sercx.h)

아티클
08/07/2023

EvtSerCx2SetWaitMask 이벤트 콜백 함수는 SerCx2(직렬 프레임워크 확장) 버전 2에서 호출되어 대기 마스크로 지정된 하드웨어 이벤트 집합을 모니터링하도록 직렬 컨트롤러를 구성합니다.

구문

EVT_SERCX2_SET_WAIT_MASK EvtSercx2SetWaitMask;

void EvtSercx2SetWaitMask(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] ULONG WaitMask
)
{...}

매개 변수

[in] Device

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

[in] Request

IOCTL_SERIAL_SET_WAIT_MASK 요청을 나타내는 프레임워크 요청 개체에 대한 WDFREQUEST 핸들입니다.

[in] WaitMask

새 대기 마스크입니다. 자세한 내용은 설명 부분을 참조하세요.

반환 값

없음

설명

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

SerCx가 클라이언트로부터 IOCTL_SERIAL_SET_WAIT_MASK 요청을 받으면 SerCx2의 요청 처리기는 EvtSerCx2SetWaitMask 함수를 호출하여 구현된 경우 드라이버에 대기 마스크가 변경되었음을 알립니다. 대기 마스크가 0이 아닌 경우 드라이버는 즉시 새 대기 마스크의 이벤트를 모니터링하기 시작하고 이전 EvtSerCx2SetWaitMask 호출에서 제공되었을 수 있는 이전 대기 마스크를 삭제합니다. 새 대기 마스크가 0이면 드라이버는 단순히 이전 대기 마스크를 삭제하고 대기 마스크 이벤트 모니터링을 중단합니다. 대기 마스크로 지정할 수 있는 이벤트 유형에 대한 자세한 내용은 SERIAL_EV_XXX.

드라이버가 이 함수를 구현하지 않으면 SerCx2는 오류 상태 코드 STATUS_NOT_SUPPORTED 모든 IOCTL_SERIAL_SET_WAIT_MASK 요청에 실패합니다.

대기 마스크에서 이벤트를 모니터링하기 위해 EvtSerCx2SetWaitMask 함수는 일반적으로 이러한 이벤트에 대해 인터럽트를 사용하도록 설정합니다. 나중에 대기 마스크의 이벤트가 감지되면 직렬 컨트롤러 드라이버가 SerCx2CompleteWait 메서드를 호출하여 SerCx2에 이벤트를 알립니다.

EvtSerCx2SetWaitMask 함수는 Request 매개 변수가 가리키는 IOCTL_SERIAL_SET_WAIT_MASK 요청을 완료해야 합니다. 직렬 컨트롤러 드라이버가 필요한 인터럽트 사용 후 WdfRequestComplete 메서드를 호출하고 요청 매개 변수 값 및 요청 성공 여부를 나타내는 상태 값을 입력 매개 변수로 제공합니다.

직렬 컨트롤러 드라이버가 WdfRequestComplete 를 호출하여 요청을 완료하기 전에 드라이버는 이전 대기 마스크의 이벤트로 인해 보류 중일 수 있는 SerCx2CompleteWait 에 대한 호출을 완료해야 합니다.

처음에는 클라이언트가 직렬 포트에 대한 논리적 연결을 열고 첫 번째 EvtSerCx2SetWaitMask 호출 전에 대기 마스크가 사실상 0이고 직렬 컨트롤러 드라이버가 SERIAL_EV_XXX 이벤트를 모니터링하지 않습니다.

SerCx2는 다음 SERIAL_EV_XXX 이벤트 플래그를 포함하는 대기 마스크가 있는 IOCTL_SERIAL_SET_WAIT_MASK 요청에 실패합니다.

SERIAL_EV_PERR
SERIAL_EV_RING
SERIAL_EV_RXFLAG

따라서 EvtSerCx2SetWaitMask 함수에 제공된 대기 마스크에는 이전 목록의 이벤트 플래그가 포함되지 않습니다.

구현된 경우 EvtSerCx2SetWaitMask 함수는 다음 이벤트 플래그를 지원해야 합니다.

SERIAL_EV_CTS
SERIAL_EV_BREAK
SERIAL_EV_ERR

또한 직렬 컨트롤러에 DSR( 데이터 세트 준비 ) 신호선이 있는 경우 EvtSerCx2SetWaitMask 함수는 SERIAL_EV_DSR 지원해야 합니다. 옵션으로 드라이버는 SERIAL_EV_XXX 설명된 다른 이벤트 플래그를 지원할 수 있습니다. 대기 마스크가 드라이버가 지원하지 않는 이벤트를 지정하는 경우 EvtSerCx2SetWaitMask 함수는 요청에 실패하고 요청의 상태 값을 STATUS_INVALID_PARAMETER 설정해야 합니다.

예제

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

예를 들어 라는 MySetWaitmaskEvtSerCx2SetWaitMask 콜백 함수를 정의하려면 이 코드 예제와 같이 EVT_SERCX2_SET_WAIT_MASK 함수 형식을 사용합니다.

EVT_SERCX2_SET_WAIT_MASK  MySetWaitmask;

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

_Use_decl_annotations_
VOID
  MySetWaitmask(
    WDFDEVICE  Device,
    WDFREQUEST Request,
    ULONG WaitMask
    )
  {...}

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

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8.1 사용하여 사용할 수 있습니다.
대상 플랫폼	데스크톱
머리글	sercx.h
IRQL	IRQL <= DISPATCH_LEVEL 호출합니다.