TdiBuildSetEventHandler
VOID
TdiBuildSetEventHandler (
IN PIRP Irp,
IN PDEVICE_OBJECT DevObj,
IN PFILE_OBJECT FileObj,
IN PVOID CompRoutine,
IN PVOID Contxt,
IN LONG InEventType,
IN PVOID InEventHandler,
IN PVOID InEventContext
);
TdiBuildSetEventHandler 함수는 로컬의 클라이언트가 주소를 구현하는 파일 객체를 이미 연 하부의 트랜스포트로 TDI_SET_EVENT_HANDLER 리퀘스트를 위해서 내부의 장치 통제 IRP를 설정한다.
매개변수
- Irp
- 더 상위 레벨 네트웍 컴포넌트에서 발생하거나 TdiBuildInternalDeviceControlIrp 함수를 가지고 할당된 클라이언트 제공 IRP를 가리킨다.
- DevObj
- 하부의 TDI 트랜스포트 드라이버에 의해서 생성된 장치 객체를 가리킨다.
- FileObj
- 주소를 구현하는 파일 객체를 가리킨다.
- CompRoutine
- 클라이언트 제공 IoCompletion 루틴의 엔트리 포인트를 서술하거나 NULL이다. 클라이언트가 이 매개변수를 NULL로 설정하지 않는다면 주어진 IRP가 완료될 때 I/O 매니저는 이 루틴을 호출한다.
- Contxt
- 클라이언트 결정 컨텍스트를 가리킨다. 이 클라이언트 제공 포인터는 완료된 IRP를 가지고 호출될 때 IoCompletion 루틴으로 전달된다. CompRoutine이 NULL이면 Contxt는 NULL이다.
- InEventType
- 다음중 하나로써 등록되는 이벤트 핸들러의 타입을 서술한다:
- TDI_EVENT_CONNECT
- 원격지에 의해서 엔드포인트 대 엔드포인트 연결이 제공됐을 때 호출되는 주어진 ClientEventConnect 핸들러를 등록한다.
- TDI_EVENT_DISCONNECT
- 원격지에 의해서 성립된 엔드포인트 대 엔드포인트 연결이 닫힐 때 호출되는 주어진 ClientEventDisconnect 핸들러를 등록한다.
- TDI_EVENT_RECEIVE
- 정상적인 리시브가 원격지로부터 엔드포인트 대 엔드포인트 연결로 들어올 때 호출되는 주어진 ClientEventReceive 핸들러를 등록하고 클라이언트는 버퍼화된 TSDU의 일부 혹은 전부를 복사할 기회를 얻는다.
- TDI_EVENT_CHAINED_RECEIVE
- 정상적인 리시브가 원격지로부터 엔드포인트 대 엔드포인트 연결로 들어올 때 호출되는 주어진 ClientEventChainedReceive 핸들러를 등록하고 클라이언트는 TdiReturnChainedReceives 함수를 호출할 때까지 버퍼화된 전체 TSDU에 대해서 읽기 전용 접근만을 얻는다.
- TDI_EVENT_RECEIVE_EXPEDITED
- 신속한 리시브가 원격지로부터 엔드포인트 대 엔드포인트 연결로 들어올 때 호출되는 주어진 ClientEventReceiveExpedited 핸들러를 등록하고 클라이언트는 버퍼화된 TSDU의 일부 혹은 전부를 복사할 기회를 얻는다.
- TDI_EVENT_CHAINED_RECEIVE_EXPEDITED
- 신속한 리시브가 원격지로부터 엔드포인트 대 엔드포인트 연결로 들어올 때 호출되는 주어진 ClientEventChainedReceiveExpedited 핸들러를 등록하고 클라이언트는 TdiReturnChainedReceives 함수를 호출할 때까지 버퍼화된 전체 TSDU로의 읽기전용 접근만을 얻는다.
- TDI_EVENT_RECEIVE_DATAGRAM
- 원격지로부터 데이타그램이 들어올 떄 호출되는 주어진 ClientEventReceiveDatagram 핸들러를 등록하고 클라이언트는 버퍼화된 TSDU의 일부 혹은 전부를 복사할 기회를 얻는다.
- TDI_EVENT_CHAINED_RECEIVE_DATAGRAM
- 원격지로부터 데이타그램이 들어올 떄 호출되는 주어진 ClientEventChainedReceiveDatagram 핸들러를 등록하고 클라이언트는 TdiReturnChainedReceives 함수를 호출할 때까지 버퍼화된 전체 TSDU로의 읽기전용 접근을 얻는다.
- TDI_EVENT_SEND_POSSIBLE
- 전에 STATUS_DEVICE_NOT_READY를 가지고 제시된 보내기 리퀘스트를 리턴한 하부의 트랜스포트가 다시 제시된 클라이언트 제공 데이타를 복사할 수 있는 내부의 버퍼공간을 다시 가질 때 호출되는 주어진 ClientEventSendPossible 핸들러를 등록한다.
- TDI_EVENT_ERROR
- 이 로컬 주소에서 네트웍 I/O가 비신용적인 하부의 드라이버에서 에러가 발생한다면 호출되는 주어진 ClientEventError 핸들러를 등록한다.
- TDI_EVENT_ERROR_EX
- 이 로컬 주소에서 네트웍 I/O가 비신용적인 하부의 드라이버에서 에러가 발생한다면 호출되는 주어진 ClientEventErrorEx 핸들러를 등록한다. 하부의 드라이버가 이 인디케이션을 지원한다면 ClientEventError 보다는 ClientEventErrorEx 함수로 그러한 에러에 대해서 버퍼화된 추가정보를 제공한다.
앞선 시스템 정의 이벤트에 추가하여 트랜스포트는 클라이언트로 이벤트의 트랜스포트 특정 통보를 지원하기 위해서 이 인터페이스를 연장한다. 그러한 트랜스포트는 가장 중요한 비트가 설정된 TDI_EVENT_XXX 코드를 정의해야한다.
- InEventHandler
- 등록되는 ClientEventXxx 핸들러의 엔트리 포인트를 서술한다. 클라이언트는 전에 등록된 이벤트 핸들러로의 통보를 디스에이블하기 위해서 이 매개변수를 NULL로 설정할 수 있다.
- InEventContext
- 트랜스포트에 의해서 호출됐을 때 ClientEventXxx 루틴으로 전달되는 호출자 결정 컨텍스트를 가리킨다. InEventHandler가 NULL이면 이 매개변수는 NULL이어야한다.
주석
클라이언트가 주소를 구현하는 파일 객체를 처음 열었을 때 하부의 트랜스포트는 모든 이벤트 핸들러를 NULL로 초기화한다.
TdiBuildSetEventHandler 함수는 주어진 IRP의 트랜스포트 I/O 스택 로케이션안에 MajorFunction로써 IRP_MJ_INTERNAL_DEVICE_CONTROL을 설정하고 MinorFunction로써 TDI_SET_EVENT_HANDLER를 설정한다.
TdiBuildSetEventHandler 함수에 의해서 설정되고 IoCallDriver 함수를 가지고 하부의 트랜스포트로 제시된 각각의 IRP를 가지고 클라이언트는 특정 트래스포트 주소상에서 발생할 수 있는 주어진 이벤트 타입을 위해서 하나의 이벤트 핸들러를 등록한다. 트랜스포트에 의해서 ClientEventXxx 루틴으로 전달되는 더 하위 레벨의 NDIS 드라이버로부터의 인디케이션은 보통 IRQL DISPATCH_LEVEL에서 발생한다. 이 클라이언트 제공 이벤트 핸들러를 위해서 호출자는 비페이지화된 풀로부터 InEventContext에 공간을 할당해야한다.
클라이언트는 ZwCreateFile 함수로의 성공적인 호출을 가지고 주소를 구현하는 파일 객체를 열자마자 ClientEvent(Chained)ReceiveDatagram과 ClientEventError(Ex) 핸들러를 등록할 수 있다. 주소와 연결 엔드포인트를 구현하는 파일 객체를 열고 하부의 트랜스포트로 주소를 연관시키는 리퀘스트를 성공하자마자 클라이언트는 ClientEventConnect 핸들러를 등록할 수 있다.
몇몇 InEventType 값에 대해서 주어진 파일 객체에 의해서 구현된 주소는 클라이언트가 ClientEventXxx 핸들러를 등록하기 전에 클라이언트에 의해서 연결 엔드포인트와 연관되어야한다. 특히 클라이언트는 연결 특정 기본에서 만들어진 네트웍 전송을 위해서 ClientEvent(Chained)Receive(Expedited), ClientEventDisconnect, 그리고 ClientEventSendPossible 핸들러를 등록하기 전에 로컬 주소를 가지고 연결 엔드포인트를 연관시켜야한다. 트랜스포트가 지연된 연결 승인을 지원하지 않는다면 클라이언트는 이벤트 핸들러를 등록하는 이벤트 핸들러 설정 리퀘스트를 할 때 주소를 구현하는 열린 파일 객체와 이미 연관된 엔드포인트 대 엔드포인트 연결이 활성화됐다고 가정한다.
내부적으로 보내기 데이타를 버퍼화한 트랜스포트의 클라이언트만이 ClientEventSendPossible 핸들러를 등록할 수 있다.
일반적으로 TDI 트랜스포트는 같은 종류의 이벤트가 진행중인 동안에 클라이언트로 이벤트를 인디케이트할 수 있다. 다시말하면 ClientEventXxx 핸들러는 다시 실행한다. 또한 이 루틴중에 하나를 등록하는 클라이언트의 이벤트 핸들러 설정 IRP가 완료되기 전에 트랜스포트는 ClientEvent(Chained)Receive(Expedited) 혹은ClientEvent(Chained)Receive(Datagram) 함수를 호출할 수 있다. 결국 클라이언트는 ClientEvent(Chained)Receive(Xxx) 핸들러의 등록을 리퀘스트하자마자 리시브의 처리를 준비해야한다.
클라이언트가 하부의 트랜스포트로 TdiBuildReceive 혹은 TdiBuildReceiveDatagram 함수를 가지고 설정된 리시브 혹은 리시브 데이타그램 IRP를 제시할 때마다 등록된 ClientEvent(Chained)Receive(Xxx) 핸들러로의 호출은 디스에이블된다. 하부의 트랜스포트가 그러한 IRP를 가지고 호출된 후에 하부의 트랜스포트는 들어오는 리시브 인디케이션을 가지고 등록된 ClientEvent(Chained)Receive(Xxx) 루틴의 호출을 다시 시작하기 전에 그 IRP를 완료하기 위해서 필요한 모든 연산을 수행한다.
같은 InEventType을 가지고 또다른 이벤트 핸들러 설정 리퀘스트를 하므로써 클라이언트는 등록된 이벤트 핸들러를 디스에이블할 수 있다. 하지만 TdiBuildSetEventHandler 핸들러의 InEventHandler와 InEventContext 매개변수로써 NULL을 서술한다.
PnP와 전원 상태 변화통보를 위해 ClientPnPXxx 핸들러를 등록하려면 클라이언트는 IoCallDriver 함수에 의해서 뒤따르는 TdiBuildSetEventHandler 함수보다는 TdiRegisterPnPHandlers 함수를 호출한다.
|