Code migration
[platform/core/api/media-content.git] / include_product / media_video.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
18 #ifndef __TIZEN_VIDEO_META_H__
19 #define __TIZEN_VIDEO_META_H__
20
21 #include <media_content_type.h>
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif /* __cplusplus */
26
27 /**
28  * @file media_video.h
29  * @brief This file contains the video metadata API and related functions to proceed with video metadata. \n
30  *        Functions include cloning and destroying video metadata, getting video metadata such as width, height, \n
31  *        album, genre, played parameters etc. and updating video to DB.
32  */
33
34 /**
35  * @addtogroup CAPI_CONTENT_MEDIA_VIDEO_META_MODULE
36  * @{
37  */
38
39 /**
40  * @brief Clones the video metadata.
41  * @details This function copies the video metadata handle from a source to destination.
42  *
43  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
44  *
45  * @remarks You must release the destination handle using video_meta_destroy().
46  *
47  * @param[out] dst The destination handle to the video metadata
48  * @param[in]  src The source handle to the video metadata
49  *
50  * @return @c 0 on success,
51  *         otherwise a negative error value
52  *
53  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
54  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
55  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
56  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
57  *
58  * @see video_meta_destroy()
59  */
60 int video_meta_clone(video_meta_h *dst, video_meta_h src);
61
62 /**
63  * @brief Destroys the video metadata.
64  * @details This function frees all resources related to the video metadata handle. This handle
65  *          no longer can be used to perform any operation. A new handle has to
66  *          be created before the next use.
67  *
68  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
69  *
70  * @param[in] video The video metadata handle
71  *
72  * @return @c 0 on success,
73  *         otherwise a negative error value
74  *
75  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
76  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
77  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
78  *
79  * @pre Get copy of video metadata handle by calling video_meta_clone().
80  *
81  * @see video_meta_clone()
82  */
83 int video_meta_destroy(video_meta_h video);
84
85 /**
86  * @brief Gets the ID of the media of the given video metadata.
87  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
88  *
89  * @remarks You must release @a media_id using free().
90  *
91  * @param[in]  video    The video metadata handle
92  * @param[out] media_id The ID of the video
93  *
94  * @return @c 0 on success,
95  *         otherwise a negative error value
96  *
97  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
98  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
99  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
100  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
101  */
102 int video_meta_get_media_id(video_meta_h video, char **media_id);
103
104 /**
105  * @brief Gets the album of the given video metadata.
106  * @details If the value is an empty string, the method returns "Unknown". \n
107  *                Since 3.0, if the media content has no album info, the method returns empty string.
108  *
109  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
110  *
111  * @remarks You must release @a album using free().
112  *
113  * @param[in]  video The video metadata handle
114  * @param[out] album The album of the video metadata
115  *
116  * @return @c 0 on success,
117  *         otherwise a negative error value
118  *
119  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
120  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
121  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
122  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
123  */
124 int video_meta_get_album(video_meta_h video, char **album);
125
126 /**
127  * @brief Gets the artist of the given video metadata.
128  * @details If the value is an empty string, the method returns "Unknown". \n
129  *                Since 3.0, if the media content has no artist info, the method returns empty string.
130  *
131  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
132  *
133  * @remarks You must release @a artist using free().
134  *
135  * @param[in]  video  The video metadata handle
136  * @param[out] artist The artist of the video metadata
137  *
138  * @return @c 0 on success,
139  *         otherwise a negative error value
140  *
141  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
142  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
143  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
144  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
145  */
146 int video_meta_get_artist(video_meta_h video, char **artist);
147
148 /**
149  * @brief Gets the video album artist.
150  * @details If the value is an empty string, the method returns "Unknown". \n
151  *                Since 3.0, if the media content has no album artist info, the method returns empty string.
152  *
153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
154  *
155  * @remarks You must release @a album_artist using free().
156  *
157  * @param[in]  video        The video metadata handle
158  * @param[out] album_artist The album artist of the video metadata
159  *
160  * @return @c 0 on success,
161  *         otherwise a negative error value
162  *
163  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
164  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
165  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
166  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
167  */
168 int video_meta_get_album_artist(video_meta_h video, char **album_artist);
169
170 /**
171  * @brief Gets the genre of the given video metadata.
172  * @details If the value is an empty string, the method returns "Unknown". \n
173  *                Since 3.0, if the media content has no genre info, the method returns empty string.
174  *
175  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
176  *
177  * @remarks You must release @a genre using free().
178  *
179  * @param[in]  video The video metadata handle
180  * @param[out] genre The genre of the video metadata
181  *
182  * @return @c 0 on success,
183  *         otherwise a negative error value
184  *
185  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
186  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
187  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
188  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
189  */
190 int video_meta_get_genre(video_meta_h video, char **genre);
191
192 /**
193  * @brief Gets the composer of the given video metadata.
194  * @details If the value is an empty string, the method returns "Unknown". \n
195  *                Since 3.0, if the media content has no composer info, the method returns empty string.
196  *
197  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
198  *
199  * @remarks You must release @a composer using free().
200  *
201  * @param[in]  video    The video metadata handle
202  * @param[out] composer The composer of the video metadata
203  *
204  * @return @c 0 on success,
205  *         otherwise a negative error value
206  *
207  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
208  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
209  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
210  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
211  */
212 int video_meta_get_composer(video_meta_h video, char **composer);
213
214 /**
215  * @brief Gets the year of the given video metadata.
216  * @details If the value is an empty string, the method returns "Unknown". \n
217  *                Since 3.0, if the media content has no year info, the method returns empty string.
218  *
219  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
220  *
221  * @remarks You must release @a year using free().
222  *
223  * @param[in]  video The video metadata handle
224  * @param[out] year  The year of the video metadata
225  *
226  * @return @c 0 on success,
227  *         otherwise a negative error value
228  *
229  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
230  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
231  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
232  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
233  */
234 int video_meta_get_year(video_meta_h video, char **year);
235
236 /**
237  * @brief Gets the recorded date of the video.
238  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
239  *
240  * @remarks You must release @a recorded_date using free().
241  *
242  * @param[in]  video         The video metadata handle
243  * @param[out] recorded_date The recorded date of the video metadata
244  *
245  * @return @c 0 on success,
246  *         otherwise a negative error value
247  *
248  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
249  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
250  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
251  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
252  */
253 int video_meta_get_recorded_date(video_meta_h video, char **recorded_date);
254
255 /**
256  * @brief Gets the copyright notice of the given video metadata.
257  * @details If the value is an empty string, the method returns "Unknown". \n
258  *                Since 3.0, if the media content has no copyright info, the method returns empty string.
259  *
260  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
261  *
262  * @remarks You must release @a copyright using free().
263  *
264  * @param[in]  video     The video metadata handle
265  * @param[out] copyright The copyright of the video metadata
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  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
274  */
275 int video_meta_get_copyright(video_meta_h video, char **copyright);
276
277 /**
278  * @brief Gets the track number of the given videoo metadata.
279  * @details If the value is an empty string, the method returns "Unknown". \n
280  *                Since 3.0, if the media content has no track info, the method returns empty string.
281  *
282  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
283  *
284  * @remarks You must release @a track_num using free().
285  *
286  * @param[in]  video     The video metadata handle
287  * @param[out] track_num The track number of the video metadata
288  *
289  * @return @c 0 on success,
290  *         otherwise a negative error value
291  *
292  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
293  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
294  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
295  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
296  */
297 int video_meta_get_track_num(video_meta_h video, char **track_num);
298
299 /**
300  * @brief Gets the bitrate of the given video metadata in bitrate per second.
301  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
302  *
303  * @param[in]  video    The video metadata handle
304  * @param[out] bit_rate The video bit rate in bit per second [bps]
305  *
306  * @return @c 0 on success,
307  *         otherwise a negative error value
308  *
309  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
310  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
311  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
312  */
313 int video_meta_get_bit_rate(video_meta_h video, int *bit_rate);
314
315 /**
316  * @brief Gets the track duration of the given videoo metadata.
317  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
318  *
319  * @param[in]  video    The video metadata handle
320  * @param[out] duration The video duration in milliseconds
321  *
322  * @return @c 0 on success,
323  *         otherwise a negative error value
324  *
325  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
326  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
327  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
328  */
329 int video_meta_get_duration(video_meta_h video, int *duration);
330
331 /**
332  * @brief Gets the width of the given videoo metadata.
333  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
334  *
335  * @param[in]  video The video metadata handle
336  * @param[out] width The video width in pixels
337  *
338  * @return @c 0 on success,
339  *         otherwise a negative error value
340  *
341  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
342  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
343  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
344  */
345 int video_meta_get_width(video_meta_h video, int *width);
346
347 /**
348  * @brief Gets the height of the given videoo metadata.
349  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
350  *
351  * @param[in]  video  The video metadata handle
352  * @param[out] height The video height in pixels
353  *
354  * @return @c 0 on success,
355  *         otherwise a negative error value
356  *
357  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
358  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
359  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
360  */
361 int video_meta_get_height(video_meta_h video, int *height);
362
363 /**
364  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use media_info_get_played_count() instead]
365  * @brief Gets the played count of the video.
366  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
367  *
368  * @param[in]  video        The video metadata handle
369  * @param[out] played_count The counter of the video played
370  *
371  * @return @c 0 on success,
372  *         otherwise a negative error value
373  *
374  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
375  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
376  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
377  */
378 int video_meta_get_played_count(video_meta_h video, int *played_count);
379
380 /**
381  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use media_info_get_played_time() instead]
382  * @brief Gets the last played time parameter of the video.
383  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
384  *
385  * @param[in]  video       The video metadata handle
386  * @param[out] played_time The last played time of the video
387  *
388  * @return @c 0 on success,
389  *         otherwise a negative error value
390  *
391  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
392  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
393  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
394  */
395 int video_meta_get_played_time(video_meta_h video, time_t *played_time);
396
397 /**
398  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif.
399  * @brief Gets the played position parameter of the video.
400  * @details This function returns the elapsed playback position parameter of the video as period
401  *          starting from the beginning of the movie.
402  *
403  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
404  *
405  * @param[in]  video           The video metadata handle
406  * @param[out] played_position The elapsed time of the video
407  *
408  * @return @c 0 on success,
409  *         otherwise a negative error value
410  *
411  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
412  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
413  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
414  */
415 int video_meta_get_played_position(video_meta_h video, int *played_position);
416
417 /**
418  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use media_info_increase_played_count() instead]
419  * @brief Sets the played count of the video.
420  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
421  *
422  * @param[in] video        The video metadata handle
423  * @param[in] played_count The number of played
424  *
425  * @return @c 0 on success,
426  *         otherwise a negative error value
427  *
428  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
429  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
430  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
431  *
432  * @post video_meta_update_to_db().
433  */
434 int video_meta_set_played_count(video_meta_h video, int played_count);
435
436 /**
437  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use media_info_set_played_time() instead]
438  * @brief Sets the last played time of the video.
439  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
440  *
441  * @param[in] video       The video metadata handle
442  * @param[in] played_time The last played time of the video
443  *
444  * @return @c 0 on success,
445  *         otherwise a negative error value
446  *
447  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
448  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
449  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
450  *
451  * @post video_meta_update_to_db().
452  */
453 int video_meta_set_played_time(video_meta_h video, time_t played_time);
454
455 /**
456  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif.
457  * @brief Sets the played position of the video.
458  *
459  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
460  *
461  * @remarks  It is NOT recommended to use this attribute for your application-specific purpose because this attribute can be overwritten by other applications (even 0).
462  *
463  * @param[in] video           The video metadata handle
464  * @param[in] played_position The position from the beginning of the video (in milliseconds)
465  *
466  * @return @c 0 on success,
467  *         otherwise a negative error value
468  *
469  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
470  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
471  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
472  *
473  * @post video_meta_update_to_db().
474  */
475 int video_meta_set_played_position(video_meta_h video, int played_position);
476
477 /**
478  * @brief Updates an video metadata with modified attributes in the media database.
479  * @details The function updates the given video meta in the media database. The function should be called after any change in video attributes, to be updated to the media
480  *          database. For example, for setting the played time using video_meta_get_played_time(), after that the video_meta_update_to_db() function should be called to update media database.
481  *
482  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
483  *
484  * @privlevel public
485  * @privilege %http://tizen.org/privilege/content.write
486  *
487  * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
488  *
489  * @param[in] video The video metadata handle
490  *
491  * @return @c 0 on success,
492  *         otherwise a negative error value
493  *
494  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
495  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
496  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
497  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
498  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
499  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
500  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
501  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
502  *
503  * @pre This function requires opened connection to content service by media_content_connect().
504  *
505  * @see media_content_connect()
506  * @see video_meta_set_played_time()
507  * @see video_meta_set_played_count()
508  * @see video_meta_set_played_position()
509  */
510 int video_meta_update_to_db(video_meta_h video);
511
512 /**
513  *@}
514  */
515
516 #ifdef __cplusplus
517 }
518 #endif /* __cplusplus */
519
520 #endif /*__TIZEN_VIDEO_META_H__*/