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 Iterates through media info from the media database.
  37  * @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.
  38  *  If NULL is passed to the @a filter, no filtering is applied.
  39  * @param[in] filter The handle to media info filter
  40  * @param[in] callback The callback function to invoke
  41  * @param[in] user_data The user data to be passed to the callback function
  42  * @return 0 on success, otherwise a negative error value.
  43  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  44  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  45  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  46  * @pre This function requires opened connection to content service by media_content_connect().
  47  * @post This function invokes media_info_cb().
  48  * @see media_content_connect()
  49  * @see #media_info_cb
  50  * @see media_info_filter_create()
  51  *
  52  */
  53 int media_info_foreach_media_from_db(media_info_filter_h filter, media_info_cb callback, void *user_data);
  54
  55
  56
  57 /**
  58  * @brief Iterates through the media tag  in the given @a media @a info from the media database.
  59  * @details This function gets all media tag associated with the given @a media and calls registered callback function for every retrieved media tag.
  60  * @param[in] media The handle to media info
  61  * @param[in] callback The callback function to invoke
  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_OUT_OF_MEMORY Out of memory
  66  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  67  * @pre This function requires opened connection to content service by media_content_connect().
  68  * @post This function invokes media_tag_cb().
  69  * @see media_content_connect()
  70  * @see #media_tag_cb
  71  */
  72 int media_info_foreach_tag_from_db(media_info_h media, media_tag_cb callback, void *user_data);
  73
  74
  75
  76 /**
  77  * @brief Clones the media info handle.
  78  *
  79  * @details This function copies the media info handle from a source to destination.
  80  * There is no media_info_create() function. The media_info_h is created internally and
  81  * available through media info foreach function such as media_info_foreach_media_from_db().
  82  * To use this handle outside of these foreach functions, use this function.
  83  * @remark The destination handle must be released with media_info_destroy() by you.
  84  *
  85  * @param[out] dst A destination handle to media info
  86  * @param[in] src The source handle to media info
  87  * @return 0 on success, otherwise a negative error value.
  88  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  89  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  90  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  91  * @see media_info_destroy()
  92  * @see audio_album_foreach_media_from_db()
  93  * @see audio_playlist_foreach_media_from_db()
  94  * @see audio_artist_foreach_media_from_db()
  95  * @see audio_author_foreach_media_from_db()
  96  * @see audio_genre_get_media_count_from_db()
  97  * @see media_tag_foreach_media_from_db()
  98  * @see media_info_foreach_media_from_db()
  99  * @see  media_folder_foreach_media_from_db()
 100  *
 101  */
 102 int media_info_clone(media_info_h* dst, media_info_h src);
 103
 104
 105 /**
 106  * @brief Destroys the media info.
 107  * @details The function frees all resources related to the media info handle. This handle
 108  * no longer can be used to perform any operation. New media info handle has to
 109  * be created before next usage.
 110  *
 111  * @param[in] media The handle to media info
 112  * @return 0 on success, otherwise a negative error value.
 113  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 114  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 115  * @pre Get copy of media_info handle by calling media_info_clone()
 116  * @see media_info_clone()
 117  */
 118 int media_info_destroy(media_info_h media);
 119
 120
 121
 122 /**
 123  * @brief Gets path to media info.
 124  *
 125  * @remarks @a path must be released with free() by you.
 126  *
 127  * @param[in] media The handle to media info
 128  * @param[out] path The path of 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  *
 134  */
 135 int media_info_get_file_path(media_info_h media, char **path);
 136
 137 /**
 138  * @brief Gets name to media info.
 139  *
 140  * @remarks @a name must be released with free() by you.
 141  *
 142  * @param[in] media The handle to media info
 143  * @param[out] name The name of media info
 144  * @return 0 on success, otherwise a negative error value.
 145  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 146  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 147  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 148  *
 149  */
 150 int media_info_get_display_name(media_info_h media, char **name);
 151
 152 /**
 153  * @brief Gets the thumbnail to media info.
 154  *
 155  * @remarks @a path must be released with free() by you.
 156  *
 157  * @param[in] media The handle to media info
 158  * @param[out] path The path to thumbnail of media info
 159  * @return 0 on success, otherwise a negative error value.
 160  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 161  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 162  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 163  *
 164  */
 165 int media_info_get_thumbnail_path(media_info_h media, char **path);
 166
 167 /**
 168  * @brief Gets media info's date of modification.
 169  *
 170  * @param[in] media The handle to media info
 171  * @param[out] time The date of modification
 172  * @return 0 on success, otherwise a negative error value.
 173  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 174  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 175  *
 176  */
 177 int media_info_get_date_modified(media_info_h media, time_t *time);
 178
 179 /**
 180  * @brief Gets media info's content type.
 181  *
 182  * @param[in] media The handle to media info
 183  * @param[out] type The type of media content(#media_content_type_e). \n
 184  * @return 0 on success, otherwise a negative error value.
 185  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 186  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 187  *
 188  */
 189 int media_info_get_media_type(media_info_h media, int *type);
 190
 191
 192
 193 /**
 194  * @brief Gets image metadata for a given media info from the media database.
 195  * @details This function returns an image metadata handle retrieved from the media info.
 196  *
 197  * @remark The @a image handle must be released with image_meta_destroy() by you.
 198  *
 199  * @param[in] media The handle to media info
 200  * @param[out] image A handle to image meta
 201  * @return 0 on success, otherwise a negative error value.
 202  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 203  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 204  * @pre This function requires opened connection to content service by media_content_connect().
 205  * @see media_content_connect()
 206  * @see image_meta_destroy()
 207  */
 208 int media_info_get_image_from_db(media_info_h media, image_meta_h* image);
 209
 210 /**
 211  * @brief Gets video metadata for a given media info from the media database.
 212  * @details This function returns a video metadata handle retrieved from the media info handle.
 213  *
 214  * @remark The @a video handle must be released with video_meta_destroy() by you.
 215  *
 216  * @param[in] media The handle to media info
 217  * @param[out] video A handle to the video meta
 218  * @return 0 on success, otherwise a negative error value.
 219  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 220  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 221  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 222  * @pre This function requires opened connection to content service by media_content_connect().
 223  * @see media_content_connect()
 224  * @see video_meta_destroy()
 225  *
 226  */
 227 int media_info_get_video_from_db(media_info_h media, video_meta_h* video);
 228
 229 /**
 230  * @brief Gets audio metadata for a given media info from the media database.
 231  * @details This function returns an audio metadata handle retrieved from the media info handle.
 232  *
 233  * @remark The @a audio handle must be released with audio_meta_destroy() by you.
 234  *
 235  * @param[in] media The handle to media info
 236  * @param[out] audio A handle to the audio meta
 237  * @return 0 on success, otherwise a negative error value.
 238  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 239  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 240  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 241  * @pre This function requires opened connection to content service by media_content_connect().
 242  * @see media_content_connect()
 243  * @see audio_meta_destroy()
 244  */
 245 int media_info_get_audio_from_db(media_info_h media, audio_meta_h* audio);
 246
 247
 248 /**
 249  * @brief Gets the given media info's favorite status.
 250  *
 251  * @param [in] media The handle to media info
 252  * @param [out] favorite The media favorite status(non zero if favorite, 0 if not favorite)
 253  * @return 0 on success, otherwise a negative error value.
 254  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 255  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 256  *
 257  */
 258 int media_info_get_favorite(media_info_h media, int* favorite);
 259
 260
 261 /**
 262  * @brief Updates media info's favorite status to the media database.
 263  *
 264  * @param [in] media The handle to media info
 265  * @param [in] favorite The media favorite status(non zero if favorite, 0 if not favorite)
 266  * @return 0 on success, otherwise a negative error value.
 267  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 268  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 269  * @pre This function requires opened connection to content service by media_content_connect().
 270  * @see media_content_connect()
 271  * @see media_info_meta_get_favorite()
 272  */
 273 int media_info_update_favorite_to_db(media_info_h media, int favorite);
 274
 275
 276
 277 /**
 278  * @brief Inserts media file into the media database.
 279  * @details This function inserts an media item with desired @a type into the content storage.
 280  * Normally, inserting a media file in database is done automatically by media server, without calling this function.
 281  * This function is only called when media server is busy and user needs to get quick result of inserting
 282  * e.g. Taking a photo while media server is busy and user want to see the quick snapshot of the photo taken.
 283  *
 284  * @param[in] type The type of media content
 285  * @param[in] path The path to the media file
 286  * @return 0 on success, otherwise a negative error value.
 287  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 288  * @pre This function requires opened connection to content service by media_content_connect().
 289  * @see #media_content_type_e media_content_connect()
 290  */
 291 int media_info_insert_to_db(media_content_type_e type, const char *path);
 292
 293
 294
 295
 296 /**
 297  * @}
 298  */
 299
 300
 301 #ifdef __cplusplus
 302 }
 303 #endif /* __cplusplus */
 304
 305 #endif /* __TIZEN_MEDIA_INFORMATION_H__ */
 306