ClientEventReceiveDatagram

NTSTATUS
   ClientEventReceiveDatagram (
       IN PVOID TdiEventContext,
       IN LONG SourceAddressLength,
       IN PVOID SourceAddress,
       IN LONG OptionsLength,
       IN PVOID Options,
       IN ULONG ReceiveDatagramFlags,
       IN ULONG BytesIndicated,
       IN ULONG BytesAvailable,
       OUT ULONG *BytesTaken,
       IN PVOID Tsdu,
       OUT PIRP *IoRequestPacket
      );

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

매개변수

TdiEventContext

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

SourceAddressLength

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

SourceAddress

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

OptionsLength

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

Options

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

ReceiveDatagramFlags

다음 플래그들의 OR 결합으로써 리시브 데이타그램 인디케이션의 특징을 서술한다:

TDI_RECEIVE_ENTIRE_MESSAGE

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

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

TDI_RECEIVE_COPY_LOOKAHEAD

TDI_RECEIVE_ENTIRE_MESSAGE가 설정되지 않았다면 BytesAvailable은 BytesIndicated 보다는 작안 값이고 ClientEventReceiveDatagram 함수는 내부의 버퍼안으로 사용가능한 버퍼의 수를 복사하고 BytesTaken에 변수를 설정해서 통제를 리턴해야한다. 클라이언트는 TSDU의 나머지를 얻기 위해서 하나이상의 TDI_RECEIVE_DATAGRAM 리퀘스트를 순차적으로 제시해야한다.

TDI_RECEIVE_BROADCAST

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

TDI_RECEIVE_MULTICAST

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

TDI_RECEIVE_PEEK

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

BytesIndicated

Tsdu에 버퍼안에 데이타의 바이트 수를 서술한다. 이 매개변수는 BytesAvailable의 값과 항상 작거나 같다. TDI 트랜스포트는 리시브된 데이타그램의 길이가 128 바이트보다 작지 않다면 트랜스포트는 클라이언트로의 리시브 인디케이션에서 적어도 128 바이트의 데이타를 제공한다. BytesAvailable이 BytesIndicated 보다 크다면 트랜스포트는 ClientEventReceiveDatagram 함수를 호출할 때 존재하지 않는 데이타를 리시브했다.

BytesAvailable

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

BytesTaken

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

Tsdu

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

IoRequestPacket

TdiBuildReceiveDatagram 함수를 가지고 설정된 IRP에 대한 포인터를 리턴하는 ClientEventReceiveDatagram 함수의 호출자 제공 변수를 가리킨다. 이 매개변수가 NULL이면 클라이언트는 TSDU의 나머지를 위해서 리시브 리퀘스트를 하지 않을 것이다.

리턴값

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

STATUS_SUCCESS

클라이언트가 주어진 TSDU안에 모든 데이타를 복사했고 BytesTaken에 변수를 BytesIndicated에 값으로 설정했음을 인디케이트한다.

STATUS_MORE_PROCESSING_REQUIRED

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

STATUS_DATA_NOT_ACCEPTED

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

주석

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

ClientEventReceiveDatagram 함수는 클라이언트가 ZwCreateFile 함수를 가지고 앞선 호출에서 열었던 특정 트랜스포트 주소상에서 TDI 드라이버가 리시브한 TSDU를 받아들이거나 거절한다. 데이타그램 TSDU는 불연속적이다. 정상적이거나 신속한 TSDU와는 달리 그것은 순차적인 레코드로써 전송될 수 없다. 다시말하면 전체 데이타그램은 드라이버가 ClientEventReceiveDatagram 함수로 한번의 호출에서 전체 TSDU를 전달하지 않았음에도 불구하고 TDI 트랜스포트에서 이용할 수 있다.

트랜스포트가 ClientEventReceiveDatagram 함수를 호출하기 전에 트랜스포트는 TSDU로부터 틀내스포트 층 헤더를 제거했다.

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

ClientEventReceiveDatagram 함수가 호출될 때 다음중 하나를 할 수 있다:

• STATUS_DATA_NOT_ACCEPTED를 리턴하므로써 데이타에 대한 사용을 할 수 없다면 인디케이트된 TSDU를 거절한다.
• TDI_RECEIVE_ENTIRE_MESSAGE가 ReceiveFlags에 설정된다면 내부의 버퍼안으로 모든 데이타를 복사하고 STATUS_SUCCESS를 리턴한다.

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

• TDI_RECEIVE_ENTIRE_MESSAGE가 클리어된다면(혹은 TDI_RECEIVE_PARTIAL이 설정된다면) 모든 인디케이트된 데이타를 복사하고 TDI_RECEIVE_DATAGRAM 리퀘스트에 대한 IRP를 설정해서 STATUS_MORE_PROCESSING_REQUIRED를 리턴한다.

  ClientEventReceiveDatagram 함수가 리시브 데이타그램 리퀘스트를 제시한다면 트랜스포트는 TDI 트랜스포트가 이용할 수 있는 새로운 어떤 데이타에 따라서 ClientEventReceiveDatagram 함수가 리시브하지 않은 어떤 데이타를 얻는다. 클라이언트가 리시브 데이타그램 리퀘스트를 하지 않았다면 이 데이타는 손실된다.

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

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