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  * @file media_video.h
  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.
  33  */
  34
  35 /**
  36  * @addtogroup CAPI_CONTENT_MEDIA_VIDEO_META_MODULE
  37  * @{
  38  */
  39
  40 /**
  41  * @brief Clones the video metadata.
  42  * @details This function copies the video metadata handle from a source to
  43  *          destination.
  44  *
  45  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  46  *
  47  * @remarks You must release the destination handle using video_meta_destroy().
  48  *
  49  * @param[out] dst The destination handle to the video metadata
  50  * @param[in]  src The source handle to the video metadata
  51  *
  52  * @return @c 0 on success,
  53  *         otherwise a negative error value
  54  *
  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
  59  *
  60  * @see video_meta_destroy()
  61  */
  62 int video_meta_clone(video_meta_h *dst, video_meta_h src);
  63
  64 /**
  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.
  69  *
  70  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  71  *
  72  * @param[in] video The video metadata handle
  73  *
  74  * @return @c 0 on success,
  75  *         otherwise a negative error value
  76  *
  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
  80  *
  81  * @pre Get copy of video metadata handle by calling video_meta_clone().
  82  *
  83  * @see video_meta_clone()
  84  */
  85 int video_meta_destroy(video_meta_h video);
  86
  87 /**
  88  * @brief Gets the ID of the media of the given video metadata.
  89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  90  *
  91  * @remarks You must release @a media_id using free().
  92  *
  93  * @param[in]  video    The video metadata handle
  94  * @param[out] media_id The ID of the video
  95  *
  96  * @return @c 0 on success,
  97  *         otherwise a negative error value
  98  *
  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
 103  */
 104 int video_meta_get_media_id(video_meta_h video, char **media_id);
 105
 106 /**
 107  * @brief Gets the video's album.
 108  * @details If the value is an empty string, the method returns "Unknown".
 109  *
 110  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 111  *
 112  * @remarks You must release @a album using free().
 113  *
 114  * @param[in]  video The video metadata handle
 115  * @param[out] album The video album or @c NULL
 116  *
 117  * @return @c 0 on success,
 118  *         otherwise a negative error value
 119  *
 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
 124  */
 125 int video_meta_get_album(video_meta_h video, char **album);
 126
 127 /**
 128  * @brief Gets the video artist.
 129  * @details If the value is an empty string, the method returns "Unknown".
 130  *
 131  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 132  *
 133  * @remarks You must release @a artist using free().
 134  *
 135  * @param[in]  video  The video metadata handle
 136  * @param[out] artist The artist of the video metadata
 137  *
 138  * @return @c 0 on success,
 139  *         otherwise a negative error value
 140  *
 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
 145  */
 146 int video_meta_get_artist(video_meta_h video, char **artist);
 147
 148 /**
 149  * @brief Gets the video album artist.
 150  * @details If the value is an empty string, the method returns "Unknown".
 151  *
 152  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 153  *
 154  * @remarks You must release @a album_artist using free().
 155  *
 156  * @param[in]  video        The video metadata handle
 157  * @param[out] album_artist The album artist of the video metadata
 158  *
 159  * @return @c 0 on success,
 160  *         otherwise a negative error value
 161  *
 162  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 163  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 164  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 165  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 166  */
 167 int video_meta_get_album_artist(video_meta_h video, char **album_artist);
 168
 169 /**
 170  * @brief Gets the video genre.
 171  * @details If the value is an empty string, the method returns "Unknown".
 172  *
 173  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 174  *
 175  * @remarks You must release @a genre using free().
 176  *
 177  * @param[in]  video The video metadata handle
 178  * @param[out] genre The genre of the video metadata
 179  *
 180  * @return @c 0 on success,
 181  *         otherwise a negative error value
 182  *
 183  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 184  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 185  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 186  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 187  */
 188 int video_meta_get_genre(video_meta_h video, char **genre);
 189
 190 /**
 191  * @brief Gets the video composer.
 192  * @details If the value is an empty string, the method returns "Unknown".
 193  *
 194  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 195  *
 196  * @remarks You must release @a composer using free().
 197  *
 198  * @param[in]  video    The video metadata handle
 199  * @param[out] composer The composer of the video metadata
 200  *
 201  * @return @c 0 on success,
 202  *         otherwise a negative error value
 203  *
 204  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 205  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 206  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 207  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 208  */
 209 int video_meta_get_composer(video_meta_h video, char **composer);
 210
 211 /**
 212  * @brief Gets the year of the video.
 213  * @details If the value is an empty string, the method returns "Unknown".
 214  *
 215  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 216  *
 217  * @remarks You must release @a year using free().
 218  *
 219  * @param[in]  video The video metadata handle
 220  * @param[out] year  The year of the video metadata
 221  *
 222  * @return @c 0 on success,
 223  *         otherwise a negative error value
 224  *
 225  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 226  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 227  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 228  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 229  */
 230 int video_meta_get_year(video_meta_h video, char **year);
 231
 232 /**
 233  * @brief Gets the recorded date of the video.
 234  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 235  *
 236  * @remarks You must release @a recorded_date using free().
 237  *
 238  * @param[in]  video         The video metadata handle
 239  * @param[out] recorded_date The recorded date of the video metadata
 240  *
 241  * @return @c 0 on success,
 242  *         otherwise a negative error value
 243  *
 244  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 245  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 246  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 247  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 248  */
 249 int video_meta_get_recorded_date(video_meta_h video, char **recorded_date);
 250
 251 /**
 252  * @brief Gets the video copyright.
 253  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 254  *
 255  * @remarks You must release @a copyright using free().
 256  *
 257  * @param[in]  video     The video metadata handle
 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  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 267  */
 268 int video_meta_get_copyright(video_meta_h video, char **copyright);
 269
 270 /**
 271  * @brief Gets the track number of the video.
 272  * @details If the value is an empty string, the method returns "Unknown".
 273  *
 274  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 275  *
 276  * @remarks You must release @a track_num using free().
 277  *
 278  * @param[in]  video     The video metadata handle
 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  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 288  */
 289 int video_meta_get_track_num(video_meta_h video, char **track_num);
 290
 291 /**
 292  * @brief Gets the video bit rate.
 293  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 294  *
 295  * @remarks You must release @a bit_rate using free().
 296  *
 297  * @param[in]  video     The video metadata handle
 298  * @param[out] bit_rate  The bit rate of the video metadata
 299  *
 300  * @return @c 0 on success,
 301  *         otherwise a negative error value
 302  *
 303  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 304  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 305  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 306  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 307  */
 308 int video_meta_get_bit_rate(video_meta_h video, int *bit_rate);
 309
 310 /**
 311  * @brief Gets the duration of video metadata.
 312  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 313  *
 314  * @param[in]  video    The video metadata handle
 315  * @param[out] duration The video duration in milliseconds
 316  *
 317  * @return @c 0 on success,
 318  *         otherwise a negative error value
 319  *
 320  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 321  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 322  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 323  */
 324 int video_meta_get_duration(video_meta_h video, int *duration);
 325
 326 /**
 327  * @brief Gets the video width in pixels.
 328  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 329  *
 330  * @param[in]  video The video metadata handle
 331  * @param[out] width The video width in pixels
 332  *
 333  * @return @c 0 on success,
 334  *         otherwise a negative error value
 335  *
 336  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 337  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 338  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 339  */
 340 int video_meta_get_width(video_meta_h video, int *width);
 341
 342 /**
 343  * @brief Gets the video height in pixels.
 344  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 345  *
 346  * @param[in]  video  The video metadata handle
 347  * @param[out] height The video height in pixels
 348  *
 349  * @return @c 0 on success,
 350  *         otherwise a negative error value
 351  *
 352  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 353  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 354  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 355  */
 356 int video_meta_get_height(video_meta_h video, int *height);
 357
 358 /**
 359  * @deprecated Deprecated since 2.4. [Use media_info_get_played_count() instead]
 360  * @brief Gets the played count of the video.
 361  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 362  *
 363  * @param[in]  video        The video metadata handle
 364  * @param[out] played_count The number of played
 365  *
 366  * @return @c 0 on success,
 367  *         otherwise a negative error value
 368  *
 369  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 370  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 371  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 372  */
 373 int video_meta_get_played_count(video_meta_h video, int *played_count);
 374
 375 /**
 376  * @deprecated Deprecated since 2.4. [Use media_info_get_played_time() instead]
 377  * @brief Gets the last played time parameter of the video.
 378  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 379  *
 380  * @param[in]  video       The video metadata handle
 381  * @param[out] played_time The time last played in the video
 382  *
 383  * @return @c 0 on success,
 384  *         otherwise a negative error value
 385  *
 386  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 387  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 388  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 389  */
 390 int video_meta_get_played_time(video_meta_h video, time_t *played_time);
 391
 392 /**
 393  * @deprecated Deprecated since 2.4.
 394  * @brief Gets the position played parameter of the video.
 395  * @details This function returns the elapsed playback time parameter of the video as period
 396  *          starting from the beginning of the movie.
 397  *
 398  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 399  *
 400  * @param[in]  video           The video metadata handle
 401  * @param[out] played_position The position from the beginning of the video (in milliseconds)
 402  *
 403  * @return @c 0 on success,
 404  *         otherwise a negative error value
 405  *
 406  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 407  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 408  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 409  */
 410 int video_meta_get_played_position(video_meta_h video, int *played_position);
 411
 412 /**
 413  * @deprecated Deprecated since 2.4. [Use media_info_increase_played_count() instead]
 414  * @brief Sets the played count of the video.
 415  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 416  *
 417  * @param[in] video        The video metadata handle
 418  * @param[in] played_count The number of played
 419  *
 420  * @return @c 0 on success,
 421  *         otherwise a negative error value
 422  *
 423  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 424  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 425  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 426  *
 427  * @post video_meta_update_to_db().
 428  */
 429 int video_meta_set_played_count(video_meta_h video, int played_count);
 430
 431 /**
 432  * @deprecated Deprecated since 2.4. [Use media_info_set_played_time() instead]
 433  * @brief Sets the time last played parameter of the video.
 434  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 435  *
 436  * @param[in] video       The video metadata handle
 437  * @param[in] played_time The time last played in the video
 438  *
 439  * @return @c 0 on success,
 440  *         otherwise a negative error value
 441  *
 442  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 443  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 444  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 445  *
 446  * @post video_meta_update_to_db().
 447  */
 448 int video_meta_set_played_time(video_meta_h video, time_t played_time);
 449
 450 /**
 451  * @deprecated Deprecated since 2.4.
 452  * @brief Sets the position played parameter of the video.
 453  * @details This function returns video's elapsed playback time parameter as period
 454  *          starting from the beginning of the movie.
 455  *
 456  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 457  *
 458  * @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).
 459  *
 460  * @param[in] video           The video metadata handle
 461  * @param[in] played_position The position from the beginning of the video (in milliseconds)
 462  *
 463  * @return @c 0 on success,
 464  *         otherwise a negative error value
 465  *
 466  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 467  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 468  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 469  *
 470  * @post video_meta_update_to_db().
 471  */
 472 int video_meta_set_played_position(video_meta_h video, int played_position);
 473
 474 /**
 475  * @brief Updates the video to the media database.
 476  *
 477  * @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
 478  *          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
 479  *          the given video attributes in the media database.
 480  *
 481  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 482  *
 483  * @privlevel public
 484  * @privilege %http://tizen.org/privilege/content.write
 485  *
 486  * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
 487  *
 488  * @param[in] video The video metadata handle
 489  *
 490  * @return @c 0 on success,
 491  *         otherwise a negative error value
 492  *
 493  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 494  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 495  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 496  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 497  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 498  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 499  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
 500  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 501  *
 502  * @pre This function requires opened connection to content service by media_content_connect().
 503  *
 504  * @see media_content_connect()
 505  * @see video_meta_set_played_time()
 506  * @see video_meta_set_played_count()s
 507  * @see video_meta_set_played_position()
 508  */
 509 int video_meta_update_to_db(video_meta_h video);
 510
 511 /**
 512  *@}
 513  */
 514
 515 #ifdef __cplusplus
 516 }
 517 #endif /* __cplusplus */
 518 #endif /*__TIZEN_VIDEO_META_H__*/