* USB host API provides direct access to USB devices. Before using it, become
* familiar with USB protocol specification.
* Note, that this API is created for *host* mode USB, i.e. communication with
- * connected devices.
+ * connected devices.\n
*
- * @defgroup CAPI_USB_HOST_INIT_MODULE Library init/cleanup
- * @brief This API is used to initialize and cleanup the library
- * @ingroup CAPI_USB_HOST_MODULE
- * @section CAPI_USB_HOST_INIT_MOUDLE_OVERVIEW Overview
* Before using any of usb_host API functions you must initialize API context.
* Also you must cleanup context after using USB host API.
*
- * @defgroup CAPI_USB_HOST_DEV_MODULE Device handling and enumeration
+ * @section CAPI_USB_HOST_MOUDLE_FEATURES Related Features
+ * This API is related with the following features:
+ * - http://tizen.org/feature/usb.host
+ *
+ * It is recommended to design feature related codes in your application for reliability.\n
+ *
+ * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
+ *
+ * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
+ *
+ * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature List</b>.</a>
+ *
+ *
+ * @defgroup CAPI_USB_HOST_DEV_MODULE USB Host Device
* @brief This API is used to manage USB devices
* @ingroup CAPI_USB_HOST_MODULE
* @section CAPI_USB_HOST_DEV_MOUDLE_OVERVIEW Overview
* Remember to release claimed interfaces after communication and re-attach manually detached
* kernel drivers.
*
+ * @section CAPI_USB_HOST_DEV_MOUDLE_FEATURES Related Features
+ * This API is related with the following features:
+ * - http://tizen.org/feature/usb.host
+ *
+ * It is recommended to design feature related codes in your application for reliability.\n
+ *
+ * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
+ *
+ * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
+ *
+ * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature List</b>.</a>
+ *
* @defgroup CAPI_USB_HOST_CONFIG_MODULE USB Configuration
* @brief USB configuration-related API
* @ingroup CAPI_USB_HOST_MODULE
* @section CAPI_USB_HOST_CONFIG_MODULE_OVERVIEW Overview
* Data structures and operations described here are related to USB configuration.
*
+ * @section CAPI_USB_HOST_CONFIG_MOUDLE_FEATURES Related Features
+ * This API is related with the following features:
+ * - http://tizen.org/feature/usb.host
+ *
+ * It is recommended to design feature related codes in your application for reliability.\n
+ *
+ * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
+ *
+ * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
+ *
+ * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature List</b>.</a>
+ *
* @defgroup CAPI_USB_HOST_INTERFACE_MODULE USB Interface
* @brief USB interface-related API
* @ingroup CAPI_USB_HOST_MODULE
* Data structures and operations described here are related to USB interface.
* Each interface has number of endpoints used for performing transfer operations.
*
+ * @section CAPI_USB_HOST_INTERFACE_MOUDLE_FEATURES Related Features
+ * This API is related with the following features:
+ * - http://tizen.org/feature/usb.host
+ *
+ * It is recommended to design feature related codes in your application for reliability.\n
+ *
+ * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
+ *
+ * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
+ *
+ * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature List</b>.</a>
+ *
* @defgroup CAPI_USB_HOST_ENDPOINT_MODULE USB Endpoint
* @brief USB endpoint-related API
* @ingroup CAPI_USB_HOST_MODULE
* Data structures and operations described here are related to USB endpoint.
* Endpoints are used to perform USB transfers.
*
+ * @section CAPI_USB_HOST_ENDPOINT_MOUDLE_FEATURES Related Features
+ * This API is related with the following features:
+ * - http://tizen.org/feature/usb.host
+ *
+ * It is recommended to design feature related codes in your application for reliability.\n
+ *
+ * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
+ *
+ * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
+ *
+ * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature List</b>.</a>
+ *
* @defgroup CAPI_USB_HOST_SYNCIO_MODULE Synchronous IO
* @brief This API is used to perform synchronous operations
* @ingroup CAPI_USB_HOST_MODULE
* In this example data buffer contains data received from device. Value of transfered
* is set to the number of received bytes.
*
- * @section CAPI_USB_HOST_MOUDLE_RELATED_FEATURES Related Features
+ * @section CAPI_USB_HOST_SYNCIO_MOUDLE_FEATURES Related Features
* This API is related with the following features:
- * - http://tizen.org/feature/USB.host
+ * - http://tizen.org/feature/usb.host
*
* It is recommended to design feature related codes in your application for reliability.\n
*
* To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
*
* More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature List</b>.</a>
+ *
*/
#endif /* __TIZEN_USB_HOST_DOC_H__ */
} usb_host_error_e;
/**
- * @ingroup CAPI_USB_HOST_INIT_MODULE
+ * @ingroup CAPI_USB_HOST_MODULE
* @brief Context handle to USB host.
* @details This structure represents usb_host session.
* Using own session allows to use this API independently.
/* Library initialization and cleanup */
/**
- * @ingroup CAPI_USB_HOST_INIT_MODULE
+ * @ingroup CAPI_USB_HOST_MODULE
* @brief Initializes usb_host context.
* @details This function must be called before any other function from this module.
* @since_tizen 3.0
int usb_host_create(usb_host_context_h *ctx);
/**
- * @ingroup CAPI_USB_HOST_INIT_MODULE
+ * @ingroup CAPI_USB_HOST_MODULE
* @brief Deinitializes usb_host context.
* @details This function must be called after closing all devices
* and before application close. It has to be called to clean
* @ingroup CAPI_USB_HOST_DEV_MODULE
* @brief Gets USB device list.
* @details This function returns list of USB devices attached to system.
- * To free obtained device list usb_host_free_devices() should be used, this
+ * To free obtained device list usb_host_free_device_list() should be used, this
* function can also unref devices. Do not unref device and then open it.
*
* All devices have reference counter. Functions usb_host_ref_device() and
* usb_host_unref_device() are used to ref or unref device. When ref counter
* reaches 0 device will be freed.
* Devices reached by calling usb_host_get_device_list() have a reference count of
- * 1, and usb_host_free_devices() can optionally decrease the reference count
+ * 1, and usb_host_free_device_list() can optionally decrease the reference count
* on all devices in the list. usb_host_device_open() adds another reference which is
* later destroyed by usb_host_device_close().
*
* @since_tizen 3.0
* @remarks @a config must be freed with usb_host_config_destroy().
* @param[in] dev Device
- * @param[in] config_index index of configuration to retrieve
+ * @param[in] config_index index of configuration to retrieve (counting from 0)
* @param[out] config Output location for USB configuration
* @return 0 on success, otherwise a negative error value
* @retval #USB_HOST_ERROR_NONE Successful
* @brief Gets maximum packet size for endpoint 0.
* @since_tizen 3.0
* @param[in] dev A device
- * @param[out] max_packet_size Maximum size of single packet
+ * @param[out] max_packet_size Maximum size of single packet, in bytes
* @return 0 on success, otherwise a negative error value
* @retval #USB_HOST_ERROR_NONE Successful
* @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
* @brief Gets string describing device manufacturer, in ASCII.
* @since_tizen 3.0
* @param[in] dev A handle to opened device
- * @param[in/out] length Data buffer size/how much was actually used
+ * @param[in, out] length Data buffer size/how much was actually used
* @param[out] data Buffer to store string
* @return 0 on success, otherwise a negative error value
* @retval #USB_HOST_ERROR_NONE Successful
* @brief Gets product string of device, in ASCII.
* @since_tizen 3.0
* @param[in] dev A handle to opened device
- * @param[in/out] length Data buffer size/how much was actually used
+ * @param[in, out] length Data buffer size/how much was actually used
* @param[out] data Buffer to store string
* @return 0 on success, otherwise a negative error value
* @retval #USB_HOST_ERROR_NONE Successful
* @brief Gets serial number of a device, in ASCII.
* @since_tizen 3.0
* @param[in] dev A handle to opened device
- * @param[in/out] length Data buffer size/how much was actually used
+ * @param[in, out] length Data buffer size/how much was actually used
* @param[out] data Buffer to store string
* @return 0 on success, otherwise a negative error value
* @retval #USB_HOST_ERROR_NONE Successful
* @since_tizen 3.0
* @param[in] dev An opened device
* @param[in] desc_index Index of descriptor to retrieve
- * @param[in/out] length Data buffer size/how much was actually used
+ * @param[in, out] length Data buffer size/how much was actually used
* @param[out] data Out buffer for ASCII string descriptor
* @return 0 on success, otherwise a negative error value
* @retval #USB_HOST_ERROR_NONE Successful
* @brief Gets string describing a configuration.
* @since_tizen 3.0
* @param[in] config A configuration
- * @param[in/out] length Data buffer size/how much was actually used
+ * @param[in, out] length Data buffer size/how much was actually used
* @param[out] data Buffer to store string
* @return 0 on success, otherwise a negative error value
* @retval #USB_HOST_ERROR_NONE Successful
* @details Gets a USB interface from configuration by its index.
* @since_tizen 3.0
* @param[in] config Configuration handle
- * @param[in] interface_index index of interface to retrieve
+ * @param[in] interface_index index of interface to retrieve (counting from 0)
* @param[out] interface Interface handle
* @remarks There is no need to destroy the @a interface handle. It is no longer valid
* when config is destroyed.
* @details Get a USB endpoint from interface by its index.
* @since_tizen 3.0
* @param[in] interface Interface handle
- * @param[in] config_index index of endpoint to retrieve
+ * @param[in] config_index index of endpoint to retrieve (counting from 0)
* @param[out] ep Endpoint handle
* @remarks @a ep handle is no longer valid when config will be destroyed. There is no need to destroy it,
* it is done automatically when the configuration is destroyed.
* @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
* @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
*/
-int usb_host_endpoint_get_direction(usb_host_endpoint_h ep, int *direction);
+int usb_host_endpoint_get_direction(usb_host_endpoint_h ep, usb_host_endpoint_direction_e *direction);
/**
* @ingroup CAPI_USB_HOST_ENDPOINT_MODULE
* @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
* @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
*/
-int usb_host_endpoint_get_transfer_type(usb_host_endpoint_h ep, int *transfer_type);
+int usb_host_endpoint_get_transfer_type(usb_host_endpoint_h ep, usb_host_transfer_type_e *transfer_type);
/**
* @ingroup CAPI_USB_HOST_ENDPOINT_MODULE
* @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
* @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
*/
-int usb_host_endpoint_get_synch_type(usb_host_endpoint_h ep, int *synch_type);
+int usb_host_endpoint_get_synch_type(usb_host_endpoint_h ep, usb_host_iso_sync_type_e *synch_type);
/**
* @ingroup CAPI_USB_HOST_ENDPOINT_MODULE
* @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
* @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
*/
-int usb_host_endpoint_get_usage_type(usb_host_endpoint_h ep, int *usage_type);
+int usb_host_endpoint_get_usage_type(usb_host_endpoint_h ep, usb_host_usage_type_e *usage_type);
/**
* @ingroup CAPI_USB_HOST_ENDPOINT_MODULE
* @brief Gets max packet size of given endpoint.
* @since_tizen 3.0
* @param[in] ep An endpoint
- * @param[out] max_packet_size Max packet size
+ * @param[out] max_packet_size Max packet size, in bytes
* @return 0 on success, otherwise a negative error value
* @retval #USB_HOST_ERROR_NONE Successful
* @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
* @brief Gets interval for polling endpoint for data transfers.
* @since_tizen 3.0
* @param[in] ep An endpoint
- * @param[out] interval Interval for polling
+ * @param[out] interval Interval for polling, in frame counts (refer to USB protocol specification)
* @return 0 on success, otherwise a negative error value
* @retval #USB_HOST_ERROR_NONE Successful
* @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
/**
* @ingroup CAPI_USB_HOST_SYNCIO_MODULE
* @brief Performs USB control transfer.
+ * @details For more explanation about the values please refer to USB protocol specification
* @since_tizen 3.0
* @remarks The wValue, wIndex and wLength fields values should be given in host-endian
* byte order.
* be at least this size
* @param[in] timeout Timeout (in milliseconds) that this function should wait
* before giving up due to no response being received. For an unlimited
+ * @param[out] transferred Number of transferred bytes
* timeout, 0 value should be used.
* @return 0 on success, negative error code otherwise
* @retval #USB_HOST_ERROR_NONE Successful
*/
int usb_host_control_transfer(usb_host_device_h dev,
uint8_t bm_request_type, uint8_t b_request, uint16_t w_value, uint16_t w_index,
- unsigned char *data, uint16_t w_length, unsigned int timeout, int *transfered);
+ unsigned char *data, uint16_t w_length, unsigned int timeout, int *transferred);
/**
* @ingroup CAPI_USB_HOST_SYNCIO_MODULE
* (depending on endpoint)
* @param[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
- * @param[out] transferred Output location for the number of bytes actually
- * transferred
+ * @param[out] transferred number of bytes actually transferred
* @param[in] timeout Timeout (in milliseconds) that this function should wait
* before giving up due to no response being received (for an unlimited
* timeout 0 value should be used)
projects / platform / core / api / usb-host.git / commitdiff