TDI_SEND_DATAGRAM

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. IRP members relevant to this request include the following:

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

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

Points 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

Points 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

Points to a TDI_CONNECTION_INFORMATION structure specifying the remote-node address to which the local-node client wants the datagram to be sent.

MdlAddress

Points 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.