TdiDispatchCreate

NTSTATUS
   TdiDispatchCreate (
       IN PDEVICE_OBJECT DeviceObject,
       IN PIRP Irp
      );

TdiDispatchCreate 함수는 열린 파일 객체에 대한 순차적인 I/O 연산을 트랙하기 위해서 드라이버 할당 상태를 설정하므로써 주소, 연결 엔드포인트, 통제 채널을 구현하는 파일 객체를 연다.

매개변수

DeviceObject

TDI 트랜스포트에 의해서 생성된 장치 객체를 가리킨다.

Irp

트랜스포트 드라이버의 I/O 스택 로케이션안에 MajorFunctionCode 로써 설정된 IRP_MJ_CREATE을 가진 IRP를 가리킨다.

IrpSp로써 다음의 리스트에 보여지는 것처럼 IRP안에 자신의 스택 로케이션에 대한 포인터를 얻기 위해서 주어진 IRP를 가지고 IoGetCurrentIrpStackLocation 함수를 호출한다. 트랜스포트는 진행중인 생성 리퀘스트안에 IRP의 다음 멤버에 설정된 정보를 사용할 수 있다:

IoStatus.Status

생성/열기 연산의 마지막 상태를 서술한다. 트랜스포트는 TdiDispatchCreate 함수에 의해서 리턴된 똑같은 값으로 이 멤버를 설정한다.(IoStatus.Information 은 0 으로 설정된다.)

IrpSp->MajorFunction

IRP_MJ_CREATE을 서술한다. 트랜스포트가 생성 리퀘스트만을 다루는 TdiDispatchCreate 루틴을 익스포트한다면 이 멤버를 무시할 수 있다.

IrpSp->FileObject

주소, 연결 엔드포인트, 통제 채널을 구현하기 위해서 I/O 매니저가 생성한 파일 객체를 가리킨다. 주소, 연결 엔드포인트, 통제 채널에서 순차적인 I/O 리퀘스트를 트랙하기 위해서 TdiDispatchCreate 함수에서 설정된 드라이버 할당 컨텍스트 지역으로의 접근을 위해서 트랜스포트 드라이버는 이 파일 객체안에 FsContext와 가능하다면 FsContext2를 설정한다.

Irp->AssociatedIrp.SystemBuffer

열려있는 주소와 연결 엔드포인트를 파일 객체가 구현한다면 FILE_FULL_EA_INFORMATION 구조화된 버퍼를 가리킨다.

주소를 위해서 EaName 멤버는 시스템 정의 상수로 TdiTransportAddress를 설정한다. 그리고 EaName 배열의 다음에 EA 값은 열린 주소를 서술하기 위해서 클라이언트에 의해서 설정된 TRANSPORT_ADDRESS 타입이다. 몇몇 트랜스포트를 위해서 이 값은 트랜스포트에 의해서 해석되는 심볼릭 netBIOS 혹은 DNS 이름이 될 수 있다.

연결 엔드포인트를 위해서 EaName 멤버는 TdiConnectionContext를 시스템 정의 상수로 설정하고 EaName 배열 다음의 EA 값은 트랜스포트 드라이버에게는 불투명한 클라이언트 제공핸들이다. 트랜스포트는 이 핸들을 저장해야하고 순차적으로 이 연결을 위한 클라이언트의 등록된 이벤트 핸들러로 그것을 전달해야한다.

주어진 파일 객체가 통제 채널을 구현한다면 이 멤버는 NULL이다.

IrpSp->Parameters.Create.EaLength

Irp->AssociatedIrp.SystemBuffer에 버퍼의 바이트 사이즈를 서술한다. 주어진 파일 객체가 통제 채널을 구현한다면 0 을 서술한다.

IrpSp->Parameters.Create.ShareAccess

주어진 파일 객체가 주소를 구현한다면 클라이언트가 파일 객체에 대해서 독점적인 열기를 리퀘스트를 했는지를 서술한다. 초기의 클라이언트가 주소를 열기 위해서 ZwCreateFile 함수의 ShareAccess 매개변수를 FILE_SHARE_READ 혹은 FILE_SHARE_WRITE로 설정한다면 똑같은 주소가 다른 클라이언트에 의해서 순차적으로 열릴 수 있다.

IrpSp->Parameters.Create.SecurityContext->AccessState

주어진 파일 객체가 공유가능한 주소를 구현한다면 그 주소로의 리퀘스트된 접근을 정의한다. 특정 주소를 구현하는 파일 객체를 열기 위해서 초기의 클라이언트는 그 주소를 위해서 접근 통제 리스트를 설정한다. 순차적인 주소 열기 리퀘스트가 발생했을 때 TDI 트랜스포트 드라이버는 대응하는 파일 객체로 할당된 근본 ACL에 대항하여 이 멤버를 체크하기 위해서 안전 레퍼런스 모니터 (SeXxx) 루틴을 호출한다. 리퀘스트된 접근이 근본 ACL에서 준 접근권으로는 불가능하다면 트랜스포트는 순차적인 열기 리퀘스트를 실패한다.

리턴값

