USB Libraries Help > USB Device Libraries > USB CDC Device Library > Library Interface > a) Functions > USB_DEVICE_CDC_Read Function
MPLAB Harmony USB Stack
USB_DEVICE_CDC_Read Function

This function requests a data read from the USB Device CDC Function Driver Layer. The function places a requests with driver, the request will get serviced as data is made available by the USB Host. A handle to the request is returned in the transferHandle parameter. The termination of the request is indicated by the USB_DEVICE_CDC_EVENT_READ_COMPLETE event. The amount of data read and the transfer handle associated with the request is returned along with the event in the pData parameter of the event handler. The transfer handle expires when event handler for the USB_DEVICE_CDC_EVENT_READ_COMPLETE exits. If the read request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID

If the size parameter is not a multiple of maxPacketSize or is 0, the function returns USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID in transferHandle and returns an error code as a return value. If the size parameter is a multiple of maxPacketSize and the host send less than maxPacketSize data in any transaction, the transfer completes and the function driver will issue a USB_DEVICE_CDC_EVENT_READ_COMPLETE event along with the USB_DEVICE_CDC_EVENT_READ_COMPLETE_DATA data structure. If the size parameter is a multiple of maxPacketSize and the host sends maxPacketSize amount of data, and total data received does not exceed size, then the function driver will wait for the next packet.

C
USB_DEVICE_CDC_RESULT USB_DEVICE_CDC_Read(
    USB_DEVICE_CDC_INDEX instanceIndex, 
    USB_DEVICE_CDC_TRANSFER_HANDLE * transferHandle, 
    void * data, 
    size_t size
);
Preconditions

The function driver should have been configured.

Parameters
Parameters 
Description 
instance 
USB Device CDC Function Driver instance.
 
transferHandle 
Pointer to a USB_DEVICE_CDC_TRANSFER_HANDLE type of variable. This variable will contain the transfer handle in case the read request was successful.
 
data 
pointer to the data buffer where read data will be stored.
 
size 
Size of the data buffer. Refer to the description section for more details on how the size affects the transfer. 
Returns

USB_DEVICE_CDC_RESULT_OK - The read request was successful. transferHandle contains a valid transfer handle. 

USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The write request could not be added. 

USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_SIZE_INVALID - The specified transfer size was not a multiple of endpoint size or is 0. 

USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet. 

USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application and is invalid.

Remarks

While the using the CDC Function Driver with the PIC32MZ USB module, the receive buffer provided to the USB_DEVICE_CDC_Read function should be placed in coherent memory and aligned at a 16 byte boundary. This can be done by declaring the buffer using the __attribute__((coherent, aligned(16))) attribute. An example is shown here 

 

uint8_t data[256] __attribute__((coherent, aligned(16)));
Example
// Shows an example of how to read. This assumes that
// driver was opened successfully.

USB_DEVICE_CDC_TRANSFER_HANDLE transferHandle;
USB_DEVICE_CDC_RESULT readRequestResult;
USB_DEVICE_CDC_HANDLE instanceHandle;

readRequestResult = USB_DEVICE_CDC_Read(instanceHandle,
                        &transferHandle, data, 128);

if(USB_DEVICE_CDC_RESULT_OK != readRequestResult)
{
    //Do Error handling here
}

// The completion of the read request will be indicated by the 
// USB_DEVICE_CDC_EVENT_READ_COMPLETE event.