3 * Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 * Licensed under the Apache License, Version 2.0 (the License);
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
19 #ifndef __STORAGE_EXPAND_H__
20 #define __STORAGE_EXPAND_H__
28 * @addtogroup CAPI_SYSTEM_STORAGE_MODULE
35 * @brief Enumeration of error codes for Storage.
40 STORAGE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
41 STORAGE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
42 STORAGE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
43 STORAGE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NO_SUCH_DEVICE, /**< Storage not supported */
44 STORAGE_ERROR_OPERATION_FAILED = TIZEN_ERROR_SYSTEM_CLASS | 0x12, /**< Operation failed */
49 * @brief Enumeration of the storage types.
54 STORAGE_TYPE_INTERNAL, /**< Internal device storage (built-in storage in a device, non-removable) */
55 STORAGE_TYPE_EXTERNAL, /**< External storage */
60 * @brief Enumeration of the state of storage devices.
65 STORAGE_STATE_UNMOUNTABLE = -2, /**< Storage is present but cannot be mounted. Typically it happens if the file system of the storage is corrupted */
66 STORAGE_STATE_REMOVED = -1, /**< Storage is not present */
67 STORAGE_STATE_MOUNTED = 0, /**< Storage is present and mounted with read/write access */
68 STORAGE_STATE_MOUNTED_READ_ONLY = 1, /**< Storage is present and mounted with read only access */
72 * @brief Called to get information once for each supported storage.
76 * @param[in] storage_id The unique storage ID
77 * @param[in] type The type of the storage
78 * @param[in] state The current state of the storage
79 * @param[in] path The absolute path to the root directory of the storage
80 * @param[in] user_data The user data passed from the foreach function
82 * @return @c true to continue with the next iteration of the loop, \n
83 * otherwise @c false to break out of the loop
85 * @pre storage_foreach_device_supported() will invoke this callback function.
86 * @see storage_foreach_device_supported()
88 typedef bool (*storage_device_supported_cb)(int storage_id, storage_type_e type,
89 storage_state_e state, const char *path, void *user_data);
92 * @brief Retrieves all storage in a device.
93 * @details This function invokes the callback function once for each storage in a device. \n
94 * If storage_device_supported_cb() returns @c false, then the iteration will be finished.
98 * @param[in] callback The iteration callback function
99 * @param[in] user_data The user data to be passed to the callback function
101 * @return @c 0 on success,
102 * otherwise a negative error value
104 * @retval #STORAGE_ERROR_NONE Successful
105 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
107 * @post This function invokes storage_device_supported_cb() repeatedly for each supported device.
108 * @see storage_device_supported_cb()
110 int storage_foreach_device_supported(storage_device_supported_cb callback, void *user_data);
113 * @brief Gets the absolute path to the root directory of the given storage.
114 * @details Files saved on the internal/external storage are readable or writeable by all applications.
115 * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.
119 * @remarks If you want to access files or directories in internal storage, you must declare http://tizen.org/privilege/mediastorage.\n
120 * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n
121 * You must release @a path using free().
123 * @param[in] storage_id The storage device
124 * @param[out] path The absolute path to the storage directory
126 * @return @c 0 on success,
127 * otherwise a negative error value
129 * @retval #STORAGE_ERROR_NONE Successful
130 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
131 * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
132 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
134 * @see storage_get_state()
136 int storage_get_root_directory(int storage_id, char **path);
139 * @brief Enumeration of the storage directory types
144 STORAGE_DIRECTORY_IMAGES, /**< Image directory */
145 STORAGE_DIRECTORY_SOUNDS, /**< Sounds directory */
146 STORAGE_DIRECTORY_VIDEOS, /**< Videos directory */
147 STORAGE_DIRECTORY_CAMERA, /**< Camera directory */
148 STORAGE_DIRECTORY_DOWNLOADS, /**< Downloads directory */
149 STORAGE_DIRECTORY_MUSIC, /**< Music directory */
150 STORAGE_DIRECTORY_DOCUMENTS, /**< Documents directory */
151 STORAGE_DIRECTORY_OTHERS, /**< Others directory */
152 STORAGE_DIRECTORY_SYSTEM_RINGTONES, /**< System ringtones directory. Only available for internal storage. */
153 STORAGE_DIRECTORY_MAX
154 } storage_directory_e;
157 * @brief Gets the absolute path to the each directory of the given storage.
158 * @details Files saved on the internal/external storage are readable or writeable by all applications.
159 * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.
163 * @remarks The directory path may not exist, so you must make sure that it exists before using it.\n
164 * 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
165 * If you want to access files or directories in #STORAGE_DIRECTORY_SYSTEM_RINGTONES, you must declare %http://tizen.org/privilege/systemsettings.\n
166 * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n
167 * You must release @a path using free().
169 * @param[in] storage_id The storage device
170 * @param[in] type The directory type
171 * @param[out] path The absolute path to the directory type
173 * @return @c 0 on success,
174 * otherwise a negative error value
176 * @retval #STORAGE_ERROR_NONE Successful
177 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
178 * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
179 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
181 * @see storage_get_state()
183 int storage_get_directory(int storage_id, storage_directory_e type, char **path);
186 * @brief Gets the type of the given storage.
190 * @param[in] storage_id The storage device
191 * @param[out] type The type of the storage
193 * @return @c 0 on success,
194 * otherwise a negative error value
196 * @retval #STORAGE_ERROR_NONE Successful
197 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
198 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
200 int storage_get_type(int storage_id, storage_type_e *type);
203 * @brief Gets the current state of the given storage.
207 * @param[in] storage_id The storage device
208 * @param[out] state The current state of the storage
210 * @return @c 0 on success,
211 * otherwise a negative error value
213 * @retval #STORAGE_ERROR_NONE Successful
214 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
215 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
217 * @see storage_get_root_directory()
218 * @see storage_get_total_space()
219 * @see storage_get_available_space()
221 int storage_get_state(int storage_id, storage_state_e *state);
224 * @brief Called when the state of storage changes
228 * @param[in] storage_id The unique storage ID
229 * @param[in] state The current state of the storage
230 * @param[in] user_data The user data passed from the foreach function
232 * @pre storage_set_state_changed_cb() will invoke this callback function.
233 * @see storage_set_state_changed_cb()
234 * @see storage_unset_state_changed_cb()
236 typedef void (*storage_state_changed_cb)(int storage_id, storage_state_e state, void *user_data);
239 * @brief Registers a callback function to be invoked when the state of the storage changes.
243 * @param[in] storage_id The storage device
244 * @param[in] callback The callback function to register
245 * @param[in] user_data The user data to be passed to the callback function
247 * @return @c 0 on success,
248 * otherwise a negative error value
250 * @retval #STORAGE_ERROR_NONE Successful
251 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
252 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
253 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
255 * @post storage_state_changed_cb() will be invoked if the state of the registered storage changes.
256 * @see storage_state_changed_cb()
257 * @see storage_unset_state_changed_cb()
259 int storage_set_state_changed_cb(int storage_id, storage_state_changed_cb callback, void *user_data);
262 * @brief Unregisters the callback function.
266 * @param[in] storage_id The storage device to monitor
267 * @param[in] callback The callback function to register
269 * @return @c 0 on success,
270 * otherwise a negative error value
272 * @retval #STORAGE_ERROR_NONE Successful
273 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
274 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
275 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
277 * @see storage_state_changed_cb()
278 * @see storage_set_state_changed_cb()
280 int storage_unset_state_changed_cb(int storage_id, storage_state_changed_cb callback);
283 * @brief Gets the total space of the given storage in bytes.
287 * @param[in] storage_id The storage device
288 * @param[out] bytes The total space size of the storage (bytes)
290 * @return @c 0 on success,
291 * otherwise a negative error value
293 * @retval #STORAGE_ERROR_NONE Successful
294 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
295 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
296 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
298 * @see storage_get_state()
299 * @see storage_get_available_space()
301 int storage_get_total_space(int storage_id, unsigned long long *bytes);
304 * @brief Gets the available space size of the given storage in bytes.
308 * @param[in] storage_id The storage device
309 * @param[out] bytes The available space size of the storage (bytes)
311 * @return @c 0 on success,
312 * otherwise a negative error value
314 * @retval #STORAGE_ERROR_NONE Successful
315 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
316 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
317 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
319 * @see storage_get_state()
320 * @see storage_get_total_space()
322 int storage_get_available_space(int storage_id, unsigned long long *bytes);