생성/열기 연산이 성공하고 트랜스포트가 주소, 연결 엔드포인트, 통제 채널에 대한 순차적인 I/O 연산을 트랙하기 위해서 상태가 무엇인지를 설정했다면 TdiDispatchCreate 함수는 STATUS_SUCCESS를 리턴한다. 반면에 다음과 같은 드라이버 결정 상태를 리턴할 수 있다:

STATUS_INVALID_PARAMETER

트랜스포트가 TdiTransportAddress와 TdiConnectionContext를 가지고 Irp->AssociatedIrp.SystemBuffer의 버퍼를 설정한 EaName 엔트리를 찾았다면 트랜스포트는 이 값을 리턴한다.

STATUS_SHARING_VIOLATION

독점적인 접근을 위해서 이미 열린 주소를 구현하는 파일 객체를 열기 위한 시도가 행해진다면 트랜스포트는 이 값을 리턴한다.

STATUS_NONEXISTENT_EA_ENTRY

엔트리의 EaName 배열이 Irp->AssociatedIrp.SystemBuffer의 버퍼안에 주어진 EaValueLength의 유효한 주소값에 의해서 뒤따르지 않는다면 트랜스포트는 이 값을 리턴한다.

STATUS_INSUFFICIENT_RESOURCES

트랜스포트가 주소, 연결 엔드포인트, 통제 채널에 대한 상태 정보를 유지하기 위해서 충분한 메모리를 할당하지 않았다면 트랜스포트는 이 상태를 리턴한다.

STATUS_INVALID_DEVICE_REQUEST

디폴트 에러리턴이나 다음 하위 드라이버의 장치가 지금 닫힌다면 트랜스포트는 이 상태를 리턴한다.

주석

주소, 연결 엔드포인트, 통제 채널 객체를 여는 것은 원래 동기적인 연산이다. 드라이버 할당 컨텍스트 지역에 있는 구조체를 초기화하거나 주소를 위해서 ACL을 체크하는 것처럼 특정 작업을 처리하기 위해서 내부의 TdiDispatchCreate 함수는 드라이버 함수를 기다리는 것을 방해할 수 있다. 그러나 TdiDispatchCreate 함수는 IRP에 IoStatus.Status를 STATUS_SUCCESS로 설정하거나 그것이 통제를 리턴하기 전에 적절한 에러 상태를 설정해야한다.

트랜스포트 드라이버는 Irp->AssociatedIrp.SystemBuffer의 버퍼가 TdiTransportAddress와 TdiConnectionContext를 가지고 설정된 EaName 멤버를 포함하는 생성/열기 리퀘스트를 실패한다. 싱글 파일 객체는 결합된 주소와 연결 엔드포인트를 리퀘스트할 수 없기 때문에 클라이언트는 주소와 연결 엔드포인트를 열기 위해서 ZwCreateFile 함수로 분리된 호출을 해야한다.

클라이언트는 트랜스포트 주소를 TDI 드라이버로 인디케이트하는 주소를 구현하는 파일 객체를 연다. 그러한 파일 객치를 여는 처음의 클라이언트는 독점적이거나 공유된다거나 하는 것을 서술할 수 있다. 처음의 클라이언트가 독점적으로 열린 파일 객체를 서술한다면 트랜스포트 드라이버는 그 주소를 열기 위한 모든 순차적인 클라이언트 리퀘스트를 실패한다. 처음의 클라이언트가 공유된 파일 객체를 서술한다면 트랜스포트 드라이버는 또한 그 주소의 독점적인 열기를 위한 모든 순차적인 클라이언트의 리퀘스트를 실패한다. 반면에 같은 주소의 공유된 접근을 위해서 어떤 수의 클라이언트는 같은 파일 객체를 열 수 있다.

트랜스포트에 의존하여 클라이언트는 열리는 트랜스포트 주소를 서술할 수 있고 트랜스포트 드라이버로 하여금 주소를 선택하게 할 수 있다. 예를들어 클라이언트는 연결지향 모드에서 데이타그램을 리시브하기 위해서 TDI 드라이버의 브로드케스트 주소를 서술할 수 있다.

연결 엔드포인트를 여는 것은 클라이언트의 네트웍 연결의 끝을 정의한다. TdiDispatchCreate 함수가 그러한 리퀘스트를 처리할 때 그것은 idle 상태로 연결 엔드포인트를 설정한다. 결국 클라이언트는 주소를 구현하는 열린 파일 객체를 가지고 열린 연결 엔드포인트 연괸시켜야한다. 즉 트랜스포트는 열린 주소와 연관될 때까지 열린 엔드포인트에서 I/O를 하지 않는다.

통제 채널을 여는 것은 클라이언트와 TDI 트랜스포트 드라이버 사이에서 통제 채널을 설정한다. 클라이언트는 주소 혹은 연결 엔드포인트와 명백하게 연관되지 않은 정보를 쿼리하고 셋하기 위해서 열린 통제 채널을 사용할 수 있다. 예를들어 트랜스포트 드라이버의 (브로드케스트 데이타그램을 리시브하기 위해서 사용되는)브로드케스트 주소를 쿼리하거나 트랜스포트가 유지하는 퍼포먼스 통계를 쿼리하기 위해서 클라이언트는 열린 통제 채널을 사용한다.

기본적으로 TdiDispatchCreate 함수는 IRQL PASSIVE_LEVEL에서 실행된다.