Rtnl2AcquirePhysicalRxQueue

Rtnl2AcquirePhysicalRxQueue acquires a Physical Receive Queue object specified by the handle of the owning interface and the index of the Physical Receive Queue within that interface.

Syntax

Copy

RTNL2_HPHYSICAL_RX_QUEUE Rtnl2AcquirePhysicalRxQueue(
  [in]    RTNL2_HINTERFACE Interface, 
  [in]    ULONG PhysicalRxQueueIndex,
  [in]    ULONG BufferHeaderStructSize,
  [in]    ULONG Flags
);

Parameters

[in] Interface

A handle to the owning interface obtained from Rtnl2OpenInterface.

[in] PhysicalRxQueueIndex

The index of the Physical Receive Queue to acquire within that interface.

[in] BufferHeaderStructSize

The Size of the RTNL2_BUFFER_HEADER structure.

[in] Flags

A bitwise OR of the optional flags:

Flag	Meaning
RTNL2_PHYSICAL_RX_QUEUE_FLAG_NO_SERIALIZE	Don’t serialize hardware accesses to this Physical Receive Queue. When this flag is set, the Rtnl2SubmitToPhysicalRxQueue and Rtnl2ExtractFromPhysicalRxQueue functions will fail with RTNL2_ERROR_PHYSICAL_TX/RX_QUEUE_CONCURRENT_ACCESS_NOT_ALLOWED if called from multiple threads at the same time. If the flag is not set, the functions mentioned above will block until the other thread is done.

Return Value

If the function succeeds, it returns a handle to the acquired Physical Receive Queue object. If the function fails, it returns NULL. Call GetLastError to obtain an error code if the function fails.

Possible error codes:

Error code	Meaning
ERROR_NOT_READY	The calling process has not called Rtnl2Init.
ERROR_INVALID_PARAMETER	One of the following conditions occurred: The supplied interface handle is invalid. Parameter PhysicalRxQueueIndex doesn't correspond to an enabled queue. The supplied BufferHeaderStructSize value is below the minimum required by the NL2. This error can happen only if the caller doesn’t properly set BufferHeaderStructSize to sizeof(RTNL2_BUFFER_HEADER).
ERROR_RESOURCE_NOT_AVAILABLE	The calling process has already opened too many (>500) Physical Receive Queue handles.
ERROR_ACCESS_DENIED	The target Physical Receive Queue is already acquired or is currently used in the shared mode.
RTNL2_ERROR_INCOMPATIBLE_REQUEST	The supplied Flags parameter is not the result of a bitwise OR operation between a set of the supported flags defined above. This may be due to using a new SDK (that defines new flag values) with an old NL2 (that doesn’t know how to interpret those new flags).
RTNL2_ERROR_NO_MORE_COMMUNICATION	Unable to communicate with the NL2 process. This might be because the NL2 process is not running anymore, or because an application process thread was terminated during a previous call to an NL2 API function.
RTNL2_ERROR_SERIALIZED_COMMAND_TIMEOUT	The NL2 process didn’t reply within an acceptable delay.

Remarks

Once acquired by an NL2 Client process, a Physical Receive Queue object cannot be acquired again, even by that same NL2 Client process, until it gets released by Rtnl2ReleasePhysicalRxQueue. Attempts to acquire the Physical Receive Queue object before it’s released will result in error code ERROR_ACCESS_DENIED.

Characteristics

Real-time
Deterministic	No
Local memory usage
Process	External MSpace usage	Internal MSpace usage
System	No	Yes. This function may create kernel objects, depending on the underlying driver.
NL2 process	For the purpose of flushing the Receive Queue, this function may allocate memory in the external MSpace of the NL2 process, and release it immediately after the flush, depending on the underlying driver.	For the purpose of flushing the Receive Queue, this function may allocate memory for object handles, depending on the underlying driver.
Calling process	Yes. This function may allocate memory for application-specific state structure, depending on the underlying driver.	Yes. This function may allocate memory for object handles, depending on the underlying driver.
Contiguous memory usage
Usage	No

Requirements

Minimum supported version	Header	Library
eRTOS 1.0 SDK	Rtnl2Api.h	Rtnl2Api.lib