include/media_bookmark.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_CONTENT_MEDIA_BOOKMARK_H__
  20 #define __TIZEN_CONTENT_MEDIA_BOOKMARK_H__
  21
  22 #include <media_content_type.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif /* __cplusplus */
  27
  28 /**
  29  * @file media_bookmark.h
  30  * @brief This file contains API on main functional operations with bookmarks that are related to media resources in the media database. \n
  31  *        Operations include: inserting a new bookmark in media to the media database, removing bookmark from database, \n
  32  *        getting number of bookmarks, cloning and destroying bookmark, getting bookmark`s ID, time marked parameter and thumbnail.
  33  */
  34
  35 /**
  36  * @addtogroup CAPI_CONTENT_MEDIA_BOOKMARK_MODULE
  37  * @{
  38  */
  39
  40 /**
  41  * @deprecated Deprecated since 9.0.
  42  * @brief Inserts a new bookmark in media on the specified time offset to the media database.
  43  * @since_tizen 2.3
  44  *
  45  * @privlevel public
  46  * @privilege %http://tizen.org/privilege/content.write
  47  *
  48  * @param[in] media_id The media ID
  49  * @param[in] time The bookmark time offset (in seconds)
  50  * @param[in] thumbnail_path The thumbnail path of video bookmark\ n
  51  *                           If the media type is audio, then thumbnail is null.
  52  *
  53  * @return @c 0 on success,
  54  *         otherwise a negative error value
  55  *
  56  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  57  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  58  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
  59  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
  60  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
  61  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
  62  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  63  *
  64  * @pre This function requires opened connection to content service by media_content_connect().
  65  *
  66  * @see media_content_connect()
  67  * @see media_bookmark_delete_from_db()
  68  */
  69 int media_bookmark_insert_to_db(const char *media_id, time_t time, const char *thumbnail_path) TIZEN_DEPRECATED_API;
  70
  71 /**
  72  * @deprecated Deprecated since 9.0.
  73  * @brief Removes a media bookmark from the media database.
  74  * @since_tizen 2.3
  75  *
  76  * @privlevel public
  77  * @privilege %http://tizen.org/privilege/content.write
  78  *
  79  * @param[in] bookmark_id The ID of the media bookmark
  80  *
  81  * @return @c 0 on success,
  82  *         otherwise a negative error value
  83  *
  84  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  85  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  86  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
  87  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
  88  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
  89  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
  90  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  91  *
  92  * @pre This function requires opened connection to content service by media_content_connect().
  93  *
  94  * @see media_content_connect()
  95  * @see media_bookmark_insert_to_db()
  96  */
  97 int media_bookmark_delete_from_db(int bookmark_id) TIZEN_DEPRECATED_API;
  98
  99 /**
 100  * @deprecated Deprecated since 9.0.
 101  * @brief Gets the number of bookmarks with an optional filter from the media database.
 102  * @since_tizen 2.3
 103  *
 104  * @param[in] filter The handle to the media filter
 105  * @param[out] bookmark_count The count of the media bookmark
 106  *
 107  * @return @c 0 on success,
 108  *         otherwise a negative error value
 109  *
 110  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 111  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 112  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 113  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 114  *
 115  * @pre This function requires opened connection to content service by media_content_connect().
 116  *
 117  * @see media_content_connect()
 118  */
 119 int media_bookmark_get_bookmark_count_from_db(filter_h filter, int *bookmark_count) TIZEN_DEPRECATED_API;
 120
 121 /**
 122  * @deprecated Deprecated since 9.0.
 123  * @brief Iterates through the bookmarks with an optional filter from the media database.
 124  * @details This function gets all bookmarks associated with the given filter and calls @a callback for every retrieved media bookmark.
 125  *          If @c NULL is passed to the @a filter, then no filtering is applied.
 126  * @since_tizen 4.0
 127  *
 128  * @param[in] filter The handle to the media filter
 129  * @param[in] callback The callback function to be invoked
 130  * @param[in] user_data The user data to be passed to the callback function
 131  *
 132  * @return @c 0 on success,
 133  *         otherwise a negative error value
 134  *
 135  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 136  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 137  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 138  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 139  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 140  *
 141  * @pre This function requires opened connection to content service by media_content_connect().
 142  * @post This function invokes media_bookmark_cb().
 143  *
 144  * @see media_content_connect()
 145  * @see media_bookmark_cb()
 146  * @see media_filter_create()
 147  */
 148 int media_bookmark_foreach_bookmark_from_db(filter_h filter, media_bookmark_cb callback, void *user_data) TIZEN_DEPRECATED_API;
 149
 150 /**
 151  * @deprecated Deprecated since 9.0.
 152  * @brief Clones a media bookmark.
 153  * @details This function copies the media bookmark handle from a source to destination. There is no media_bookmark_create() function.
 154  *          The media_bookmark_h is created internally and available through media bookmark foreach function such as media_info_foreach_bookmark_from_db().
 155  *          To use this handle outside of these foreach functions, use this function.
 156  *
 157  * @since_tizen 2.3
 158  *
 159  * @remarks The @a dst should be released using media_bookmark_destroy().
 160  *
 161  * @param[out] dst The destination handle to the media bookmark
 162  * @param[in] src The source handle to the media bookmark
 163  *
 164  * @return @c 0 on success,
 165  *         otherwise a negative error value
 166  *
 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  *
 171  * @see media_bookmark_destroy()
 172  * @see media_info_foreach_bookmark_from_db()
 173  */
 174 int media_bookmark_clone(media_bookmark_h *dst, media_bookmark_h src) TIZEN_DEPRECATED_API;
 175
 176 /**
 177  * @deprecated Deprecated since 9.0.
 178  * @brief Destroys a media bookmark.
 179  * @details This function frees all the resources related to the bookmark handle. This handle
 180  *          no longer can be used to perform any operations. A new handle has to
 181  *          be created before the next use.
 182  *
 183  * @since_tizen 2.3
 184  *
 185  * @param[in] bookmark The handle to the media bookmark
 186  *
 187  * @return @c 0 on success,
 188  *         otherwise a negative error value
 189  *
 190  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 191  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 192  *
 193  * @pre Get copy of bookmark handle by calling media_bookmark_clone().
 194  *
 195  * @see media_bookmark_clone()
 196  */
 197 int media_bookmark_destroy(media_bookmark_h bookmark) TIZEN_DEPRECATED_API;
 198
 199 /**
 200  * @deprecated Deprecated since 9.0.
 201  * @brief Gets the bookmark ID.
 202  * @since_tizen 2.3
 203  *
 204  * @param[in] bookmark The handle to the media bookmark
 205  * @param[out] bookmark_id The ID of the media bookmark
 206  *
 207  * @return @c 0 on success,
 208  *         otherwise a negative error value
 209  *
 210  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 211  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 212  */
 213 int media_bookmark_get_bookmark_id(media_bookmark_h bookmark, int *bookmark_id) TIZEN_DEPRECATED_API;
 214
 215 /**
 216  * @deprecated Deprecated since 9.0.
 217  * @brief Gets the bookmark time marked parameter.
 218  * @details This function returns time offset in seconds from beginning of the movie on which bookmark
 219  *          was placed.
 220  *
 221  * @since_tizen 2.3
 222  *
 223  * @param[in] bookmark The handle to the media bookmark
 224  * @param[out] marked_time The bookmark time offset (in seconds)
 225  *
 226  * @return @c 0 on success,
 227  *         otherwise a negative error value
 228  *
 229  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 230  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 231  */
 232 int media_bookmark_get_marked_time(media_bookmark_h bookmark, time_t *marked_time) TIZEN_DEPRECATED_API;
 233
 234 /**
 235  * @deprecated Deprecated since 9.0.
 236  * @brief Gets the media bookmark thumbnail.
 237  * @since_tizen 2.3
 238  *
 239  * @remarks The @a path should be released using free().
 240  *
 241  * @param[in] bookmark The handle to the media bookmark
 242  * @param[out] path The thumbnail path of media bookmark
 243  *
 244  * @return @c 0 on success,
 245  *         otherwise a negative error value
 246  *
 247  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 248  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 249  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 250  */
 251 int media_bookmark_get_thumbnail_path(media_bookmark_h bookmark, char **path) TIZEN_DEPRECATED_API;
 252
 253 /**
 254  * @deprecated Deprecated since 9.0.
 255  * @brief Gets the media bookmark name which user set.
 256  * @since_tizen 4.0
 257  *
 258  * @remarks The @a name should be released using free().
 259  *
 260  * @param[in] bookmark The handle to the media bookmark
 261  * @param[out] name The name of media bookmark. If name was not set, empty string is returned.
 262  *                               If User set bookmark name to NULL, name will be empty string also.
 263  *
 264  * @return @c 0 on success,
 265  *         otherwise a negative error value
 266  *
 267  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 268  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 269  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 270  */
 271 int media_bookmark_get_name(media_bookmark_h bookmark, char **name) TIZEN_DEPRECATED_API;
 272
 273 /**
 274  * @deprecated Deprecated since 9.0.
 275  * @brief Sets the media bookmark name.
 276  * @since_tizen 4.0
 277  *
 278  * @param[in] bookmark The handle to the media bookmark
 279  * @param[in] name The name of media bookmark. Can be NULL, empty or non-empty string.
 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  *
 288  * @post media_bookmark_update_to_db()
 289  */
 290 int media_bookmark_set_name(media_bookmark_h bookmark, const char *name) TIZEN_DEPRECATED_API;
 291
 292 /**
 293  * @deprecated Deprecated since 9.0.
 294  * @brief Updates bookmark information to the media database.
 295  * @details The function updates the given bookmark meta in the media database. \n
 296  *          The function should be called after any change in bookmark attributes, to be updated to the media database. \n
 297  *          For example, after using media_bookmark_set_name() for setting the name of the bookmark, \n
 298  *          the media_bookmark_update_to_db() function should be called so as to update the given bookmark attributes in the media database.
 299  * @since_tizen 4.0
 300  *
 301  * @privlevel public
 302  * @privilege %http://tizen.org/privilege/content.write
 303  *
 304  * @remarks Do not call this function in callback function of foreach function like media_info_foreach_bookmark_from_db().
 305  * @param[in] bookmark The handle to the media bookmark
 306  *
 307  * @return @c 0 on success,
 308  *         otherwise a negative error value
 309  *
 310  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 311  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 312  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 313  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 314  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
 315  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
 316  * @retval #MEDIA_CONTENT_ERROR_NETWORK Network fail
 317  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied when Application has no privilege
 318  *
 319  * @pre This function requires opened connection to content service by media_content_connect().
 320  *
 321  * @see media_content_connect()
 322  * @see media_bookmark_set_name()
 323  */
 324 int media_bookmark_update_to_db(media_bookmark_h bookmark) TIZEN_DEPRECATED_API;
 325
 326 /**
 327  * @}
 328  */
 329
 330 #ifdef __cplusplus
 331 }
 332 #endif /* __cplusplus */
 333 #endif /*__TIZEN_CONTENT_MEDIA_BOOKMARK_H__*/