RtndAttachRxQueue

RtndAttachRxQueue attaches the specified Receive Queue to the current application process.

Syntax

BOOL RtndAttachRxQueue(
  [in]    ULONG_PTR RtndInterfaceId,
  [in]    ULONG RxQueueIndex,
  [out]   VOID **ppRxQueueAppContext
);

Parameters

[in] RtndInterfaceId

The number or pointer used to identify the interface. This value is returned by RtndManageInterface.

[in] RxQueueIndex

The index of the Receive Queue.

[out] ppRxQueueAppContext

The address of a context structure allocated by the driver for the calling process.

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. To get extended error information, call GetLastError.

Common error codes:

Note: Custom drivers may return other error codes not listed above.

Remarks

This function may be called from any process.

This function allows the driver to allocate resources specifically needed for the calling process before it calls RtndSubmitRxBuffer, RtndApplyRxBuffers, and RtndExtractRxBuffer for the Receive Queue. If there is no specific requirement, the driver should set ppRxQueueAppContext to NULL and return. Otherwise, it should allocate memory for a context structure, open all needed handles to kernel objects, store the handle values in the context, and set ppRxQueueAppContext to the address of that context.

In all subsequent calls to RtndSubmitRxBuffer, RtndApplyRxBuffers, and RtndExtractRxBuffer, the NL2 will supply as a parameter the address of the context that was allocated by the driver here, for the specific calling process.

The driver must NOT access a register of the NIC in this function and must make sure that if the calling process is terminated, all the resources allocated here are released by the kernel as if the calling process had called RtndDetachRxQueue. This is the case for all memory allocated with RtAllocateLocalMemory and all open handles to kernel objects – mutexes, events, etc.

The driver must anticipate that this function may be called at the same time as, or even after, RtndShutdownInterface. However, it will never be called at the same time or after RtndStopInterface and RtndUnmanageInterface.

Characteristics

Requirements

See Also:

• RtndApplyRxBuffers
• RtndDetachRxQueue
• RtndExtractRxBuffer
• RtndManageInterface
• RtndSubmitRxBuffer