This API is used to perform asynchronous operations.
Overview
Asynchronous transfers are performed by submitting previously prepared transfer handle (usb_host_transfer_h). When the transfer is finished, the callback set by user is called. Transfer handle contains all transfer parameters and, when configured, can be submitted multiple times. Most of parameters required for asynchronous transfers match those from synchronous transfer.
Like in synchronous transfer, you must first obtain the endpoint handle. Then you can create a transfer handle with desired parameters.
The transfer_callback() is a function which will be called when transfer is finished. It should match the usb_host_transfer_cb() type, e.g.:
void transfer_callback(usb_host_transfer_h transfer, void user_data)
{
int status;
int length;
char *data;
usb_host_get_transfer_status(transfer, &status);
if (status != USB_HOST_TRANSFER_COMPLETED) {
}
usb_host_get_data(transfer, &data, &length);
}
Note, that not always successfully submitted transfer finishes with success. The callback function is called with status code set to value from usb_host_transfer_status_e enum. It informs what happened with the transfer.
Also remember, that received data length can be different than length of buffer (i.e. requested length).
You can change the transfer handle parameters by using usb_host_transfer_set_* functions and resubmit the transfer multiple times.
For passing additional data to callback function user_data pointer can be used. The user_data passed to callback is the same as was set for submitted transfer.
After transfer is submitted, it can be canceled by calling usb_host_transfer_cancel(). This will cause the transfer callback function to be called with USB_HOST_TRANSFER_CANCELLED status.
Isochronous transfers
For creating isochronous transfers use usb_host_create_isochronous_transfer() function. It takes parameters similar to usb_host_create_transfer(), with addition of num_iso_packets. The data buffer is used to store all packets data and should be large enough to do so.
Before submitting the transfer you must setup isochronous packets lengths (and data, if making out transfer).
for (i = 0; i < num_iso_packets; ++i) {
ret = usb_host_set_iso_packet_length(transfer, i, packet_lenght);
ret = usb_host_get_iso_packet_data(transfer, i, &data, &len);
}
Similarly, you can obtain received data in callback function by calling usb_host_transfer_get_iso_packet_data(). Note, that length of received data can be different than length of buffer space set for an isochronous packet.
Each packet has its own status code. Check them by calling usb_host_transfer_get_iso_packet_status().
Control transfers
You can make asynchronous control transfers as well. They use the same data type as other asynchronous transfers (usb_host_transfer_h) and can be handled in similar way.
A control transfer need specific format of data in buffer, i.e. first 8 bytes of buffer need to contain a setup packet. You can find more informations about setup packets in usb protocol specification. This API provides functions helping with filling the setup packet.
ret = usb_host_create_control_transfer(dev, transfer_callback, data, length, user_data, timeout, &transfer);
if (ret < 0)
error();
usb_host_control_transfer_set_request_type(transfer, bm_request_type);
usb_host_control_transfer_set_request(transfer, b_request);
usb_host_control_transfer_set_value(transfer, w_value);
usb_host_control_transfer_set_index(transfer, w_index);
ret = usb_host_transfer_submit(transfer);
if (ret < 0)
error();
ret = usb_host_transfer_destroy(transfer);
When receiving data from control transfer, remember that first 8 bytes of buffer are filled with setup packet. To obtain pointer to actual data, use usb_host_control_transfer_get_data().
Functions |
int | usb_host_create_transfer (usb_host_endpoint_h ep, usb_host_transferred_cb callback, unsigned char *data, int length, void *user_data, unsigned int timeout, usb_host_transfer_h *transfer) |
| Prepares an asynchronous USB transfer.
|
int | usb_host_create_isochronous_transfer (usb_host_endpoint_h ep, usb_host_transferred_cb callback, unsigned char *data, int length, unsigned int num_iso_packets, void *user_data, unsigned int timeout, usb_host_transfer_h *transfer) |
| Prepares an asynchronous USB isochronous transfer.
|
int | usb_host_create_control_transfer (usb_host_device_h dev, usb_host_transferred_cb callback, unsigned char *data, int length, void *user_data, unsigned int timeout, usb_host_transfer_h *transfer) |
| Prepares an asynchronous USB control transfer.
|
int | usb_host_transfer_set_ep (usb_host_transfer_h transfer, usb_host_endpoint_h ep) |
| Sets an endpoint for asynchronous transfer.
|
int | usb_host_transfer_set_callback (usb_host_transfer_h transfer, usb_host_transferred_cb callback) |
| Sets a callback for asynchronous transfer.
|
int | usb_host_transfer_set_data (usb_host_transfer_h transfer, unsigned char *data, int length) |
| Sets data buffer for asynchronous transfer.
|
int | usb_host_transfer_set_timeout (usb_host_transfer_h transfer, unsigned int timeout) |
| Sets timeout for asynchronous transfer.
|
int | usb_host_transfer_set_num_iso_packets (usb_host_transfer_h transfer, unsigned int num_iso_packets) |
| Sets number of isochronous packet for isochronous transfer.
|
int | usb_host_control_transfer_set_request_type (usb_host_transfer_h transfer, uint8_t bm_request_type) |
| Sets request type for control transfer setup packet.
|
int | usb_host_control_transfer_set_request (usb_host_transfer_h transfer, uint8_t b_request) |
| Sets request field for control transfer setup packet.
|
int | usb_host_control_transfer_set_value (usb_host_transfer_h transfer, uint16_t w_value) |
| Sets w_value field for control transfer setup packet.
|
int | usb_host_control_transfer_set_index (usb_host_transfer_h transfer, uint16_t w_index) |
| Sets w_index field for control transfer setup packet.
|
int | usb_host_transfer_get_status (usb_host_transfer_h transfer, int *status) |
| Gets the transfer status.
|
int | usb_host_transfer_get_data (usb_host_transfer_h transfer, unsigned char **data, unsigned int *actual_length) |
| Gets the transfer data.
|
int | usb_host_control_transfer_get_data (usb_host_transfer_h transfer, unsigned char **data, unsigned int *actual_length) |
| Gets the *control* transfer data.
|
int | usb_host_transfer_get_length (usb_host_transfer_h transfer, unsigned int *length) |
| Gets length of data buffer.
|
int | usb_host_transfer_get_num_iso_packets (usb_host_transfer_h transfer, unsigned int *num_iso_packets) |
| Gets number of isochronous packets for this transfer.
|
int | usb_host_transfer_set_iso_packet_length (usb_host_transfer_h transfer, unsigned int packet_number, int length) |
| Sets an isochronous packet length.
|
int | usb_host_transfer_get_iso_packet_status (usb_host_transfer_h transfer, unsigned int packet_number, int *status) |
| Gets an isochronous packet status.
|
int | usb_host_transfer_get_iso_packet_data (usb_host_transfer_h transfer, unsigned int packet_number, unsigned char **data, int *actual_length) |
| Gets data buffer of isochronous packet.
|
int | usb_host_transfer_get_iso_packet_length (usb_host_transfer_h transfer, unsigned int packet_number, int *length) |
| Gets isochronous packet data buffer length.
|
int | usb_host_transfer_destroy (usb_host_transfer_h transfer) |
| Destroys an asynchronous transfer structure.
|
int | usb_host_transfer_submit (usb_host_transfer_h transfer) |
| Submits an asynchronous USB transfer.
|
int | usb_host_transfer_cancel (usb_host_transfer_h transfer) |
| Cancels an asynchronous USB transfer.
|
Typedefs |
typedef struct
usb_host_transfer_s * | usb_host_transfer_h |
| USB asynchronous transfer handle.
|
typedef void(* | usb_host_transferred_cb )(usb_host_transfer_h transfer, void *user_data) |
| Called when asynchronous transfers finishes.
|
Typedef Documentation
USB asynchronous transfer handle.
This type represents an asynchronous USB transfer.
- Since :
- 5.0
Called when asynchronous transfers finishes.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer for which this callback was set |
[in] | user_data | User data pointer passed on callback registration |
Enumeration Type Documentation
Enumeration of transfer status codes.
- Since :
- 5.0
- Enumerator:
USB_HOST_TRANSFER_COMPLETED |
Transfer completed without error
|
USB_HOST_TRANSFER_ERROR |
Transfer failed
|
USB_HOST_TRANSFER_TIMED_OUT |
Transfer timed out
|
USB_HOST_TRANSFER_CANCELLED |
Transfer cancelled
|
USB_HOST_TRANSFER_STALL |
Halt condition detected
|
USB_HOST_TRANSFER_NO_DEVICE |
Device was disconnected
|
USB_HOST_TRANSFER_OVERFLOW |
Device sent more data than requested
|
USB_HOST_TRANSFER_UNKNOWN |
Unknown status
|
Function Documentation
Gets the *control* transfer data.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Control transfer handle |
[out] | data | Data buffer of this transfer |
[out] | actual_length | Actual length of transferred data |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Sets w_index field for control transfer setup packet.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | A transfer handle |
[in] | w_index | wIndex field for the setup packet |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- transfer should be created by usb_host_create_control_transfer().
Sets request field for control transfer setup packet.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | A transfer handle |
[in] | b_request | bRequest field for the setup packet |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- transfer should be created by usb_host_create_control_transfer().
Sets request type for control transfer setup packet.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | A transfer handle |
[in] | bm_request_type | bmRequestType type field for the setup packet |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- transfer should be created by usb_host_create_control_transfer().
Sets w_value field for control transfer setup packet.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | A transfer handle |
[in] | w_value | wValue field for the setup packet |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- transfer should be created by usb_host_create_control_transfer().
Prepares an asynchronous USB control transfer.
This function prepares control transfer handle. Transfer handle can be used for multiple transfers after this initialization. Note, that first 8 bytes of data buffer are interpreted as control setup packet. You may use usb_host_control_transfer_set_* functions to set the setup packet fields.
- Since :
- 5.0
- Parameters:
-
[in] | dev | Device handle |
[in] | callback | Callback to be called when transfer is finished |
[in] | data | Suitably-sized data buffer |
[in] | length | For writes, the number of bytes from data to be sent, for reads, the maximum number of bytes to receive into the data buffer |
[in] | user_data | Pointer to data which will be passed to callback function later on |
[in] | timeout | Timeout (in milliseconds) that transfer should wait before giving up due to no response being received (for an unlimited timeout use value of 0) |
[out] | transfer | Transfer handle |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- dev must be an opened device handle
- Postcondition:
- transfer should be destroyed by calling usb_host_transfer_destroy() when it's no longer needed.
Prepares an asynchronous USB isochronous transfer.
This function prepares transfer handle for asynchronous communication. Usage is similar to usb_host_create_transfer(), except this function is intended for isochronous endpoints. Transfer handle can be used for multiple transfers after this initialization. Note however, that this function needs to allocate memory for num_iso_packets isochronous packets and it will be the limit for number of them in this transfer.
- Since :
- 5.0
- Parameters:
-
[in] | ep | Endpoint handle |
[in] | callback | Callback to be called when transfer is finished |
[in] | data | Suitably-sized data buffer, similar to synchronized transfer |
[in] | length | For writes, the number of bytes from data to be sent; for reads, the maximum number of bytes to receive into the data buffer |
[in] | num_iso_packets | Number of isochronous packets |
[in] | user_data | Pointer to data which will be passed to callback function later on |
[in] | timeout | Timeout (in milliseconds) that transfer should wait before giving up due to no response being received (for an unlimited timeout use value of 0) |
[out] | transfer | Transfer handle |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- ep must be a valid endpoint received from usb_host_interface_get_endpoint().
- Postcondition:
- transfer should be destroyed by calling usb_host_transfer_destroy() when it's no longer needed.
Prepares an asynchronous USB transfer.
This function prepares transfer handle for asynchronous communication. Transfer handle can be used for multiple transfers after this initialization.
- Since :
- 5.0
- Parameters:
-
[in] | ep | Endpoint handle |
[in] | callback | Callback to be called when transfer is finished |
[in] | data | Suitably-sized data buffer, similar to synchronized transfer |
[in] | length | For writes, the number of bytes from data to be sent; for reads, the maximum number of bytes to receive into the data buffer |
[in] | user_data | Pointer to data which will be passed to callback function later on |
[in] | timeout | Timeout (in milliseconds) that transfer should wait before giving up due to no response being received (for an unlimited timeout use value of 0) |
[out] | transfer | Transfer handle |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- ep must be a valid endpoint received from usb_host_interface_get_endpoint().
- Postcondition:
- transfer should be destroyed by calling usb_host_transfer_destroy() when it's no longer needed.
Cancels an asynchronous USB transfer.
After calling this function the transfer will be cancelled, if only it was not finished already. The transfer callback will be called with USB_HOST_TRANSFER_CANCELLED status.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle to be cancelled |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Destroys an asynchronous transfer structure.
When no longer needed, transfer should be destroyed by this function. It frees memory allocated for the transfer. You cannot destroy unfinished transfer, wait for its completion or cancel it.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle to be destroyed |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Gets the transfer data.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle |
[out] | data | Data buffer of this transfer |
[out] | actual_length | Actual length of transferred data |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Gets data buffer of isochronous packet.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle |
[in] | packet_number | Number of isochronous packet |
[out] | data | Data buffer for this packet |
[out] | actual_length | Length of transferred data |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Gets isochronous packet data buffer length.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle |
[in] | packet_number | Number of isochronous packet |
[out] | length | Length of data buffer |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Gets an isochronous packet status.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle |
[in] | packet_number | Number of isochronous packet |
[out] | status | Status of selected packet |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Gets length of data buffer.
This functions gets length that was set for data buffer, not the actual transferred data length. For length of transferred data see usb_host_transfer_get_data().
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle |
[out] | length | Length of data buffer for this transfer |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Gets number of isochronous packets for this transfer.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle |
[out] | num_iso_packets | Number of isochronous packets |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Gets the transfer status.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle |
[out] | status | Status of this transfer |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Sets a callback for asynchronous transfer.
This function changes the callback to be called on transfer completion.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | A transfer handle |
[in] | callback | A callback function |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- transfer should be created by usb_host_create_transfer() or usb_host_create_isochronous_transfer().
Sets data buffer for asynchronous transfer.
This function changes the data buffer used for this transfer.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | A transfer handle |
[in] | data | A data buffer |
[in] | length | Length of data buffer |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- transfer should be created by usb_host_create_transfer() or usb_host_create_isochronous_transfer().
Sets an endpoint for asynchronous transfer.
This function changes the endpoint on which given transfer is performed. Next submissions will be performed on this endpoint.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | A transfer handle |
[in] | ep | An endpoint handle |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- transfer should be created by usb_host_create_transfer() or usb_host_create_isochronous_transfer().
Sets an isochronous packet length.
This function sets length of individual packet.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | Transfer handle |
[in] | packet_number | Number of isochronous packet |
[in] | length | Length of the packet handle |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
Sets number of isochronous packet for isochronous transfer.
This function changes the number of isochronous packets in transfer. This parameter affects only isochronous transfers (i.e. transfers on isochronous endpoints). Use usb_host_endpoint_get_transfer_type() for checking types of your endpoints.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | A transfer handle |
[in] | num_iso_packets | Number of isochronous packets in this transfer |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- transfer should be created by usb_host_create_transfer() or usb_host_create_isochronous_transfer().
Sets timeout for asynchronous transfer.
This function changes the timeout after which transfer will be stopped due to no response being received.
- Since :
- 5.0
- Parameters:
-
[in] | transfer | A transfer handle |
[in] | timeout | A timeout in milliseconds |
- Returns:
- 0 on success, negative error code on error
- Return values:
-
- Precondition:
- transfer should be created by usb_host_create_transfer() or usb_host_create_isochronous_transfer().