TdiBuildListen

VOID
   TdiBuildListen (
       IN PIRP Irp,
       IN PDEVICE_OBJECT DevObj,
       IN PFILE_OBJECT FileObj,
       IN PVOID CompRoutine,
       IN PVOID Contxt,
       IN ULONG Flags,
       IN PTDI_CONNECTION_INFORMATION RequestConnectionInfo,
       OUT PTDI_CONNECTION_INFORMATION ReturnConnectionInfo
      );

TdiBuildListen 함수는 로컬 클라이언트가 주소와 연결 엔드포인트를 이미 연관시킨 하부 트랜스포트로 TDI_LISTEN 리퀘스트를 위해서 내부의 장치 통제 IRP를 설정한다.

매개변수

Irp

더 상위 레벨의 네트웍 컴포넌트에서 발생하거나 TdiBuildInternalDeviceControlIrp 함수를 가지고 할당된 클라이언트 제공 IRP를 가리킨다.

DevObj

하부의 TDI 트랜스포트 드라이버에 의해서 생성된 장치 객체를 가리킨다.

FileObj

연결 엔드포인트를 구현하는 파일 객체를 가리킨다. 클라이언트는 이 연결과 로컬의 주소사이에서 관계를 설정하기 위해서 트랜스포트로 TdiBuildAssociateAddress 함수를 가지고 설정된 리퀘스트를 전에 성공했다.

CompRoutine

클라이언트 제공 IoCompletion 루틴의 엔트리 포인트를 서술하거나NULL이다. 클라이언트가 이 매개변수를 NULL로 설정하지 않았다면 주어진 IRP가 완료될 때 I/O 매니저는 이 루틴을 호출한다.

Contxt

클라이어늩 결정 컨텍스트를 가리킨다. 이 클라이언트 제공 포인터는 완료된 IRP를 가지고 호출될 때 클라이언트의 IoCompletion 루틴으로 전달된다. CompRoutine이 NULL이면 Contxt는 NULL이다.

Flags

0을 서술하거나 하부의 트랜스포트가 지연된 연결 승인을 지원한다면 TDI_QUERY_ACCEPT를 서술한다.

Flags가 0이면 하부의 트랜스포트는 원격지로부터의 연결이 제공되자마자 원격지로부터 연결을 받아들인다. 클라이언트는 대기 리퀘스트가 완료될 때 엔드포인트 대 엔드포인트 연결이 완전하게 연산되었다고 추측할 수 있다. 사실 연결 엔드포인트 상에서의 리시브는 이 대기 IRP가 클라이언트로 완전하게 완료되어 돌아오기 전에 발생할 수 있다.

트랜스포트가 지연된 연결 승인을 지원하고 클라이언트가 TDI_QUERY_ACCEPT를 설정했다면 그 클라이언트는 대기 리퀘스트가 완료될 때 가능한 한 빨리 제공된 연결을 승인하거나 거절해야한다. 즉 이 IRP의 완료에서 클라이언트는 각각 TdiBuildAccept와 TdiBuildDisconnect 함수를 가지고 트랜스포트로 또다른 리퀘스트를 설정해야한다.

RequestConnectionInfo

로컬 클라이언트가 엔드포인트 대 엔드포인트 연결제공을 기대하는 원격의 클라이언트 주소를 서술하는 TDI_CONNECTION_INFORMATION 구조체를 포함하는 클라이언트 제공 버퍼를 가리킨다.

Flags의 값에 의존하여 클라이언트는 또한 이 구조체의 다음 멤버로 추가적인 정보를 제공한다:

UserData: Flags가 0이면 원격지로부터 제공된 연결의 승인을 가지고 클라이언트가 보내고자하는 데이타의 버퍼를 가리킨다.
하부의 트랜스포트가 지연된 연결 승인을 지원하고 클라이언트가 Flags를 TDI_QUERY_ACCEPT로 설정하다면 클라이언트는 이 멤버를 NULL로 설정한다. 그러한 클라이언트는 제공된 연결을 순차적으로 받아들일 때 데이타 승인을 제공할 수 있다.
UserDataLength: UserData에 버퍼의 바이트 사이즈를 서술한다. UserData가 NULL이면 이 멤버는 0이다.
Options: Flags와 같은 값이 설정된다.
OptionsLength: sizeof(ULONG)이 설정된다.
RemoteAddress: 로컬의 클라이언트가 받아들이게 될 연결제공의 예상으로부터 원격지 주소를 서술하는 버퍼를 가리킨다. 원격지에서 제공된 연결이 클라이언트에서 승인된다면 이 멤버는 NULL일 수 있다.
몇몇 트랜스포트에 대해서 로컬의 클라이언트는 부분적인 주소를 서술할 수 있다. 그러나 TDI 드라이버는 부분적인 주소를 다루는 다양한 능력이 있다.그러한 주소의 신택스는 프로토콜 특정이기 때문에 하부의 TDI 트랜스포트가 부분적인 주소 서술을 지원한다면 부분적인 주소를 서술하기 위해서 합의를 정의한다.
RemoteAddressLength: RemoteAddress에 버퍼의 바이트 사이즈를 서술한다. RemoteAddress가 NULL이면 이 멤버는 0이어야한다.

