TdiBuildSendDatagram macro

Article
06/19/2017

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.

Syntax

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
);

Parameters

Irp [in]
Pointer to a client-supplied IRP, either originating in a higher level network component or allocated with TdiBuildInternalDeviceControlIrp.
DevObj [in]
Pointer to the device object created by the underlying TDI transport driver.
FileObj [in]
Pointer to a file object representing an address.
CompRoutine [in]
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 [in]
Pointer 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 is NULL if CompRoutine is NULL.
MdlAddr [in]
Pointer 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 [in]
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 [in]
Pointer to a TDI_CONNECTION_INFORMATION structure specifying the remote-node address to which the caller-supplied datagram is to be sent.

Return value

None

Remarks

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.

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

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

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

Requirements

Target platform	Desktop
Header	Tdikrnl.h (include TdiKrnl.h)