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's album_artist.
150 * If the value is an empty string, the method returns "Unknown".
152 * @remarks @a album_artist must be released with free() by you.
154 * @param [in] video The handle to video metadata
155 * @param [out] album_artist The album_artist of video metadata
156 * @return 0 on success, otherwise a negative error value.
157 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
158 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
159 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
161 int video_meta_get_album_artist(video_meta_h video, char **album_artist);
164 * @brief Gets the video genre.
165 * @details If the value is an empty string, the method returns "Unknown".
169 * @remarks You must release @a genre using free().
171 * @param[in] video The video metadata handle
172 * @param[out] genre The genre of the video metadata
174 * @return @c 0 on success,
175 * otherwise a negative error value
177 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
178 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
179 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
180 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
182 int video_meta_get_genre(video_meta_h video, char **genre);
185 * @brief Gets the video composer.
186 * @details If the value is an empty string, the method returns "Unknown".
190 * @remarks You must release @a composer using free().
192 * @param[in] video The video metadata handle
193 * @param[out] composer The composer of the video metadata
195 * @return @c 0 on success,
196 * otherwise a negative error value
198 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
199 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
200 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
201 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
203 int video_meta_get_composer(video_meta_h video, char **composer);
206 * @brief Gets the year of the video.
207 * @details If the value is an empty string, the method returns "Unknown".
211 * @remarks You must release @a year using free().
213 * @param[in] video The video metadata handle
214 * @param[out] year The year of the video metadata
216 * @return @c 0 on success,
217 * otherwise a negative error value
219 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
220 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
221 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
222 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
224 int video_meta_get_year(video_meta_h video, char **year);
227 * @brief Gets the recorded date of the video.
230 * @remarks You must release @a recorded_date using free().
232 * @param[in] video The video metadata handle
233 * @param[out] recorded_date The recorded date of the video metadata
235 * @return @c 0 on success,
236 * otherwise a negative error value
238 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
239 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
240 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
241 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
243 int video_meta_get_recorded_date(video_meta_h video, char **recorded_date);
246 * @brief Gets the video copyright.
249 * @remarks You must release @a copyright using free().
251 * @param[in] video The video metadata handle
252 * @param[out] copyright The copyright of the video metadata
254 * @return @c 0 on success,
255 * otherwise a negative error value
257 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
258 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
259 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
260 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
262 int video_meta_get_copyright(video_meta_h video, char **copyright);
265 * @brief Gets the track number of the video.
266 * @details If the value is an empty string, the method returns "Unknown".
270 * @remarks You must release @a track_num using free().
272 * @param[in] video The video metadata handle
273 * @param[out] track_num The track number of the video metadata
275 * @return @c 0 on success,
276 * otherwise a negative error value
278 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
279 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
280 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
281 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
283 int video_meta_get_track_num(video_meta_h video, char **track_num);
286 * @brief Gets the video bit rate.
289 * @remarks You must release @a bit_rate using free().
291 * @param[in] video The video metadata handle
292 * @param[out] bit_rate The bit rate of the video metadata
294 * @return @c 0 on success,
295 * otherwise a negative error value
297 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
298 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
299 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
300 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
302 int video_meta_get_bit_rate(video_meta_h video, int *bit_rate);
305 * @brief Gets the duration of video metadata.
308 * @param[in] video The video metadata handle
309 * @param[out] duration The video duration in milliseconds
311 * @return @c 0 on success,
312 * otherwise a negative error value
314 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
315 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
316 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
318 int video_meta_get_duration(video_meta_h video, int *duration);
321 * @brief Gets the video width in pixels.
324 * @param[in] video The video metadata handle
325 * @param[out] width The video width in pixels
327 * @return @c 0 on success,
328 * otherwise a negative error value
330 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
331 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
332 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
334 int video_meta_get_width(video_meta_h video, int *width);
337 * @brief Gets the video height in pixels.
340 * @param[in] video The video metadata handle
341 * @param[out] height The video height in pixels
343 * @return @c 0 on success,
344 * otherwise a negative error value
346 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
347 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
348 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
350 int video_meta_get_height(video_meta_h video, int *height);
353 * @brief Gets the played count of the video.
356 * @param[in] video The video metadata handle
357 * @param[out] played_count The number of played
359 * @return @c 0 on success,
360 * otherwise a negative error value
362 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
363 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
364 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
366 int video_meta_get_played_count(video_meta_h video, int *played_count);
369 * @brief Gets the last played time parameter of the video.
372 * @param[in] video The video metadata handle
373 * @param[out] played_time The time last played in the video
375 * @return @c 0 on success,
376 * otherwise a negative error value
378 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
379 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
380 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
382 int video_meta_get_played_time(video_meta_h video, time_t *played_time);
385 * @brief Gets the position played parameter of the video.
386 * @details This function returns the elapsed playback time parameter of the video as period
387 * starting from the beginning of the movie.
391 * @param[in] video The video metadata handle
392 * @param[out] played_position The position from the beginning of the video (in milliseconds)
394 * @return @c 0 on success,
395 * otherwise a negative error value
397 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
398 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
399 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
401 int video_meta_get_played_position(video_meta_h video, int *played_position);
404 * @brief Sets the played count of the video.
407 * @param[in] video The video metadata handle
408 * @param[in] played_count The number of played
410 * @return @c 0 on success,
411 * otherwise a negative error value
413 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
414 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
415 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
417 * @post video_meta_update_to_db().
419 int video_meta_set_played_count(video_meta_h video, int played_count);
422 * @brief Sets the time last played parameter of the video.
425 * @param[in] video The video metadata handle
426 * @param[in] played_time The time last played in the video
428 * @return @c 0 on success,
429 * otherwise a negative error value
431 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
432 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
433 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
435 * @post video_meta_update_to_db().
437 int video_meta_set_played_time(video_meta_h video, time_t played_time);
440 * @brief Sets the position played parameter of the video.
441 * @details This function returns video's elapsed playback time parameter as period
442 * starting from the beginning of the movie.
446 * @param[in] video The video metadata handle
447 * @param[in] played_position The position from the beginning of the video (in milliseconds)
449 * @return @c 0 on success,
450 * otherwise a negative error value
452 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
453 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
454 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
456 * @post video_meta_update_to_db().
458 int video_meta_set_played_position(video_meta_h video, int played_position);
461 * @brief Updates the video to the media database.
463 * @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
464 * 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
465 * the given video attributes in the media database.
470 * @privilege %http://tizen.org/privilege/content.write
472 * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
474 * @param[in] video The video metadata handle
476 * @return @c 0 on success,
477 * otherwise a negative error value
479 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
480 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
481 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
483 * @pre This function requires opened connection to content service by media_content_connect().
485 * @see media_content_connect()
486 * @see video_meta_set_played_time()
487 * @see video_meta_set_played_count()s
488 * @see video_meta_set_played_position()
490 int video_meta_update_to_db(video_meta_h video);
498 #endif /* __cplusplus */
499 #endif /*__TIZEN_VIDEO_META_H__*/