RtNalAcquireQueue

RtNalAcquireQueue reserves a network queue for the application. The application must also call RtNalConfigureQueue to configure the queue to send or receive data.

Syntax

RTNAL_QUEUE_HANDLE RtNalAcquireQueue(
	PRTNAL_QUEUE_CRITERIA pQueueCriteria,
	PRTNAL_QUEUE pNalQueue,
	PRTNAL_QUEUE_EVENTS pQueueEvents
);

Parameters

pQueueCriteria

A pointer to a RTNAL_QUEUE_CRITERIA queue configuration structure. The application must fill in this structure with criteria that specifies the queue to acquire. This parameter cannot be NULL.

pNalQueue

A pointer to a RTNAL_QUEUE structure filled in by the NAL with information about the acquired queue returned by the function. This parameter cannot be NULL.

pQueueEvents

A pointer to a RTNAL_QUEUE_EVENTS structure filled in by the NAL with notification event handles based on the flags set in pQueueCriteria. This parameter cannot be NULL.

Return Value

Returns a handle for the queue if the call succeeds. This handle is used in all future API calls to access this queue. Returns NULL if the call fails. Call GetLastError to obtain an error code for why the call failed. The possible error codes are listed below:

Error Code	Meaning
ERROR_INVALID_PARAMETER	A pointer argument is NULL or pQueueCriteria contains an invalid field.
ERROR_NOT_FOUND	The requested queue was not found in a system.
ERROR_ACCESS_DENIED	The requested queue is already in use.
ERROR_NOT_READY	RtNalInit has not completed successfully.
ERROR_NO_NETWORK	The NAL has not started or has not fully initialized.
ERROR_RESOURCE_NOT_AVAILABLE	An internal system resource is not available.

Remarks

The queue can be used either to receive or send data.

To acquire a queue, the application must specify the queue type, the network device ASCII friendly name, or PCI location and the search method. An application can reserve the default queue (which receives unfiltered data) or any available queue, or can specify the device queue index.

The RTNAL_QUEUE_CRITERIA structure contains a flags field that is a bitmask of ORed flags that indicates which notifications an application wants to receive from this queue:

Set the RTNAL_USE_LINK_EVENT_FLAG bit to use link status notifications.
Set the RTNAL_USE_RX_EVENT_FLAG bit to use receive notifications. This flag must not be used if an application uses a polling timer to receive data.
Set the RTNAL_USE_TX_COMPLETE_EVENT_FLAG bit to use transmit complete notifications. This flag must be used if an application wants the transmit complete thread to call a transmit complete callback supplied by the application for frames in RtNalTramsmitEx.

Notification events are for this particular queue. The stop event is a manual reset event. It is always enabled and always provided to the application. All other events are auto-reset events.

Requirements

Minimum Supported Version (NAL)	RTX64 Network Abstraction Layer 2.0
Minimum Supported Version (RTX64)	RTX64 3.4
Header	rtnapi.h, RtNalApi.h
Library	RtNal.lib