include_product/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 @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 364  *        This function does not guarantee independence of the played count value between applications. It is recommended that the value is managed by the application.
 365  * @brief Gets the played count of the video.
 366  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 367  *
 368  * @param[in]  video        The video metadata handle
 369  * @param[out] played_count The counter of the video played
 370  *
 371  * @return @c 0 on success,
 372  *         otherwise a negative error value
 373  *
 374  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 375  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 376  */
 377 int video_meta_get_played_count(video_meta_h video, int *played_count) TIZEN_DEPRECATED_API;
 378
 379 /**
 380  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 381  *        This function does not guarantee independence of the played time value between applications. It is recommended that the value is managed by the application.
 382  * @brief Gets the last played time parameter of the video.
 383  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 384  *
 385  * @param[in]  video       The video metadata handle
 386  * @param[out] played_time The last played time of the video
 387  *
 388  * @return @c 0 on success,
 389  *         otherwise a negative error value
 390  *
 391  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 392  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 393  */
 394 int video_meta_get_played_time(video_meta_h video, time_t *played_time) TIZEN_DEPRECATED_API;
 395
 396 /**
 397  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 398  *        This function does not guarantee independence of the played position value between applications. It is recommended that the value is managed by the application.
 399  * @brief Gets the played position parameter of the video.
 400  * @details This function returns the elapsed playback position parameter of the video as period
 401  *          starting from the beginning of the movie.
 402  *
 403  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 404  *
 405  * @param[in]  video           The video metadata handle
 406  * @param[out] played_position The elapsed time of the video
 407  *
 408  * @return @c 0 on success,
 409  *         otherwise a negative error value
 410  *
 411  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 412  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 413  */
 414 int video_meta_get_played_position(video_meta_h video, int *played_position) TIZEN_DEPRECATED_API;
 415
 416 /**
 417  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 418  *        This function does not guarantee independence of the played count value between applications. It is recommended that the value is managed by the application.
 419  * @brief Sets the played count of the video.
 420  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 421  *
 422  * @param[in] video        The video metadata handle
 423  * @param[in] played_count The number of played
 424  *
 425  * @return @c 0 on success,
 426  *         otherwise a negative error value
 427  *
 428  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 429  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 430  */
 431 int video_meta_set_played_count(video_meta_h video, int played_count) TIZEN_DEPRECATED_API;
 432
 433 /**
 434  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 435  *        This function does not guarantee independence of the played time value between applications. It is recommended that the value is managed by the application.
 436  * @brief Sets the last played time of the video.
 437  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 438  *
 439  * @param[in] video       The video metadata handle
 440  * @param[in] played_time The last played time of the video
 441  *
 442  * @return @c 0 on success,
 443  *         otherwise a negative error value
 444  *
 445  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 446  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 447  */
 448 int video_meta_set_played_time(video_meta_h video, time_t played_time) TIZEN_DEPRECATED_API;
 449
 450 /**
 451  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 452  *        This function does not guarantee independence of the played position value between applications. It is recommended that the value is managed by the application.
 453  * @brief Sets the played position of the video.
 454  *
 455  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 456  *
 457  * @remarks  It is NOT recommended to use this attribute for your application-specific purpose because this attribute can be overwritten by other applications (even 0).
 458  *
 459  * @param[in] video           The video metadata handle
 460  * @param[in] played_position The position from the beginning of the video (in milliseconds)
 461  *
 462  * @return @c 0 on success,
 463  *         otherwise a negative error value
 464  *
 465  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 466  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 467  */
 468 int video_meta_set_played_position(video_meta_h video, int played_position) TIZEN_DEPRECATED_API;
 469
 470 /**
 471  * @deprecated Deprecated since 4.0. Related setter functions are deprecated, therefore this function is not needed anymore.
 472  * @brief Updates an video metadata with modified attributes in the media database.
 473  * @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
 474  *          database.
 475  *
 476  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 477  *
 478  * @privlevel public
 479  * @privilege %http://tizen.org/privilege/content.write
 480  *
 481  * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
 482  *
 483  * @param[in] video The video metadata handle
 484  *
 485  * @return @c 0 on success,
 486  *         otherwise a negative error value
 487  *
 488  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 489  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 490  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 491  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 492  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 493  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 494  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
 495  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 496  *
 497  * @pre This function requires opened connection to content service by media_content_connect().
 498  *
 499  * @see media_content_connect()
 500  */
 501 int video_meta_update_to_db(video_meta_h video) TIZEN_DEPRECATED_API;
 502
 503 /**
 504  *@}
 505  */
 506
 507 #ifdef __cplusplus
 508 }
 509 #endif /* __cplusplus */
 510
 511 #endif /*__TIZEN_VIDEO_META_H__*/