TdiBuildSendDatagram

TdiBuildSendDatagram

VOID
TdiBuildSendDatagram (
IN PIRP Irp,
IN PDEVICE_OBJECT DevObj,
IN PFILE_OBJECT FileObj,
IN PVOID CompRoutine,
IN PVOID Contxt,
IN PMDL MdlAddr,
IN ULONG SendLen,
IN PTDI_CONNECTION_INFORMATION SendDatagramInfo
);

TdiBuildSendDatagram sets up an internal device control IRP for a TDI_SEND_DATAGRAM request to the underlying transport in which the local-node client has already opened a file object representing an address.

Parameters

Irp

Points to a client-supplied IRP, either originating in a higher level network component or allocated with TdiBuildInternalDeviceControlIrp.

DevObj

Points to the device object created by the next lower TDI transport driver.

FileObj

Points to a file object representing an address.

CompRoutine

Specifies the entry point of a client-supplied IoCompletion routine or NULL. The I/O Manager calls this routine when the given IRP is completed, unless the client sets this parameter to NULL.

Contxt

Points to a client-determined context. This client-supplied pointer is passed in to the IoCompletion routine when it is called with the completed IRP. Contxt should be NULL if CompRoutine is NULL.

MdlAddr

Points to an MDL, possibly the initial MDL in a chain of MDLs, mapping a client-supplied buffer from which the transport is to transfer the datagram to be sent.

SendLen

Specifies the size in bytes of the buffer mapped at MdlAddr. The maximum datagram size depends on the underlying transport. Whether zero is valid also depends on the underlying transport.

SendDatagramInfo

Points to a TDI_CONNECTION_INFORMATION structure specifying the remote-node address to which the caller-supplied datagram is to be sent.

Comments

TdiBuildSendDatagram sets IRP_MJ_INTERNAL_DEVICE_CONTROL as the MajorFunction and TDI_SEND_DATAGRAM as the MinorFunction codes in the transport's I/O stack location of the given IRP.

TDI transports never fragment datagrams. Consequently, their clients make one send-datagram request to transmit each datagram, which is associated only with the particular request for a connectionless data transfer to the given destination address. To determine the maximum possible value for SendLen, the client usually issued a preceding query-information request, set up with TdiBuildQueryInformation for any of the QType values TDI_QUERY_PROVIDER_INFO, TDI_QUERY_DATAGRAM_INFO, or TDI_QUERY_MAX_DATAGRAM_INFO.

Certain transports support broadcast and/or multicast datagram transmissions. The client of such a transport can send a datagram to a multicast or broadcast address on the remote node. However, the syntax of the multicast or broadcast address is driver-specific. The client can obtain such a transport's broadcast address by issuing a query-information request with the QType value TDI_QUERY_BROADCAST_ADDRESS.

Any connectionless transfer is inherently unreliable. The underlying transport can lose or duplicate any given datagram at the discretion of the driver writer.

When a client issues send-datagram request, the transport usually queues the request internally. Transports process send-datagram requests in FIFO order. They queue send-datagram requests separately from endpoint-to-endpoint send requests from the same client.