ClientEventChainedReceive

NTSTATUS
   ClientEventChainedReceive(
       IN PVOID TdiEventContext,
       IN CONNECTION_CONTEXT ConnectionContext,
       IN ULONG ReceiveFlags,
       IN ULONG ReceiveLength,
       IN ULONG StartingOffset,
       IN PMDL Tsdu,
       IN PVOID TsduDescriptor
       );

ClientEventChainedReceive 함수는 클라이언트가 성립된 엔드포인트 대 엔드포인트 연결을 가지고 원격지로부터 들어오는 리시브에 대한 응답으로 하부의 TDI 트랜스포트가 호출하는 이벤트 핸들러이다.

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

매개변수

TdiEventContext

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

ConnectionContext

이 연결 엔드포인트에 대한 클라이언트의 컨텍스트 지역을 가리킨다. 클라이언트의 ClientEventConnect 함수가 원격지로부터의 연결 제공을 승인하거나 ZwCreateFile 함수를 가지고 연결 엔드포인트를 열었을 때 클라이언트는 전에 이 값을 하부의 트랜스포트로 제공했다.

ReceiveFlags

다음 플래그들의 OR 연산으로써 리시브 인디케이션의 특징을 서술한다:

TDI_RECEIVE_NORMAL

Tsdu에 맵된 버퍼는 클라이언트의 원격지로부터 리시브된 정상적인 데이타를 포함한다. 이 플래그와 TDI_RECEIVE_EXPEDITED는 서로 배타적이다.

TDI_RECEIVE_EXPEDITED

Tsdu에 맵된 버퍼는 클라이언트의 원격지로부터 리시브된 신속한 데이타를 포함한다. 클라이언트가 ClientEventChainedReceiveExpedited와 ClientEventReceiveExpedited 핸들러를 등록하지 않았거나 하부의 트랜스포트가 신속한 전송을 지원할 때만 이 플래그는 설정될 수 있다.

TDI_RECEIVE_ENTIRE_MESSAGE

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

ReceiveLength

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

StartingOffset

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

Tsdu

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

TsduDescriptor

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

리턴값

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

STATUS_SUCCESS

주어진 TSDU안에 소비된 모든 데이타를 클라이언트로 인디케이트한다. 그리고 즉시 버퍼(그리고 TsduDescriptor)의 소유권을 리턴한다.

STATUS_PENDING

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

STATUS_DATA_NOT_ACCEPTED

클라이언트가 TSDU에 관심이 없음을 인디케이트한다.

하부의 트랜스포트가 내부적으로 리시브들을 버퍼화한다면 트랜스포트가 ClientEventChainedReceive(Xxx) 핸들러로 인디케이트된 버퍼화된 데이타를 버리지 않을 때 클라이언트는 TDI_RECEIVE 리퀘스트를 가지고 데이타를 얻는다.

주석

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

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

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

클라이언트가 엔드포인트 대 엔드포인트 연결을 위해서 ClientEventChainedReceive와 ClientEventReceive 핸들러를 등록했을 때 ClientEventChainedReceive 함수는 트랜스포트가 신속한 보내기와 받기를 지원한다고 가정하고 ReceiveFlags를 체크하므로써 TSDU가 정상의 것인지 신속한 것인지를 결정할 수 있다. 트랜스포트는 ClientEventChainedReceive 함수로 행하는 같은 인디케이션을 가지고 대응하는 ClientEventReceive 핸들러를 결코 호출할 수 없다.

클라이언트가 지금 처리중인 정상적인 리시브 리퀘스트를 가지거나 리시브가 완료될 때까지 들어오는 특정의 정상적인 리시브에 대해서 인디케이트된 데이타를 전에 거절했다면 트랜스포트는 ClientEvent(Chained)Receive 함수를 호출할 수 없다. 그러나 신속한 데이타를 지원하는 트랜스포트는 신속한 TSDU가 원격지로부터 들어온다면 정상적인 TSDU를 인디케이트하는 중에ClientEvent(Chained)Receive(Expedited) 함수를 호출할 수 있다.

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

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