ClientEventReceive

NTSTATUS
   ClientEventReceive (
       IN PVOID TdiEventContext,
       IN CONNECTION_CONTEXT ConnectionContext,
       IN ULONG ReceiveFlags,
       IN ULONG BytesIndicated,
       IN ULONG BytesAvailable,
       OUT ULONG *BytesTaken,
       IN PVOID Tsdu,
       OUT PIRP *IoRequestPacket
      );

ClientEventReceive 함수는 클라이언트가 성립한 엔드포인트 대 엔드포인트 연결을 가지고 원격지로부터 들어오는 리시브에 대한 응답으로 하부의 TDI 트랜스포트가 호출하는 이벤트 핸들러이다. 보통 클라이언트가 ClientEventReceiveExpedited 핸들러를 등록한다면 이것은 정상적인 TSDU이다.

매개변수

TdiEventContext

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

ConnectionContext

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

ReceiveFlags

하나이상의 다음 플래그들을 가지고 OR 결합으로써 리시브 인디케이션의 특징을 서술한다:

TDI_RECEIVE_NORMAL

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

TDI_RECEIVE_EXPEDITED

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

TDI_RECEIVE_ENTIRE_MESSAGE

Tsdu에 버퍼는 전체 TSDU를 포함한다. 클라이언트가 TSDU를 받아들인다면 내부 버퍼안으로 인디케이트된 데이타를 복사한 후에 가능한 한 빨리 통제를 리턴해야한다.

이 플래그가 클리어되다면 ClientEventReceive 함수는 TSDU가 얼마나 많이 제공됐는지를 결정하기 위해서 BytesIndicated과 BytesAvailable 매개변수를 검사해야한다. 리거시 TDI 트랜스포트가 TDI_RECEIVE_PARTIAL 플래그 설정을 계속한다고 하더라도 더 새로운 트랜스포트는 그들의 클라이언트로 부분적인 TSDU를 인디케이트하기 위해서 TDI_RECEIVE_ENTIRE_MESSAGE 플래그를 클리어 상태로 남겨둔다.

TDI_RECEIVE_COPY_LOOKAHEAD

TDI_RECEIVE_ENTIRE_MESSAGE 가 설정되지 않는다면 BytesIndicated는 BytesAvailable보다 작은 값이고 ClientEventReceive 함수는 내부 버퍼안으로 인디케이트된 바이트의 수를 복사해야하고 BytesTaken에 변수를 설정해서 통제를 리턴한다. 클라이언트는 TSDU의 나머지를 얻기 위해서 순차적으로 하나이상의 TDI_RECEIVE 리퀘스트를 제시할 것이다. 그렇지 않으면 ClientEventReceive 함수는 TSDU의 나머지를 복사하기 위해서 다시 호출될 것이다.

TDI_RECEIVE_FRAGMENT

Tsdu에 버퍼는 단편화된 TSDU를 포함한다.

TDI_RECEIVE_PEEK

트랜스포트는 내부적으로 몇몇 리시브 데이타를 버퍼화한다. 하지만 전체 TSDU는 아니다. 클라이언트는 TSDU에 대해서 TDI_RECEIVE 리퀘스트를 제시할 것인지를 결정하기 위해서 Tsdu에 버퍼를 검사할 수 있다.

BytesIndicated

Tsdu에 버퍼안에 메세지 모드나 스트림 모드의 바이트 수를 서술한다. 이 매개변수는 항상 BytesAvailable의 값보다 작거나 같다. 리시브된 메세지 혹은 스트림 세그먼트의 길이가 128 바이트보다 박지 않다면 TDI 트랜스포트는 클라이어트로의 리시브 인디케이션에서 적어도 128 바이트의 데이타를 제공한다. BytesAvailable이 BytesIndicated보다 더 크다면 트랜스포트는 ClientEventReceive 함수를 호출할 때 이용할 수 없는 리시브 데이타를 갖는다.

BytesAvailable

리시브된 TSDU안에 바이트의 전체 수를 서술한다.

BytesTaken

TSDU로부터 복사하는 데이타의 바이트 수를 리턴하는 ClientEventReceive 함수의 호출자 제공 변수를 가리킨다.

Tsdu

리시브된 TSDU 데이타를 포함하는 버퍼를 가리킨다.

IoRequestPacket

