4.5 TDI Library Functions and Macros

Windows NT provides a small set of TDI library functions as a kernel-mode dynamic-link library (the tdi.sys export library) with which TDI drivers and kernel-mode clients link themselves. However, most of the system-supplied TdiBuildXxx called by kernel-mode clients are implemented as macros in the tdikrnl.h header that both clients and transports include.

Any kernel-mode TDI client can use the TdiBuildXxx macros as needed in preparing the TDI_XXX IOCTL IRPs, already mentioned in Section 4.3. After the client has set up such an IRP with a TdiBuildXxx macro, it submits the request to the underlying TDI driver by passing the IRP to IoCallDriver. Each of these macros fills in the relevant members of the client-provided IRP, except for the Status and Information members, which the underlying transport fills in after processing its client's request. Before using one of TdiBuildXxx IOCTL macros, a client can call TdiBuildInternalDeviceControlIrp to allocate the IRP if it has not already been allocated by a still higher level network component and given to the client.

A transport driver never uses the TdiBuildXxx macros. However, a TDI driver can use some of the remaining TDI library routines, such as TdiCompleteRequest and TdiCopyBufferToMdl, for assistance in processing client requests.

TDI library routines and macros include the following:

TdiBuildInternalDeviceControlIrp

Allocates an IRP if the client does not receive an IRP from a higher network layer.

TdiBuildAccept 

Sets up an IRP for a client-submitted TDI_ACCEPT request.

TdiBuildAction 

Sets up an IRP for a client-submitted TDI_ACTION request.

TdiBuildAssociateAddress 

Sets up an IRP for a client-submitted TDI_ASSOCIATE_ADDRESS request.

TdiBuildConnect 

Sets up an IRP for a client-submitted TDI_CONNECT request.

TdiBuildDisassociateAddress

Sets up an IRP for a client-submitted TDI_DISASSOCIATE_ADDRESS request.

TdiBuildListen 

Sets up an IRP for a client-submitted TDI_LISTEN request.

TdiBuildQueryInformation 

Sets up an IRP for a client-submitted TDI_QUERY_INFORMATION request.

TdiBuildReceive 

Sets up an IRP for a client-submitted TDI_RECEIVE request.

TdiBuildReceiveDatagram 

Sets up an IRP for a client-submitted TDI_RECEIVE_DATAGRAM request.

TdiBuildSend 

Sets up an IRP for a client-submitted TDI_SEND request.

TdiBuildSendDatagram 

Sets up an IRP for a client-submitted TDI_SEND_DATAGRAM request.

TdiBuildSetEventHandler 

Sets up an IRP for a client-submitted TDI_SET_EVENT_HANDLER request.

TdiBuildSetInformation 

Sets up an IRP for a client-submitted TDI_SET_INFORMATION request.

TdiBuildNetbiosAddress 

Sets up a NetBIOS address for a client.

TdiBuildNetbiosAddressEa

Sets up a buffered NetBIOS address that a client can pass subsequently to ZwCreateFile to open the address.

TdiReturnChainedReceives

Relinquishes control of the buffer that was passed to a ClientEventChainedReceive(Xxx) handler after the client has consumed the received TSDU.

TdiCopyBufferToMdl 

Copies a range of buffered data into a destination buffer mapped by a given MDL.

Both clients and transports can use this function.

TdiCopyMdlToBuffer 

Copies data from buffer(s) mapped by a given MDL into a caller-supplied destination buffer.

Both clients and transports can use this function.

TdiCopyLookaheadData

Safely copies received data indicated to the transport by a NIC driver, whatever the nature of the memory (including mapped device memory) the NIC is using.

TdiMapUserRequest

Converts an IRP passed in to a transport's TdiDispatchDeviceControl routine into a TDI_XXX IOCTL IRP if TdiMapUserRequest recognizes the minor function code specified in the input IRP.

TdiCompleteRequest

Completes an IRP with the system-defined network-specific priority boost for a transport driver.