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