include/media_book.h

   1 /*
   2 * Copyright (c) 2021 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_CONTENT_MEDIA_BOOK_H__
  19 #define __TIZEN_CONTENT_MEDIA_BOOK_H__
  20
  21 #include <media_content_type.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif /* __cplusplus */
  26
  27 /**
  28  * @file media_book.h
  29  * @brief This file contains the book metadata API and related functions to proceed with book metadata. \n
  30  *        Description of the book content involves: author, publisher, date, and subject.
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_CONTENT_MEDIA_BOOK_META_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @brief Clones the book metadata.
  40  * @details This function copies the book metadata handle from a source to destination.
  41  *
  42  * @since_tizen 6.5
  43  *
  44  * @remarks The @a dst should be released using book_meta_destroy().
  45  *
  46  * @param[out] dst The destination handle to the book metadata
  47  * @param[in] src The source handle to the book metadata
  48  *
  49  * @return @c 0 on success,
  50  *         otherwise a negative error value
  51  *
  52  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  53  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  54  *
  55  * @see media_info_get_book()
  56  * @see book_meta_destroy()
  57  */
  58 int book_meta_clone(book_meta_h *dst, book_meta_h src);
  59
  60 /**
  61  * @brief Destroys the book metadata.
  62  * @details This function frees all resources related to the book metadata handle. This handle
  63  *          can no longer be used to perform any operations. A new handle has to
  64  *          be created before the next use.
  65  *
  66  * @since_tizen 6.5
  67  *
  68  * @param[in] book The handle to the book metadata
  69  *
  70  * @return @c 0 on success,
  71  *         otherwise a negative error value
  72  *
  73  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  74  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  75  *
  76  * @see book_meta_clone()
  77  */
  78 int book_meta_destroy(book_meta_h book);
  79
  80 /**
  81  * @brief Gets the ID of the media of the given book metadata.
  82  * @since_tizen 6.5
  83  *
  84  * @remarks The @a media_id should be released using free().
  85  *
  86  * @param[in] book The handle to the book metadata
  87  * @param[out] media_id The media ID
  88  *
  89  * @return @c 0 on success,
  90  *         otherwise a negative error value
  91  *
  92  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  93  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  94  */
  95 int book_meta_get_media_id(book_meta_h book, char **media_id);
  96
  97 /**
  98  * @brief Gets the subject of the given book metadata.
  99  * @details If there is no information, @a subject will be NULL.
 100  *
 101  * @since_tizen 6.5
 102  *
 103  * @remarks The @a subject should be released using free().
 104  *
 105  * @param[in] book The handle to the book metadata
 106  * @param[out] subject The subject of the book metadata
 107  *
 108  * @return @c 0 on success,
 109  *         otherwise a negative error value
 110  *
 111  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 112  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 113  */
 114 int book_meta_get_subject(book_meta_h book, char **subject);
 115
 116 /**
 117  * @brief Gets the author of the given book metadata.
 118  * @details If there is no information, @a author will be NULL.
 119  *
 120  * @since_tizen 6.5
 121  *
 122  * @remarks The @a author should be released using free().
 123  *
 124  * @param[in] book The handle to the book metadata
 125  * @param[out] author The author of the book metadata
 126  *
 127  * @return @c 0 on success,
 128  *         otherwise a negative error value
 129  *
 130  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 131  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 132  */
 133 int book_meta_get_author(book_meta_h book, char **author);
 134
 135 /**
 136  * @deprecated Deprecated since 9.0.
 137  * @brief Gets the publication date of the given book metadata.
 138  * @details If there is no information, @a date will be NULL.
 139  *
 140  * @since_tizen 6.5
 141  *
 142  * @remarks The @a date should be released using free().
 143  *
 144  * @param[in] book The handle to the book metadata
 145  * @param[out] date The date of the book metadata
 146  *
 147  * @return @c 0 on success,
 148  *         otherwise a negative error value
 149  *
 150  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 151  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 152  */
 153 int book_meta_get_date(book_meta_h book, char **date) TIZEN_DEPRECATED_API;
 154
 155 /**
 156  * @deprecated Deprecated since 9.0.
 157  * @brief Gets the publisher notice of the given book metadata.
 158  * @details If there is no information, @a publisher will be NULL.
 159  *
 160  * @since_tizen 6.5
 161  *
 162  * @remarks The @a publisher should be released using free().
 163  *
 164  * @param[in] book The handle to the book metadata
 165  * @param[out] publisher The publisher of the book metadata
 166  *
 167  * @return @c 0 on success,
 168  *         otherwise a negative error value
 169  *
 170  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 171  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 172  */
 173 int book_meta_get_publisher(book_meta_h book, char **publisher) TIZEN_DEPRECATED_API;
 174
 175 /**
 176  * @brief Gets a list of paths to ebooks which contain a given keyword.
 177  * @details This function returns a list of ebook paths including @a keyword.\n
 178  *          The search scope is title, table of contents, and body.\n
 179  *          If there are no ebooks matching the criteria, @a path_list will be NULL.
 180  *
 181  * @since_tizen 6.5
 182  *
 183  * @remarks Each element of @a path_list should be released with free(), then the array itself should be released with free(). \n
 184  *          %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage. \n
 185  *          %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 186  *
 187  * @param[in] keyword Keyword to search for
 188  * @param[out] path_list A list of paths to books containing @a keyword
 189  * @param[out] len Length of @a path_list
 190  *
 191  * @return @c 0 on success,
 192  *         otherwise a negative error value
 193  *
 194  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 195  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 196  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 197  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 198  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 199  *
 200  * @see media_info_get_media_from_db_by_path()
 201  */
 202 int book_meta_get_path_with_keyword(const char *keyword, char ***path_list, unsigned int *len);
 203
 204 /**
 205  *@}
 206  */
 207
 208 #ifdef __cplusplus
 209 }
 210 #endif /* __cplusplus */
 211
 212 #endif /*__TIZEN_CONTENT_MEDIA_BOOK_H__*/