TdiBuildInternalDeviceControlIrp

PIRP
   TdiBuildInternalDeviceControlIrp (
       IN CCHAR IrpSubFunction,
       IN PDEVICE_OBJECT DeviceObject,
       IN PFILE_OBJECT FileObject,
       IN PKEVENT Event,
       IN PIO_STATUS_BLOCK IoStatusBlock
      );

TdiBuildInternalDeviceControlIrp 함수는 클라이언트가 시작하는 내부 장치 통제 리퀘스트를 위해서 IRP를 할당한다. 그것이 리턴한 후에 클라이언트는 IoCallDriver 함수를 가지고 리퀘스트를 하기전에 하부 트랜스포트 드라이버의 I/O 스택 로케이션을 설정하기 위해서 리턴된 IRP를 가지고 또다른 TdiBuildXxx 매크로를 호출한다.

매개변수

IrpSubFunction

리턴된 IRP를 위해서 MinorFunction로써 TdiBuildXxx 매크로로의 순차적인 호출에서 설정될 TDI_XXX 코드를 서술한다. 이 매개변수는 다음중 하나가 될 수 있다:

TDI_ASSOCIATE_ADDRESS

호출자는 TdiBuildAssociateAddress 함수로 리턴된 IRP를 전달할 것이다.

TDI_DISASSOCIATE_ADDRESS

호출자는 TdiBuildDisassociateAddress 함수로 리턴된 IRP를 전달할 것이다.

TDI_CONNECT

호출자는 TdiBuildConnect 함수로 리턴된 IRP를 전달할 것이다.

TDI_LISTEN

호출자는 TdiBuildListen 함수로 리턴된 IRP를 전달할 것이다.

TDI_ACCEPT

호출자는 TdiBuildAccept 함수로 리턴된 IRP를 전달할 것이다.

TDI_DISCONNECT

호출자는 TdiBuildDisconnect 함수로 리턴된 IRP를 전달할 것이다.

TDI_SEND

호출자는 TdiBuildSend 함수로 리턴된 IRP를 전달할 것이다.

TDI_RECEIVE

호출자는 TdiBuildReceive 함수로 리턴된 IRP를 전달할 것이다.

TDI_SEND_DATAGRAM

호출자는 TdiBuildSendDatagram 함수로 리턴된 IRP를 전달할 것이다.

TDI_RECEIVE_DATAGRAM

호출자는 TdiBuildReceiveDatagram 함수로 리턴된 IRP를 전달할 것이다.

TDI_SET_EVENT_HANDLER

호출자는 TdiBuildSetEventHandler 함수로 리턴된 IRP를 전달할 것이다.

TDI_QUERY_INFORMATION

호출자는 TdiBuildQueryInformation 함수로 리턴된 IRP를 전달할 것이다.

TDI_SET_INFORMATION

호출자는 TdiBuildSetInformation 함수로 리턴된 IRP를 전달할 것이다.

TDI_ACTION

호출자는 TdiBuildAction 함수로 리턴된 IRP를 전달할 것이다.

DeviceObject

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

FileObject

주어진 IrpSubFunction에 의존하여 주소, 연결 엔드포인트, 통제 채널을 구현하는 파일 객체를 가리킨다.

Event

호출자가 저장소를 제공하기 위해서 초기화된 이벤트 객체를 가리킨다.

IoStatusBlock

IO_STATUS_BLOCK 타입의 호출자 제공 변수를 가리킨다.

리턴값

TdiBuildInternalDeviceControlIrp 함수는 할당된 IRP에 대한 포인터를 리턴한다. 할당 시도가 실패한다면 NULL을 리턴한다.

주석

TDI 트랜스포트의 커널 모드 클라이언트는 TdiBuildInternalDeviceControlIrp 함수의 호출없이 IRP를 TdiBuildXxx 매크로로 직접 여전히 상위 레벨인 니트웍 컴포넌트에 의해서 밑으로 전달된다.

그러나 그러한 클라이언트는 들어오는 IRP를 하이재킹해서는 안된다. 그리고 그 대신에 하부 트랜스포트로의 내부 장치 통제 리퀘스트를 하기 위해서 그것을 재사용한다. 대신에 클라이언트는 그러한 리퀘스트를 가지고 자신의 IRP를 얻기 위해서 TdiBuildInternalDeviceControlIrp 함수를 호출할 수 있다.

TdiBuildInternalDeviceControl 함수가 IRP에 대한 포인터를 리턴한 후에 클라이언트는 IoCallDriver 함수를 가지고 트랜스포트쪽으로 IRP를 전달하기 전에 TDI_XXX를 요구하는 추가적인 매개변수에 따라서 적절한 TdiBuildXxx 매크로로 IRP를 전달해야한다. TdiBuildInternalDeviceControl 함수는 할당된 IRP안에서 하부 트랜스포트의 I/O 스택 로케이션을 부분적으로 설정한다. 그러나 TdiBuildXxx 매크로가 하는 것처럼 TDI_XXX 리퀘스트를 위해서 TDI 트랜스포트의 예상에 따라서 I/O 스택 로케이션을 포맷하지는 않는다.

IoCallDriver 함수로의 호출에 대한 특징에 대해서는 커널 모드 드라이버 레퍼런스를 봐라.

클라이언트가 TdiBuildInternalDeviceControlIrp 함수를 호출했을 때 이벤트 포인터를 제공하다면 I/O 매니저는 IRP가 하위 드라이버에 의해서 완료될 때 이벤트를 시그널 상태로 설정할 것이다. 그러나 클라이언트는 클라이언트 생성 스레드나 가능하다면 이것이 호출되었을 때 실행되는 스레드처럼 적절한 스레드 컨텍스트에서 IRQL PASSIVE_LEVEL에서 기다리지 않는다면 IRP의 완료를 위해서 그 이벤트에서 기다릴 수 없다.

TdiBuildInternalDeviceControlIrp 함수의 호출자는 IRQL PASSIVE_LEVEL에서 실행되어야한다. 결과적으로 클라이언트는 이 함수를 가지고 몇몇 IRP를 미리 할당해야한다. 그래서 클라이언트는 상위 IRQL에서 실행될 때 그것을 TDI_XXX 리퀘스트를 제출하기 위해서 사용할 수 있다.