2.2.4.26 USB_DEVICE_EndpointRead Function

C

USB_DEVICE_RESULT USB_DEVICE_EndpointRead(
    USB_DEVICE_HANDLE usbDeviceHandle, 
    USB_DEVICE_TRANSFER_HANDLE * transferHandle, 
    USB_ENDPOINT_ADDRESS endpoint, 
    void * buffer, 
    size_t bufferSize
);

Summary

This function requests a endpoint data read from the USB Device 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_EVENT_ENDPOINT_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_EVENT_ENDPOINT_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_TRANSFER_HANDLE_INVALID.

If the size parameter is not a multiple of maxPacketSize or is 0, the function returns USB_DEVICE_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 sends less than maxPacketSize data in any transaction, the transfer completes and the function driver will issue a USB_DEVICE_EVENT_ENDPOINT_READ_COMPLETE event along with the USB_DEVICE_EVENT_DATA_ENDPOINT_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.

Precondition

The device should have been configured.

Parameters


Parameters	Description
usbDeviceHandle	USB Device Layer Handle.
transferHandle	Pointer to a USB_DEVICE_TRANSFER_HANDLE type of variable. This variable will contain the transfer handle in case the read request was successful.
endpoint	Endpoint from which the data should be read.
buffer	pointer to the data buffer where read data will be stored.
bufferSize	Size of the data buffer. Refer to the description section for more details on how the size affects the transfer.

Returns

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

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

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

USB_DEVICE_RESULT_ERROR_ENDPOINT_NOT_CONFIGURED - The specified endpoint is not configured yet and is not ready for data transfers.

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

Example

// Shows an example of how to read. This assumes that
// driver was opened successfully. Note how the endpoint 
// is specified. The most significant bit is cleared while
// the lower nibble specifies the endpoint (which is 1).

USB_DEVICE_TRANSFER_HANDLE transferHandle;
USB_DEVICE_RESULT readRequestResult;
USB_DEVICE_HANDLE usbDeviceHandle;
USB_ENDPOINT_ADDRESS endpoint = 0x01;

readRequestResult = USB_DEVICE_EndpointRead(usbDeviceHandle,
                        &transferHandle, endpoint, data, 128);

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

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

Remarks

While the using the device layer with PIC32MZ USB module, the receive buffer provided to the USB_DEVICE_EndpointRead 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)));