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
  19 #ifndef __TIZEN_VIDEO_META_H__
  20 #define __TIZEN_VIDEO_META_H__
  21
  22 #include <media_content_type.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif /* __cplusplus */
  27
  28
  29 /**
  30  * @addtogroup CAPI_CONTENT_MEDIA_VIDEO_META_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief Clones video metadata.
  36  * @details This function copies the video metadata handle from a source to
  37  * destination.
  38
  39  * @remark The destination handle must be released with video_meta_destroy() by you.
  40  *
  41  * @param [out] dst A destination handle to video metadata
  42  * @param [in] src The source handle to video metadata
  43  * @return 0 on success, otherwise a negative error value.
  44  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  45  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  46  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  47  * @see video_meta_destroy()
  48  */
  49 int video_meta_clone(video_meta_h *dst, video_meta_h src);
  50
  51 /**
  52  * @brief Destroys video metadata.
  53  * @details Function frees all resources related to video metadata handle. This handle
  54  * no longer can be used to perform any operation. A new handle has to
  55  * be created before the next use.
  56  *
  57  * @param [in] video The handle to video metadata
  58  * @return 0 on success, otherwise a negative error value.
  59  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  60  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  61  * @pre Get copy of video metadata handle by calling video_meta_clone()
  62  * @see video_meta_clone()
  63  *
  64  */
  65 int video_meta_destroy(video_meta_h video);
  66
  67 /**
  68  * @brief Gets id of media of given video metadata.
  69  *
  70  * @remarks @a media id must be released with free() by you.
  71  *
  72  * @param [in] video The handle to video metadata
  73  * @param [out] media_id The id of the video
  74  * @return 0 on success, otherwise a negative error value.
  75  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  76  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  77  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  78  */
  79 int video_meta_get_media_id(video_meta_h video, char **media_id);
  80
  81 /**
  82  * @brief Gets the video's title.
  83  *
  84  * @remarks @a title must be released with free() by you.
  85  *
  86  * @param [in] video The handle to video metadata
  87  * @param [out] title The title of video metadata
  88  * @return 0 on success, otherwise a negative error value.
  89  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  90  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  91  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  92  */
  93 int video_meta_get_title(video_meta_h video, char **title);
  94
  95 /**
  96  * @brief Gets the video's album.
  97  * If the value is an empty string, the method returns "Unknown".
  98  *
  99  * @remarks @a album must be released with free() by you.
 100  *
 101  * @param [in] video The handle to video metadata
 102  * @param [out] album The video album or NULL
 103  * @return 0 on success, otherwise a negative error value.
 104  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 105  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 106  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 107  */
 108 int video_meta_get_album(video_meta_h video, char **album);
 109
 110 /**
 111  * @brief Gets the video's artist.
 112  * If the value is an empty string, the method returns "Unknown".
 113  *
 114  * @remarks @a artist must be released with free() by you.
 115  *
 116  * @param [in] video The handle to video metadata
 117  * @param [out] artist The artist of video metadata
 118  * @return 0 on success, otherwise a negative error value.
 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  */
 123 int video_meta_get_artist(video_meta_h video, char **artist);
 124
 125 /**
 126  * @brief Gets the video's genre.
 127  * If the value is an empty string, the method returns "Unknown".
 128  *
 129  * @remarks @a genre must be released with free() by you.
 130  *
 131  * @param [in] video The handle to video metadata
 132  * @param [out] genre The genre of video metadata
 133  * @return 0 on success, otherwise a negative error value.
 134  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 135  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 136  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 137  */
 138 int video_meta_get_genre(video_meta_h video, char **genre);
 139
 140 /**
 141  * @brief Gets the video's composer.
 142  * If the value is an empty string, the method returns "Unknown".
 143  *
 144  * @remarks @a composer must be released with free() by you.
 145  *
 146  * @param [in] video The handle to video metadata
 147  * @param [out] composer The composer of video metadata
 148  * @return 0 on success, otherwise a negative error value.
 149  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 150  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 151  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 152  */
 153 int video_meta_get_composer(video_meta_h video, char **composer);
 154
 155 /**
 156  * @brief Gets the video's year.
 157  * If the value is an empty string, the method returns "Unknown".
 158  *
 159  * @remarks @a year must be released with free() by you.
 160  *
 161  * @param [in] video The handle to video metadata
 162  * @param [out] year The year of video metadata
 163  * @return 0 on success, otherwise a negative error value.
 164  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 165  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 166  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 167  */
 168 int video_meta_get_year(video_meta_h video, char **year);
 169
 170 /**
 171  * @brief Gets the video's recorded_date.
 172  *
 173  * @remarks @a recorded_date must be released with free() by you.
 174  *
 175  * @param [in] video The handle to video metadata
 176  * @param [out] recorded_date The recorded_date of video metadata
 177  * @return 0 on success, otherwise a negative error value.
 178  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 179  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 180  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 181  */
 182 int video_meta_get_recorded_date(video_meta_h video, char **recorded_date);
 183
 184 /**
 185  * @brief Gets the video's copyright.
 186  *
 187  * @remarks @a copyright must be released with free() by you.
 188  *
 189  * @param [in] video The handle to video metadata
 190  * @param [out] copyright The copyright of video metadata
 191  * @return 0 on success, otherwise a negative error value.
 192  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 193  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 194  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 195  */
 196 int video_meta_get_copyright(video_meta_h video, char **copyright);
 197
 198 /**
 199  * @brief Gets the video's track number.
 200  * If the value is an empty string, the method returns "Unknown".
 201  *
 202  * @remarks @a track_num must be released with free() by you.
 203  *
 204  * @param [in] video The handle to video metadata
 205  * @param [out] track_num The track number of video metadata
 206  * @return 0 on success, otherwise a negative error value.
 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  */
 211 int video_meta_get_track_num(video_meta_h video, char **track_num);
 212
 213 /**
 214  * @brief Gets the video's bit rate.
 215  *
 216  * @remarks @a bit_rate must be released with free() by you.
 217  *
 218  * @param [in] video The handle to video metadata
 219  * @param [out] bit_rate The bit rate of video metadata
 220  * @return 0 on success, otherwise a negative error value.
 221  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 222  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 223  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 224  */
 225 int video_meta_get_bit_rate(video_meta_h video, int *bit_rate);
 226
 227 /**
 228  * @brief Gets duration of video metadata.
 229  *
 230  * @param [in] video The handle to video metadata
 231  * @param [out] duration The video duration in milliseconds
 232  * @return 0 on success, otherwise a negative error value.
 233  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 234  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 235  */
 236 int video_meta_get_duration(video_meta_h video, int *duration);
 237
 238 /**
 239  * @brief Gets the video's width in pixels.
 240  *
 241  * @param [in] video The handle to video metadata
 242  * @param [out] width The video width in pixels
 243  * @return 0 on success, otherwise a negative error value.
 244  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 245  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 246  */
 247 int video_meta_get_width(video_meta_h video, int *width);
 248
 249 /**
 250  * @brief Gets the video's height in pixels.
 251  *
 252  * @param [in] video The handle to video metadata
 253  * @param [out] height The video height in pixels
 254  * @return 0 on success, otherwise a negative error value.
 255  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 256  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 257  */
 258 int video_meta_get_height(video_meta_h video, int *height);
 259
 260 /**
 261  * @brief Gets the video's played count.
 262  *
 263  * @param [in] video The handle to video metadata
 264  * @param [out] played_count The number of played
 265  * @return 0 on success, otherwise a negative error value.
 266  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 267  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 268  */
 269 int video_meta_get_played_count(video_meta_h video, int *played_count);
 270
 271 /**
 272  * @brief Gets the video's time last played parameter.
 273  *
 274  * @param [in] video The handle to video metadata
 275  * @param [out] played_time The time last played in the video
 276  * @return 0 on success, otherwise a negative error value.
 277  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 278  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 279  */
 280 int video_meta_get_played_time(video_meta_h video, time_t *played_time);
 281
 282 /**
 283  * @brief Gets the video's position played parameter.
 284  * @details Function returns video's elapsed playback time parameter as period
 285  * starting from the beginning of the movie.
 286  *
 287  * @param [in] video The handle to video metadata
 288  * @param [out] played_position The position from the beginning of the video (in milliseconds)
 289  * @return 0 on success, otherwise a negative error value.
 290  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 291  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 292  */
 293 int video_meta_get_played_position(video_meta_h video, int *played_position);
 294
 295 /**
 296  * @brief Sets the video's played count.
 297  *
 298  * @param [in] video The handle to video metadata
 299  * @param [in] played_count The number of played
 300  * @return 0 on success, otherwise a negative error value.
 301  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 302  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 303  * @post video_meta_update_to_db()
 304  */
 305 int video_meta_set_played_count(video_meta_h video, int played_count);
 306
 307 /**
 308  * @brief Sets the video's time last played parameter.
 309  *
 310  * @param [in] video The handle to video metadata
 311  * @param [in] played_time The time last played in the video
 312  * @return 0 on success, otherwise a negative error value.
 313  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 314  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 315  * @post video_meta_update_to_db()
 316  */
 317 int video_meta_set_played_time(video_meta_h video, time_t played_time);
 318
 319 /**
 320  * @brief Sets the video's position played parameter.
 321  * @details Function returns video's elapsed playback time parameter as period
 322  * starting from the beginning of the movie.
 323  *
 324  * @param [in] video The handle to video metadata
 325  * @param [in] played_position The position from the beginning of the video (in milliseconds)
 326  * @return 0 on success, otherwise a negative error value.
 327  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 328  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 329  * @post video_meta_update_to_db()
 330  */
 331 int video_meta_set_played_position(video_meta_h video, int played_position);
 332
 333 /**
 334  * @brief Updates the video to the media database.
 335  *
 336  * @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
 337  * database. For example, after using video_meta_get_played_time() for setting the played time of the video, video_meta_update_to_db() function should be called so as to update
 338  * the given video attibutes in the media database.
 339  *
 340  * @param[in] image The handle to image
 341  * @return 0 on success, otherwise a negative error value.
 342  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 343  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 344  * @pre This function requires opened connection to content service by media_content_connect().
 345  * @see media_content_connect()
 346  * @see video_meta_set_played_time()
 347  * @see video_meta_set_played_count()
 348  * @see video_meta_set_played_position()
 349  */
 350 int video_meta_update_to_db(video_meta_h video);
 351
 352 /**
 353  *@}
 354  */
 355
 356 #ifdef __cplusplus
 357 }
 358 #endif /* __cplusplus */
 359 #endif /*__TIZEN_VIDEO_META_H__*/