From: Paweł Szewczyk Date: Tue, 6 Sep 2016 16:33:10 +0000 (+0200) Subject: api: Fix documentation and spelling X-Git-Tag: submit/tizen/20160913.011724~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=63cae7ad40b2ab4dcaeedc16c18f53a500f42e46;p=platform%2Fcore%2Fapi%2Fusb-host.git api: Fix documentation and spelling Change-Id: I9402bb3d6c43874b32621e84920d3a50400a0a67 Signed-off-by: Paweł Szewczyk --- diff --git a/doc/usb_host_doc.h b/doc/usb_host_doc.h index 62a426f..4bd9288 100644 --- a/doc/usb_host_doc.h +++ b/doc/usb_host_doc.h @@ -29,16 +29,25 @@ * 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 Feature List. + * + * + * @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 @@ -110,12 +119,36 @@ * 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 Feature List. + * * @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 Feature List. + * * @defgroup CAPI_USB_HOST_INTERFACE_MODULE USB Interface * @brief USB interface-related API * @ingroup CAPI_USB_HOST_MODULE @@ -123,6 +156,18 @@ * 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 Feature List. + * * @defgroup CAPI_USB_HOST_ENDPOINT_MODULE USB Endpoint * @brief USB endpoint-related API * @ingroup CAPI_USB_HOST_MODULE @@ -130,6 +175,18 @@ * 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 Feature List. + * * @defgroup CAPI_USB_HOST_SYNCIO_MODULE Synchronous IO * @brief This API is used to perform synchronous operations * @ingroup CAPI_USB_HOST_MODULE @@ -157,9 +214,9 @@ * 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 * @@ -168,6 +225,7 @@ * 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 Feature List. + * */ #endif /* __TIZEN_USB_HOST_DOC_H__ */ diff --git a/include/usb_host.h b/include/usb_host.h index aa1488b..55c489c 100644 --- a/include/usb_host.h +++ b/include/usb_host.h @@ -98,7 +98,7 @@ typedef enum { } 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. @@ -157,7 +157,7 @@ typedef struct usb_host_endpoint_s *usb_host_endpoint_h; /* 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 @@ -172,7 +172,7 @@ typedef struct usb_host_endpoint_s *usb_host_endpoint_h; 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 @@ -192,14 +192,14 @@ int usb_host_destroy(usb_host_context_h ctx); * @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(). * @@ -365,7 +365,7 @@ int usb_host_device_get_port_numbers(usb_host_device_h dev, int *port_numbers, i * @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 @@ -473,7 +473,7 @@ int usb_host_device_get_protocol(usb_host_device_h dev, int *protocol); * @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 @@ -551,7 +551,7 @@ int usb_host_is_device_opened(usb_host_device_h dev, bool *is_opened); * @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 @@ -568,7 +568,7 @@ int usb_host_device_get_manufacturer_str(usb_host_device_h dev, int *length, uns * @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 @@ -585,7 +585,7 @@ int usb_host_device_get_product_str(usb_host_device_h dev, int *length, unsigned * @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 @@ -604,7 +604,7 @@ int usb_host_device_get_serial_number_str(usb_host_device_h dev, int *length, un * @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 @@ -676,7 +676,7 @@ int usb_host_config_get_max_power(usb_host_config_h config, int *max_power); * @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 @@ -695,7 +695,7 @@ int usb_host_device_get_config_str(usb_host_config_h config, int *length, unsign * @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. @@ -793,7 +793,7 @@ int usb_host_interface_get_num_endpoints(usb_host_interface_h interface, int *nu * @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. @@ -858,7 +858,7 @@ int usb_host_endpoint_get_number(usb_host_endpoint_h ep, int *number); * @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 @@ -871,7 +871,7 @@ int usb_host_endpoint_get_direction(usb_host_endpoint_h ep, int *direction); * @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 @@ -884,7 +884,7 @@ int usb_host_endpoint_get_transfer_type(usb_host_endpoint_h ep, int *transfer_ty * @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 @@ -897,14 +897,14 @@ int usb_host_endpoint_get_synch_type(usb_host_endpoint_h ep, int *synch_type); * @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 @@ -916,7 +916,7 @@ int usb_host_endpoint_get_max_packet_size(usb_host_endpoint_h ep, int *max_packe * @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 @@ -928,6 +928,7 @@ int usb_host_endpoint_get_interval(usb_host_endpoint_h ep, int *interval); /** * @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. @@ -942,6 +943,7 @@ int usb_host_endpoint_get_interval(usb_host_endpoint_h ep, int *interval); * 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 @@ -956,7 +958,7 @@ int usb_host_endpoint_get_interval(usb_host_endpoint_h ep, int *interval); */ 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 @@ -969,8 +971,7 @@ int usb_host_control_transfer(usb_host_device_h dev, * (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) diff --git a/src/usb_host.c b/src/usb_host.c index 23ead0b..b74c828 100644 --- a/src/usb_host.c +++ b/src/usb_host.c @@ -1179,7 +1179,7 @@ int usb_host_endpoint_get_number(usb_host_endpoint_h ep, int *number) return USB_HOST_ERROR_NONE; } -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) { if (!usb_host_feature_enabled()) return USB_HOST_ERROR_NOT_SUPPORTED; @@ -1194,7 +1194,7 @@ int usb_host_endpoint_get_direction(usb_host_endpoint_h ep, int* direction) return USB_HOST_ERROR_NONE; } -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) { if (!usb_host_feature_enabled()) return USB_HOST_ERROR_NOT_SUPPORTED; @@ -1225,7 +1225,7 @@ int usb_host_endpoint_get_transfer_type(usb_host_endpoint_h ep, int *transfer_ty return USB_HOST_ERROR_NONE; } -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) { if (!usb_host_feature_enabled()) return USB_HOST_ERROR_NOT_SUPPORTED; @@ -1256,7 +1256,7 @@ int usb_host_endpoint_get_synch_type(usb_host_endpoint_h ep, int *synch_type) return USB_HOST_ERROR_NONE; } -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) { if (!usb_host_feature_enabled()) return USB_HOST_ERROR_NOT_SUPPORTED;