TdiBuildReceive 함수를 가지고 설정된 호출자 할당 IRP에 대한 포인터를 리턴하는 ClientEventReceive 함수의 변수를 가리킨다. 이 변수가 NULL로 설정된다면 클라이언트는 TSDU의 나머지에 대해서 리시브 리퀘스트를 하지 않을 것이다.

리턴값

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

STATUS_SUCCESS

클라이언트가 주어진 TSDU안에 모든 데이타를 복사했다고 인디케이트하거나 클라이언트가 BytesTaken을 BytesAvailable로 설정했고 즉시 통제를 리턴했다(사실상 "tossing" 인디케이션)고 인디케이트한다.

STATUS_MORE_PROCESSING_REQUIRED

보통 내부 버퍼안으로 BytesIndicated를 복사한 후에 클라이언트는 TSDU의 나머지를 리퀘스트하는 IRP를 제공했다고 인디케이트한다.

STATUS_DATA_NOT_ACCEPTED

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

주석

ClientEventReceive 함수는 성립된 엔드포인트 대 엔드포인트 연결에서 하부의 TDI 드라이버가 리시브한 TSDU를 승인하거나 거절한다. TSDU는 데이타 스트림의 세그먼트를 구현하는 스트림 모드 혹은 메세지 모드 데이타와 전체 메세지, 그리고 메세지 조각으로 구성되어 있다. 트랜스포트는 ClientEventReceive 함수를 호출하기 전에 TSDU로부터 트랜스포트 층 헤더를 제거한다.

ClientEventReceive 함수는 TDI 드라이버가 네트웍에서 리시브한 정상적인 데이타를 복사한다. 클라이언트가 두드러진 정상의 리시브 리퀘스트를 가지거나 리시브가 끝날 때까지 들어오는 특정 정상적인 리시브에 대해서 미리 인디케이트된 데이타를 거절하는 동안에 트랜스포트는 ClientEvent(Chained)Receive 함수를 호출할 수 없다. 그러나 신속한 데이타를 지원하는 트랜스포트는 신속한 TSDU가 원격지로부터 들어온다면 정상적인 TSDU를 인디케이트하는 중에 ClientEvent(Chained)ReceiveExpedited 함수를 호출할 수 있다.

메세지 모드 트랜스포트는 레코드의 끝 표시를 사용하여 메세지의 한계를 정한다. 그러한 트랜스포트는 리시브된 특정 TSDU안에서 레코드의 끝을 가지고 종료된 각각의 데이타 블럭을 위해서 순차적인 분리된 리시브 인디케이션을 할 수 있다. 그러한 리시브는 보통 원격지의 클라이언트가 TSDU를 전송하기 위해서 순차적인 보내기를 제시한다고 인디케이트한다.

ClientEventReceive 함수가 호출됐을 때 다음중 하나를 할 수 있다:

• STATUS_DATA_NOT_ACCEPTED를 리턴하므로써 데이타를 사용할 수 없다면 인디케이트된 TSDU를 거절한다.
• TDI_RECEIVE_ENTIRE_MESSAGE가 ReceiveFlags에 설정되고 STATUS_SUCCESS를 리턴한다면 내부의 버퍼안으로 모든 데이타를 복사한다.
• TDI_RECEIVE_ENTIRE_MESSAGE가 클리어된다면(혹은 TDI_RECEIVE_PARTIAL이 설정된다면) 수행되는 연산에 의존하여 인디케이트된 데이타의 일부 혹은 전부를 복사하고 다음중 하나를 리턴한다:

  클라이언트가 남아있는 TSDU 데이타를 얻기 위해서 IoRequestPacket에 TDI_RECEIVE 리퀘스트를 제공한다면 STATUS_MORE_PROCESSING_REQUIRED를 리턴한다.

  트랜스포트가 남아있는 TSDU 데이타를 가지고 다시 ClientEventReceive 함수를 호출하기를 기대한다면 STATUS_SUCCESS를 리턴한다.

리시브된 데이타의 복사가 끝났을 때 ClientEventReceive 함수는 통제를 리턴하기 전에 받아들인 데이타의 바이트 수를 BytesTaken에 변수에 설정한다.

