TDI_SEND_DATAGRAM
When a kernel-mode client makes a TDI_SEND_DATAGRAM request, it asks the underlying TDI transport driver to transmit a TSDU, as a datagram, to a specified remote-node address.
IRP
The transport calls IoGetCurrentIrpStackLocation with the given Irp to get a pointer to its own I/O stack location in the IRP, shown in the following list as IrpSp. The pointer to the IRP is shown in the following list as Irp. IRP members relevant to this request include the following:
Irp->IoStatus.Status
Specifies the final status of the send-datagram request. The transport sets this member before it completes the IRP, possibly to one of the following:
STATUS_PENDING
STATUS_INSUFFICIENT_RESOURCES
STATUS_INVALID_ADDRESS
STATUS_INVALID_PARAMETER
Irp->IoStatus.Information
Specifies the number of bytes of client-supplied data the driver transferred from the client-supplied buffer mapped at Irp->MdlAddress.
IrpSp->MajorFunction
Specifies IRP_MJ_INTERNAL_DEVICE_CONTROL. The transport can ignore this member if it exports a TdiDispatchInternalDeviceControl routine that handles only TDI_XXX requests.
IrpSp->MinorFunction
Specifies TDI_SEND_DATAGRAM.
IrpSp->FileObject
Pointer to an open file object representing the local-node address. The transport uses the FsContext and, possibly, FsContext2 fields to access the state it maintains about this address.
IrpSp->Parameters
Pointer to a TDI_REQUEST_KERNEL_SENDDG structure, defined as follows:
struct _TDI_REQUEST_KERNEL_SENDDG {
ULONG SendLength;
PTDI_CONNECTION_INFORMATION SendDatagramInformation;
} TDI_REQUEST_KERNEL_SENDDG, *PTDI_REQUEST_KERNEL_SENDDG;
The transport uses the members of this structure as follows:
SendLength
Specifies the number of bytes in the datagram to send.SendDatagramInformation
Pointer to a TDI_CONNECTION_INFORMATION structure specifying the remote-node address to which the local-node client wants the datagram to be sent.
Irp->MdlAddress
Pointer to an MDL, possibly the initial MDL in a chain, mapping a client-supplied buffer containing the datagram to be sent.
Comments
A TDI transport does not send fragmented datagrams. Consequently, its client makes one send-datagram request to send each datagram, which is associated only with the particular request for a connectionless data transfer operation.
In its send-datagram request, the sending client provides a buffer containing the TSDU. The client can provide a buffer of any size up to the transport-determined limit. The transport is given ownership of this client-supplied buffer until it completes the send-datagram IRP. The transport fails any send-datagram request for which a client specifies a SendLength larger than the transport supports.
Clients can determine their underlying transports' send-size limits by submitting query-information requests with QueryType set to any of TDI_QUERY_PROVIDER_INFO, TDI_QUERY_DATAGRAM_INFO, or TDI_QUERY_MAX_DATAGRAM_INFO.
A transport can allow its clients to send zero-length datagrams. For example, a zero-length send-datagram request might force protocol flow.
Some transports allow clients to direct datagrams to remote-node multicast and/or broadcast addresses. The syntax of such a multicast or broadcast address is transport-specific.
As a connectionless transfer, a datagram-send is inherently unreliable. The transport can drop or duplicate a datagram at the discretion of the driver writer. The transport must complete each send-datagram IRP in a timely manner, whether with a success or error status. The driver should determine a reasonable time-out based on its knowledge of underlying network conditions.
If it queues datagrams internally, the transport must process send-datagram requests in FIFO order. Send-datagram requests should be queued separately from endpoint-to-endpoint send requests.
TdiBuildSendDatagram is the macro a client uses to fill in this IRP.
Note The TDI feature is deprecated and will be removed in future versions of Microsoft Windows. Depending on how you use TDI, use either the Winsock Kernel (WSK) or Windows Filtering Platform (WFP). For more information about WFP and WSK, see Windows Filtering Platform and Winsock Kernel. For a Windows Core Networking blog entry about WSK and TDI, see Introduction to Winsock Kernel (WSK).
See Also
TdiBuildSendDatagram, TDI_CONNECTION_INFORMATION, TdiDispatchInternalDeviceControl, TDI_QUERY_INFORMATION, TDI_RECEIVE_DATAGRAM
Requirements
Header |
TdiKrnl.h (include TdiKrnl.h) |