RxCeSendDatagram sends a transport service data unit (TSDU) along the specified connection on a virtual circuit.
NTSTATUS RxCeSendDatagram( _In_ PRXCE_TRANSPORT pTransport, _In_ PRXCE_ADDRESS pAddress, _In_ PRXCE_CONNECTION_INFORMATION pConnectionInformation, _In_ ULONG Options, _In_ PMDL pMdl, _In_ ULONG SendLength, _In_ PVOID pCompletionContext );
- pTransport [in]
A pointer to the transport along which the TSDU is to be sent.
- pAddress [in]
A pointer to the local transport address.
- pConnectionInformation [in]
A pointer to connection information that contains the remote address.
- Options [in]
The desired options for transmitting the data on this send operation by the transport. Note that this is only a request sent to the transport. The transport may only support a limited number of the options specified and ignore options not supported. The Options parameter consists of set of bits defined in rxce.h. The Options parameter can be a combination of the following bits:
Signifies if an RX_MEM_DESC(MDL) is to be sent in its entirety, or if only portions of it need to be sent. This option requests that the transport allow the send operation to transmit part of the data if the transport and MDL allow this behavior.
Signifies if the send operation is to transmit the data synchronously. When this option is set, the request is submitted to the underlying transport and control does not return to the caller until the request completes. Note that the pCompletionContext parameter is ignored when this bit is set.
Note that the RXCE_SEND_SYNCHRONOUS option is disregarded for sending datagrams because the underlying transports do not block on datagram sends.
- pMdl [in]
A pointer to the buffer to be sent.
- SendLength [in]
The length of data to be sent.
- pCompletionContext [in]
The context passed back to the caller during SendCompletion for asynchronous operations. Not that this parameter is ignored if the Options parameter requests a synchronous send operation.
RxCeSendDatagram returns STATUS_SUCCESS on success or one of the following error codes on failure:
The allocation of nonpaged pool memory needed by this routine failed.
An invalid length was passed in the SendLength parameter based on the Options specified.
The asynchronous and synchronous options indicated in the Options parameter used in RxCeSendDatagram distinguish between two situations. In the asynchronous case, control returns to the caller once the request has been successfully submitted to the underlying transport. The results for any given request are communicated back using the SendCompletion callback routine. The pCompletionContext parameter in RxCeSendDatagram is passed back in the callback routine to assist the caller in disambiguating the requests.
In the synchronous case, the request is submitted to the underlying transport and the control does not return to the caller till the request completes. Note that in the synchronous case, the pCompletionContext parameter is ignored and the status that is returned corresponds to the completion status of the operations.
The benefit of asynchronous and synchronous options depends on the underlying transport. In a virtual circuit environment (TCP, for example), a synchronous option implies that the control does not return until the data reaches the server. On the other hand for datagram oriented transports (UDP, for example), there is very little difference between the two options.
Note that the synchronous Option is disregarded for sending datagrams because the underlying transports do not block on datagram sends.
RXCE_CONNECTION_INFORMATION is a typedef for a TDI_CONNECTION_INFORMATION structure.