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
36 * @brief Enumeration for Storage of error codes.
37 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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 for the storage types.
50 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
53 STORAGE_TYPE_INTERNAL, /**< Internal device storage (built-in storage in a device, non-removable) */
54 STORAGE_TYPE_EXTERNAL, /**< External storage */
55 STORAGE_TYPE_EXTENDED_INTERNAL, /**< Extended internal storage (External storage used as internal storage) (Since 4.0) */
60 * @brief Enumeration for storage devices state.
61 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
64 STORAGE_STATE_UNMOUNTABLE = -2, /**< Storage is present but cannot be mounted. Typically it happens if the file system of the storage is corrupted */
65 STORAGE_STATE_REMOVED = -1, /**< Storage is not present */
66 STORAGE_STATE_MOUNTED = 0, /**< Storage is present and mounted with read/write access */
67 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.
73 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
74 * @param[in] storage_id The unique storage ID
75 * @param[in] type The type of the storage
76 * @param[in] state The current state of the storage
77 * @param[in] path The absolute path to the root directory of the storage
78 * @param[in] user_data The user data passed from the foreach function
79 * @return @c true to continue with the next iteration of the loop, \n
80 * otherwise @c false to break out of the loop
81 * @pre storage_foreach_device_supported() will invoke this callback function.
82 * @see storage_foreach_device_supported()
84 typedef bool (*storage_device_supported_cb)(int storage_id, storage_type_e type,
85 storage_state_e state, const char *path, void *user_data);
89 * @brief Retrieves all the storage in a device.
90 * @details This function invokes the callback function once for each storage in a device. \n
91 * If storage_device_supported_cb() returns @c false, then the iteration will be finished.
92 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
93 * @param[in] callback The iteration callback function
94 * @param[in] user_data The user data to be passed to the callback function
95 * @return @c 0 on success,
96 * otherwise a negative error value
97 * @retval #STORAGE_ERROR_NONE Successful
98 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
99 * @post This function invokes storage_device_supported_cb() repeatedly for each supported device.
100 * @see storage_device_supported_cb()
102 int storage_foreach_device_supported(storage_device_supported_cb callback, void *user_data);
106 * @brief Gets the absolute path to the root directory of the given storage.
107 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
108 * @remarks Files saved on the internal/external storage are readable or writable by all applications.\n
109 * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n
110 * If you want to access files or directories in internal storage, you must declare http://tizen.org/privilege/mediastorage.\n
111 * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n
112 * You must release @a path using free().
113 * @param[in] storage_id The storage device
114 * @param[out] path The absolute path to the storage directory
115 * @return @c 0 on success,
116 * otherwise a negative error value
117 * @retval #STORAGE_ERROR_NONE Successful
118 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
119 * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
120 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
121 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
122 * @see storage_get_state()
124 int storage_get_root_directory(int storage_id, char **path);
128 * @brief Enumeration for the storage directory types.
129 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
132 STORAGE_DIRECTORY_IMAGES, /**< Image directory */
133 STORAGE_DIRECTORY_SOUNDS, /**< Sounds directory */
134 STORAGE_DIRECTORY_VIDEOS, /**< Videos directory */
135 STORAGE_DIRECTORY_CAMERA, /**< Camera directory */
136 STORAGE_DIRECTORY_DOWNLOADS, /**< Downloads directory */
137 STORAGE_DIRECTORY_MUSIC, /**< Music directory */
138 STORAGE_DIRECTORY_DOCUMENTS, /**< Documents directory */
139 STORAGE_DIRECTORY_OTHERS, /**< Others directory */
140 STORAGE_DIRECTORY_SYSTEM_RINGTONES, /**< System ringtones directory. Only available for internal storage. */
141 STORAGE_DIRECTORY_MAX
142 } storage_directory_e;
146 * @brief Gets the absolute path to the each directory of the given storage.
147 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
148 * @remarks Files saved on the internal/external storage are readable or writable by all applications.\n
149 * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n
150 * The directory path may not exist, so you must make sure that it exists before using it.\n
151 * 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
152 * If you want to access files or directories in #STORAGE_DIRECTORY_SYSTEM_RINGTONES, you must declare %http://tizen.org/privilege/systemsettings.\n
153 * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n
154 * You must release @a path using free().
155 * @param[in] storage_id The storage device
156 * @param[in] type The directory type
157 * @param[out] path The absolute path to the directory type
158 * @return @c 0 on success,
159 * otherwise a negative error value
160 * @retval #STORAGE_ERROR_NONE Successful
161 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
162 * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
163 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
164 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
165 * @see storage_get_state()
167 int storage_get_directory(int storage_id, storage_directory_e type, char **path);
171 * @brief Gets the type of the given storage.
172 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
173 * @param[in] storage_id The storage device
174 * @param[out] type The type of the storage
175 * @return @c 0 on success,
176 * otherwise a negative error value
177 * @retval #STORAGE_ERROR_NONE Successful
178 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
179 * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
180 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
181 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
183 int storage_get_type(int storage_id, storage_type_e *type);
187 * @brief Gets the current state of the given storage.
188 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
189 * @param[in] storage_id The storage device
190 * @param[out] state The current state of the storage
191 * @return @c 0 on success,
192 * otherwise a negative error value
193 * @retval #STORAGE_ERROR_NONE Successful
194 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
195 * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
196 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
197 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
198 * @see storage_get_root_directory()
199 * @see storage_get_total_space()
200 * @see storage_get_available_space()
202 int storage_get_state(int storage_id, storage_state_e *state);
206 * @brief Called when the state of storage changes.
207 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
208 * @param[in] storage_id The unique storage ID
209 * @param[in] state The current state of the storage
210 * @param[in] user_data The user data passed from the foreach function
211 * @pre storage_set_state_changed_cb() will invoke this callback function.
212 * @see storage_set_state_changed_cb()
213 * @see storage_unset_state_changed_cb()
215 typedef void (*storage_state_changed_cb)(int storage_id, storage_state_e state, void *user_data);
219 * @brief Registers a callback function to be invoked when the state of the storage changes.
220 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
221 * @param[in] storage_id The storage device
222 * @param[in] callback The callback function to register
223 * @param[in] user_data The user data to be passed to the callback function
224 * @return @c 0 on success,
225 * otherwise a negative error value
226 * @retval #STORAGE_ERROR_NONE Successful
227 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
228 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
229 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
230 * @post storage_state_changed_cb() will be invoked if the state of the registered storage changes.
231 * @see storage_state_changed_cb()
232 * @see storage_unset_state_changed_cb()
234 int storage_set_state_changed_cb(int storage_id, storage_state_changed_cb callback, void *user_data);
238 * @brief Unregisters the callback function.
239 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
240 * @param[in] storage_id The storage device to monitor
241 * @param[in] callback The callback function to register
242 * @return @c 0 on success,
243 * otherwise a negative error value
244 * @retval #STORAGE_ERROR_NONE Successful
245 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
246 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
247 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
248 * @see storage_state_changed_cb()
249 * @see storage_set_state_changed_cb()
251 int storage_unset_state_changed_cb(int storage_id, storage_state_changed_cb callback);
255 * @brief Enumeration for storage device types.
259 STORAGE_DEV_EXT_SDCARD = 1001, /**< SD card device (external storage) */
260 STORAGE_DEV_EXT_USB_MASS_STORAGE, /**< USB storage device (external storage) */
261 STORAGE_DEV_EXTENDED_INTERNAL, /**< Extended internal storage device (External storage used as internal storage) (Since 4.0) */
266 * @brief Called when the state of a storage type changes.
268 * @param[in] storage_id The unique storage ID
269 * @param[in] dev The type of the external storage device
270 * @param[in] state The state of the storage
271 * @param[in] fstype The type of the file system
272 * @param[in] fsuuid The uuid of the file system
273 * @param[in] mountpath The mount path of the file system
274 * @param[in] primary The primary partition
275 * @param[in] flags The flags for the storage status
276 * @param[in] user_data The user data
277 * @pre storage_set_changed_cb() will invoke this callback function.
278 * @see storage_set_changed_cb()
279 * @see storage_unset_changed_cb()
281 typedef void (*storage_changed_cb)(int storage_id,
282 storage_dev_e dev, storage_state_e state,
283 const char *fstype, const char *fsuuid, const char *mountpath,
284 bool primary, int flags, void *user_data);
288 * @brief Registers a callback function to be invoked when the state of the specified storage device type changes.
290 * @param[in] type The type of the storage device
291 * @param[in] callback The callback function to register
292 * @param[in] user_data The user data to be passed to the callback function
293 * @return @c 0 on success,
294 * otherwise a negative error value
295 * @retval #STORAGE_ERROR_NONE Successful
296 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
297 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
298 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
299 * @post storage_changed_cb() will be invoked if the state of the registered storage type changes.
300 * @see storage_changed_cb()
301 * @see storage_unset_changed_cb()
303 int storage_set_changed_cb(storage_type_e type, storage_changed_cb callback, void *user_data);
307 * @brief Unregisters the callback function for storage type state changes.
309 * @param[in] type The type of the the storage device
310 * @param[in] callback The callback function to unregister
311 * @return @c 0 on success,
312 * otherwise a negative error value
313 * @retval #STORAGE_ERROR_NONE Successful
314 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
315 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
316 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
317 * @see storage_changed_cb()
318 * @see storage_set_changed_cb()
320 int storage_unset_changed_cb(storage_type_e type, storage_changed_cb callback);
324 * @brief Gets the total space of the given storage in bytes.
325 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
326 * @param[in] storage_id The storage device
327 * @param[out] bytes The total space size of the storage (bytes)
328 * @return @c 0 on success,
329 * otherwise a negative error value
330 * @retval #STORAGE_ERROR_NONE Successful
331 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
332 * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
333 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
334 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
335 * @see storage_get_state()
336 * @see storage_get_available_space()
338 int storage_get_total_space(int storage_id, unsigned long long *bytes);
342 * @brief Gets the available space size of the given storage in bytes.
343 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
344 * @param[in] storage_id The storage device
345 * @param[out] bytes The available space size of the storage (bytes)
346 * @return @c 0 on success,
347 * otherwise a negative error value
348 * @retval #STORAGE_ERROR_NONE Successful
349 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
350 * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
351 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
352 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
353 * @see storage_get_state()
354 * @see storage_get_total_space()
356 int storage_get_available_space(int storage_id, unsigned long long *bytes);
360 * @brief Gets the type and the kind of external device for the given storage id.
364 * @remarks This function works only for external storages.
365 * If @a type is #STORAGE_TYPE_INTERNAL, this function returns #STORAGE_ERROR_INVALID_PARAMETER and @a dev is unchanged.
367 * @param[in] storage_id The storage id
368 * @param[out] type The storage @a type (internal or external). If @a type is #STORAGE_TYPE_INTERNAL, this function returns #STORAGE_ERROR_INVALID_PARAMETER and @a dev is unchanged.
369 * @param[out] dev The storage device for external storage.
371 * @return @c 0 on success,
372 * otherwise a negative error value
374 * @retval #STORAGE_ERROR_NONE Successful
375 * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
376 * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
377 * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
378 * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
380 int storage_get_type_dev(int storage_id, storage_type_e *type, storage_dev_e *dev);