TdiBuildReceiveDatagram macro

  • Artigo

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

Syntax

VOID TdiBuildReceiveDatagram(
  [in]  PIRP                        Irp,
  [in]  PDEVICE_OBJECT              DevObj,
  [in]  PFILE_OBJECT                FileObj,
  [in]  PVOID                       CompRoutine,
  [in]  PVOID                       Contxt,
  [in]  PMDL                        MdlAddr,
  [in]  ULONG                       ReceiveLen,
  [in]  PTDI_CONNECTION_INFORMATION ReceiveDatagramInfo,
  [out] PTDI_CONNECTION_INFORMATION ReturnInfo,
        ULONG                       InFlags
);

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 into which the transport is to transfer the received datagram.

  • ReceiveLen [in]
    Specifies the maximum size in bytes of the datagram to return in the buffer mapped at MdlAddr. If this parameter is zero, the transport can use the whole buffer mapped at MdlAddr.

  • ReceiveDatagramInfo [in]
    Pointer to a TDI_CONNECTION_INFORMATION structure specifying a particular remote-node address from which this local-node client will accept a datagram. If the RemoteAddressLength member is zero, a datagram from any remote node is acceptable to this client. A RemoteAddressLength of zero implies a RemoteAddress set to NULL.

  • ReturnInfo [out]
    Pointer to caller-supplied buffer in which the transport is to return the source address of the received datagram, formatted as a TDI_CONNECTION_INFORMATION structure.

  • InFlags
    Specifies the type of receive to be returned by the transport as one or more (Ored) of the following:

    • TDI_RECEIVE_NORMAL
      Return a normal TSDU to the client-supplied buffer.

    • TDI_RECEIVE_PEEK
      Return an indicated datagram as soon as it arrives from a remote node, even if it is a partial TSDU, and the client will request another receive for the remainder of the datagram if it is of interest to this client.

      This flag is valied only if the underlying transport buffers received datagrams internally. In general, clients that go through the system AFD driver, which buffers data internally for nonbuffering transports, can use this flag.

Return value

None

Remarks

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

Because a datagram is not associated with an established connection, the TDI driver returns the transport address of the remote-node sender to the receiving client along with the datagram.

The transport satisfies this IRP when it receives a datagram directed to the local-node address represented by the client's open file object and a source address matching the client's specification at ReceiveDatagramInfo. If such a received datagram is too large for the client-supplied buffer, the underlying transport truncates the datagram, discarding any superfluous data, and completes the client's receive-datagram request.

TDI transports never fragment datagrams. Consequently, their clients make one receive-datagram request to receive each datagram. To determine the maximum possible value for ReceiveLen, 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.

A client can receive a broadcast datagram by opening a broadcast address that has a transport-specific format, which can be obtained with a query-information request. However, such a client cannot send a datagram from the broadcast address, nor can it establish an association between a connection of its own and that broadcast address.

A client also can receive datagrams by registering its ClientEventReceiveDatagram and/or ClientEventChainedReceiveDatagram handler(s) on a particular address.

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)

See also

ClientEventChainedReceiveDatagram

ClientEventReceiveDatagram

TdiBuildInternalDeviceControlIrp

TdiBuildQueryInformation

TdiBuildSendDatagram

TdiBuildSetEventHandler

TDI_CONNECTION_INFORMATION

TDI_RECEIVE_DATAGRAM

 

 

Send comments about this topic to Microsoft