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_VIDEO_META_H__
  19 #define __TIZEN_VIDEO_META_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  * @remarks You must release the destination handle 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 video metadata handle
  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 You must release @a media_id using free().
  88  *
  89  * @param[in]  video    The video metadata handle
  90  * @param[out] media_id The ID of the video
  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 You must release @a album using free().
 109  *
 110  * @param[in]  video The video metadata handle
 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 You must release @a artist using free().
 130  *
 131  * @param[in]  video  The video metadata handle
 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 You must release @a album_artist using free().
 151  *
 152  * @param[in]  video        The video metadata handle
 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 You must release @a genre using free().
 172  *
 173  * @param[in]  video The video metadata handle
 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 You must release @a composer using free().
 193  *
 194  * @param[in]  video    The video metadata handle
 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 You must release @a year using free().
 214  *
 215  * @param[in]  video The video metadata handle
 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  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 230  *
 231  * @remarks You must release @a recorded_date using free().
 232  *
 233  * @param[in]  video         The video metadata handle
 234  * @param[out] recorded_date The recorded date of the video metadata
 235  *
 236  * @return @c 0 on success,
 237  *         otherwise a negative error value
 238  *
 239  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 240  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 241  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 242  */
 243 int video_meta_get_recorded_date(video_meta_h video, char **recorded_date);
 244
 245 /**
 246  * @brief Gets the copyright notice of the given video metadata.
 247  * @details If the value is an empty string, the method returns "Unknown". \n
 248  *                Since 3.0, if the media content has no copyright info, the method returns empty string.
 249  *
 250  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 251  *
 252  * @remarks You must release @a copyright using free().
 253  *
 254  * @param[in]  video     The video metadata handle
 255  * @param[out] copyright The copyright of the video metadata
 256  *
 257  * @return @c 0 on success,
 258  *         otherwise a negative error value
 259  *
 260  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 261  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 262  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 263  */
 264 int video_meta_get_copyright(video_meta_h video, char **copyright);
 265
 266 /**
 267  * @brief Gets the track number of the given video metadata.
 268  * @details If the value is an empty string, the method returns "Unknown". \n
 269  *                Since 3.0, if the media content has no track info, the method returns empty string.
 270  *
 271  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 272  *
 273  * @remarks You must release @a track_num using free().
 274  *
 275  * @param[in]  video     The video metadata handle
 276  * @param[out] track_num The track number of the video metadata
 277  *
 278  * @return @c 0 on success,
 279  *         otherwise a negative error value
 280  *
 281  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 282  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 283  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 284  */
 285 int video_meta_get_track_num(video_meta_h video, char **track_num);
 286
 287 /**
 288  * @brief Gets the bitrate of the given video metadata in bitrate per second.
 289  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 290  *
 291  * @param[in]  video    The video metadata handle
 292  * @param[out] bit_rate The video bit rate in bit per second [bps]
 293  *
 294  * @return @c 0 on success,
 295  *         otherwise a negative error value
 296  *
 297  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 298  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 299  */
 300 int video_meta_get_bit_rate(video_meta_h video, int *bit_rate);
 301
 302 /**
 303  * @brief Gets the track duration of the given video metadata.
 304  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 305  *
 306  * @param[in]  video    The video metadata handle
 307  * @param[out] duration The video duration in milliseconds
 308  *
 309  * @return @c 0 on success,
 310  *         otherwise a negative error value
 311  *
 312  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 313  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 314  */
 315 int video_meta_get_duration(video_meta_h video, int *duration);
 316
 317 /**
 318  * @brief Gets the width of the given video metadata.
 319  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 320  *
 321  * @param[in]  video The video metadata handle
 322  * @param[out] width The video width in pixels
 323  *
 324  * @return @c 0 on success,
 325  *         otherwise a negative error value
 326  *
 327  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 328  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 329  */
 330 int video_meta_get_width(video_meta_h video, int *width);
 331
 332 /**
 333  * @brief Gets the height of the given video metadata.
 334  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 335  *
 336  * @param[in]  video  The video metadata handle
 337  * @param[out] height The video height in pixels
 338  *
 339  * @return @c 0 on success,
 340  *         otherwise a negative error value
 341  *
 342  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 343  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 344  */
 345 int video_meta_get_height(video_meta_h video, int *height);
 346
 347 /**
 348  * @brief Gets the rotation of the given video metadata.
 349  * @since_tizen 4.0
 350  *
 351  * @param[in]  video  The video metadata handle
 352  * @param[out] rotation The clockwise rotation angle of the video in degrees (can be returned from 0 to less than 360)
 353  *
 354  * @return @c 0 on success,
 355  *         otherwise a negative error value
 356  *
 357  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 358  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 359  */
 360 int video_meta_get_rotation(video_meta_h video, int *rotation);
 361
 362 /**
 363  * @deprecated Deprecated since 4.0. Related setter functions are deprecated, therefore this function is not needed anymore.
 364  * @brief Updates an video metadata with modified attributes in the media database.
 365  * @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
 366  *          database.
 367  *
 368  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 369  *
 370  * @privlevel public
 371  * @privilege %http://tizen.org/privilege/content.write
 372  *
 373  * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
 374  *
 375  * @param[in] video The video metadata handle
 376  *
 377  * @return @c 0 on success,
 378  *         otherwise a negative error value
 379  *
 380  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 381  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 382  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 383  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 384  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 385  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 386  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
 387  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 388  *
 389  * @pre This function requires opened connection to content service by media_content_connect().
 390  *
 391  * @see media_content_connect()
 392  */
 393 int video_meta_update_to_db(video_meta_h video) TIZEN_DEPRECATED_API;
 394
 395 /**
 396  *@}
 397  */
 398
 399 #ifdef __cplusplus
 400 }
 401 #endif /* __cplusplus */
 402
 403 #endif /*__TIZEN_VIDEO_META_H__*/