RtNalTransmitEx

RtNalTransmitEx transmits an array of NAL frames.

Syntax

BOOL RtNalTransmitEx(
	RTNAL_QUEUE_HANDLE queueHandle,
	RTNAL_FRAME pNalFrameArray[],
	ULONG numberOfFrames,
	ULONG *pSubmittedCnt
);

Parameters

queueHandle

Network queue handle returned by RtNalAcquireQueue.

pNalFrameArray

An array of pointers to Ethernet frames of type RTNAL_FRAME.

numberOfFrames

The number of frames to transmit. This must be a non-zero value.

pSubmittedCnt

An output pointer to a ULONG filled in with the number of frames submitted to the driver to transmit. This pointer cannot be NULL.

Return Value

Returns TRUE if frames were submitted to the driver. Returns FALSE if no frames were submitted to the driver. The last error is set if RtNalTransmitEx has submitted a number of frames to the driver that is less than the value of numberOfFrames. Call GetLastError to obtain an error code. The possible error codes are listed below:

Error Code Meaning
ERROR_DEVICE_NO_RESOURCES The DMA buffer descriptor ring is full.
ERROR_INCORRECT_SIZE The frame size is 0 or it exceeds the maximum configured by the driver.
ERROR_INVALID_ADDRESS A frame is not allocated by RtNalAllocateFrame.
ERROR_INVALID_PARAMETER queueHandle, pNalFrameArray, or pSubmittedCnt is a NULL pointer, or numberOfFrames is 0.
ERROR_IO_DEVICE The Ethernet link is down.
ERROR_NOT_OWNER A frame submitted for transmit is still owned by the NAL from the previous transmit.
ERROR_NOT_SUPPORTED Called for a receive queue or the driver does not support RtndTransmitEx.
ERROR_NOT_READY RtNalConfigureQueue has not completed successfully.
ERROR_INVALID_HANDLE queueHandle is invalid. This might be occur if the queue was released in another thread or on process exit, as if by RtssKill.

Remarks

For a list of supported functions for specific drivers, see Matrix of Supported Real-Time NAL Functions by NIC Driver.

PNalFrameArray must contain pointers to NAL frames previously allocated by RtNalAllocateFrame. Each frame structure contains a virtual and physical memory address of the frame data buffer. An application must not change these pointers. An application should write the Ethernet data to transmit at the virtual address of the data buffer and supply the data size.

RtNalTransmitEx is a zero-copy API. The frame is transmitted directly from the physical address in a NAL_FRAME structure. The NAL does not check that the physical address corresponds to the virtual address.

A frame can be reused for transmission after its ownership has been relinquished by a transmit complete thread. If RtNalTransmitEx encounters a frame still owned by the NAL, it sets last error to ERROR_NOT_OWNER. The application must not modify fields of the RTNAL_FRAME structure or write to a data buffer of the NAL frame still owned by the NAL. RtNalIsApplicationFrame should be used to determine ownership of the frame. The function executes completely in the caller’s context, priority, and CPU affinity.

If an application wants to receive transmit complete callbacks, it must subscribe to transmit complete notifications in RtNalAcquireQueue. The NAL runs an additional transmit complete thread per queue for each queue that requested transmit complete notifications. The NAL runs this queue in an application context with the ideal processor and priority configured for the interface. The application must not use the transmit complete event handle directly.

This function requires RtndTransmitEx to be exported by the NIC driver.

The NIC driver must export RtndAttachToTransmitQueue, RtndDetachTransmitQueue, and RtndServiceTransmitQueue for an application to use transmit notifications.

For the devices listed below, transmit timestamps are retrieved from the packet descriptor, not the registers:

Requirements

Minimum Supported Version RTX64 4.0
Header rtnapi.h, RtNalApi.h
Library RtNal.lib

See Also: