Remove profile tag
[platform/core/api/media-content.git] / include / media_playlist.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_PLAYLIST_H__
18 #define __TIZEN_CONTENT_MEDIA_PLAYLIST_H__
19
20 #include <media_content_type.h>
21
22 #ifdef __cplusplus
23 extern "C" {
24 #endif /* __cplusplus */
25
26 /**
27  * @file
28  * @brief This file contains the playlist API and functions related with handling playlists. \n
29  *        Functions include operations to get the number of playlists, the number of media-info for the playlist  \n
30  *        and all media files in the playlist, to clone, destroy, insert and delete playlist from DB,  \n
31  *        to handle with name, ID, thumbnail, played order and media info of the playlist.
32  */
33
34 /**
35  * @addtogroup CAPI_CONTENT_MEDIA_PLAYLIST_MODULE
36  * @{
37  */
38
39
40 /**
41  * @brief Gets the number of playlists for the passed @a filter from the media database.
42  * @since_tizen 2.3
43  *
44  * @param[in] filter The handle to the media filter
45  * @param[out] playlist_count The count of the media playlist
46  *
47  * @return @c 0 on success,
48  *         otherwise a negative error value
49  *
50  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
51  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
52  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
53  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
54  *
55  * @pre This function requires opened connection to content service by media_content_connect().
56  *
57  * @see media_content_connect()
58  */
59 int media_playlist_get_playlist_count_from_db(filter_h filter, int *playlist_count);
60
61 /**
62  * @brief Iterates through the media playlists with an optional @a filter from the media database.
63  * @details This function gets all media playlists meeting the given filter.
64  *          The callback function will be invoked for every retrieved media playlist.
65  *          If @c NULL is passed to the filter, no filtering is applied.
66  *
67  * @since_tizen 2.3
68  *
69  * @param[in] filter The handle to the media filter
70  * @param[in] callback The callback function to be invoked
71  * @param[in] user_data The user data to be passed to the callback function
72  *
73  * @return @c 0 on success,
74  *         otherwise a negative error value
75  *
76  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
77  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
78  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
79  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
80  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
81  *
82  * @pre  This function requires opened connection to content service by media_content_connect().
83  * @post This function invokes media_playlist_cb().
84  *
85  * @see media_playlist_cb()
86  * @see media_content_connect()
87  * @see media_filter_create()
88  */
89 int media_playlist_foreach_playlist_from_db(filter_h filter, media_playlist_cb callback, void *user_data);
90
91 /**
92  * @brief Gets the number of the media info for the given playlist present in the media database.
93  * @since_tizen 2.3
94  *
95  * @param[in] playlist_id The ID of the media playlist
96  * @param[in] filter The handle to the media filter
97  * @param[out] media_count The number of media items
98  *
99  * @return @c 0 on success,
100  *         otherwise a negative error value
101  *
102  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
103  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
104  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
105  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
106  *
107  * @pre This function requires opened connection to content service by media_content_connect().
108  *
109  * @see media_content_connect()
110  */
111 int media_playlist_get_media_count_from_db(int playlist_id, filter_h filter, int *media_count);
112
113 /**
114  * @brief Iterates through the media files with an optional @a filter in the given audio playlist from the media database.
115  * @details This function gets all media files associated with the given media playlist and
116  *          meeting desired filter option and calls @a callback for
117  *          every retrieved media info. If @c NULL is passed to the @a filter, no filtering is applied.
118  *
119  * @since_tizen 2.3
120  *
121  * @param[in] playlist_id The ID of the media playlist
122  * @param[in] filter The handle to the media filter
123  * @param[in] callback The callback function to be invoked
124  * @param[in] user_data The user data to be passed to the callback function
125  *
126  * @return @c 0 on success,
127  *         otherwise a negative error value
128  *
129  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
130  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
131  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
132  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
133  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
134  *
135  * @pre  This function requires opened connection to content service by media_content_connect().
136  * @post This function invokes media_info_cb().
137  *
138  * @see media_info_cb()
139  * @see media_content_connect()
140  * @see media_filter_create()
141  */
142 int media_playlist_foreach_media_from_db(int playlist_id, filter_h filter, playlist_member_cb callback, void *user_data);
143
144 /**
145  * @brief Inserts a new playlist with the given name into the media database.
146  * @since_tizen 2.3
147  *
148  * @privlevel public
149  * @privilege %http://tizen.org/privilege/content.write
150  *
151  * @remarks The @a playlist should be released using media_playlist_destroy().
152  *
153  * @param[in] name The name of the inserted playlist
154  * @param[out] playlist The handle to the media playlist
155  *
156  * @return @c 0 on success,
157  *         otherwise a negative error value
158  *
159  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
160  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
161  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
162  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
163  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
164  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
165  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
166  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
167  *
168  * @pre This function requires opened connection to content service by media_content_connect().
169  *
170  * @see media_content_connect()
171  * @see media_playlist_delete_from_db()
172  */
173 int media_playlist_insert_to_db(const char *name, media_playlist_h *playlist);
174
175 /**
176  * @brief Deletes the given playlist from the media database.
177  * @since_tizen 2.3
178  *
179  * @privlevel public
180  * @privilege %http://tizen.org/privilege/content.write
181  *
182  * @param[in] playlist_id The ID of media playlist
183  *
184  * @return @c 0 on success,
185  *         otherwise a negative error value
186  *
187  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
188  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
189  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
190  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
191  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
192  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
193  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
194  *
195  * @pre This function requires opened connection to content service by media_content_connect().
196  *
197  * @see media_content_connect()
198  * @see media_playlist_insert_to_db()
199  */
200 int media_playlist_delete_from_db(int playlist_id);
201
202 /**
203  * @brief Gets the media playlist from the media database.
204  *
205  * @details This function creates a new media playlist handle from the media database by the given @a playlist_id.
206  *          The media playlist will be created and will be filled with the playlist information.
207  *
208  * @since_tizen 2.3
209  *
210  * @remarks The @a playlist should be released using media_playlist_destroy().
211  *
212  * @param[in] playlist_id The ID of the media playlist
213  * @param[out] playlist The handle to the media playlist
214  *
215  * @return @c 0 on success,
216  *         otherwise a negative error value
217  *
218  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
219  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
220  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
221  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
222  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
223  *
224  * @pre This function requires opened connection to content service by media_content_connect().
225  *
226  * @see media_content_connect()
227  * @see media_playlist_destroy()
228  */
229 int media_playlist_get_playlist_from_db(int playlist_id, media_playlist_h *playlist);
230
231 /**
232  * @brief Destroys a playlist handle.
233  * @details This function frees all resources related to the playlist handle. This
234  *          handle no longer can be used to perform any operations. A new handle has to
235  *          be created before next usage.
236  *
237  * @since_tizen 2.3
238  *
239  * @param[in] playlist The handle to the media playlist
240  *
241  * @return @c 0 on success,
242  *         otherwise a negative error value
243  *
244  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
245  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
246  *
247  * @pre Get a copy of playlist handle by calling media_playlist_clone() or media_playlist_insert_to_db().
248  *
249  * @see media_playlist_clone()
250  */
251 int media_playlist_destroy(media_playlist_h playlist);
252
253 /**
254  * @brief Clones a playlist handle.
255  * @details This function copies the media playlist handle from a source to
256  *          destination. There is no media_playlist_create() function. The media_playlist_h is created internally and available through
257  *          media playlist foreach function such as media_playlist_foreach_playlist_from_db().
258  *          To use this handle outside of these foreach functions, use this function.
259  *
260  * @since_tizen 2.3
261  *
262  * @remarks The @a dst should be released using media_playlist_destroy().
263  *
264  * @param[out] dst The destination handle to the media playlist
265  * @param[in] src The source handle to the media playlist
266  *
267  * @return @c 0 on success,
268  *         otherwise a negative error value
269  *
270  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
271  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
272  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
273  *
274  * @see media_playlist_destroy()
275  * @see media_playlist_foreach_playlist_from_db()
276  */
277 int media_playlist_clone(media_playlist_h *dst, media_playlist_h src);
278
279 /**
280  * @brief Gets the media playlist ID.
281  * @since_tizen 2.3
282  *
283  * @param[in] playlist The handle to the media playlist
284  * @param[out] playlist_id The ID of the media playlist
285  *
286  * @return @c 0 on success,
287  *         otherwise a negative error value
288  *
289  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
290  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
291  */
292 int media_playlist_get_playlist_id(media_playlist_h playlist, int *playlist_id);
293
294 /**
295  * @brief Gets a name of the playlist.
296  * @since_tizen 2.3
297  *
298  * @remarks The @a playlist_name should be released using free().
299  *
300  * @param[in] playlist The handle to the media playlist
301  * @param[out] playlist_name The playlist name
302  *
303  * @return @c 0 on success,
304  *         otherwise a negative error value
305  *
306  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
307  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
308  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
309  */
310 int media_playlist_get_name(media_playlist_h playlist, char **playlist_name);
311
312 /**
313  * @brief Sets the name of the playlist.
314  * @since_tizen 2.3
315  *
316  * @param[in] playlist The handle to the media playlist
317  * @param[in] playlist_name The name of the media playlist
318  *
319  * @return @c 0 on success,
320  *         otherwise a negative error value
321  *
322  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
323  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
324  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
325  *
326  * @post media_playlist_update_to_db()
327  *
328  */
329 int media_playlist_set_name(media_playlist_h playlist, const char *playlist_name);
330
331 /**
332  * @brief Gets a thumbnail path of the playlist.
333  * @since_tizen 2.3
334  *
335  * @remarks The @a path should be released using free().
336  *
337  * @param[in] playlist The handle to the media playlist
338  * @param[out] path The path of the thumbnail
339  *
340  * @return @c 0 on success,
341  *         otherwise a negative error value
342  *
343  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
344  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
345  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
346  */
347 int media_playlist_get_thumbnail_path(media_playlist_h playlist, char **path);
348
349 /**
350  * @brief Sets the thumbnail path of the playlist.
351  * @since_tizen 2.3
352  *
353  * @param[in] playlist The handle to the media playlist
354  * @param[in] path The path of the thumbnail
355  *
356  * @return @c 0 on success,
357  *         otherwise a negative error value
358  *
359  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
360  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
361  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
362  *
363  * @post media_playlist_update_to_db()
364  */
365 int media_playlist_set_thumbnail_path(media_playlist_h playlist, const char *path);
366
367
368 /**
369  * @brief Sets the playing order in the playlist.
370  * @since_tizen 2.3
371  *
372  * @param[in] playlist The handle to the media playlist
373  * @param[in] playlist_member_id The ID of the playlist member
374  * @param[in] play_order The playing order
375  *
376  * @return @c 0 on success,
377  *         otherwise a negative error value
378  *
379  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
380  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
381  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
382  *
383  * @post media_playlist_update_to_db()
384  */
385 int media_playlist_set_play_order(media_playlist_h playlist, int playlist_member_id, int play_order);
386
387 /**
388  * @brief Adds a new media info to the playlist.
389  * @since_tizen 2.3
390  *
391  * @param[in] playlist The handle to the media playlist
392  * @param[in] media_id The media ID
393  *
394  * @return @c 0 on success,
395  *         otherwise a negative error value
396  *
397  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
398  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
399  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
400  *
401  * @pre  This function requires opened connection to content service by media_content_connect().
402  * @post media_playlist_update_to_db()
403  *
404  * @see media_content_connect()
405  * @see media_playlist_remove_media()
406  */
407 int media_playlist_add_media(media_playlist_h playlist, const char *media_id);
408
409 /**
410  * @brief Removes the playlist members related with the media from the given playlist.
411  * @since_tizen 2.3
412  *
413  * @param[in] playlist The handle to the media playlist
414  * @param[in] playlist_member_id The ID of the playlist member
415  *
416  * @return @c 0 on success,
417  *         otherwise a negative error value
418  *
419  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
420  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
421  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
422  *
423  * @pre  This function requires opened connection to content service by media_content_connect().
424  * @post media_playlist_update_to_db()
425  *
426  * @see media_content_connect()
427  * @see media_playlist_add_media()
428  */
429 int media_playlist_remove_media(media_playlist_h playlist, int playlist_member_id);
430
431 /**
432  * @brief Gets the played order of the playlist.
433  * @since_tizen 2.3
434  *
435  * @param[in] playlist The handle to the media playlist
436  * @param[in] playlist_member_id The ID of the playlist member
437  * @param[out] play_order The played order
438  *
439  * @return @c 0 on success,
440  *         otherwise a negative error value
441  *
442  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
443  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
444  */
445 int media_playlist_get_play_order(media_playlist_h playlist, int playlist_member_id, int *play_order);
446
447 /**
448  * @brief Updates the media playlist to the media database.
449  *
450  * @details The function updates the given media playlist in the media database.
451  *          The function should be called after any change in the playlist, to be updated to the media database.
452  *          For example, after using media_playlist_set_name() for setting the name of the playlist, the
453  *          media_playlist_update_to_db() function should be called so as to update
454  *          the given playlist attributes in the media database.
455  *
456  * @since_tizen 2.3
457  *
458  * @privlevel public
459  * @privilege %http://tizen.org/privilege/content.write
460  *
461  * @param[in] playlist The handle to the media playlist
462  *
463  * @return @c 0 on success,
464  *         otherwise a negative error value
465  *
466  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
467  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
468  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
469  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
470  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
471  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
472  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
473  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
474  *
475  * @pre This function requires opened connection to content service by media_content_connect().
476  *
477  * @see media_content_connect()
478  * @see media_playlist_destroy()
479  * @see media_playlist_add_media()
480  * @see media_playlist_remove_media()
481  * @see media_playlist_set_name()
482  * @see media_playlist_set_play_order()
483  */
484 int media_playlist_update_to_db(media_playlist_h playlist);
485
486 /**
487  * @brief Imports the playlist from m3u playlist file.
488  * @details This function reads a playlist from the m3u playlist file and insert into the db.
489  * @since_tizen 2.4
490  *
491  * @privlevel public
492  * @privilege %http://tizen.org/privilege/content.write
493  *
494  * @remarks The @a playlist should be released using media_playlist_destroy().
495  * @remarks   %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage. \n
496  *                     %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage. \n
497  *                     This function does not support the file of extended m3u playlist.
498  *
499  * @param[in] playlist_name The name of the media playlist to save
500  * @param[in] path The path to import the playlist file
501  * @param[out] playlist The handle to the media playlist
502  *
503  * @return @c 0 on success,
504  *         otherwise a negative error value
505  *
506  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
507  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
508  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
509  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
510  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
511  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
512  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
513  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
514  */
515 int media_playlist_import_from_file(const char *playlist_name, const char *path, media_playlist_h *playlist);
516
517 /**
518  * @brief Exports the playlist to m3u playlist file.
519  * @since_tizen 2.4
520  *
521  * @remarks   %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage. \n
522  *                     %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
523  *
524  * @param[in] playlist The handle to the media playlist
525  * @param[in] path path The path to export the playlist
526  *
527  * @return @c 0 on success,
528  *         otherwise a negative error value
529  *
530  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
531  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
532  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
533  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
534  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
535  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
536  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
537  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
538  */
539 int media_playlist_export_to_file(media_playlist_h playlist, const char* path);
540
541 /**
542  * @}
543  */
544
545 #ifdef __cplusplus
546 }
547 #endif /* __cplusplus */
548 #endif /*__TIZEN_CONTENT_MEDIA_PLAYLIST_H__*/