TdiDispatchFastDeviceControl

TdiDispatchFastDeviceControl

BOOLEAN
TdiDispatchFastDeviceControl (
IN STRUCT FILE_OBJECT *FileObject,
IN BOOLEAN Wait,
IN PVOID InputBuffer,
IN ULONG InputBufferLength,
IN OUT PVOID OutputBuffer,
IN ULONG OutputBufferLength,
IN ULONG IoControlCode,
OUT PIO_STATUS_BLOCK IoStatus
);

TdiDispatchFastDeviceControl is an optional TDI transport driver function that usually returns data already buffered internally by the transport.

Parameters

FileObject

Points to the file object representing the open address, connection endpoint, or control channel.

Wait

Specifies TRUE if the driver can wait in the context of the call to TdiDispatchFastDeviceControl.

InputBuffer

Optionally points to the input buffer, containing caller-supplied information required by the given IoControlCode.

InputBufferLength

Specifies the size in bytes of the input buffer.

OutputBuffer

Optionally points to the output buffer in which the transport returns any data requested.

OutputBufferLength

Specifies the size in bytes of the output buffer.

IoControlCode

Specifies the IOCTL_TDI_XXX code for the requested operation. This value must be one of the codes defined in ntddtdi.h.

The set of valid IOCTL_TDI_XXX codes depends on the fast I/O support, if any, provided by an individual transport and on what that transport currently holds in its internal buffers. In general, transports are most likely to buffer read-ahead data to satisfy anticipated IOCTL_TDI_RECEIVE requests and, possibly, data used to satisfy IOCTL_TDI_QUERY_INFORMATION requests.

The afd.sys driver, which provides support for Windows Sockets to communicate with underlying transports, also provides read-ahead fast I/O support for system transports that do not provide a fast I/O path for received data.

IoStatus

Points to a caller–supplied variable in which TdiDispatchFastDeviceControl returns the completion status, formatted as an IO_STATUS_BLOCK structure. TdiDispatchFastDeviceControl fills in the Status and Information members as appropriate for the given IoControlCode.

Return Value

TdiDispatchFastDeviceControl returns TRUE only if it satisfies or completes the kernel-mode client's request before returning control.

Comments

When preparing a fast I/O request, a client neither allocates an IRP nor uses an IRP passed in from a higher network layer.

When the I/O Manager calls TdiDispatchFastDeviceControl, a given OutputBuffer usually corresponds to the buffer at Irp->MdlAddress in a client-supplied IRP. The InputBuffer contains any client-supplied information for the request, depending on the IoControlCode. This request is different from other kernel requests in that system-defined user-mode IOCTLs identify the requests, as opposed to the TDI_XXX minor function codes listed with TdiBuildInternalDeviceControlIrp.

For example, for IOCTL_TDI_SEND, InputBuffer contains a client-supplied TDI_REQUEST_SEND structure, and OutputBuffer contains the actual data to be sent over the network. For IOCTL_TDI_RECEIVE, InputBuffer contains a TDI_REQUEST_RECEIVE structure, and the transport driver copies the receive data to OutputBuffer.

The definition of each IOCTL_TDI_XXX code in ntddtdi.h determines how buffers should be set up. See the Kernel-Mode Driver Reference for an explanation of how to interpret IOCTL_XXX codes.

When the buffer parameters have been set up for the transport, the client calls IoCallDriver to deliver the request to TdiDispatchFastDeviceControl if the transport exports this routine. If the transport cannot complete a fast I/O client request immediately, TdiDispatchFastDeviceControl returns FALSE and the I/O Manager repackages the given request into an IRP_MJ_DEVICE_CONTROL IRP and submits the IRP to the transport driver's TdiDispatchDeviceControl routine. Otherwise, TdiDispatchFastDeviceControl satisfies the request itself, possibly by calling an internal driver function to process the request, or it fails the request.

At initialization, a TDI transport driver enables its fast I/O path by setting the FastIoDispatch field in the input driver object to the address of a driver-allocated FAST_IO_DISPATCH structure. The transport must fill in the SizeOfFastIoDispatch member and set FastIoDeviceControl to the entry point of the transport's TdiDispatchFastDeviceControl function; all other members of the FAST_IO_DISPATCH structure must be set to NULL. For more information about this structure and about driver objects, see the Kernel-Mode Driver Reference.

If TdiDispatchFastDeviceControl returns TRUE, the transport relinquishes ownership of the original buffers to the client. If TdiDispatchFastDeviceControl cannot complete the request by using data already available in the transport, it should return FALSE immediately. When it returns FALSE, the I/O Manager sets up an IRP and resubmits the client's request to the transport's TdiDispatchDeviceControl routine.

By default, TdiDispatchFastDeviceControl runs at IRQL PASSIVE_LEVEL.