TdiBuildReceiveDatagram

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

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.

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

ReceiveLen

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

Points 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

Points 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) or none (zero) 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.

Comments

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 of a NetBIOS transport 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.

Windows NT currently specifies the reception of broadcast datagrams only for NetBIOS TDI clients. From some other transports, a client can receive a broadcast datagram in the same way it receives a nonbroadcast datagram.

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