ClientEventReceive 함수가 하부의 드라이버를 위해서 IoRequestPacket에 TDI_RECEIVE 리퀘스트를 제공한다면 트랜스포트는 사용가능한 새로운 데이타를 가지고 클라이언트로 아직 전달되지 않은 데이타를 얻는다. IRP안에 클라이언트 제공 버퍼가 꽉차거나 트랜스포트가 레코드의 끝 표시를 만날 때까지 데이타 얻기는 계속된다. 이 클라이언트를 위해서 ClientEvent(Chained)Receive 핸들러로의 순차적인 호출을 제시하기 전에 트랜스포트는 주어진 IRP를 항상 완료한다. 결국 클라이언트는 트랜스포트가 클라이어트로 순차적인 정상적인 리시브를 인디케이트하기 전에 리시브된 각각의 정상적인 TSDU를 완료로 처리한다. 이것은 각각의 클라이언트로 하여금 정확하게 데이타의 리시브를 동기화하도록 허락한다.

클라이언트가 TSDU로부터 몇몇 데이타를 받아들인 후에 ClientEventReceive 함수가 STATUS_DATA_NOT_ACCEPTED를 리턴한다면 TDI 드라이버는 다음과 같이 클라이언트가 받아들인 인디케이트된 데이타의 양과 추가적인 데이타의 사용에 따라서 계속 진행한다:

• 드라이버가 모든 인디케이트된 데이타를 전달하고 인디케이트의 시점에서 사용가능한 데이타가 없다면 드라이버는 네트웍으로부터 TSDU를 위한 데이타를 리시브했을 때 다시 ClientEventReceive 함수를 호출한다.
• 드라이버가 클라이언트에게 인디케이트된 모든 데이타를 전달하지 않았다면 혹은 ClientEventReceive 함수로의 앞선 호출에서 사용할 수 없는 추가적인 데이타를 갖는다면 트랜스포트는 클라이언트가 명확한 TDI_RECEIVE 리퀘스트를 제시할 때까지 클라이언트는 데이타를 위한 내부의 버퍼 공간을 갖지 않고 그 이상의 인디케이션을 하지 않는다고 가정한다.

  이런 상황에서 트랜스포트는 로컬의 클라이언트가 리시브 리퀘스트를 할 때까지 원격지의 트랜스포트로부터 데이타의 제해석을 막기 위해서 프로토콜 흐름 컨트롤 동작을 선택적으로 시작할 수 있다.

TDI 트랜스포트는 TDI_EVENT_RECEIVE 인디케이션을 가지고 네트웍으로부터 데이타 수신을 연관시킬 필요가 없다. 드라이버가 내부의 버퍼화를 제공한다면 어느정도의 데이타를 받거나 내부의 버퍼가 거의 찼을 때 어떤 시간에 데이타를 인식할 수 있고 필요할 때 리시브 인디케이션을 한다. 버퍼화한 드라이버는 클라이언트가 클라이언트의 리시브 리퀘스트가 만족한다고 트랜스포트에게 알릴 때까지 클라이언트가 인디케이션에서 받아들이지 않는 어떤 데이타를 유지해야한다. 내부의 데이타 버퍼화를 지원하지 않는 트랜스포트는 클라이언트가 ClientEventReceive 함수로부터 데이타를 받아들인 후나 드라이버가 클라이언트 제공 IRP 안으로 리시브된 데이타를 전송한 후에 리시브된 데이타를 인식할 수 있다.

트랜스포트가 리시브된 데이타를 내부적으로 버퍼화한다면 ReceiveBufferSize에 대해서 리턴된 값을 검사하고 QType TDI_QUERY_CONNECTION_INFO에 대해서 TdiBuildQueryInformation 함수를 가지고 설정된 리퀘스트를 제시하므로써 클라이언트가 찾을 수 있는 트랜스포트 특정 제한으로 리시브된 TSDU는 길이를 맞출 수 있다. 그러나 ClientEventReceive 함수는 전체 TSDU나 TSDU의 사용가능한 부분을 이 핸들러가 호출될 때마다 리시브할 필요가 없다. 최소값이 적어도 128 바이트인 한 각각의 TDI 트랜스포트는 클라이언트로의 각각의 리시브에서 인디케이트하는 데이타의 최대 최소 양에서 자신의 제한을 설정할 수 있다. 클라이언트는 QType TDI_QUERY_PROVIDER_INFO에 대해서 또다른 정보 쿼리 리퀘스트를 제시하므로써 그리고 MinimumLookaheadData와 MaximumLookaheadData에 대해서 리턴된 값을 검사하므로써 이런 제한을 찾을 수 있다.

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