include/media_info.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_MEDIA_INFORMATION_H__
  19 #define __TIZEN_MEDIA_INFORMATION_H__
  20
  21 #include <media_content_type.h>
  22
  23
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif /* __cplusplus */
  28
  29
  30 /**
  31  * @addtogroup CAPI_CONTENT_MEDIA_INFO_MODULE
  32  * @{
  33  */
  34
  35 /**
  36  * @brief Inserts media file into the media database.
  37  * @details This function inserts an media item into the content storage.
  38  * Normally, inserting a media file in database is done automatically by media server, without calling this function.
  39  * This function is only called when media server is busy and user needs to get quick result of inserting
  40  * e.g. Taking a photo while media server is busy and user want to see the quick snapshot of the photo taken.
  41  * @remark The handle must be released with media_info_destroy() by you.
  42  *
  43  * @param[in] path The path to the media file
  44  * @param[out] info The handle to the media info
  45  * @return 0 on success, otherwise a negative error value.
  46  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  47  * @pre This function requires opened connection to content service by media_content_connect().
  48  * @see media_content_connect()
  49  */
  50 int media_info_insert_to_db (const char *path, media_info_h *info);
  51
  52 /**
  53  * @brief Insert media files into the media database, asynchronously.
  54  * @details This function insert an media items into the content storage.
  55  * Normally, inserting a media file in database is done automatically by media server, without calling this function.
  56  * This function invokes media_insert_completed_cb callback function.
  57  * #media_insert_completed_cb will be called when insertion to media database is finished.
  58  *
  59  * @param[in] path_array The path array to the media files
  60  * @param[in] array_length The length of array
  61  * @param[in] callback The callback to invoke when media items inserted completely
  62  * @param[in] user_data The user data to be passed to the callback function
  63  * @return 0 on success, otherwise a negative error value.
  64  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  65  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  66  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
  67  * @pre This function requires opened connection to content service by media_content_connect().
  68  * @see media_content_connect()
  69  * @see media_insert_completed_cb()
  70  */
  71 int media_info_insert_batch_to_db(const char **path_array,unsigned int array_length, media_insert_completed_cb callback, void *user_data);
  72
  73
  74 /**
  75  * @brief Deletes media file from the media database.
  76  * @details This function deletes an media item from the content storage.
  77  * Normally, deleting a media file in database is done automatically by media server, without calling this function.
  78  * This function is only called when media server is busy and user needs to get quick result of deleting
  79  *
  80  * @param[in] media_id The ID to the media file
  81  * @return 0 on success, otherwise a negative error value.
  82  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  83  * @pre This function requires opened connection to content service by media_content_connect().
  84  * @see media_content_connect()
  85  */
  86 int media_info_delete_from_db(const char *media_id);
  87
  88 /**
  89  * @brief Deletes media files from the media database. The media files to delete can be specified as a condition in a filter.
  90  * @details This function deletes the media items from the content storage.
  91  * Normally, deleting  media files in database are done automatically by media server, without calling this function.
  92  * This function is only called when media server is busy and user needs to get quick result of deleting
  93  *
  94  * @param[in] filter The handle to filter
  95  * @return 0 on success, otherwise a negative error value.
  96  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  97  * @pre This function requires opened connection to content service by media_content_connect().
  98  * @see media_content_connect()
  99  */
 100 int media_info_delete_batch_from_db(filter_h filter);
 101
 102
 103 /**
 104  * @brief Destroys the media info.
 105  * @details The function frees all resources related to the media info handle. This handle
 106  * no longer can be used to perform any operation. New media info handle has to
 107  * be created before next usage.
 108  *
 109  * @param[in] media The handle to media info
 110  * @return 0 on success, otherwise a negative error value.
 111  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 112  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 113  * @pre Get copy of media_info handle by calling media_info_clone()
 114  * @see media_info_clone()
 115  */
 116 int media_info_destroy(media_info_h media);
 117
 118 /**
 119  * @brief Clones the media info handle.
 120  *
 121  * @details This function copies the media info handle from a source to destination.
 122  * There is no media_info_create() function. The media_info_h is created internally and
 123  * available through media info foreach function such as media_info_foreach_media_from_db().
 124  * To use this handle outside of these foreach functions, use this function.
 125  * @remark The destination handle must be released with media_info_destroy() by you.
 126  *
 127  * @param[out] dst A destination handle to media info
 128  * @param[in] src The source handle to media info
 129  * @return 0 on success, otherwise a negative error value.
 130  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 131  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 132  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 133  * @see media_info_destroy()
 134  * @see media_album_foreach_media_from_db()
 135  * @see media_playlist_foreach_media_from_db()
 136  * @see media_group_foreach_media_from_db
 137  * @see media_tag_foreach_media_from_db()
 138  * @see media_info_foreach_media_from_db()
 139  * @see media_folder_foreach_media_from_db()
 140  *
 141  */
 142 int media_info_clone(media_info_h *dst, media_info_h src);
 143
 144 /**
 145  * @brief Gets the number of media info for the passed @a filter from the media database.
 146  *
 147  * @param[in] filter The handle to filter.
 148  * @param[out] media_count The count of media tag
 149  * @return 0 on success, otherwise a negative error value.
 150  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 151  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 152  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
 153  * @pre This function requires opened connection to content service by media_content_connect().
 154  * @see media_content_connect()
 155  *
 156  */
 157 int media_info_get_media_count_from_db(filter_h filter, int *media_count);
 158
 159 /**
 160  * @brief Iterates through media info from the media database.
 161  * @details This function gets all media info handles meeting the given @a filter. The @a callback function will be invoked for every retrieved media info.
 162  * If NULL is passed to the @a filter, no filtering is applied.
 163  * @param[in] filter The handle to media info filter
 164  * @param[in] callback The callback function to invoke
 165  * @param[in] user_data The user data to be passed to the callback function
 166  * @return 0 on success, otherwise a negative error value.
 167  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 168  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 169  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 170  * @pre This function requires opened connection to content service by media_content_connect().
 171  * @post This function invokes media_info_cb().
 172  * @see media_content_connect()
 173  * @see #media_info_cb
 174  * @see media_info_filter_create()
 175  *
 176  */
 177 int media_info_foreach_media_from_db(filter_h filter, media_info_cb callback, void *user_data);
 178
 179 /**
 180  * @brief Gets the number of media tag for the passed @a filter in the given @a media ID from the media database.
 181  *
 182  * @param[in] media_id The ID of media info
 183  * @param[in] filter The handle to media filter
 184  * @param[out] tag_count The count of media tag
 185  * @return 0 on success, otherwise a negative error value.
 186  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 187  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 188  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
 189  * @pre This function requires opened connection to content service by media_content_connect().
 190  * @see media_content_connect()
 191  *
 192  */
 193 int media_info_get_tag_count_from_db(const char *media_id, filter_h filter, int *tag_count);
 194
 195 /**
 196  * @brief Iterates through the media tag in the given @a media @a info from the media database.
 197  * @details This function gets all media tag associated with the given @a media and calls registered callback function for every retrieved media tag.
 198  * @param[in] media_id The ID of media info
 199  * @param[in] filter The handle to media filter
 200  * @param[in] callback The callback function to invoke
 201  * @param[in] user_data The user data to be passed to the callback function
 202  * @return 0 on success, otherwise a negative error value.
 203  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 204  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 205  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 206  * @pre This function requires opened connection to content service by media_content_connect().
 207  * @post This function invokes media_tag_cb().
 208  * @see media_content_connect()
 209  * @see #media_tag_cb
 210  */
 211 int media_info_foreach_tag_from_db(const char *media_id, filter_h filter, media_tag_cb callback, void *user_data);
 212
 213 /**
 214  * @brief Gets the number of bookmark for the passed @a filter in the given @a media ID from the media database.
 215  *
 216  * @param[in] media_id The ID of media info
 217  * @param[in] filter The handle to media filter
 218  * @param[out] bookmark_count The count of media tag
 219  * @return 0 on success, otherwise a negative error value.
 220  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 221  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 222  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
 223  * @pre This function requires opened connection to content service by media_content_connect().
 224  * @see media_content_connect()
 225  *
 226  */
 227 int media_info_get_bookmark_count_from_db(const char *media_id, filter_h filter, int *bookmark_count);
 228
 229 /**
 230  * @brief Iterates through the media bookmark in the given @a media @a info from the media database.
 231  * @details This function gets all media bookmark associated with the given @a media and calls registered callback function for every retrieved media bookmark.
 232  * @param[in] media_id The ID of media info
 233  * @param[in] filter The handle to media filter
 234  * @param[in] callback The callback function to invoke
 235  * @param[in] user_data The user data to be passed to the callback function
 236  * @return 0 on success, otherwise a negative error value.
 237  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 238  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 239  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 240  * @pre This function requires opened connection to content service by media_content_connect().
 241  * @post This function invokes media_bookmark_cb().
 242  * @see media_content_connect()
 243  * @see #media_bookmark_cb
 244  */
 245 int media_info_foreach_bookmark_from_db (const char *media_id, filter_h filter, media_bookmark_cb callback, void *user_data);
 246
 247 /**
 248  * @brief Gets image metadata for a given media info.
 249  * @details This function returns an image metadata handle retrieved from the media info.
 250  *
 251  * @remark The @a image handle must be released with image_meta_destroy() by you.
 252  *
 253  * @param [in] media The handle to media info
 254  * @param[out] image A handle to image meta
 255  * @return 0 on success, otherwise a negative error value.
 256  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 257  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 258  * @see image_meta_destroy()
 259  */
 260 int media_info_get_image(media_info_h media, image_meta_h *image);
 261
 262 /**
 263  * @brief Gets video metadata for a given media info.
 264  * @details This function returns a video metadata handle retrieved from the media info handle.
 265  *
 266  * @remark The @a video handle must be released with video_meta_destroy() by you.
 267  *
 268  * @param [in] media The handle to media info
 269  * @param[out] video A handle to the video meta
 270  * @return 0 on success, otherwise a negative error value.
 271  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 272  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 273  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 274  * @see video_meta_destroy()
 275  *
 276  */
 277 int media_info_get_video(media_info_h media, video_meta_h *video);
 278
 279 /**
 280  * @brief Gets audio metadata for a given media info.
 281  * @details This function returns an audio metadata handle retrieved from the media info handle.
 282  *
 283  * @remark The @a audio handle must be released with audio_meta_destroy() by you.
 284  *
 285  * @param [in] media The handle to media info
 286  * @param[out] audio A handle to the audio meta
 287  * @return 0 on success, otherwise a negative error value.
 288  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 289  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 290  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 291  * @see audio_meta_destroy()
 292  */
 293 int media_info_get_audio(media_info_h media, audio_meta_h *audio);
 294
 295 /**
 296  * @brief Gets ID to media info.
 297  *
 298  *
 299  * @param [in] media_id The ID if media info
 300  * @param [out] media_id The ID of media tag
 301  * @return 0 on success, otherwise a negative error value.
 302  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 303  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 304  */
 305 int media_info_get_media_id(media_info_h media, char **media_id);
 306
 307 /**
 308  * @brief Gets path to media info.
 309  *
 310  * @remarks @a path must be released with free() by you.
 311  *
 312  * @param[in] media The handle to media info
 313  * @param[out] path The path of media info
 314  * @return 0 on success, otherwise a negative error value.
 315  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 316  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 317  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 318  *
 319  */
 320 int media_info_get_file_path(media_info_h media, char **path);
 321
 322 /**
 323  * @brief Gets name to media info.
 324  *
 325  * @remarks @a name must be released with free() by you.
 326  *
 327  * @param[in] media The handle to media info
 328  * @param[out] name The name of media info
 329  * @return 0 on success, otherwise a negative error value.
 330  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 331  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 332  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 333  *
 334  */
 335 int media_info_get_display_name(media_info_h media, char **name);
 336
 337 /**
 338  * @brief Gets media info's content type.
 339  *
 340  * @param[in] media The handle to media info
 341  * @param[out] type The type of media content(#media_content_type_e)
 342  * @return 0 on success, otherwise a negative error value.
 343  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 344  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 345  *
 346  */
 347 int media_info_get_media_type(media_info_h media, media_content_type_e *type);
 348
 349 /**
 350  * @brief Gets name to media info.
 351  *
 352  * @remarks @a mime_type must be released with free() by you.
 353  *
 354  * @param[in] media The handle to media info
 355  * @param[out] mime_type The mime type of media info
 356  * @return 0 on success, otherwise a negative error value.
 357  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 358  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 359  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 360  *
 361  */
 362 int media_info_get_mime_type(media_info_h media, char **mime_type);
 363
 364 /**
 365  * @brief Gets media file's size.
 366  *
 367  * @param[in] media The handle to media info
 368  * @param[out] size The type of media content
 369  * @return 0 on success, otherwise a negative error value.
 370  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 371  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 372  *
 373  */
 374 int media_info_get_size(media_info_h media, unsigned long long *size);
 375
 376 /**
 377  * @brief Gets added time.
 378  *
 379  * @param[in] media The handle to media info
 380  * @param[out] added_time The added time
 381  * @return 0 on success, otherwise a negative error value.
 382  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 383  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 384  *
 385  */
 386 int media_info_get_added_time(media_info_h media, time_t *added_time);
 387
 388 /**
 389  * @brief Gets media info's date of modification.
 390  *
 391  * @param[in] media The handle to media info
 392  * @param[out] time The date of modification
 393  * @return 0 on success, otherwise a negative error value.
 394  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 395  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 396  *
 397  */
 398 int media_info_get_modified_time(media_info_h media, time_t *time);
 399
 400 /**
 401  * @brief Gets the thumbnail to media info.
 402  *
 403  * @remarks @a path must be released with free() by you.
 404  *
 405  * @param[in] media The handle to media info
 406  * @param[out] path The path to thumbnail of media info
 407  * @return 0 on success, otherwise a negative error value.
 408  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 409  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 410  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 411  *
 412  */
 413 int media_info_get_thumbnail_path(media_info_h media, char **path);
 414
 415 /**
 416  * @brief Gets the description to media info.
 417  *
 418  * @remarks @a description must be released with free() by you.
 419  *
 420  * @param[in] media The handle to media info
 421  * @param[out] description The description of media info
 422  * @return 0 on success, otherwise a negative error value.
 423  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 424  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 425  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 426  *
 427  */
 428 int media_info_get_description(media_info_h media, char **description);
 429
 430 /**
 431  * @brief Gets media info's longitude.
 432  *
 433  * @param[in] media The handle to media info
 434  * @param[out] longitude The longitude of media info
 435  * @return 0 on success, otherwise a negative error value.
 436  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 437  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 438  *
 439  */
 440 int media_info_get_longitude(media_info_h media, double* longitude);
 441
 442 /**
 443  * @brief Gets media info's latitude.
 444  *
 445  * @param[in] media The handle to media info
 446  * @param[out] latitude The latitude of media info
 447  * @return 0 on success, otherwise a negative error value.
 448  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 449  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 450  *
 451  */
 452 int media_info_get_latitude(media_info_h media, double* latitude);
 453
 454 /**
 455  * @brief Gets media info's altitude of modification.
 456  *
 457  * @param[in] media The handle to media info
 458  * @param[out] altitude The altitude of media info
 459  * @return 0 on success, otherwise a negative error value.
 460  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 461  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 462  *
 463  */
 464 int media_info_get_altitude(media_info_h media, double* altitude);
 465
 466 /**
 467  * @brief Gets media info's rating.
 468  *
 469  * @param[in] media The handle to media info
 470  * @param[out] rating The rating of media info
 471  * @return 0 on success, otherwise a negative error value.
 472  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 473  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 474  *
 475  */
 476 int media_info_get_rating(media_info_h media, int *rating);
 477
 478 /**
 479  * @brief Gets the given media info's favorite status.
 480  *
 481  * @param [in] media The handle to media info
 482  * @param [out] favorite The media favorite status(non zero if favorite, 0 if not favorite)
 483  * @return 0 on success, otherwise a negative error value.
 484  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 485  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 486  *
 487  */
 488 int media_info_get_favorite(media_info_h media, bool* favorite);
 489
 490 /**
 491  * @brief Gets the author to media info.
 492  *
 493  * @remarks @a author must be released with free() by you.
 494  *
 495  * @param[in] media The handle to media info
 496  * @param[out] author The author of media info
 497  * @return 0 on success, otherwise a negative error value.
 498  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 499  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 500  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 501  *
 502  */
 503 int media_info_get_author(media_info_h media, char **author);
 504
 505 /**
 506  * @brief Gets the provider to media info.
 507  *
 508  * @remarks @a provider must be released with free() by you.
 509  *
 510  * @param[in] media The handle to media info
 511  * @param[out] provider The provider of media info
 512  * @return 0 on success, otherwise a negative error value.
 513  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 514  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 515  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 516  *
 517  */
 518 int media_info_get_provider(media_info_h media, char **provider);
 519
 520 /**
 521  * @brief Gets the content name to media info.
 522  *
 523  * @remarks @a content_name must be released with free() by you.
 524  *
 525  * @param[in] media The handle to media info
 526  * @param[out] content_name The content name of media info
 527  * @return 0 on success, otherwise a negative error value.
 528  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 529  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 530  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 531  *
 532  */
 533 int media_info_get_content_name(media_info_h media, char **content_name);
 534
 535 /**
 536  * @brief Gets the provider to media info.
 537  *
 538  * @remarks @a category must be released with free() by you.
 539  *
 540  * @param[in] media The handle to media info
 541  * @param[out] category The category of media info
 542  * @return 0 on success, otherwise a negative error value.
 543  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 544  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 545  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 546  *
 547  */
 548 int media_info_get_category(media_info_h media, char **category);
 549
 550 /**
 551  * @brief Gets the location_tag to media info.
 552  *
 553  * @remarks @a location_tag must be released with free() by you.
 554  *
 555  * @param[in] media The handle to media info
 556  * @param[out] location_tag The location of media info
 557  * @return 0 on success, otherwise a negative error value.
 558  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 559  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 560  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 561  *
 562  */
 563 int media_info_get_location_tag(media_info_h media, char **location_tag);
 564
 565 /**
 566  * @brief Gets the age_rating to media info.
 567  *
 568  * @remarks @a age_rating must be released with free() by you.
 569  *
 570  * @param[in] media The handle to media info
 571  * @param[out] age_rating The age rating of media info
 572  * @return 0 on success, otherwise a negative error value.
 573  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 574  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 575  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 576  *
 577  */
 578 int media_info_get_age_rating(media_info_h media, char **age_rating);
 579
 580 /**
 581  * @brief Gets the keyword to media info.
 582  *
 583  * @remarks @a keyword must be released with free() by you.
 584  *
 585  * @param[in] media The handle to media info
 586  * @param[out] keyword The keyword of media info
 587  * @return 0 on success, otherwise a negative error value.
 588  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 589  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 590  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 591  *
 592  */
 593 int media_info_get_keyword(media_info_h media, char **keyword);
 594
 595 /**
 596  * @brief Checks whether the media is protected via drm.
 597  *
 598  * @param[in] media The handle to media info
 599  * @param[out] is_drm /@a true if the drm media,
 600  *                    /@a false if not drm.
 601  * @return 0 on success, otherwise a negative error value.
 602  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 603  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 604  *
 605  */
 606 int media_info_is_drm(media_info_h media, bool *is_drm);
 607
 608 /**
 609  * @brief Gets media info's storage_type.
 610  *
 611  * @param[in] media The handle to media info
 612  * @param[out] storage_type The storage type of media info
 613  * @return 0 on success, otherwise a negative error value.
 614  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 615  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 616  *
 617  */
 618 int media_info_get_storage_type(media_info_h media, media_content_storage_e *storage_type);
 619
 620 /**
 621  * @brief Gets the media info from the media database.
 622  *
 623  * @details This function creates a new media handle from the media database by the given media_id.
 624  * media info will be created, which is filled with info information.
 625  *
 626  * @remarks @a media must be released with media_tag_destroy() by you.
 627  *
 628  * @param[in] media_id The ID of media info
 629  * @param[out] media The media handle associated with the media ID
 630  * @return 0 on success, otherwise a negative error value.
 631  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 632  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 633  * @pre This function requires opened connection to content service by media_content_connect().
 634  * @see media_content_connect()
 635  * @see media_info_destroy()
 636  *
 637  */
 638 int media_info_get_media_from_db(const char *media_id, media_info_h *media);
 639
 640 /**
 641  * @brief Sets display name to media info.
 642  *
 643  * @param[in] media The handle to media info
 644  * @param[in] display_name The display name of media info
 645  * @return 0 on success, otherwise a negative error value.
 646  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 647  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 648  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 649  * @post media_info_update_to_db()
 650  *
 651  */
 652 int media_info_set_display_name(media_info_h media, const char *display_name);
 653
 654 /**
 655  * @brief Sets description to media info.
 656  *
 657  * @param[in] media The handle to media info
 658  * @param[in] description The description of media info
 659  * @return 0 on success, otherwise a negative error value.
 660  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 661  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 662  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 663  * @post media_info_update_to_db()
 664  *
 665  */
 666 int media_info_set_description(media_info_h media, const char *description);
 667
 668 /**
 669  * @brief Sets longitude to media info.
 670  *
 671  * @param[in] media The handle to media info
 672  * @param[in] longitude The longitude of media info
 673  * @return 0 on success, otherwise a negative error value.
 674  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 675  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 676  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 677  * @post media_info_update_to_db()
 678  *
 679  */
 680 int media_info_set_longitude(media_info_h media, double longitude);
 681
 682 /**
 683  * @brief Sets latitude to media info.
 684  *
 685  * @param[in] media The handle to media info
 686  * @param[in] latitude The latitude of media info
 687  * @return 0 on success, otherwise a negative error value.
 688  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 689  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 690  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 691  * @post media_info_update_to_db()
 692  *
 693  */
 694 int media_info_set_latitude(media_info_h media, double latitude);
 695
 696 /**
 697  * @brief Sets altitude to media info.
 698  *
 699  * @param[in] media The handle to media info
 700  * @param[in] altitude The altitude of media info
 701  * @return 0 on success, otherwise a negative error value.
 702  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 703  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 704  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 705  * @post media_info_update_to_db()
 706  *
 707  */
 708 int media_info_set_altitude(media_info_h media, double altitude);
 709
 710 /**
 711  * @brief Sets rating to media info.
 712  *
 713  * @param[in] media The handle to media info
 714  * @param[in] rating The rating of media info
 715  * @return 0 on success, otherwise a negative error value.
 716  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 717  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 718  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 719  * @post media_info_update_to_db()
 720  *
 721  */
 722 int media_info_set_rating(media_info_h media, int rating);
 723
 724 /**
 725  * @brief Sets favorite to media info.
 726  *
 727  * @param[in] media The handle to media info
 728  * @param[in] favorite The favorite of media info
 729  * @return 0 on success, otherwise a negative error value.
 730  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 731  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 732  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 733  *
 734  */
 735 int media_info_set_favorite(media_info_h media, bool favorite);
 736
 737 /**
 738  * @brief Sets author to media info.
 739  *
 740  * @param[in] media The handle to media info
 741  * @param[in] author The author of media info
 742  * @return 0 on success, otherwise a negative error value.
 743  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 744  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 745  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 746  *
 747  */
 748 int media_info_set_author(media_info_h media, const char *author);
 749
 750 /**
 751  * @brief Sets provider to media info.
 752  *
 753  * @param[in] media The handle to media info
 754  * @param[in] provider The provider of media info
 755  * @return 0 on success, otherwise a negative error value.
 756  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 757  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 758  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 759  *
 760  */
 761 int media_info_set_provider(media_info_h media, const char *provider);
 762
 763 /**
 764  * @brief Sets content name to media info.
 765  *
 766  * @param[in] media The handle to media info
 767  * @param[in] content_name The content name of media info
 768  * @return 0 on success, otherwise a negative error value.
 769  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 770  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 771  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 772  * @post media_info_update_to_db()
 773  *
 774  */
 775 int media_info_set_content_name(media_info_h media, const char *content_name);
 776
 777 /**
 778  * @brief Sets category to media info.
 779  *
 780  * @param[in] media The handle to media info
 781  * @param[in] category The category of media info
 782  * @return 0 on success, otherwise a negative error value.
 783  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 784  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 785  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 786  * @post media_info_update_to_db()
 787  *
 788  */
 789 int media_info_set_category(media_info_h media, const char *category);
 790
 791 /**
 792  * @brief Sets location tag to media info.
 793  *
 794  * @param[in] media The handle to media info
 795  * @param[in] location_tag The location of media info
 796  * @return 0 on success, otherwise a negative error value.
 797  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 798  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 799  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 800  * @post media_info_update_to_db()
 801  *
 802  */
 803 int media_info_set_location_tag(media_info_h media, const char *location_tag);
 804
 805 /**
 806  * @brief Sets age rating to media info.
 807  *
 808  * @param[in] media The handle to media info
 809  * @param[in] age_rating The age rating of media info
 810  * @return 0 on success, otherwise a negative error value.
 811  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 812  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 813  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 814  * @post media_info_update_to_db()
 815  *
 816  */
 817 int media_info_set_age_rating(media_info_h media, const char *age_rating);
 818
 819 /**
 820  * @brief Sets keyword to media info.
 821  *
 822  * @param[in] media The handle to media info
 823  * @param[in] keyword The keyword of media info
 824  * @return 0 on success, otherwise a negative error value.
 825  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 826  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 827  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 828  * @post media_info_update_to_db()
 829  *
 830  */
 831 int media_info_set_keyword(media_info_h media, const char *keyword);
 832
 833 /**
 834  * @brief Updates the media info to the media database.
 835  *
 836  * @details The function updates the given media info in the media database. The function should be called after any change in media, to be updated to the media
 837  * database. For example, after using media_info_set_display_name() for setting the name of the media, media_info_update_to_db() function should be called so as to update
 838  * the given media info attibutes in the media database.
 839  *
 840  * @param[in] media The handle to media info
 841  * @return 0 on success, otherwise a negative error value.
 842  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 843  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 844  * @pre This function requires opened connection to content service by media_content_connect().
 845  * @see media_content_connect()
 846  * @see media_info_set_display_name()
 847  * @see media_info_set_description()
 848  * @see media_info_set_longitude()
 849  * @see media_info_set_latitude()
 850  * @see media_info_set_altitude()
 851  * @see media_info_set_rating()
 852  * @see media_info_set_favorite()
 853  * @see media_info_set_author()
 854  * @see media_info_set_provider()
 855  * @see media_info_set_content_name()
 856  * @see media_info_set_category()
 857  * @see media_info_set_location_tag()
 858  * @see media_info_set_age_rating()
 859  *
 860  */
 861 int media_info_update_to_db(media_info_h media);
 862
 863 /**
 864  * @brief Refresh the metadata of media to media database.
 865  *
 866  * @param[in] media_id The ID of media info
 867  * @return 0 on success, otherwise a negative error value.
 868  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 869  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 870  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
 871  * @pre This function requires opened connection to content service by media_content_connect().
 872  * @see media_content_connect()
 873  *
 874  */
 875 int media_info_refresh_metadata_to_db(const char *media_id);
 876
 877 /**
 878  * @brief Sets added_time to media info.
 879  *
 880  * @param[in] media The handle to media info
 881  * @param[in] added_time The added time of media info
 882  * @return 0 on success, otherwise a negative error value.
 883  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 884  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 885  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 886  * @post media_info_update_to_db()
 887  *
 888  */
 889 int media_info_set_added_time(media_info_h media, time_t added_time);
 890
 891 /**
 892  * @brief Moves the media info to the given destination path in the media database.
 893  *
 894  * @param[in] media The handle to media info
 895  * @param[in] dst_path The path of destination
 896  * @return 0 on success, otherwise a negative error value.
 897  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 898  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 899  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
 900  * @pre This function requires opened connection to content service by media_content_connect().
 901  * @see media_content_connect()
 902  *
 903  */
 904 int media_info_move_to_db(media_info_h media, const char* dst_path);
 905
 906 /**
 907  * @brief Creates a thumbnail image for given the media, asynchronously.
 908  * @details This function creates an thumbnail image for given media item and and calls registered callback function for completion of creating the thumbnail.
 909  * If there already exist a thumbnail for given media, then the path of thumbnail will be return in callback function.
 910  *
 911  * @param[in] media The handle to media info
 912  * @param[in] callback The callback function to invoke
 913  * @param[in] user_data The user data to be passed to the callback function
 914  * @return 0 on success, otherwise a negative error value.
 915  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 916  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 917  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
 918  * @pre This function requires opened connection to content service by media_content_connect().
 919  * @see media_content_connect()
 920  */
 921 int media_info_create_thumbnail(media_info_h media, media_thumbnail_completed_cb callback, void *user_data);
 922
 923
 924 /**
 925  * @brief Cancel to creates a thumbnail image for given the media.
 926  *
 927  * @param[in] media The handle to media info
 928  * @return 0 on success, otherwise a negative error value.
 929  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 930  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 931  * @pre This function requires opened connection to content service by media_content_connect().
 932  * @see media_content_connect()
 933  */
 934 int media_info_cancel_thumbnail(media_info_h media);
 935
 936 /**
 937  * @}
 938  */
 939
 940
 941 #ifdef __cplusplus
 942 }
 943 #endif /* __cplusplus */
 944
 945 #endif /* __TIZEN_MEDIA_INFORMATION_H__ */