TDI_SET_EVENT_HANDLER

커널 모드 클라이어트가 TDI_SET_EVENT_HANDLER 리퀘스트를 할 때 커널 모드 클라이어트는 대응하는 네트웍 이벤트가 발생할 때마다 하부의 TDI 트랜스포트 드라이버에게 명시된 ClientEventXxx 루틴을 호출하도록한다.

IRP

IrpSp로써 다음의 리스트에 보여지는 IRP안에 자신의 I/O 스택 로케이션에 대한 포인터를 얻기 위해서 주어진 Irp를 가지고 트랜스포트는 IoGetCurrentIrpStackLocation 함수를 호출한다. IRP에 대한 포인터는 Irp로써 다음의 리스트에 보여진다. 이 리퀘스트와 연관된 IRP 멤버는 다음과 같다:

Irp->IoStatus.Status

셋 이벤트 핸들러 리퀘스트에 대한 마지막 상태를 서술한다. 트랜스포트는 다음중 하나로 IRP를 완료하기 전에 이 멤버를 설정한다:

STATUS_SUCCESS
STATUS_INVALID_ADDRESS_COMPONENT
STATUS_INVALID_PARAMETER

데이타가 이 리퀘스트에 대해서는 전송되지 않기 때문에 IoStatus.Information 멤버는 0이다.

IrpSp->MajorFunction

IRP_MJ_INTERNAL_DEVICE_CONTROL을 서술한다. 트랜스포트는 TDI_XXX 리퀘스트만을 다루는 TdiDispatchInternalDeviceControl 루틴을 익스포트한다면 이 멤버를 무시할 수 있다.

IrpSp->MinorFunction

TDI_SET_EVENT_HANDLER를 서술한다.

IrpSp->FileObject

로컬 주소를 구현하는 열린 파일 객체를 가리킨다. 트랜스포트는 이 주소에 대해서 유지하는 상태를 접근하기 위해서 FsContext와 가능하다면 FsContext2 필드를 사용한다.

등록된 ClientEventXxx 핸들러의 타입에 의존하여 이 주소는 클라이어트에 의해서 만들어진 성립된 엔드포인트 대 엔드포인트 연결과 연관될 수 있다.

IrpSp->Parameters

다음과 같이 정의되는 TDI_REQUEST_KERNEL_SET_EVENT 구조체를 가리킨다:

struct _TDI_REQUEST_KERNEL_SET_EVENT {

    LONG EventType;

    PVOID EventHandler;

    PVOID EventContext;

} TDI_REQUEST_KERNEL_SET_EVENT, *PTDI_REQUEST_KERNEL_SET_EVENT;

트랜스포트는 다음과 같이 이 구조체의 멤버를 사용한다:

EventType

등록된 ClientEventXxx 핸들러의 타입을 서술한다(주석을 봐라).

EventHandler

이 타입의 이벤트가 발생했을 때 호출되는 ClientEventXxx 루틴의 엔트리 포인트를 서술한다. 클라이언트가 전에 등록된 이벤트 핸들러를 등록해제한다면 이 멤버는 NULL에 될 수 있다.

EventContext

트랜스포트에 의해서 언인터프리트되는 주어진 ClientEventXxx 루틴으로 전달되는 포인터를 서술한다. EventHandler가 NULL이면 이 멤버는 NULL이다.

주석

클라이언트가 주소를 구현하는 파일 객체를 처음 열었을 때 TDI 트랜스포트는 클라이언트를 위해서 그 주소와 연관된 모든 이벤트 핸들러를 NULL로 초기화한다.

순차적으로 클라이언트가 이 IRP를 설정한 TdiBuildSetEventHandler 함수를 호출할 때 클라이언트는 등록되는 핸들러의 타입을 서술한다. 트랜스포트는 EventType 멤버안에 IrpSp->Parameters에서 이 정보를 찾는다. 입력에서 EventType은 다음의 시스템 정의 값중에 하나가 될 수 있다:

TDI_EVENT_CONNECT

엔드포인트 대 엔드포인트 연결이 원격지에 의해서 제공될 때 호출되는 ClientEventConnect 핸들러를 등록해라.

TDI_EVENT_DISCONNECT

성립된 엔드포인트 대 엔드포인트 연결이 원격지에 의해서 닫힐 때 호출되는 ClientEventDisconnect 핸들러를 등록해라.

TDI_EVENT_RECEIVE

정상적이 리시브가 원격지의 엔드포인트 대 엔드포인트 연결상에서 올 때 호출되는 ClientEventReceive 핸들러를 등록해라. 그리고 트랜스포트는 클라이언트에게 전체 혹은 버퍼화된 TSDU를 복사할 기회를 줄 것이다.

TDI_EVENT_CHAINED_RECEIVE

정상적인 리시브가 원격지의 엔드포인트 대 엔드포인트 연결상에서 올 때 호출되는 ClientEventChainedReceive 핸들러를 등록해라. 그리고 클라이언트가 TsduDescriptor를 가지고 TdiReturnChainedReceives 함수를 호출할 때까지 버퍼화된 전체 TSDU로의 읽기 전용접근을 줄 수 있다.

TDI_EVENT_RECEIVE_EXPEDITED

신속한 리시브가 원격지의 엔드포인트 대 엔드포인트 연결상에서 올 때 호출되는 ClientEventReceiveExpedited 핸들러를 등록해라. 그리고 트랜스포트는 이 클라이언트에게 전체 혹은 부분의 버퍼화된 TSDU를 복사할 기회를 준다.

