2.9.4.2 USB_DEVICE_PRINTER_Read Function

C

USB_DEVICE_PRINTER_RESULT USB_DEVICE_PRINTER_Read(
    USB_DEVICE_PRINTER_INDEX instanceIndex, 
    USB_DEVICE_PRINTER_TRANSFER_HANDLE * transferHandle, 
    void * data, 
    size_t size
);

Description

This function requests a data read from the USB Device PRINTER 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_PRINTER_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_PRINTER_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_PRINTER_TRANSFER_HANDLE_INVALID.

If the size parameter is not a multiple of maxPacketSize or is 0, the function returns USB_DEVICE_PRINTER_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_PRINTER_EVENT_READ_COMPLETE event along with the USB_DEVICE_PRINTER_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.

Precondition

The function driver should have been configured.

Parameters

Returns

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

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

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

USB_DEVICE_PRINTER_RESULT_ERROR_INSTANCE_NOT_CONFIGURED -The specified instance is not configured yet.

USB_DEVICE_PRINTER_RESULT_ERROR_INSTANCE_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.

USB_DEVICE_PRINTER_TRANSFER_HANDLE transferHandle;
USB_DEVICE_PRINTER_RESULT readRequestResult;
USB_DEVICE_PRINTER_HANDLE instanceHandle;

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

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

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

Remarks

While the using the PRINTER Function Driver with the PIC32MZ USB module, the receive buffer provided to the USB_DEVICE_PRINTER_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)));