2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef __TIZEN_MEDIA_CONTENT_H__
18 #define __TIZEN_MEDIA_CONTENT_H__
20 #include <media_audio.h>
21 #include <media_content_type.h>
22 #include <media_filter.h>
23 #include <media_folder.h>
24 #include <media_image.h>
25 #include <media_info.h>
26 #include <media_tag.h>
27 #include <media_video.h>
28 #include <media_group.h>
29 #include <media_playlist.h>
30 #include <media_bookmark.h>
31 #include <media_storage.h>
32 #include <media_face.h>
33 #include <media_pvr.h>
34 #include <media_uhd.h>
38 #endif /* __cplusplus */
41 * @file media_content.h
42 * @brief This file contains API providing functions for media content in DB. \n
43 * Operations include connect and disconnect the media content service, scanning media file and folder with subfolders, \n
44 * subscribing and unsubscribing notifications of media DB change.
48 * @addtogroup CAPI_MEDIA_CONTENT_MODULE
53 * @brief Connects to the media content service.
54 * @details Any media content related function call should be invoked after this function call.
56 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
58 * @return @c 0 on success,
59 * otherwise a negative error value
61 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
62 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
63 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
65 * @post media_content_disconnect()
67 * @see media_content_disconnect()
69 int media_content_connect(void);
72 * @brief Disconnects from the media content service.
73 * @details This function closes connection to the media content service. Any further media content related operation
74 * cannot be performed after this function is called.
76 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
78 * @return @c 0 on success,
79 * otherwise a negative error value
81 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
82 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
83 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
85 * @pre media_content_connect()
87 * @see media_content_connect()
90 int media_content_disconnect(void);
93 * @brief Requests to scan a media file.
94 * @details This function requests to scan a media file to the media server.
95 * If media file is not registered to DB yet, that media file information will be added to the media DB. If it is already registered to the DB, then this tries to refresh information.
96 * If requested file does not exist on file system, information of the media file will be removed from the media DB.
98 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
101 * @privilege %http://tizen.org/privilege/content.write \n
102 * %http://tizen.org/privilege/mediastorage \n
103 * %http://tizen.org/privilege/externalstorage
105 * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
106 * If you want to access only internal storage by using this API, you should add privilege http://tizen.org/privilege/mediastorage. \n
107 * Or if you want to access only external storage by using this API, you should add privilege http://tizen.org/privilege/externalstorage. \n
108 * If you can access both storage, you must add all privilege.
110 * @param[in] path The file path
112 * @return @c 0 on success,
113 * otherwise a negative error value
115 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
116 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
117 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
119 * @pre This function requires opened connection to content service by media_content_connect().
121 int media_content_scan_file(const char *path);
124 * @brief Requests to scan a media folder, asynchronously.
125 * @details This function requests to scan a media folder to the media server with given completed callback function.
126 * media_scan_completed_cb() function will be called when the scanning is finished.
127 * The sub folders are also scanned, if there are sub folders in that folder. \n
128 * If any folder must not be scanned, a blank file ".scan_ignore" has to be created in that folder.
130 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
133 * @privilege %http://tizen.org/privilege/content.write \n
134 * %http://tizen.org/privilege/mediastorage \n
135 * %http://tizen.org/privilege/externalstorage
137 * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
138 * If you want to access only internal storage by using this API, you should add privilege http://tizen.org/privilege/mediastorage. \n
139 * Or if you want to access only external storage by using this API, you should add privilege http://tizen.org/privilege/externalstorage. \n
140 * If you can access both storage, you must add all privilege.
142 * @param[in] path The folder path
143 * @param[in] is_recursive Set @c true to scan recursively subdirectories,
144 * otherwise @c false to scan only the current directory
145 * @param[in] callback The callback to be invoked when the scanning is finished
146 * @param[in] user_data The user data to be passed to the callback function
148 * @return @c 0 on success,
149 * otherwise a negative error value
151 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
152 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
154 * @see media_scan_completed_cb()
156 int media_content_scan_folder(const char *path, bool is_recursive, media_scan_completed_cb callback, void *user_data);
159 * @brief Requests to cancel the media folder scanning.
160 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
162 * @param[in] path The folder path
164 * @return @c 0 on success,
165 * otherwise a negative error value
167 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
168 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
170 * @pre media_content_scan_folder()
172 int media_content_cancel_scan_folder(const char *path);
175 * @deprecated Deprecated since 3.0. Use media_content_add_db_updated_cb() instead.
176 * @brief Subscribes notifications of the media DB change.
177 * @details This function subscribes notifications of the media DB change which are published by the media server or other apps.
178 * media_content_db_update_cb() function will be called when notification of the media DB change is subscribed.
180 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
182 * @param[in] callback The callback to be invoked when the scanning is finished
183 * @param[in] user_data The user data to be passed to the callback function
185 * @return @c 0 on success,
186 * otherwise a negative error value
188 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
189 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
190 * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
191 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
192 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
194 * @see media_content_db_update_cb()
195 * @see media_content_unset_db_updated_cb()
197 int media_content_set_db_updated_cb(media_content_db_update_cb callback, void *user_data);
200 * @deprecated Deprecated since 3.0. Use media_content_remove_db_updated_cb() instead.
201 * @brief Unsubscribes notifications of the media DB change.
202 * @details This function unsubscribes notifications of the media DB change which are published by the media server or other apps.
204 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
206 * @return @c 0 on success,
207 * otherwise a negative error value
209 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
210 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
212 * @pre media_content_set_db_updated_cb()
214 * @see media_content_set_db_updated_cb()
216 int media_content_unset_db_updated_cb(void);
219 * @brief Subscribes notifications of the media DB change.
220 * @details This function subscribes notifications of the media DB change which are published by the media server or other apps. \n
221 * media_content_db_update_cb() function will be called when notification of the media DB change is subscribed. \n
222 * Using this API, multiple callback is possible to register in one process.
226 * @remarks To release the registered callback, you must use media_content_remove_db_updated_cb() API. \n
227 * media_content_unset_db_updated_cb() API can not release the callbacks added by this API. \n
228 * If you set the same callback that you previously added, this API returns MEDIA_CONTENT_ERROR_INVALID_OPERATION error. \n
230 * @param[in] callback The callback to be invoked when the scanning is finished
231 * @param[in] user_data The user data to be passed to the callback function
232 * @param[out] noti_handle The handle to db updated notification
234 * @return @c 0 on success,
235 * otherwise a negative error value
237 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
238 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
239 * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
240 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
242 * @see media_content_db_update_cb()
243 * @see media_content_remove_db_updated_cb()
245 int media_content_add_db_updated_cb(media_content_db_update_cb callback, void *user_data, media_content_noti_h *noti_handle);
249 * @brief Unsubscribes notifications of the media DB change.
250 * @details This function unsubscribes notifications of the media DB change which are published by the media server or other apps.
254 * @param[in] noti_handle The handle to db updated notification
256 * @return @c 0 on success,
257 * otherwise a negative error value
259 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
260 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
262 * @pre media_content_add_db_updated_cb()
264 * @see media_content_add_db_updated_cb()
266 int media_content_remove_db_updated_cb(media_content_noti_h noti_handle);
274 #endif /* __cplusplus */
276 #endif /* __TIZEN_MEDIA_CONTENT_H__ */