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 #ifndef __TIZEN_CONTENT_MEDIA_VIDEO_H__
  19 #define __TIZEN_CONTENT_MEDIA_VIDEO_H__
  20
  21 #include <media_content_type.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif /* __cplusplus */
  26
  27 /**
  28  * @file media_video.h
  29  * @brief This file contains the video metadata API and related functions to proceed with video metadata. \n
  30  *        Functions include cloning and destroying video metadata, getting video metadata such as width, height, \n
  31  *        album, genre, played parameters etc. and updating video to DB.
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_CONTENT_MEDIA_VIDEO_META_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Clones the video metadata.
  41  * @details This function copies the video metadata handle from a source to destination.
  42  *
  43  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  44  *
  45  * @remarksThe @a dst should be released using video_meta_destroy().
  46  *
  47  * @param[out] dst The destination handle to the video metadata
  48  * @param[in] src The source handle to the video metadata
  49  *
  50  * @return @c 0 on success,
  51  *         otherwise a negative error value
  52  *
  53  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  54  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  55  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  56  *
  57  * @see video_meta_destroy()
  58  */
  59 int video_meta_clone(video_meta_h *dst, video_meta_h src);
  60
  61 /**
  62  * @brief Destroys the video metadata.
  63  * @details This function frees all resources related to the video metadata handle. This handle
  64  *          no longer can be used to perform any operation. A new handle has to
  65  *          be created before the next use.
  66  *
  67  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  68  *
  69  * @param[in] video The handle to the video metadata
  70  *
  71  * @return @c 0 on success,
  72  *         otherwise a negative error value
  73  *
  74  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  75  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  76  *
  77  * @pre Get copy of video metadata handle by calling video_meta_clone().
  78  *
  79  * @see video_meta_clone()
  80  */
  81 int video_meta_destroy(video_meta_h video);
  82
  83 /**
  84  * @brief Gets the ID of the media of the given video metadata.
  85  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  86  *
  87  * @remarks The @a media_id should be released using free().
  88  *
  89  * @param[in] video The handle to the video metadata
  90  * @param[out] media_id The media ID
  91  *
  92  * @return @c 0 on success,
  93  *         otherwise a negative error value
  94  *
  95  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  96  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  97  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
  98  */
  99 int video_meta_get_media_id(video_meta_h video, char **media_id);
 100
 101 /**
 102  * @brief Gets the album of the given video metadata.
 103  * @details If the value is an empty string, the method returns "Unknown". \n
 104  *                Since 3.0, if the media content has no album info, the method returns empty string.
 105  *
 106  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 107  *
 108  * @remarks The @a album should be released using free().
 109  *
 110  * @param[in] video The handle to the video metadata
 111  * @param[out] album The album of the video metadata
 112  *
 113  * @return @c 0 on success,
 114  *         otherwise a negative error value
 115  *
 116  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 117  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 118  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 119  */
 120 int video_meta_get_album(video_meta_h video, char **album);
 121
 122 /**
 123  * @brief Gets the artist of the given video metadata.
 124  * @details If the value is an empty string, the method returns "Unknown". \n
 125  *                Since 3.0, if the media content has no artist info, the method returns empty string.
 126  *
 127  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 128  *
 129  * @remarks The @a artist should be released using free().
 130  *
 131  * @param[in] video The handle to the video metadata
 132  * @param[out] artist The artist of the video metadata
 133  *
 134  * @return @c 0 on success,
 135  *         otherwise a negative error value
 136  *
 137  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 138  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 139  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 140  */
 141 int video_meta_get_artist(video_meta_h video, char **artist);
 142
 143 /**
 144  * @brief Gets the video album artist.
 145  * @details If the value is an empty string, the method returns "Unknown". \n
 146  *                Since 3.0, if the media content has no album artist info, the method returns empty string.
 147  *
 148  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 149  *
 150  * @remarks The @a album_artist should be released using free().
 151  *
 152  * @param[in] video The handle to the video metadata
 153  * @param[out] album_artist The album artist of the video metadata
 154  *
 155  * @return @c 0 on success,
 156  *         otherwise a negative error value
 157  *
 158  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 159  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 160  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 161  */
 162 int video_meta_get_album_artist(video_meta_h video, char **album_artist);
 163
 164 /**
 165  * @brief Gets the genre of the given video metadata.
 166  * @details If the value is an empty string, the method returns "Unknown". \n
 167  *                Since 3.0, if the media content has no genre info, the method returns empty string.
 168  *
 169  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 170  *
 171  * @remarks The @a genre should be released using free().
 172  *
 173  * @param[in] video The handle to the video metadata
 174  * @param[out] genre The genre of the video metadata
 175  *
 176  * @return @c 0 on success,
 177  *         otherwise a negative error value
 178  *
 179  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 180  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 181  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 182  */
 183 int video_meta_get_genre(video_meta_h video, char **genre);
 184
 185 /**
 186  * @brief Gets the composer of the given video metadata.
 187  * @details If the value is an empty string, the method returns "Unknown". \n
 188  *                Since 3.0, if the media content has no composer info, the method returns empty string.
 189  *
 190  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 191  *
 192  * @remarks The @a composer should be released using free().
 193  *
 194  * @param[in] video The handle to the video metadata
 195  * @param[out] composer The composer of the video metadata
 196  *
 197  * @return @c 0 on success,
 198  *         otherwise a negative error value
 199  *
 200  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 201  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 202  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 203  */
 204 int video_meta_get_composer(video_meta_h video, char **composer);
 205
 206 /**
 207  * @brief Gets the year of the given video metadata.
 208  * @details If the value is an empty string, the method returns "Unknown". \n
 209  *                Since 3.0, if the media content has no year info, the method returns empty string.
 210  *
 211  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 212  *
 213  * @remarks The @a year should be released using free().
 214  *
 215  * @param[in] video The handle to the video metadata
 216  * @param[out] year The year of the video metadata
 217  *
 218  * @return @c 0 on success,
 219  *         otherwise a negative error value
 220  *
 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_year(video_meta_h video, char **year);
 226
 227 /**
 228  * @brief Gets the recorded date of the video.
 229  * @details The recorded date is got from video file's metadata. Some formats like mp4 use UTC and the rest can be different. \n
 230  *              So, please refer to the format specification if needed.
 231  *
 232  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 233  *
 234  * @remarks The @a recorded_date should be released using free().
 235  *
 236  * @param[in] video The handle to the video metadata
 237  * @param[out] recorded_date The recorded date of the video metadata
 238  *
 239  * @return @c 0 on success,
 240  *         otherwise a negative error value
 241  *
 242  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 243  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 244  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 245  */
 246 int video_meta_get_recorded_date(video_meta_h video, char **recorded_date);
 247
 248 /**
 249  * @brief Gets the copyright notice of the given video metadata.
 250  * @details If the value is an empty string, the method returns "Unknown". \n
 251  *                Since 3.0, if the media content has no copyright info, the method returns empty string.
 252  *
 253  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 254  *
 255  * @remarks The @a copyright should be released using free().
 256  *
 257  * @param[in] video The handle to the video metadata
 258  * @param[out] copyright The copyright of the video metadata
 259  *
 260  * @return @c 0 on success,
 261  *         otherwise a negative error value
 262  *
 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  */
 267 int video_meta_get_copyright(video_meta_h video, char **copyright);
 268
 269 /**
 270  * @brief Gets the track number of the given video metadata.
 271  * @details If the value is an empty string, the method returns "Unknown". \n
 272  *                Since 3.0, if the media content has no track info, the method returns empty string.
 273  *
 274  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 275  *
 276  * @remarks The @a track_num should be released using free().
 277  *
 278  * @param[in] video The handle to the video metadata
 279  * @param[out] track_num The track number of the video metadata
 280  *
 281  * @return @c 0 on success,
 282  *         otherwise a negative error value
 283  *
 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  */
 288 int video_meta_get_track_num(video_meta_h video, char **track_num);
 289
 290 /**
 291  * @brief Gets the bitrate of the given video metadata in bitrate per second.
 292  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 293  *
 294  * @param[in] video The handle to the video metadata
 295  * @param[out] bit_rate The video bit rate in bit per second [bps]
 296  *
 297  * @return @c 0 on success,
 298  *         otherwise a negative error value
 299  *
 300  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 301  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 302  */
 303 int video_meta_get_bit_rate(video_meta_h video, int *bit_rate);
 304
 305 /**
 306  * @brief Gets the track duration of the given video metadata.
 307  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 308  *
 309  * @param[in] video The handle to the video metadata
 310  * @param[out] duration The video duration in milliseconds
 311  *
 312  * @return @c 0 on success,
 313  *         otherwise a negative error value
 314  *
 315  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 316  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 317  */
 318 int video_meta_get_duration(video_meta_h video, int *duration);
 319
 320 /**
 321  * @brief Gets the width of the given video metadata.
 322  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 323  *
 324  * @param[in] video The handle to the video metadata
 325  * @param[out] width The video width in pixels
 326  *
 327  * @return @c 0 on success,
 328  *         otherwise a negative error value
 329  *
 330  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 331  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 332  */
 333 int video_meta_get_width(video_meta_h video, int *width);
 334
 335 /**
 336  * @brief Gets the height of the given video metadata.
 337  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 338  *
 339  * @param[in] video The handle to the video metadata
 340  * @param[out] height The video height in pixels
 341  *
 342  * @return @c 0 on success,
 343  *         otherwise a negative error value
 344  *
 345  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 346  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 347  */
 348 int video_meta_get_height(video_meta_h video, int *height);
 349
 350 /**
 351  * @brief Gets the rotation of the given video metadata.
 352  * @since_tizen 4.0
 353  *
 354  * @param[in] video The handle to the video metadata
 355  * @param[out] rotation The clockwise rotation angle of the video in degrees (can be returned from 0 to less than 360)
 356  *
 357  * @return @c 0 on success,
 358  *         otherwise a negative error value
 359  *
 360  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 361  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 362  */
 363 int video_meta_get_rotation(video_meta_h video, int *rotation);
 364
 365 /**
 366  * @deprecated Deprecated since 4.0. Related setter functions are deprecated, therefore this function is not needed anymore.
 367  * @brief Updates an video metadata with modified attributes in the media database.
 368  * @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
 369  *          database.
 370  *
 371  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 372  *
 373  * @privlevel public
 374  * @privilege %http://tizen.org/privilege/content.write
 375  *
 376  * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
 377  *
 378  * @param[in] video The handle to the video metadata
 379  *
 380  * @return @c 0 on success,
 381  *         otherwise a negative error value
 382  *
 383  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 384  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 385  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 386  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 387  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 388  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 389  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
 390  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 391  *
 392  * @pre This function requires opened connection to content service by media_content_connect().
 393  *
 394  * @see media_content_connect()
 395  */
 396 int video_meta_update_to_db(video_meta_h video) TIZEN_DEPRECATED_API;
 397
 398 /**
 399  *@}
 400  */
 401
 402 #ifdef __cplusplus
 403 }
 404 #endif /* __cplusplus */
 405
 406 #endif /*__TIZEN_CONTENT_MEDIA_VIDEO_H__*/