ClientEventChainedReceiveDatagram

NTSTATUS
   ClientEventChainedReceiveDatagram(
       IN PVOID TdiEventContext,
       IN LONG SourceAddressLength,
       IN PVOID SourceAddress,
       IN LONG OptionsLength,
       IN PVOID Options,
       IN ULONG ReceiveDatagramFlags,
       IN ULONG ReceiveDatagramLength,
       IN ULONG StartingOffset,
       IN PMDL Tsdu,
       IN PVOID TsduDescriptor
       );

ClientEventChainedReceiveDatagram 함수는 클라이언트에 의해서 열린 로컬 트랜스포트 주소로 지시되는 원격지로부터 들어오는 리시브에 대한 응답으로 하부의 TDI 트랜스포트가 호출하는 이벤트 핸들러이다.

NDIS 미니포트에 의해서 트랜스포트로 인디케이트된 전체 TSDU를 전달할 때 그리고 클라이언트가 데이타를 소비할 때까지 버퍼화된 TSDU로의 직접 읽기 전용접근을 얻을 때 트랜스포트는 ClientEventReceiveDatagram 함수보다는 이 핸들러를 호출한다.

매개변수

TdiEventContext

ClientEventChainedReceiveDatagram 함수가 하부의 트랜스포트를 가지고 등록될 때 TdiBuildSetEventHandler 함수를 가지고 설정된 IRP안에 제공된 클라이언트 제공 컨텍스트를 가리킨다.

SourceAddressLength

SourceAddress에 버퍼의 바이트 사이즈를 서술한다.

SourceAddress

보내지는 데이타그램으로부터 원격제의 트랜스포트 주소를 서술하는 버퍼를 가리킨다.

OptionsLength

Options에 버퍼의 바이트 사이즈를 서술한다. 0은옵션의 문자열이 사용될 수 없음을 의미한다. 이 매개변수가 0이면 Options는 NULL이다.

Options

데이타그램을 가지고 보내진 트랜스포트 특정 옵션의 문자열을 서술하는 버퍼를 가리킨다. OptionsLength가 0이면 이 포인터는 NULL이다.

ReceiveDatagramFlags

다음의 플래그를 OR 연산하므로써 리시브 데이타그램 인디케이션의 특징을 서술한다:

TDI_RECEIVE_ENTIRE_MESSAGE

Tsdu에 맵된 버퍼는 전체 TSDU를 포함한다. 그리고 ClientEventChainedReceiveDatagram 함수가 STATUS_PENDING을 리턴한다면 클라이언트는 인디케이트된 데이타를 소비할 때까지 이 버퍼로의 읽기 전용접근을 유지한다. ClientEventChainedReceiveDatagram 함수가 호출될 때 이 플래그는 항상 설정된다.

TDI_RECEIVE_BROADCAST

리시브는 브로드캐스트이다.

TDI_RECEIVE_MULTICAST

리시브는 멀티캐스트이다.

ReceiveLength

Tsdu에 맵된 버퍼안에 클라이언트 데이타의 바이트 수를 서술한다.

StartingOffset

tsdu에 맵된 버퍼안에서 시작하는 클라이언트 데이타의 바이트 옵셋을 서술한다.

Tsdu

리시브된 TSDU를 포함하는 버퍼를 매핑하는 체인화된 MDL의 처음 MDL을 가리킨다.

TsduDescriptor

리시브된 TSDU에 대한 디스크립터를 가리킨다. 이 리시브 인디케이션에 대해서 ClientEventChainedReceiveDatagram 함수가 STATUS_PENDING을 리턴한다면 클라이언트는 순차적으로 이 포인터를 가지고 TdiReturnChainedReceives 함수를 호출해야한다. 이 포인터는 ClientEventChainedReceiveDatagram 함수가 STATUS_PENDING을 리턴한다면 TdiReturnChainedReceives 함수에 대한 매개변수로써만이 클라이언트에 의해서 사용되는 불투명한 변수에 대한 핸들로써 취급되어야한다.

리턴값

ClientEventChainedReceiveDatagram 함수는 다음중 하나를 리턴할 수 있다:

STATUS_SUCCESS

클라이언트가 주어진 TSDU에서 모든 데이타를 소비했고 즉시 하부의 드라이버로 버퍼의 소유권을 리턴하고 있다고 인디케이트한다.

STATUS_PENDING

클라이언트가 주어진 TsduDescriptor를 가지고 TdiReturnChainedReceives 함수를 호출할 때까지 주어진 TSDU를 포함하는 버퍼의 소유권을 유지하고 있다고 인디케이트한다.

