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.
19 #ifndef __TIZEN_VIDEO_META_H__
20 #define __TIZEN_VIDEO_META_H__
22 #include <media_content_type.h>
26 #endif /* __cplusplus */
30 * @brief This file contains the video metadata API and related functions to proceed with video metadata. \n
31 * Functions include cloning and destroying video metadata, getting video metadata such as width, height, \n
32 * album, genre, played parameters etc. and updating video to DB.
36 * @addtogroup CAPI_CONTENT_MEDIA_VIDEO_META_MODULE
41 * @brief Clones the video metadata.
42 * @details This function copies the video metadata handle from a source to
47 * @remarks You must release the destination handle using video_meta_destroy().
49 * @param[out] dst The destination handle to the video metadata
50 * @param[in] src The source handle to the video metadata
52 * @return @c 0 on success,
53 * otherwise a negative error value
55 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
56 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
57 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
58 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
60 * @see video_meta_destroy()
62 int video_meta_clone(video_meta_h *dst, video_meta_h src);
65 * @brief Destroys the video metadata.
66 * @details This function frees all resources related to the video metadata handle. This handle
67 * no longer can be used to perform any operation. A new handle has to
68 * be created before the next use.
72 * @param[in] video The video metadata handle
74 * @return @c 0 on success,
75 * otherwise a negative error value
77 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
78 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
79 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
81 * @pre Get copy of video metadata handle by calling video_meta_clone().
83 * @see video_meta_clone()
85 int video_meta_destroy(video_meta_h video);
88 * @brief Gets the ID of the media of the given video metadata.
91 * @remarks You must release @a media_id using free().
93 * @param[in] video The video metadata handle
94 * @param[out] media_id The ID of the video
96 * @return @c 0 on success,
97 * otherwise a negative error value
99 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
100 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
101 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
102 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
104 int video_meta_get_media_id(video_meta_h video, char **media_id);
107 * @brief Gets the video's album.
108 * @details If the value is an empty string, the method returns "Unknown".
112 * @remarks You must release @a album using free().
114 * @param[in] video The video metadata handle
115 * @param[out] album The video album or @c NULL
117 * @return @c 0 on success,
118 * otherwise a negative error value
120 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
121 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
122 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
123 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
125 int video_meta_get_album(video_meta_h video, char **album);
128 * @brief Gets the video artist.
129 * @details If the value is an empty string, the method returns "Unknown".
133 * @remarks You must release @a artist using free().
135 * @param[in] video The video metadata handle
136 * @param[out] artist The artist of the video metadata
138 * @return @c 0 on success,
139 * otherwise a negative error value
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
146 int video_meta_get_artist(video_meta_h video, char **artist);
149 * @brief Gets the video album artist.
150 * @details If the value is an empty string, the method returns "Unknown".
154 * @remarks You must release @a album_artist using free().
156 * @param[in] video The video metadata handle
157 * @param[out] album_artist The album artist of the video metadata
159 * @return @c 0 on success,
160 * otherwise a negative error value
162 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
163 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
164 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
165 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
167 int video_meta_get_album_artist(video_meta_h video, char **album_artist);
170 * @brief Gets the video genre.
171 * @details If the value is an empty string, the method returns "Unknown".
175 * @remarks You must release @a genre using free().
177 * @param[in] video The video metadata handle
178 * @param[out] genre The genre of the video metadata
180 * @return @c 0 on success,
181 * otherwise a negative error value
183 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
184 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
185 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
186 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
188 int video_meta_get_genre(video_meta_h video, char **genre);
191 * @brief Gets the video composer.
192 * @details If the value is an empty string, the method returns "Unknown".
196 * @remarks You must release @a composer using free().
198 * @param[in] video The video metadata handle
199 * @param[out] composer The composer of the video metadata
201 * @return @c 0 on success,
202 * otherwise a negative error value
204 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
205 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
206 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
207 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
209 int video_meta_get_composer(video_meta_h video, char **composer);
212 * @brief Gets the year of the video.
213 * @details If the value is an empty string, the method returns "Unknown".
217 * @remarks You must release @a year using free().
219 * @param[in] video The video metadata handle
220 * @param[out] year The year of the video metadata
222 * @return @c 0 on success,
223 * otherwise a negative error value
225 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
226 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
227 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
228 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
230 int video_meta_get_year(video_meta_h video, char **year);
233 * @brief Gets the recorded date of the video.
236 * @remarks You must release @a recorded_date using free().
238 * @param[in] video The video metadata handle
239 * @param[out] recorded_date The recorded date of the video metadata
241 * @return @c 0 on success,
242 * otherwise a negative error value
244 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
245 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
246 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
247 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
249 int video_meta_get_recorded_date(video_meta_h video, char **recorded_date);
252 * @brief Gets the video copyright.
255 * @remarks You must release @a copyright using free().
257 * @param[in] video The video metadata handle
258 * @param[out] copyright The copyright of the video metadata
260 * @return @c 0 on success,
261 * otherwise a negative error value
263 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
264 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
265 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
266 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
268 int video_meta_get_copyright(video_meta_h video, char **copyright);
271 * @brief Gets the track number of the video.
272 * @details If the value is an empty string, the method returns "Unknown".
276 * @remarks You must release @a track_num using free().
278 * @param[in] video The video metadata handle
279 * @param[out] track_num The track number of the video metadata
281 * @return @c 0 on success,
282 * otherwise a negative error value
284 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
285 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
286 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
287 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
289 int video_meta_get_track_num(video_meta_h video, char **track_num);
292 * @brief Gets the video bit rate.
295 * @remarks You must release @a bit_rate using free().
297 * @param[in] video The video metadata handle
298 * @param[out] bit_rate The bit rate of the video metadata
300 * @return @c 0 on success,
301 * otherwise a negative error value
303 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
304 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
305 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
306 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
308 int video_meta_get_bit_rate(video_meta_h video, int *bit_rate);
311 * @brief Gets the duration of video metadata.
314 * @param[in] video The video metadata handle
315 * @param[out] duration The video duration in milliseconds
317 * @return @c 0 on success,
318 * otherwise a negative error value
320 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
321 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
322 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
324 int video_meta_get_duration(video_meta_h video, int *duration);
327 * @brief Gets the video width in pixels.
330 * @param[in] video The video metadata handle
331 * @param[out] width The video width in pixels
333 * @return @c 0 on success,
334 * otherwise a negative error value
336 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
337 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
338 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
340 int video_meta_get_width(video_meta_h video, int *width);
343 * @brief Gets the video height in pixels.
346 * @param[in] video The video metadata handle
347 * @param[out] height The video height in pixels
349 * @return @c 0 on success,
350 * otherwise a negative error value
352 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
353 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
354 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
356 int video_meta_get_height(video_meta_h video, int *height);
359 * @deprecated Deprecated since 2.4. [Use media_info_get_played_count() instead]
360 * @brief Gets the played count of the video.
363 * @param[in] video The video metadata handle
364 * @param[out] played_count The number of played
366 * @return @c 0 on success,
367 * otherwise a negative error value
369 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
370 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
371 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
373 int video_meta_get_played_count(video_meta_h video, int *played_count);
376 * @deprecated Deprecated since 2.4. [Use media_info_get_played_time() instead]
377 * @brief Gets the last played time parameter of the video.
380 * @param[in] video The video metadata handle
381 * @param[out] played_time The time last played in the video
383 * @return @c 0 on success,
384 * otherwise a negative error value
386 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
387 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
388 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
390 int video_meta_get_played_time(video_meta_h video, time_t *played_time);
393 * @deprecated Deprecated since 2.4.
394 * @brief Gets the position played parameter of the video.
395 * @details This function returns the elapsed playback time parameter of the video as period
396 * starting from the beginning of the movie.
400 * @param[in] video The video metadata handle
401 * @param[out] played_position The position from the beginning of the video (in milliseconds)
403 * @return @c 0 on success,
404 * otherwise a negative error value
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
410 int video_meta_get_played_position(video_meta_h video, int *played_position);
413 * @deprecated Deprecated since 2.4. [Use media_info_increase_played_count() instead]
414 * @brief Sets the played count of the video.
417 * @param[in] video The video metadata handle
418 * @param[in] played_count The number of played
420 * @return @c 0 on success,
421 * otherwise a negative error value
423 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
424 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
425 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
427 * @post video_meta_update_to_db().
429 int video_meta_set_played_count(video_meta_h video, int played_count);
432 * @deprecated Deprecated since 2.4. [Use media_info_set_played_time() instead]
433 * @brief Sets the time last played parameter of the video.
436 * @param[in] video The video metadata handle
437 * @param[in] played_time The time last played in the video
439 * @return @c 0 on success,
440 * otherwise a negative error value
442 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
443 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
444 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
446 * @post video_meta_update_to_db().
448 int video_meta_set_played_time(video_meta_h video, time_t played_time);
451 * @deprecated Deprecated since 2.4.
452 * @brief Sets the position played parameter of the video.
453 * @details This function returns video's elapsed playback time parameter as period
454 * starting from the beginning of the movie.
458 * @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).
460 * @param[in] video The video metadata handle
461 * @param[in] played_position The position from the beginning of the video (in milliseconds)
463 * @return @c 0 on success,
464 * otherwise a negative error value
466 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
467 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
468 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
470 * @post video_meta_update_to_db().
472 int video_meta_set_played_position(video_meta_h video, int played_position);
475 * @brief Updates the video to the media database.
477 * @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
478 * database. For example, after using video_meta_get_played_time() for setting the played time of the video, the video_meta_update_to_db() function should be called so as to update
479 * the given video attributes in the media database.
484 * @privilege %http://tizen.org/privilege/content.write
486 * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
488 * @param[in] video The video metadata handle
490 * @return @c 0 on success,
491 * otherwise a negative error value
493 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
494 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
495 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
496 * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
497 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
498 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
499 * @retval #MEDIA_CONTENT_ERROR_NETWORK Network fail
500 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
502 * @pre This function requires opened connection to content service by media_content_connect().
504 * @see media_content_connect()
505 * @see video_meta_set_played_time()
506 * @see video_meta_set_played_count()s
507 * @see video_meta_set_played_position()
509 int video_meta_update_to_db(video_meta_h video);
517 #endif /* __cplusplus */
518 #endif /*__TIZEN_VIDEO_META_H__*/