2 * Copyright (c) 2021 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef __TIZEN_CONTENT_MEDIA_BOOK_H__
19 #define __TIZEN_CONTENT_MEDIA_BOOK_H__
21 #include <media_content_type.h>
25 #endif /* __cplusplus */
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.
34 * @addtogroup CAPI_CONTENT_MEDIA_BOOK_META_MODULE
39 * @brief Clones the book metadata.
40 * @details This function copies the book metadata handle from a source to destination.
44 * @remarks The @a dst should be released using book_meta_destroy().
46 * @param[out] dst The destination handle to the book metadata
47 * @param[in] src The source handle to the book metadata
49 * @return @c 0 on success,
50 * otherwise a negative error value
52 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
53 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
55 * @see media_info_get_book()
56 * @see book_meta_destroy()
58 int book_meta_clone(book_meta_h *dst, book_meta_h src);
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.
68 * @param[in] book The handle to the book metadata
70 * @return @c 0 on success,
71 * otherwise a negative error value
73 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
74 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
76 * @see book_meta_clone()
78 int book_meta_destroy(book_meta_h book);
81 * @brief Gets the ID of the media of the given book metadata.
84 * @remarks The @a media_id should be released using free().
86 * @param[in] book The handle to the book metadata
87 * @param[out] media_id The media ID
89 * @return @c 0 on success,
90 * otherwise a negative error value
92 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
93 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
95 int book_meta_get_media_id(book_meta_h book, char **media_id);
98 * @brief Gets the subject of the given book metadata.
99 * @details If there is no information, @a subject will be NULL.
103 * @remarks The @a subject should be released using free().
105 * @param[in] book The handle to the book metadata
106 * @param[out] subject The subject of the book metadata
108 * @return @c 0 on success,
109 * otherwise a negative error value
111 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
112 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
114 int book_meta_get_subject(book_meta_h book, char **subject);
117 * @brief Gets the author of the given book metadata.
118 * @details If there is no information, @a author will be NULL.
122 * @remarks The @a author should be released using free().
124 * @param[in] book The handle to the book metadata
125 * @param[out] author The author of the book metadata
127 * @return @c 0 on success,
128 * otherwise a negative error value
130 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
131 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
133 int book_meta_get_author(book_meta_h book, char **author);
136 * @brief Gets the publication date of the given book metadata.
137 * @details If there is no information, @a date will be NULL.
141 * @remarks The @a date should be released using free().
143 * @param[in] book The handle to the book metadata
144 * @param[out] date The date of the book metadata
146 * @return @c 0 on success,
147 * otherwise a negative error value
149 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
150 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
152 int book_meta_get_date(book_meta_h book, char **date);
155 * @brief Gets the publisher notice of the given book metadata.
156 * @details If there is no information, @a publisher will be NULL.
160 * @remarks The @a publisher should be released using free().
162 * @param[in] book The handle to the book metadata
163 * @param[out] publisher The publisher of the book metadata
165 * @return @c 0 on success,
166 * otherwise a negative error value
168 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
169 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
171 int book_meta_get_publisher(book_meta_h book, char **publisher);
174 * @brief Gets a list of paths to ebooks which contain a given keyword.
175 * @details This function returns a list of ebook paths including @a keyword.\n
176 * The search scope is title, table of contents, and body.\n
177 * If there are no ebooks matching the criteria, @a path_list will be NULL.
181 * @remarks Each element of @a path_list should be released with free(), then the array itself should be released with free(). \n
182 * %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage. \n
183 * %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
185 * @param[in] keyword Keyword to search for
186 * @param[out] path_list A list of paths to books containing @a keyword
187 * @param[out] len Length of @a path_list
189 * @return @c 0 on success,
190 * otherwise a negative error value
192 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
193 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
194 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
195 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
196 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
198 * @see media_info_get_media_from_db_by_path()
200 int book_meta_get_path_with_keyword(const char *keyword, char ***path_list, unsigned int *len);
208 #endif /* __cplusplus */
210 #endif /*__TIZEN_CONTENT_MEDIA_BOOK_H__*/