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.

See Also

ClientEventChainedReceiveDatagram, ClientEventReceiveDatagram, TdiBuildInternalDeviceControlIrp, TdiBuildQueryInformation, TdiBuildReceiveDatagram, TdiBuildSend, TDI_CONNECTION_INFORMATION, TDI_SEND_DATAGRAM