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);
150 * @brief Gets the video genre.
151 * @details If the value is an empty string, the method returns "Unknown".
155 * @remarks You must release @a genre using free().
157 * @param[in] video The video metadata handle
158 * @param[out] genre The genre of the video metadata
160 * @return @c 0 on success,
161 * otherwise a negative error value
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
168 int video_meta_get_genre(video_meta_h video, char **genre);
171 * @brief Gets the video composer.
172 * @details If the value is an empty string, the method returns "Unknown".
176 * @remarks You must release @a composer using free().
178 * @param[in] video The video metadata handle
179 * @param[out] composer The composer of the video metadata
181 * @return @c 0 on success,
182 * otherwise a negative error value
184 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
185 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
186 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
187 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
189 int video_meta_get_composer(video_meta_h video, char **composer);
192 * @brief Gets the year of the video.
193 * @details If the value is an empty string, the method returns "Unknown".
197 * @remarks You must release @a year using free().
199 * @param[in] video The video metadata handle
200 * @param[out] year The year of the video metadata
202 * @return @c 0 on success,
203 * otherwise a negative error value
205 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
206 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
207 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
208 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
210 int video_meta_get_year(video_meta_h video, char **year);
213 * @brief Gets the recorded date of the video.
216 * @remarks You must release @a recorded_date using free().
218 * @param[in] video The video metadata handle
219 * @param[out] recorded_date The recorded date of the video metadata
221 * @return @c 0 on success,
222 * otherwise a negative error value
224 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
225 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
226 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
227 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
229 int video_meta_get_recorded_date(video_meta_h video, char **recorded_date);
232 * @brief Gets the video copyright.
235 * @remarks You must release @a copyright using free().
237 * @param[in] video The video metadata handle
238 * @param[out] copyright The copyright of the video metadata
240 * @return @c 0 on success,
241 * otherwise a negative error value
243 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
244 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
245 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
246 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
248 int video_meta_get_copyright(video_meta_h video, char **copyright);
251 * @brief Gets the track number of the video.
252 * @details If the value is an empty string, the method returns "Unknown".
256 * @remarks You must release @a track_num using free().
258 * @param[in] video The video metadata handle
259 * @param[out] track_num The track number of the video metadata
261 * @return @c 0 on success,
262 * otherwise a negative error value
264 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
265 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
266 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
267 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
269 int video_meta_get_track_num(video_meta_h video, char **track_num);
272 * @brief Gets the video bit rate.
275 * @remarks You must release @a bit_rate using free().
277 * @param[in] video The video metadata handle
278 * @param[out] bit_rate The bit rate of the video metadata
280 * @return @c 0 on success,
281 * otherwise a negative error value
283 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
284 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
285 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
286 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
288 int video_meta_get_bit_rate(video_meta_h video, int *bit_rate);
291 * @brief Gets the duration of video metadata.
294 * @param[in] video The video metadata handle
295 * @param[out] duration The video duration in milliseconds
297 * @return @c 0 on success,
298 * otherwise a negative error value
300 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
301 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
302 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
304 int video_meta_get_duration(video_meta_h video, int *duration);
307 * @brief Gets the video width in pixels.
310 * @param[in] video The video metadata handle
311 * @param[out] width The video width in pixels
313 * @return @c 0 on success,
314 * otherwise a negative error value
316 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
317 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
318 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
320 int video_meta_get_width(video_meta_h video, int *width);
323 * @brief Gets the video height in pixels.
326 * @param[in] video The video metadata handle
327 * @param[out] height The video height in pixels
329 * @return @c 0 on success,
330 * otherwise a negative error value
332 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
333 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
334 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
336 int video_meta_get_height(video_meta_h video, int *height);
339 * @brief Gets the played count of the video.
342 * @param[in] video The video metadata handle
343 * @param[out] played_count The number of played
345 * @return @c 0 on success,
346 * otherwise a negative error value
348 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
349 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
350 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
352 int video_meta_get_played_count(video_meta_h video, int *played_count);
355 * @brief Gets the last played time parameter of the video.
358 * @param[in] video The video metadata handle
359 * @param[out] played_time The time last played in the video
361 * @return @c 0 on success,
362 * otherwise a negative error value
364 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
365 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
366 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
368 int video_meta_get_played_time(video_meta_h video, time_t *played_time);
371 * @brief Gets the position played parameter of the video.
372 * @details This function returns the elapsed playback time parameter of the video as period
373 * starting from the beginning of the movie.
377 * @param[in] video The video metadata handle
378 * @param[out] played_position The position from the beginning of the video (in milliseconds)
380 * @return @c 0 on success,
381 * otherwise a negative error value
383 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
384 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
385 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
387 int video_meta_get_played_position(video_meta_h video, int *played_position);
390 * @brief Sets the played count of the video.
393 * @param[in] video The video metadata handle
394 * @param[in] played_count The number of played
396 * @return @c 0 on success,
397 * otherwise a negative error value
399 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
400 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
401 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
403 * @post video_meta_update_to_db().
405 int video_meta_set_played_count(video_meta_h video, int played_count);
408 * @brief Sets the time last played parameter of the video.
411 * @param[in] video The video metadata handle
412 * @param[in] played_time The time last played in the video
414 * @return @c 0 on success,
415 * otherwise a negative error value
417 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
418 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
419 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
421 * @post video_meta_update_to_db().
423 int video_meta_set_played_time(video_meta_h video, time_t played_time);
426 * @brief Sets the position played parameter of the video.
427 * @details This function returns video's elapsed playback time parameter as period
428 * starting from the beginning of the movie.
432 * @param[in] video The video metadata handle
433 * @param[in] played_position The position from the beginning of the video (in milliseconds)
435 * @return @c 0 on success,
436 * otherwise a negative error value
438 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
439 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
440 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
442 * @post video_meta_update_to_db().
444 int video_meta_set_played_position(video_meta_h video, int played_position);
447 * @brief Updates the video to the media database.
449 * @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
450 * 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
451 * the given video attributes in the media database.
456 * @privilege %http://tizen.org/privilege/content.write
458 * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
460 * @param[in] video The video metadata handle
462 * @return @c 0 on success,
463 * otherwise a negative error value
465 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
466 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
467 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
469 * @pre This function requires opened connection to content service by media_content_connect().
471 * @see media_content_connect()
472 * @see video_meta_set_played_time()
473 * @see video_meta_set_played_count()s
474 * @see video_meta_set_played_position()
476 int video_meta_update_to_db(video_meta_h video);
484 #endif /* __cplusplus */
485 #endif /*__TIZEN_VIDEO_META_H__*/