ReturnConnectionInfo

만들어진 연결제공으로부터 원격지 주소를 리턴하는 트랜스포트의 호출자 제공 버퍼를 가리킨다. 이 버퍼는 TDI_CONNECTION_INFORMATION 구조체로써 포맷된다.

로컬의 클라이언트가 Flags를 TDI_QUERY_ACCEPT로 설정한다면 로컬의 클라이언트는 이 대기 리퀘스트가 완료될 때 연결을 승인하는지 거절하는지를 결정하기 위해서 리턴된 정보를 검사한다.

클라이언트가 아웃풋 정보를 요구하지 않거나 하부의 트랜스포트가 그러한 정보를 리턴하지 않는다면 이 매개변수는 NULL이어야한다.

주석

TdiBuildListen 함수는 주어진 IRP의 트랜스포트 I/O 스택 로케이션안에 MajorFunction로써 IRP_MJ_INTERNAL_DEVICE_CONTROL을 설정하고 MinorFunction로써 TDI_LISTEN을 설정한다.

클라이언트가 TdiBuildListen 함수를 호출하므로써 설정된 IRP를 가지고 하부의 트랜스포트를 호출하기 전에 클라이언트는 로컬 주소를 가지고 작업을 하지 않고 있는 연결 엔드포인트와의 연관관계를 성공한 TdiBuildAssociateAddress 함수를 가지고 설정한 앞선 주소 연관 리퀘스트를 해야한다. 이 관계가 성립된 후에 클라이언트는 제공된 엔드포인트 대 엔드포인트 연결을 받아들일 때까지 많은 대기 리퀘스트를 제시할 수 있다.

하부의 트랜스포트가 그들의 클라이언트를 위해서 QoS(quality-of-service)를 지원하지 않아서 들어오는 대기 리퀘스트에 순서를 매기지 않는다면 FIFO 순서로 클라이언트 각각의 대기 리퀘스트를 처리한다. 그러나 클라이언트는 하부의 트랜스포트가 현재 모든 클라이언트로부터 리퀘스트된 순서에 대해서 권리를 인수할 수 없다.

트랜스포트가 지연된 연결 승인을 지원한다면 클라이언트가 TDI_QUERY_ACCEPT를 설정할 것인지를 체크하기 전에 RequestConnectionInfo에 클라이언트 제공 주소화 정보는 하부의 트랜스포트 드라이버가 적용한 필터로써 동작한다. 만약 들어오는 연결 제공이 클라이언트의 대기 리퀘스트와 일치하지 않는다면 트랜스포트는 클라이언트를 위해서 대기 리퀘스트를 완료할 수 없다. 그렇지 않으면 들어오는 연결제공이 명시된 원격의 주소로부터 만들어졌을 때 로컬 클라이언트의 대기 리퀘스트는 다음중 하나의 방법으로 완료된다:

클라이언트가 지연된 연결 승인을 인디케이트하는 TDI_QUERY_ACCEPT로 Flags를 설정한다면 트랜스포트는 대기 리퀘스트를 완료하고 클라이언트는 트랜스포트로 즉시 TDI_ACCEPT나 TDI_DISCONNECT 리퀘스트를 제시하므로써 제공된 엔드포인트 대 엔드포인트 연결을 받아들이거나 거절해야한다.

클라이언트가 Flags를 0으로 설정한다면 하부의 트랜스포트는 지연된 연결 승인을 지원하지 않기 때문에 트랜스포트는 원격지로 클라이언트가 제공한 승인 데이타를 가지고 승인을 전송한다. 그리고 대기 리퀘스트를 완료한다.

대기 리퀘스트를 하기 전에 클라이언트는 TdiBuildSetEventHandler 함수를 가지고 하나이상의 IRP를 설정하고 연결 엔드포인트와 연관된 로컬 주소를 위해서 ClientEvent(Chained)Receive(Expedited) 핸들러를 등록한다. 클라이언트가 이것을 한다면 ClientEvent(Chained)Receive(Expedited) 루틴은 클라이언트의 대기 리퀘스트가 완료되기 전에 TSDU를 받을 수 있다. 그러한 클라이언트는 대기 리퀘스트를 할 때 즉각적인 연결을 받아들일 준비가 되어있어야한다.

클라이언트의 연결 엔드포인트에 대한 대기가 특정 로컬 주소상에서 지연중일 때 클라이언트의 ClientEventConnect 함수는 특정한 상황외에는 호출될 수ㅜ없다. 즉 대기 연산이 지연이고 트랜스포트가 원격의 주소 승인 기준이 대기 연산을 완료로부터 막는 것이다라고 결정한다면 하부의 트랜스포트는 ClientEventConnect 함수를 호출할 수 있다.

전에 엄급했듯이 몇몇 트랜스포트는 대기중에 원격지의 부분적인 주소의 사양을 지원한다. 또한 트랜스포트는 QOS의 사양을 지원한다. 예를들어 그러한 TDI 트랜스포트의 클라이언트는 트랜스포트 정의 신택스와 의미 체계를 가진 가변적인 길이로 카운트된 문자열을 사용하여 대기를 위한 QOS를 서술한다.