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_MEDIA_BOOKMARK_H__
  20 #define __TIZEN_MEDIA_BOOKMARK_H__
  21
  22 #include <media_content_type.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif /* __cplusplus */
  27
  28
  29 /**
  30  * @addtogroup CAPI_CONTENT_MEDIA_BOOKMARK_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief Inserts a new bookmark in media on specified time offset to the media database.
  36  *
  37  * @param [in] media_id The id of media
  38  * @param [in] time The bookmark time offset(in seconds)
  39  * @param [in] thumbnail_path The thumbnail path of video bookmark. If the media type is audio, then thumbnail is null.
  40  * @return 0 on success, otherwise a negative error value.
  41  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  42  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  43  * @pre This function requires opened connection to content service by media_content_connect().
  44  * @see media_content_connect()
  45  * @see media_bookmark_delete_from_db()
  46  *
  47  */
  48 int media_bookmark_insert_to_db(const char *media_id, time_t time, const char *thumbnail_path);
  49
  50 /**
  51  * @brief Removes media bookmark from the media database.
  52  *
  53  * @param [in] bookmark The handle to media bookmark
  54  * @return 0 on success, otherwise a negative error value.
  55  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  56  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  57  * @pre This function requires opened connection to content service by media_content_connect().
  58  * @see media_content_connect()
  59  * @see media_bookmark_insert_to_db()
  60  *
  61  */
  62 int media_bookmark_delete_from_db(int bookmark_id);
  63
  64 /**
  65  * @brief Gets number of bookmark with optional filter from media database.
  66  *
  67  * @param [in]  filter  The handle to media filter
  68  * @param [out] bookmark_count The count of media bookmark
  69  * @return 0 on success, otherwise a negative error value.
  70  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  71  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  72  * @pre This function requires opened connection to content service by media_content_connect().
  73  * @see media_content_connect()
  74  */
  75 int media_bookmark_get_bookmark_count_from_db(filter_h filter, int *bookmark_count);
  76
  77 /**
  78  * @brief Clones media bookmark.
  79  * @details This function copies the media bookmark handle from a source to destination. There is no media_bookmark_create() function.
  80  * The media_bookmark_h is created internally and available through media bookmark foreach function such as media_info_foreach_bookmark_from_db().
  81  * To use this handle outside of these foreach functions, use this function.
  82  *
  83  * @remark The destination handle must be released with media_bookmark_destroy() by you.
  84  *
  85  * @param [out] dst A destination handle to media bookmark
  86  * @param [in] src The source handle to media bookmark
  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_bookmark_destroy()
  92  * @see media_info_foreach_bookmark_from_db()
  93  *
  94  */
  95 int media_bookmark_clone(media_bookmark_h *dst, media_bookmark_h src);
  96
  97 /**
  98  * @brief Destroys media bookmark.
  99  * @details Function frees all resources related to bookmark handle. This handle
 100  * no longer can be used to perform any operation. A new handle has to
 101  * be created before the next use.
 102  *
 103  * @param [in] bookmark The handle to media bookmark
 104  * @return 0 on success, otherwise a negative error value.
 105  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 106  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 107  * @pre Get copy of bookmark handle by calling media_bookmark_clone()
 108  * @see media_bookmark_clone()
 109  */
 110 int media_bookmark_destroy(media_bookmark_h bookmark);
 111
 112 /**
 113  * @brief Gets bookmark's id.
 114  *
 115  * @param [in] bookmark The handle to media bookmark
 116  * @param [out] bookmark_id The id of media bookmark
 117  * @return 0 on success, otherwise a negative error value.
 118  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 119  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 120  */
 121 int media_bookmark_get_bookmark_id(media_bookmark_h bookmark, int *bookmark_id);
 122
 123 /**
 124  * @brief Gets bookmark's time marked parameter.
 125  * @details Function returns time offset in milliseconds from beginning of the movie on which bookmark
 126  * was placed.
 127  *
 128  * @param [in] bookmark The handle to media bookmark
 129  * @param [out] marked_time The bookmark time offset(in milliseconds)
 130  * @return 0 on success, otherwise a negative error value.
 131  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 132  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 133  */
 134 int media_bookmark_get_marked_time(media_bookmark_h bookmark, time_t *marked_time);
 135
 136 /**
 137  * @brief Gets the media bookmark's thumbnail.
 138  *
 139  * @remarks @a path must be released with free() by you.
 140  *
 141  * @param [in] bookmark The handle to media bookmark
 142  * @param [out] path The thumbnail path of media bookmark
 143  * @return 0 on success, otherwise a negative error value.
 144  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 145  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 146  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 147  */
 148 int media_bookmark_get_thumbnail_path(media_bookmark_h bookmark, char **path);
 149
 150
 151 /**
 152  * @}
 153  */
 154
 155 #ifdef __cplusplus
 156 }
 157 #endif /* __cplusplus */
 158 #endif /*__TIZEN_MEDIA_BOOKMARK_H__*/