Fix Doxygen mistakes
[platform/core/api/media-content.git] / include_product / media_content.h
1 /*
2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
3 *
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
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
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.
15 */
16
17 #ifndef __TIZEN_CONTENT_MEDIA_CONTENT_H__
18 #define __TIZEN_CONTENT_MEDIA_CONTENT_H__
19
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_content_product.h>
34
35 #ifdef __cplusplus
36 extern "C" {
37 #endif /* __cplusplus */
38
39 /**
40  * @file media_content.h
41  * @brief This file contains API providing functions for media content in DB. \n
42  *        Operations include connect and disconnect the media content service, scanning media file and folder with subfolders, \n
43  *        subscribing and unsubscribing notifications of media DB change.
44  */
45
46 /**
47  * @addtogroup CAPI_MEDIA_CONTENT_MODULE
48  * @{
49  */
50
51 /**
52  * @brief Connects to the media content service.
53  * @details Any media content related function call should be invoked after this function call.
54  *
55  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
56  *
57  * @return @c 0 on success,
58  *         otherwise a negative error value
59  *
60  * @retval #MEDIA_CONTENT_ERROR_NONE      Successful
61  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
62  *
63  * @post media_content_disconnect()
64  *
65  * @see media_content_disconnect()
66  */
67 int media_content_connect(void);
68
69 /**
70  * @brief Disconnects from the media content service.
71  * @details This function closes connection to the media content service. Any further media content related operation
72  *          cannot be performed after this function is called.
73  *
74  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
75  *
76  * @return @c 0 on success,
77  *         otherwise a negative error value
78  *
79  * @retval #MEDIA_CONTENT_ERROR_NONE      Successful
80  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
81  *
82  * @pre media_content_connect()
83  *
84  * @see media_content_connect()
85  *
86  */
87 int media_content_disconnect(void);
88
89 /**
90  * @brief Requests to scan a media file.
91  * @details This function requests to scan a media file to the media server.
92  *          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. \n
93  *          If requested file does not exist on file system, information of the media file will be removed from the media DB. \n
94  *          If file information does not exist in DB, this function will be return #MEDIA_CONTENT_ERROR_INVALID_PARAMETER.
95  *
96  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
97  *
98  * @privlevel public
99  * @privilege %http://tizen.org/privilege/content.write \n
100  *                   %http://tizen.org/privilege/mediastorage \n
101  *                   %http://tizen.org/privilege/externalstorage
102  *
103  * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
104  *                   If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage. \n
105  *                   Or if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage. \n
106  *                   If you can access both storage, you must add all privilege.
107  * @remarks Since 4.0, this function is related to the following feature:\n
108  *              %http://tizen.org/feature/content.scanning.others\n
109  *              If this feature is not suppported on the device, MEDIA_CONTENT_TYPE_OTHERS type file is not scanned.
110  *
111  * @param[in] path The file path
112  *
113  * @return @c 0 on success,
114  *         otherwise a negative error value
115  *
116  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
117  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
118  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
119  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
120  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED    DB Operation failed
121  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY    DB Operation busy
122  * @retval #MEDIA_CONTENT_ERROR_NOT_SUPPORTED     Not supported
123  *
124  * @pre This function requires opened connection to content service by media_content_connect().
125  * @see media_content_connect()
126  */
127 int media_content_scan_file(const char *path);
128
129 /**
130  * @brief Requests to scan a media folder, asynchronously.
131  * @details This function requests to scan a media folder to the media server with given completed callback function.
132  *          media_scan_completed_cb() function will be called when the scanning is finished.
133  *          The sub folders are also scanned, if there are sub folders in that folder. \n
134  *          If any folder must not be scanned, a blank file ".scan_ignore" has to be created in that folder.
135  *          After adding or removing a folder from the filesystem, call this function on its source location
136  *          (this will add or remove an entry from the database). \n
137  *          After moving or renaming a folder in the filesystem, call this function on its source location
138  *          (this will remove an entry from the database) and call this function again on its destination location
139  *          (this will add a new entry to the database).\n
140  *          Alternatively, you can call this function on any parent of source location and on any parent of destination location.\n
141  *          You can also call the function once, on a folder which is a parent of both source and destination.\n
142  *
143  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
144  *
145  * @privlevel public
146  * @privilege %http://tizen.org/privilege/content.write \n
147  *                   %http://tizen.org/privilege/mediastorage \n
148  *                   %http://tizen.org/privilege/externalstorage
149  *
150  * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
151  *                   If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage. \n
152  *                   Or if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage. \n
153  *                   If you can access both storage, you must add all privilege.
154  *
155  * @param[in] path The folder path
156  * @param[in] is_recursive Set @c true to scan recursively subdirectories,
157  *                         otherwise @c false to scan only the current directory
158  * @param[in] callback The callback to be invoked when the scanning is finished
159  * @param[in] user_data The user data to be passed to the callback function
160  *
161  * @return @c 0 on success,
162  *         otherwise a negative error value
163  *
164  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
165  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
166  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
167  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
168  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
169  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED    DB Operation failed
170  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY    DB Operation busy
171  * @retval #MEDIA_CONTENT_ERROR_NETWORK   Network fail
172  *
173  * @pre This function requires opened connection to content service by media_content_connect().
174  * @see media_scan_completed_cb()
175  * @see media_content_connect()
176  */
177 int media_content_scan_folder(const char *path, bool is_recursive, media_scan_completed_cb callback, void *user_data);
178
179 /**
180  * @brief Requests to cancel the media folder scanning.
181  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
182  *
183  * @param[in] path The folder path
184  *
185  * @return @c 0 on success,
186  *         otherwise a negative error value
187  *
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  *
192  * @pre media_content_scan_folder()
193  */
194 int media_content_cancel_scan_folder(const char *path);
195
196 /**
197  * @brief Subscribes notifications of the media DB change.
198  * @details This function subscribes notifications of the media DB change which are published by the media server or other apps. \n
199  *          media_content_db_update_cb() function will be called when notification of the media DB change is subscribed. \n
200  *          Using this function, multiple callback is possible to register in one process.
201  *
202  * @since_tizen 3.0
203  *
204  * @remarks The @a noti_handle should be released using media_content_remove_db_updated_cb(). \n
205  *           If you set the same callback that you previously added, this function returns MEDIA_CONTENT_ERROR_INVALID_OPERATION error. \n
206  *
207  * @param[in] callback The callback to be invoked when the scanning is finished
208  * @param[in] user_data The user data to be passed to the callback function
209  * @param[out] noti_handle The handle to db updated notification
210  *
211  * @return @c 0 on success,
212  *         otherwise a negative error value
213  *
214  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
215  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
216  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
217  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
218  *
219  * @see media_content_db_update_cb()
220  * @see media_content_remove_db_updated_cb()
221  */
222 int media_content_add_db_updated_cb(media_content_db_update_cb callback, void *user_data, media_content_noti_h *noti_handle);
223
224 /**
225  * @brief Removes notifications of the media DB change.
226  * @details This function unsubscribes notifications of the media DB change which are published by the media server or other apps.
227  *
228  * @since_tizen 3.0
229  *
230  * @param[in] noti_handle The handle to db updated notification
231  *
232  * @return @c 0 on success,
233  *         otherwise a negative error value
234  *
235  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
236  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
237  *
238  * @pre media_content_add_db_updated_cb()
239  *
240  * @see media_content_add_db_updated_cb()
241  */
242 int media_content_remove_db_updated_cb(media_content_noti_h noti_handle);
243
244 /**
245  * @}
246  */
247
248 #ifdef __cplusplus
249 }
250 #endif /* __cplusplus */
251
252 #endif /* __TIZEN_CONTENT_MEDIA_CONTENT_H__ */