From 6b91f2f077f9b4ed493b1bacae577eff595b2e3c Mon Sep 17 00:00:00 2001 From: Kichan Kwon Date: Thu, 16 Feb 2017 16:43:55 +0900 Subject: [PATCH] Proofread header file Change-Id: I4422a9601b3c45d5d23670198bc22d073c605154 Signed-off-by: Kichan Kwon --- include/storage-expand.h | 222 +++++++++++++++++++---------------------------- include/storage.h | 28 +++--- 2 files changed, 102 insertions(+), 148 deletions(-) diff --git a/include/storage-expand.h b/include/storage-expand.h index bd134ac..48c26b8 100644 --- a/include/storage-expand.h +++ b/include/storage-expand.h @@ -31,21 +31,22 @@ extern "C" { #include + /** - * @brief Enumeration of error codes for Storage. + * @brief Enumeration for Storage of error codes. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { - STORAGE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ - STORAGE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - STORAGE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ - STORAGE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NO_SUCH_DEVICE, /**< Storage not supported */ + STORAGE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ + STORAGE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ + STORAGE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ + STORAGE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NO_SUCH_DEVICE, /**< Storage not supported */ STORAGE_ERROR_OPERATION_FAILED = TIZEN_ERROR_SYSTEM_CLASS | 0x12, /**< Operation failed */ } storage_error_e; /** - * @brief Enumeration of the storage types. + * @brief Enumeration for the storage types. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { @@ -55,7 +56,7 @@ typedef enum { /** - * @brief Enumeration of the state of storage devices. + * @brief Enumeration for storage devices state. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { @@ -65,228 +66,197 @@ typedef enum { STORAGE_STATE_MOUNTED_READ_ONLY = 1, /**< Storage is present and mounted with read only access */ } storage_state_e; + /** * @brief Called to get information once for each supported storage. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[in] storage_id The unique storage ID * @param[in] type The type of the storage * @param[in] state The current state of the storage * @param[in] path The absolute path to the root directory of the storage * @param[in] user_data The user data passed from the foreach function - * * @return @c true to continue with the next iteration of the loop, \n * otherwise @c false to break out of the loop - * * @pre storage_foreach_device_supported() will invoke this callback function. * @see storage_foreach_device_supported() */ typedef bool (*storage_device_supported_cb)(int storage_id, storage_type_e type, storage_state_e state, const char *path, void *user_data); + /** - * @brief Retrieves all storage in a device. + * @brief Retrieves all the storage in a device. * @details This function invokes the callback function once for each storage in a device. \n * If storage_device_supported_cb() returns @c false, then the iteration will be finished. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[in] callback The iteration callback function * @param[in] user_data The user data to be passed to the callback function - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter * @post This function invokes storage_device_supported_cb() repeatedly for each supported device. * @see storage_device_supported_cb() */ int storage_foreach_device_supported(storage_device_supported_cb callback, void *user_data); + /** * @brief Gets the absolute path to the root directory of the given storage. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @remarks Files saved on the internal/external storage are readable or writable by all applications.\n - * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n - * If you want to access files or directories in internal storage, you must declare http://tizen.org/privilege/mediastorage.\n - * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n - * You must release @a path using free(). - * + * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n + * If you want to access files or directories in internal storage, you must declare http://tizen.org/privilege/mediastorage.\n + * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n + * You must release @a path using free(). * @param[in] storage_id The storage device * @param[out] path The absolute path to the storage directory - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported - * + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported * @see storage_get_state() */ int storage_get_root_directory(int storage_id, char **path); + /** - * @brief Enumeration of the storage directory types + * @brief Enumeration for the storage directory types. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { - STORAGE_DIRECTORY_IMAGES, /**< Image directory */ - STORAGE_DIRECTORY_SOUNDS, /**< Sounds directory */ - STORAGE_DIRECTORY_VIDEOS, /**< Videos directory */ - STORAGE_DIRECTORY_CAMERA, /**< Camera directory */ - STORAGE_DIRECTORY_DOWNLOADS, /**< Downloads directory */ - STORAGE_DIRECTORY_MUSIC, /**< Music directory */ - STORAGE_DIRECTORY_DOCUMENTS, /**< Documents directory */ - STORAGE_DIRECTORY_OTHERS, /**< Others directory */ + STORAGE_DIRECTORY_IMAGES, /**< Image directory */ + STORAGE_DIRECTORY_SOUNDS, /**< Sounds directory */ + STORAGE_DIRECTORY_VIDEOS, /**< Videos directory */ + STORAGE_DIRECTORY_CAMERA, /**< Camera directory */ + STORAGE_DIRECTORY_DOWNLOADS, /**< Downloads directory */ + STORAGE_DIRECTORY_MUSIC, /**< Music directory */ + STORAGE_DIRECTORY_DOCUMENTS, /**< Documents directory */ + STORAGE_DIRECTORY_OTHERS, /**< Others directory */ STORAGE_DIRECTORY_SYSTEM_RINGTONES, /**< System ringtones directory. Only available for internal storage. */ STORAGE_DIRECTORY_MAX } storage_directory_e; + /** * @brief Gets the absolute path to the each directory of the given storage. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @remarks Files saved on the internal/external storage are readable or writable by all applications.\n - * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n - * The directory path may not exist, so you must make sure that it exists before using it.\n - * If you want to access files or directories in internal storage except #STORAGE_DIRECTORY_SYSTEM_RINGTONES, you must declare http://tizen.org/privilege/mediastorage.\n - * If you want to access files or directories in #STORAGE_DIRECTORY_SYSTEM_RINGTONES, you must declare %http://tizen.org/privilege/systemsettings.\n - * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n - * You must release @a path using free(). - * + * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n + * The directory path may not exist, so you must make sure that it exists before using it.\n + * If you want to access files or directories in internal storage except #STORAGE_DIRECTORY_SYSTEM_RINGTONES, you must declare http://tizen.org/privilege/mediastorage.\n + * If you want to access files or directories in #STORAGE_DIRECTORY_SYSTEM_RINGTONES, you must declare %http://tizen.org/privilege/systemsettings.\n + * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n + * You must release @a path using free(). * @param[in] storage_id The storage device * @param[in] type The directory type * @param[out] path The absolute path to the directory type - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported - * + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported * @see storage_get_state() */ int storage_get_directory(int storage_id, storage_directory_e type, char **path); + /** * @brief Gets the type of the given storage. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[in] storage_id The storage device * @param[out] type The type of the storage - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported */ int storage_get_type(int storage_id, storage_type_e *type); + /** * @brief Gets the current state of the given storage. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[in] storage_id The storage device * @param[out] state The current state of the storage - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported - * + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported * @see storage_get_root_directory() * @see storage_get_total_space() * @see storage_get_available_space() */ int storage_get_state(int storage_id, storage_state_e *state); + /** - * @brief Called when the state of storage changes - * + * @brief Called when the state of storage changes. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[in] storage_id The unique storage ID * @param[in] state The current state of the storage * @param[in] user_data The user data passed from the foreach function - * * @pre storage_set_state_changed_cb() will invoke this callback function. * @see storage_set_state_changed_cb() * @see storage_unset_state_changed_cb() */ typedef void (*storage_state_changed_cb)(int storage_id, storage_state_e state, void *user_data); + /** * @brief Registers a callback function to be invoked when the state of the storage changes. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[in] storage_id The storage device * @param[in] callback The callback function to register * @param[in] user_data The user data to be passed to the callback function - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed - * * @post storage_state_changed_cb() will be invoked if the state of the registered storage changes. * @see storage_state_changed_cb() * @see storage_unset_state_changed_cb() */ int storage_set_state_changed_cb(int storage_id, storage_state_changed_cb callback, void *user_data); + /** * @brief Unregisters the callback function. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[in] storage_id The storage device to monitor * @param[in] callback The callback function to register - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported - * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed - * + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported + * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed * @see storage_state_changed_cb() * @see storage_set_state_changed_cb() */ int storage_unset_state_changed_cb(int storage_id, storage_state_changed_cb callback); + /** - * @brief Enumeration of storage device types + * @brief Enumeration for storage device types. * @since_tizen 3.0 */ typedef enum { - STORAGE_DEV_EXT_SDCARD = 1001, /**< sdcard device (external storage) */ - STORAGE_DEV_EXT_USB_MASS_STORAGE, /**< USB storage device (external storage) */ + STORAGE_DEV_EXT_SDCARD = 1001, /**< sdcard device (external storage) */ + STORAGE_DEV_EXT_USB_MASS_STORAGE, /**< USB storage device (external storage) */ } storage_dev_e; + /** * @brief Called when the state of a storage type changes. - * * @since_tizen 3.0 - * * @param[in] storage_id The unique storage ID * @param[in] type The type of the storage device * @param[in] state The state of the storage @@ -296,7 +266,6 @@ typedef enum { * @param[in] primary The primary partition * @param[in] flags The flags for the storage status * @param[in] user_data The user data - * * @pre storage_set_changed_cb() will invoke this callback function. * @see storage_set_changed_cb() * @see storage_unset_changed_cb() @@ -306,92 +275,77 @@ typedef void (*storage_changed_cb)(int storage_id, const char *fstype, const char *fsuuid, const char *mountpath, bool primary, int flags, void *user_data); + /** * @brief Registers a callback function to be invoked when the state of the specified storage device type changes. - * * @since_tizen 3.0 - * * @param[in] type The type of the storage device * @param[in] callback The callback function to register * @param[in] user_data The user data to be passed to the callback function - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported - * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed - * + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported + * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed * @post storage_changed_cb() will be invoked if the state of the registered storage type changes. * @see storage_changed_cb() * @see storage_unset_changed_cb() */ int storage_set_changed_cb(storage_type_e type, storage_changed_cb callback, void *user_data); + /** * @brief Unregisters the callback function for storage type state changes. - * * @since_tizen 3.0 - * * @param[in] type The type of the the storage device * @param[in] callback The callback function to unregister - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported - * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed - * + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported + * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed * @see storage_changed_cb() * @see storage_set_changed_cb() */ int storage_unset_changed_cb(storage_type_e type, storage_changed_cb callback); + /** * @brief Gets the total space of the given storage in bytes. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[in] storage_id The storage device * @param[out] bytes The total space size of the storage (bytes) - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported - * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed - * + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported + * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed * @see storage_get_state() * @see storage_get_available_space() */ int storage_get_total_space(int storage_id, unsigned long long *bytes); + /** * @brief Gets the available space size of the given storage in bytes. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[in] storage_id The storage device * @param[out] bytes The available space size of the storage (bytes) - * * @return @c 0 on success, * otherwise a negative error value - * - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported - * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed - * + * @retval #STORAGE_ERROR_NONE Successful + * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported + * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed * @see storage_get_state() * @see storage_get_total_space() */ int storage_get_available_space(int storage_id, unsigned long long *bytes); + /** * @} */ diff --git a/include/storage.h b/include/storage.h index 235c72b..0665cf3 100644 --- a/include/storage.h +++ b/include/storage.h @@ -23,33 +23,34 @@ extern "C" { #endif + /** - * @file storage.h - * @ingroup FRAMEWORK/SYSTEM - * @brief This file contains the API for the status of devices. - * @author TIZEN - * @date 2013-02-15 - * @version 0.1 + * @file storage.h + * @ingroup FRAMEWORK/SYSTEM + * @brief This file contains the API for the status of devices. + * @author TIZEN + * @date 2013-02-15 + * @version 0.1 */ + /** * @addtogroup CAPI_SYSTEM_STORAGE_MODULE * @{ */ + #include #include "storage-expand.h" + /** - * @fn int storage_get_internal_memory_size(struct statvfs *buf) + * @brief int storage_get_internal_memory_size(struct statvfs *buf). * @brief This generic API is used to get the internal memory size. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[out] buf A pointer to a statvfs structure * @return @c 0 on success, * otherwise a negative error value on failure - * @see * @par Example: * @code * ... @@ -72,16 +73,14 @@ extern int storage_get_internal_memory_size(struct statvfs *buf); extern int storage_get_internal_memory_size64(struct statvfs *buf); #endif + /** - * @fn int storage_get_external_memory_size(struct statvfs *buf) + * @brief int storage_get_external_memory_size(struct statvfs *buf). * @brief This generic API is used to get the external memory size. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * * @param[out] buf A pointer to a statvfs structure * @return @c 0 on success, * otherwise a negative error value on failure - * @see * @par Example: * @code * ... @@ -110,6 +109,7 @@ extern int __REDIRECT_NTH(storage_get_external_memory_size, extern int storage_get_external_memory_size64(struct statvfs *buf); #endif + /** * @} */ -- 2.7.4