ISoftUSBEndpoint::DrainOUTQueue Method

Article
09/21/2010

The DrainOUTQueue method drains an endpoint's OUT transaction data queue and returns remaining transfers as a doubly-linked list of SOFTUSB_OUT_TRANSFER structures.

Syntax

HRESULT DrainOUTQueue(
  [in]   ULONG cMaxTransfers,
  [out]  ULONG *pcTransfersRemaining,
  [out]  SOFTUSB_OUT_TRANSFER **ppTransfers
);

Parameters

cMaxTransfers [in]
The number of transfers that DrainOUTQueue should return. If this parameter is 0, DrainOUTQueue returns the number of elements in the queue.

You can specify SOFTUSB_ALL for cMaxTransfers to get the complete contents of the queue.
pcTransfersRemaining [out]
Caller-allocated space to hold the number of transfers that remain in the OUT queue after DrainOUTQueue completes, independent of the value of the cMaxTransfers parameter. That is, the caller can do one of the following:
- Dequeue transfers (up to the number of transfers that cMaxTransfers specifies) and determine the remaining number of transfers.
- Determine the remaining number of transfers.
ppTransfers [out]
A pointer to a doubly-linked list of SOFTUSB_OUT_TRANSFER structures that represent transfers (if cMaxTransfers is greater than 0 and there were transfers in the queue). The caller must free the list by calling ISoftUSBEndpoint::FreeOUTQueue.

DrainOUTQueue will return ppTransfers as NULL if there are no queued transfers.

Return Value

DrainOUTQueue returns S_OK if the operation succeeds.

Remarks

The caller of the DrainOUTQueue method must free the doubly linked list of SOFTUSB_OUT_TRANSFER structures by calling ISoftUSBEndpoint::FreeOUTQueue.

The caller can also call the ISoftUSBEndpoint::PurgeINQueue, ISoftUSBEndpoint::PurgeOUTQueue, ISoftUSBEndpoint::PurgeOUTQueueOlderThan, and ISoftUSBEndpoint::QueueINData methods to manage data queues.

The following C++ code example shows how to read one SOFTUSB_OUT_TRANSFER structure from the endpoint OUT queue.

HRESULT               hr                = S_OK;
ULONG                 ulNoOfQueuedItems = 0; // The number of items that are currently in the queue
ULONG                 ulTransfers       = 1; // Read only one transfer at a time
SOFTUSB_OUT_TRANSFER *pOUTTransfer      = NULL;
BYTE                  bStatus           = 0; // Copied the message status
 

    // Read one data transfer from the out quue
 hr = m_piOUTEndpoint->DrainOUTQueue(ulTransfers, 
        &ulNoOfQueuedItems, 
        &pOUTTransfer);

 if(FAILED(hr))
 goto Exit;

//Process the data read from the quue
 hr = ProcessOutData(pOutTransfer);
 if(FAILED(hr))
  goto Exit;
    // Free the memory that pOUTTransfer uses  
 hr = m_piINEndpoint ->FreeOUTQueue(pOUTTransfer);
 pOUTTransfer = NULL;


Exit:
    // If there was a failurepOUTTransfer will be non-NULL 
    // and needs to be freed
 if (NULL != pOUTTransfer)
    {
        // Free the memory that pOUTTransfer uses
 hr = m_piINEndpoint ->FreeOUTQueue(pOUTTransfer);
 if(FAILED(hr))
 goto Exit;
 pOUTTransfer = NULL;
    }

 return hr;

Requirements

Header

SoftUSBif.h