openusb_ctrl_xfer, openusb_intr_xfer, openusb_bulk_xfer, openusb_isoc_xfer

OpenUSB Developers Guide
Prev |  | Next

# `openusb_ctrl_xfer, openusb_intr_xfer, openusb_bulk_xfer, openusb_isoc_xfer`

## Name

`openusb_ctrl_xfer, openusb_intr_xfer, openusb_bulk_xfer, openusb_isoc_xfer` -- Issue synchronous Control, Interrupt, Bulk, Isochronous request

## Synopsis

``int32_t openusb_ctrl_xfer`(openusb_dev_handle_t dev, uint8_t ifc, uint8_t ept, openusb_ctrl_request_t *ctrl);`

``int32_t openusb_intr_xfer`(openusb_dev_handle_t dev, uint8_t ifc, uint8_t ept, openusb_intr_request_t *intr);`

``int32_t openusb_bulk_xfer`(openusb_dev_handle_t dev, uint8_t ifc, uint8_t ept, openusb_bulk_request_t *bulk);`

``int32_t openusb_isoc_xfer`(openusb_dev_handle_t dev, uint8_t ifc, uint8_t ept, openusb_isoc_request_t *isoc);`

## Parameters

`dev` - Device handle.

`ifc` - Interface number.

`ept` - Endpoint number.

`ctrl` - Control request set by application.

`intr` - Interrupt request set by application.

`bulk` - Bulk request set by application.

`isoc` - Isochronous request set by application.

## Description

`openusb_ctrl_xfer()` is used to do synchronous USB CONTROL transfers. Application should allocate and fill a openusb_ctrl_request:

            struct openusb_ctrl_request {
        	    struct openusb_ctrl_setup {
        		    uint8_t         bmRequestType;
        		    uint8_t         bRequest;
        		    uint16_t        wValue;
        		    uint16_t        wIndex;

        		    /* wLength set automatically based on length */
        	    } setup;

        	    uint8_t                 *payload;
        	    uint32_t                length; /* platform endian */
        	    uint32_t                timeout;
        	    uint32_t                flags;
        	    openusb_request_result_t result;
        	    struct openusb_ctrl_request      *next;
            }

`openusb_intr_xfer()` is used to do synchronous USB INTERRUPT transfers. Application should allocate and fill a openusb_intr_request:

            struct openusb_intr_request {
            	uint16_t                interval;       /* may not work on some OS */
            	uint8_t                 *payload;
            	uint32_t                length;
            	uint32_t                timeout;
            	uint32_t                flags;
            	openusb_request_result_t result;
            	struct openusb_intr_request      *next;
            }

`openusb_bulk_xfer()` is used to do synchronous USB BULK transfers. Application should allocate and fill a openusb_bulk_request:

            struct openusb_bulk_request {
        	    uint8_t                 *payload;
        	    uint32_t                length;
        	    uint32_t                timeout;
        	    uint32_t                flags;
        	    openusb_request_result_t result;
        	    struct openusb_bulk_request      *next;
            }

`openusb_isoc_xfer()` is used to do synchronous USB ISOCHRONOUS transfers. Application should allocate and fill a openusb_isoc_request:

            typedef struct openusb_isoc_pkts {
        	    uint32_t                num_packets;
        	    struct openusb_isoc_packet {
        		    uint8_t         *payload;
        		    uint32_t        length;
        	    } *packets;
            } openusb_isoc_pkts_t;

            struct openusb_isoc_request {
        	    uint32_t                start_frame;
        	    uint32_t                flags;
        	    openusb_isoc_pkts_t      pkts;

        	    /* pointer to isoc result array */
        	    openusb_request_result_t *isoc_results;

        	    /* overall isoc transfer completion status */
        	    int32_t                 isoc_status;

        	    struct openusb_isoc_request      *next;
            }

For `openusb_ctrl_xfer, openusb_intr_xfer and openusb_bulk_xfer`, the request status is returned in `openusb_request_result`. Application may get transfer status and length of its last request. For `openusb_isoc_xfer()`, every packet in the isoc request has a corresponding `result`, application can check individual packet status from the `isoc_results`. Application must allocate enough number of `isoc_results` for openusb to fill the status.

openusb_request_result_t has the following elements:

        	   int32_t                 status;
        	   uint32_t                transferred_bytes;

## Return Value

`openusb_ctrl_xfer`, `openusb_intr_xfer, openusb_bulk_xfer and openusb_isoc_xfer` () returns 0 on success. Otherwise, a openusb error is returned. NOTE, when there's no error, it just means submission of this request succeed. Even if these functions didn't return failure, the data transfer may still have error and such kind of failure is reflected in in `result` of individual request.

OPENUSB_SUCCESS No errors.

OPENUSB_BADARG `handle` or elements in `handle` is not valid.

OPENUSB_UNKNOWN_DEVICE Device handle `dev` is not valid

OPENUSB_PLATFORM_FAILURE Unspecified kernel/driver failure

OPENUSB_NO_RESOURCES Memory allocation failure

OPENUSB_IO_* USB host controller errors

## See Also

Prev | Home | Next
`openusb_xfer_wait, openusb_xfer_aio` | Up | `openusb_abort`