Merge "[ACR-960] Deprecate cloud storage API" into tizen
[platform/core/api/media-content.git] / include / 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 video 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 video 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 video 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 video 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  * @brief Gets the rotation of the given video metadata.
365  * @since_tizen 4.0
366  *
367  * @param[in]  video  The video metadata handle
368  * @param[out] rotation The clockwise rotation angle of the video in degrees (can be returned from 0 to less than 360)
369  *
370  * @return @c 0 on success,
371  *         otherwise a negative error value
372  *
373  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
374  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
375  */
376 int video_meta_get_rotation(video_meta_h video, int *rotation);
377
378 /**
379  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use media_info_get_played_count() instead]
380  * @brief Gets the played count of the video.
381  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
382  *
383  * @param[in]  video        The video metadata handle
384  * @param[out] played_count The counter of the video played
385  *
386  * @return @c 0 on success,
387  *         otherwise a negative error value
388  *
389  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
390  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
391  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
392  */
393 int video_meta_get_played_count(video_meta_h video, int *played_count) TIZEN_DEPRECATED_API;
394
395 /**
396  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use media_info_get_played_time() instead]
397  * @brief Gets the last played time parameter of the video.
398  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
399  *
400  * @param[in]  video       The video metadata handle
401  * @param[out] played_time The last played time of the video
402  *
403  * @return @c 0 on success,
404  *         otherwise a negative error value
405  *
406  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
407  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
408  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
409  */
410 int video_meta_get_played_time(video_meta_h video, time_t *played_time) TIZEN_DEPRECATED_API;
411
412 /**
413  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif.
414  * @brief Gets the played position parameter of the video.
415  * @details This function returns the elapsed playback position parameter of the video as period
416  *          starting from the beginning of the movie.
417  *
418  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
419  *
420  * @param[in]  video           The video metadata handle
421  * @param[out] played_position The elapsed time of the video
422  *
423  * @return @c 0 on success,
424  *         otherwise a negative error value
425  *
426  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
427  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
428  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
429  */
430 int video_meta_get_played_position(video_meta_h video, int *played_position) TIZEN_DEPRECATED_API;
431
432 /**
433  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use media_info_increase_played_count() instead]
434  * @brief Sets the played count of the video.
435  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
436  *
437  * @param[in] video        The video metadata handle
438  * @param[in] played_count The number of played
439  *
440  * @return @c 0 on success,
441  *         otherwise a negative error value
442  *
443  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
444  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
445  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
446  *
447  * @post video_meta_update_to_db().
448  */
449 int video_meta_set_played_count(video_meta_h video, int played_count) TIZEN_DEPRECATED_API;
450
451 /**
452  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use media_info_set_played_time() instead]
453  * @brief Sets the last played time of the video.
454  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
455  *
456  * @param[in] video       The video metadata handle
457  * @param[in] played_time The last played time of the video
458  *
459  * @return @c 0 on success,
460  *         otherwise a negative error value
461  *
462  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
463  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
464  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
465  *
466  * @post video_meta_update_to_db().
467  */
468 int video_meta_set_played_time(video_meta_h video, time_t played_time) TIZEN_DEPRECATED_API;
469
470 /**
471  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif.
472  * @brief Sets the played position of the video.
473  *
474  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
475  *
476  * @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).
477  *
478  * @param[in] video           The video metadata handle
479  * @param[in] played_position The position from the beginning of the video (in milliseconds)
480  *
481  * @return @c 0 on success,
482  *         otherwise a negative error value
483  *
484  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
485  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
486  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
487  *
488  * @post video_meta_update_to_db().
489  */
490 int video_meta_set_played_position(video_meta_h video, int played_position) TIZEN_DEPRECATED_API;
491
492 /**
493  * @brief Updates an video metadata with modified attributes in the media database.
494  * @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
495  *          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.
496  *
497  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
498  *
499  * @privlevel public
500  * @privilege %http://tizen.org/privilege/content.write
501  *
502  * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
503  *
504  * @param[in] video The video metadata handle
505  *
506  * @return @c 0 on success,
507  *         otherwise a negative error value
508  *
509  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
510  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
511  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
512  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
513  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
514  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
515  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
516  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
517  *
518  * @pre This function requires opened connection to content service by media_content_connect().
519  *
520  * @see media_content_connect()
521  * @see video_meta_set_played_time()
522  * @see video_meta_set_played_count()
523  * @see video_meta_set_played_position()
524  */
525 int video_meta_update_to_db(video_meta_h video);
526
527 /**
528  *@}
529  */
530
531 #ifdef __cplusplus
532 }
533 #endif /* __cplusplus */
534
535 #endif /*__TIZEN_VIDEO_META_H__*/