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 * @brief Gets the played count of the video.
362 * @param[in] video The video metadata handle
363 * @param[out] played_count The number of played
365 * @return @c 0 on success,
366 * otherwise a negative error value
368 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
369 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
370 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
372 int video_meta_get_played_count(video_meta_h video, int *played_count);
375 * @brief Gets the last played time parameter of the video.
378 * @param[in] video The video metadata handle
379 * @param[out] played_time The time last played in the video
381 * @return @c 0 on success,
382 * otherwise a negative error value
384 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
385 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
386 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
388 int video_meta_get_played_time(video_meta_h video, time_t *played_time);
391 * @brief Gets the position played parameter of the video.
392 * @details This function returns the elapsed playback time parameter of the video as period
393 * starting from the beginning of the movie.
397 * @param[in] video The video metadata handle
398 * @param[out] played_position The position from the beginning of the video (in milliseconds)
400 * @return @c 0 on success,
401 * otherwise a negative error value
403 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
404 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
405 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
407 int video_meta_get_played_position(video_meta_h video, int *played_position);
410 * @brief Sets the played count of the video.
413 * @param[in] video The video metadata handle
414 * @param[in] played_count The number of played
416 * @return @c 0 on success,
417 * otherwise a negative error value
419 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
420 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
421 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
423 * @post video_meta_update_to_db().
425 int video_meta_set_played_count(video_meta_h video, int played_count);
428 * @brief Sets the time last played parameter of the video.
431 * @param[in] video The video metadata handle
432 * @param[in] played_time The time last played in the video
434 * @return @c 0 on success,
435 * otherwise a negative error value
437 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
438 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
439 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
441 * @post video_meta_update_to_db().
443 int video_meta_set_played_time(video_meta_h video, time_t played_time);
446 * @brief Sets the position played parameter of the video.
447 * @details This function returns video's elapsed playback time parameter as period
448 * starting from the beginning of the movie.
452 * @param[in] video The video metadata handle
453 * @param[in] played_position The position from the beginning of the video (in milliseconds)
455 * @return @c 0 on success,
456 * otherwise a negative error value
458 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
459 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
460 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
462 * @post video_meta_update_to_db().
464 int video_meta_set_played_position(video_meta_h video, int played_position);
467 * @brief Updates the video to the media database.
469 * @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
470 * 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
471 * the given video attributes in the media database.
476 * @privilege %http://tizen.org/privilege/content.write
478 * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
480 * @param[in] video The video metadata handle
482 * @return @c 0 on success,
483 * otherwise a negative error value
485 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
486 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
487 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
488 * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
489 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
490 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
491 * @retval #MEDIA_CONTENT_ERROR_NETWORK Network fail
492 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
494 * @pre This function requires opened connection to content service by media_content_connect().
496 * @see media_content_connect()
497 * @see video_meta_set_played_time()
498 * @see video_meta_set_played_count()s
499 * @see video_meta_set_played_position()
501 int video_meta_update_to_db(video_meta_h video);
509 #endif /* __cplusplus */
510 #endif /*__TIZEN_VIDEO_META_H__*/