ISoftUSBEndpoint::QueueINData Method

Article
09/21/2010

The QueueINData method enables the device simulator to queue data for responses to subsequent IN transactions that specify the data and the transaction status.

Syntax

HRESULT QueueINData(
  [in]  BYTE *pbDataBuffer,
  [in]  ULONG cbDataBuffer,
  [in]  BYTE bStatus,
  [in]  ULONG ulTimeToLive
);

Parameters

pbDataBuffer [in]
A byte buffer that contains the data to place in the IN data queue.
cbDataBuffer [in]
The size of the byte buffer to add to the IN data queue.
bStatus [in]
The USB status to return for this transfer.
ulTimeToLive [in]
The time, in milliseconds, that this data should remain in the queue if it is never transferred to the controller. You should specify SOFTUSB_FOREVER for this parameter if the data should remain in the queue until the controller consumes it.

Return Value

QueueINData returns S_OK if the operation succeeds.

Remarks

The endpoint copies the data and keeps it in the queue until the host controller requests the data or the time that the ulTimeToLive specifies passes.

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

The following C++ code example shows how to add data items to the IN queue so that they can be sent to the USB controller in response to an IN data request.

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
BYTE                 *pDataBuffer       = NULL; // Copied the message data
ULONG                 cbDataBuffer      = 0; // Holds the size of the data buffer
 
    // Get the OUT data
 hr = m_piOUTEndpoint->DrainOUTQueue(ulTransfers, 
        &ulNoOfQueuedItems, 
        &pOUTTransfer);
 if(FAILED(hr))
 goto Exit;

 if(0 != ulNoOfQueuedItems)
    {
 // Set up the IN data
  bStatus= pOUTTransfer->bStatus;
  cbDataBuffer = pOUTTransfer->cbData;
  pDataBuffer = &pOUTTransfer->Data[0];
 
 // Send the data to theINqueue
  hr = m_piINEndpoint->QueueINData(pDataBuffer,
  cbDataBuffer,
  bStatus,
 SOFTUSB_FOREVER));
 if (FAILED(hr))
 goto Exit;

 // Free the memory that pOUTTransfer uses  
  hr = m_piINEndpoint ->FreeOUTQueue(pOUTTransfer);
  if(FAILED(hr))
  goto Exit;
  pOUTTransfer = NULL;

}

Exit:
    // If the failed pOUTTransfer 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