STATUS_DATA_NOT_ACCEPTED

클라이언트가 TSDU와 무관하다고 인디케이트한다.

주석

데이타그램이 원격지로부터 도착했을 때 트랜스포트는 데이타그램의 목적지 주소와 일치하는 주소를 구현한 열린 파일 객체를 가지고 각각의 클라이언트를 위해서 등록된 ClientEvent(Chained)ReceiveDatagram 핸들러를 호출한다. 데이타그램은 성립된 연결과 무관하기 때문에 TDI 드라이버는 데이타그램을 따라서 리시브하는 클라이언트로 SourceAddress에 원격지의 전송자의 트랜스포트 주소를 전달한다.

ClientEventChainedReceiveDatagram 함수의 호출은 입력 StartingOffset과 ReceiveLength에 의해서 서술된 버퍼안에 범위에 대해서 인디케이트된 TSDU로의 읽기 전용접근을 클라이언트에게 준다. 인디케이트된 데이타가 클라이언트와 관계된 것이라면 ClientEventChainedReceiveDatagram 함수는 클라이언트 할당 내부 버퍼안으로 인디케이트된 TSDU 데이타의 범위를 복사하고 즉시 STATUS_SUCCESS를 리턴하거나 STATUS_PENDING을 리턴하므로써 버퍼의 통제를 유지한다. STATUS_PENDING을 리턴한다면 클라이언트가 데이타를 소비한 후에 버퍼의 통제를 양도하기 위해서 입력 TsduDescriptor를 가지고 순차적으로 TdiReturnChainedReceives 함수를 호출해야한다.

일반적으로 TdiReturnChainedReceives 함수로의 그러한 호출은 가능한 한 빨리 발생해야한다. 연장된 기간동안 ClientEventChainedReceiveDatagram 함수로 전달된 버퍼를 유지하는 것은 하부의 드라이버에서 I/O의 효율을 강요한다. 왜냐하면 버퍼를 할당한 NDIS 미니포트는 TdiReturnChainedReceives 함수가 호출될 때까지 순차적인 리시브 인디케이션을 위해서 이 자원을 다시 사용할 수 없기 때문이다.

ClientEventChainedReceiveDatagram 함수로의 호출이 항상 전체 TSDU의 사용을 인디케이트하기 때문에 클라이언트는 대응하는 ClientEventReceiveDatagram 핸들러가 가끔 전체 TSDU를 얻어야할 때 그러한 인디케이션에 대해서 TDI_RECEIVE_DATAGRAM 리퀘스트를 결코 설정해서는 안된다. 결국 ClientEventChainedReceiveDatagram 함수로 만들러진 리시브 인디케이션은 클라이언트, 하부의 트랜스포트, 시스템 전체에 대한 호출 과부하를 줄임으로써 네트웍 I/O 효율과 퍼포먼스를 증가시킨다. 트랜스포트는 ClientEventChainedReceiveDatagram 함수로 만들어진 같은 인디케이션을 가지고 대응하는 ClientEventReceiveDatagram 핸들러를 결코 호출할 수 없다.

ClientEventChainedReceiveDatagram 함수가 STATUS_SUCCESS나 STATUS_DATA_NOT_ACCEPTED를 가지고 통제를 리턴할 때 하부의 트랜스포트는 클라이언트가 이 리시브 인디케이션을 가지고 행해진다고 가정한다. 클라이언트가 STATUS_PENDING을 리턴한다면 트랜스포트는 클라이언트가 인디케이트된 TSDU를 소비했을 때 TdiReturnChainedReceives 함수의 호출에 책임이 있기 때문에 이 리시브 인디케이션의 완료를 트랙할 방법이 없다고 가정한다.

클라이언트가 들어오는 데이타그램의 타겟인 로컬 트랜스포트 주소상에서 두드러진 리시브 혹은 리시브 데이타그램 리퀘스트를 가진다면 하부의 TDI 트랜스포트는 ClientEventChainedReceiveDatagram 함수를 호출하지 않는다.

네트웍에서 TDI 드라이버가 리시브하는 브로드캐스트 데이타그램에 대해서 인디케이션을 받기 위해서 클라이언트는 하부 트랜스포트의 브로드캐스트 주소를 열고 ClientEvent(Chained)ReceiveDatagram 핸들러를 등록해야한다.

ClientEventChainedReceiveDatagram 함수는 IRQL DISPATCH_LEVEL에서 연산을 수행할 능력이 있어야한다.