TDI_EVENT_CHAINED_RECEIVE_EXPEDITED

신속한 리시브가 원격지의 엔드포인트 대 엔드포인트 연결상에서 올 때 호출되는 ClientEventChainedReceiveExpedited 핸들러를 등록해라. 그리고 트랜스포트는 이 클라이언트에게 클라이언트가 TsduDescriptor를 가지고 TdiReturnChainedReceives 함수를 호출할 때까지 버퍼화된 전체 TSDU로의 읽기전용 접근을 줄 수 있다.

TDI_EVENT_RECEIVE_DATAGRAM

데이타그램이 원격지에서 들어올 때 호출되는 ClientEventReceive 핸들러를 등록해라. 그리고 트랜스포트는 이 클라이언트에게 전체 혹은 부분의 버퍼화된 TSDU를 복사할 기회를 준다.

TDI_EVENT_CHAINED_RECEIVE_DATAGRAM

데이타그램이 원격지에서 들어올 때 호출되는 ClientEventChainedReceiveDatagram 핸들러를 등록해라. 트랜스포트는 클라이언트가 TsduDescriptor를 가지고 TdiReturnChainedReceives 함수를 호출할 때까지 버퍼화된 전체 TSDU로의 읽기 전용 접근을 준다.

TDI_EVENT_SEND_POSSIBLE

전에 STATUS_DEVICE_NOT_READY를 가지고 제시된 보내기 리퀘스트를 리턴한 하부의 트랜스포트가 보내지는 다시 제시된 클라이언트 제공 데이타를 복사할 수 있는 이용가능한 내부버퍼공간을 가질 때 호출되는 ClientEventSendPossible 핸들러를 등록해라.

TDI_EVENT_ERROR

로컬 주소에서의 네트웍 I/O가 비신뢰적이거나 불가능할 때 트랜스포트나 하부의 드라이버에서 에러가 발생한다면 호출되는 ClientEventError 핸들러를 등록해라.

TDI_EVENT_ERROR_EX

로컬 주소에서의 네트웍 I/O가 비신뢰적이거나 불가능할 때 트랜스포트나 하부의 드라이버에서 에러가 발생한다면 호출되는 ClientEventError 핸들러를 등록해라.

앞에 서술된 시스템 정의 이벤트에 추가하여 트랜스포트는 드라이버 개발자의 결정에서 이 인터페이스를 트랜스포트 특정 이벤트 통보를 지원하기 위해서 커널 모드 클라이언트로 확장할 수 있다. 그러한 트랜스포트는 가장 중요한 비트를 설정한 TDI_EVENT_XXX 코드를 정의해야한다.

TDI 트랜스포트는 같은 종류의 트랜스포트가 진행중인 동안에 클라이언트로 이벤트를 인디케이트할 수 있다. 다시말하면 ClientEventXxx 핸들러는 재호출된다.

트랜스포트는 클라이언트에게 엔트리 포인트를 제공한 셋 이벤트 핸들러 IRP를 완료하기 전에 원격지로부터 데이타를 받고 있다면 TDI 트랜스포트는 클라이언트 제공 ClientEvent(Chained)ReceiveXxx 핸들러를 즉시 호출할 수 있다.

일반적으로 트랜스포트 스택의 밑에서 ProtocolReceivePacket 함수가 리시브 인디케이션을 가지고 호출될 때 트랜스포트는 ClientEventChainedReceiveXxx 핸들러를 호출한다. ProtocolReceivePacket 함수로의 호출은 패킷 디스크립터가 하부 NDIS 미니포트로 리턴될 때까지 입력 NDIS_PACKET 타입의 디스크립터에 의해서 서술된 인디케이션을 위해서 하부의 NDIS 미니포트가 모든 자원의 소유권을 임시적으로 양도한다는 것을 암시한다.

트랜스포트는 전에 TDI_RECEIVE에서 서술했드시 클라이언트의 ClientEventChainedReceiveXxx 핸들러로 입력되는 TsduDescriptor로써 NDIS_PACKET 타입의 디스크립터를 전달하므로써 그러한 인디케이션을 설정해야한다. 클라이언트의 TdiReturnChainedReceives 함수로의 순차적인 호출은 모든 클라이언트가 리시브된 데이타를 소비했을 때 트랜스포트 하부에 있는 인디케이트하는 미니포트로 이 자원을 리턴하는 NDIS에서 직접 서술되는 TsduDescriptor와 모든 자원을 리턴한다.

반면에 트랜스포트의 ProtocolReceive 함수가 리시브 인디케이션을 가지고 호출될 때 ClientEventReceiveXxx 핸들러를 호출한다. ProtocolReceive 함수로의 호출은 하부의 NDIS 드라이버가 모든 상위 레벨 네트웍 컴포넌트가 인디케이트된 데이타를 복사하도록 기대하고 하위 드라이버가 리시브 인디케이션을 하기 위해서 사용하는 자원의 통제를 다시 얻기 위해서 가능한 한 빨리 리턴한다는 것을 의미한다.

클라이언트는 EventHandler와 EventContext가 NULL이지만 EventType 멤버에가 핸들러의 타입을 서술한 순차적인 TDI_SET_EVENT_HANDLER 리퀘스트를 하므로써 이미 등록된 이벤트 핸들러를 디스에이블할 수 있다.

TdiBuildSetEventHandler 함수는 클라이언트가 IRP안에 채우기 위해서 사용된 매크로이다.