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 a TDI driver function that provides fast driver control for expedited kernel-mode client requests other than those for opening and closing objects. When preparing a request, the client first issues a request message

and then either calls a library build macro to format an IRP or uses an IRP passed in from a higher network layer. It places the appropriate I/O control in the IRP parameters and uses IRP_MJ_DEVICE_CONTROL as the major function code. When the IRP is ready, the client calls IoCallDriver to deliver the request to TdiDispatchFastDeviceControl. TdiDispatchFastDeviceControl then forwards the client request to the appropriate internal driver function for processing.

At initialization, the TDI driver enables the fast I/O path by setting the FastIoDispatch field in the input driver object to a driver-allocated FAST_IO_DISPATCH structure. The driver must fill in the SizeOfFastIoDispatch and FastIoDeviceControl members in this structure but all other members must be set to NULL. FastIoControl is set to the entry point of a driver-supplied routine. This structure is defined as follows:

typedef struct _FAST_IO_DISPATCH {

ULONG SizeOfFastIoDispatch;

PFAST_IO_CHECK_IF_POSSIBLE FastIoCheckIfPossible;

PFAST_IO_READ FastIoRead;

PFAST_IO_WRITE FastIoWrite;

PFAST_IO_QUERY_BASIC_INFO FastIoQueryBasicInfo;

PFAST_IO_QUERY_STANDARD_INFO FastIoQueryStandardInfo;

PFAST_IO_LOCK FastIoLock;

PFAST_IO_UNLOCK_SINGLE FastIoUnlockSingle;

PFAST_IO_UNLOCK_ALL FastIoUnlockAll;

PFAST_IO_UNLOCK_ALL_BY_KEY FastIoUnlockAllByKey;

PFAST_IO_DEVICE_CONTROL FastIoDeviceControl;

} FAST_IO_DISPATCH, *PFAST_IO_DISPATCH;

A TDI driver sets only the FastIoDeviceControl entry points in this structure. All other members must be set to NULL.

Note Because the I/O subsystem does not necessarily map and lock the input buffer and the output buffer of the IRP, TdiDispatchFastDeviceControl must access them inside a try-except clause.

When the I/O subsystem calls TdiDispatchFastDeviceControl, the output buffer contains the primary buffer for the client request, which is the buffer the MDL chain for a regular kernel-mode client request describes. The input buffer contains information about the client request, depending on the request message (IoControlCode) in the IRP. This request is defferent from other kernel requests in that the user-mode IOCTLs are used to identify the requests, as opposed to the minor function codes listed in TdiBuildInternalDeviceControlIrp.

For example, for a request message of TDI_SEND, InputBuffer contains an instance of the TDI_REQUEST_SEND structure. OutputBuffer contains the actual data the driver sends and the IoControlCode contains the value IOCTL_TD_SEND. A corresponding value is also present for TDI_RECEIVE. For a request message of TDI_RECEIVE, InputBuffer contains an instance of the TDI_REQUEST_RECEIVE structure, and the driver copies the receive data to OutputBuffer. In the case of the receive, if the data is not already available in the driver buffers, TdiDispatchFastDeviceControl cannot complete successfully using the fast I/O path.

TdiDispatchFastDeviceControl returns TRUE only if the client request succeeds and the driver copies or no longer needs the contents of InputBuffer and OutputBuffer. In this case, the driver relinquishes ownership of the original buffers to the client and the I/O subsystem prevents the client request from entering the regular IRP-based path (TdiDispatchInternalDeviceControl).

If TdiDispatchFastDeviceControl cannot complete the kernel-mode client request immediately, it returns FALSE. The I/O subsystem will then resubmit the client request later using TdiDispatchInternalDeviceControl.

Parameters

FileObject

Points to the file object for the client request.

Wait

Specifies TRUE if the driver can wait inside TdiDispatchFastDeviceControl.

InputBuffer

Optionally points to the input buffer.

InputBufferLength

Specifies the length, in bytes, of the input buffer.

OutputBuffer

Optionally points to the caller–defined memory location of the output buffer.

OutputBufferLength

Specifies the length, in bytes, of the output buffer.

IoControlCode

Specifies the client request message.

IoStatus

Points to the caller–defined memory location to which TdiDispatchFastDeviceControl writes an IO_STATUS_BLOCK structure containing its completion status. The structure contains Status and Information members that TdiDispatchFastDeviceControl fills in as appropriate for the specific client request.

Return Value

TdiDispatchFastDeviceControl returns TRUE only if the kernel-mode client request succeeds. If the driver cannot complete the client request immediately, TdiDispatchFastDeviceControl returns FALSE.