[ACR-593] Add attributes(video codec, audio codec)
[platform/core/api/metadata-extractor.git] / include / metadata_extractor.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 #ifndef __TIZEN_MEDIA_METADATA_EXTRACTOR_H__
18 #define __TIZEN_MEDIA_METADATA_EXTRACTOR_H__
19
20
21 #include <tizen.h>
22 #include <metadata_extractor_type.h>
23
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif /* __cplusplus */
28
29 /**
30  * @file metadata_extractor.h
31  * @brief This file contains the multimedia content metadata extractor API and related structure and enumeration.
32  *        It also contains the description of metadata: duration, bitrate, album, artist, author, genre, description, and so on.
33  */
34
35 /**
36  * @addtogroup CAPI_METADATA_EXTRACTOR_MODULE
37  * @{
38  */
39
40 /**
41  * @brief Creates metadata.
42  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
43  * @remarks You must release @a metadata using metadata_extractor_destroy().
44  *
45  * @param[in] metadata The handle to metadata
46  * @return @c 0 on success,
47  *         otherwise a negative error value
48  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
49  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
50  * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
51  * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
52  * @see metadata_extractor_destroy()
53  */
54 int metadata_extractor_create(metadata_extractor_h *metadata);
55
56 /**
57  * @brief Sets the file path to extract.
58  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
59  * @param [in] metadata The handle to metadata
60  * @param [in] path The path to extract metadata
61  * @return @c 0 on success,
62  *         otherwise a negative error value
63  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
64  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
65  * @retval #METADATA_EXTRACTOR_ERROR_FILE_EXISTS File does not exist
66  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
67  * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
68  * @pre Create a metadata handle by calling metadata_extractor_create().
69  * @see metadata_extractor_create()
70  * @see metadata_extractor_destroy()
71  */
72 int metadata_extractor_set_path(metadata_extractor_h metadata, const char *path);
73
74 /**
75  * @brief Sets the buffer to extract.
76  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
77  * @param [in] metadata The handle to metadata
78  * @param [in] buffer The buffer to extract metadata
79  * @param [in] size The buffer size
80  * @return @c 0 on success,
81  *         otherwise a negative error value
82  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
83  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
84  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
85  * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
86  * @pre Create a metadata handle by calling metadata_extractor_create().
87  * @see metadata_extractor_create()
88  * @see metadata_extractor_destroy()
89  */
90 int metadata_extractor_set_buffer(metadata_extractor_h metadata, const void *buffer, int size);
91
92 /**
93  * @brief Destroys metadata.
94  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
95  * @param [in] metadata The handle to metadata
96  * @return @c 0 on success,
97  *         otherwise a negative error value
98  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
99  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
100  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
101  * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
102  * @pre Create a metadata handle by calling metadata_extractor_create().
103  * @see metadata_extractor_create()
104  */
105 int metadata_extractor_destroy(metadata_extractor_h metadata);
106
107 /**
108  * @brief Gets metadata.
109  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
110  *
111  * @remarks You must release @a value using @c free(). \n
112  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
113  *                   For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
114  *
115  * @param[in] metadata The handle to metadata
116  * @param[in] attribute The key attribute name to get
117  * @param[out] value The value of the attribute
118  * @return @c 0 on success,
119  *         otherwise a negative error value
120  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
121  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
122  * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
123  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
124  * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
125  * @pre Set the path to extract by calling metadata_extractor_set_path().
126  * @see metadata_extractor_create()
127  * @see metadata_extractor_destroy()
128  */
129 int metadata_extractor_get_metadata(metadata_extractor_h metadata, metadata_extractor_attr_e attribute, char **value);
130
131 /**
132  * @brief Gets the artwork image in a media file.
133  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
134  *
135  * @remarks You must release @a artwork and @a artwork_mime using @c free(). \n
136  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
137  *                   For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
138  *
139  * @param[in] metadata The handle to metadata
140  * @param[out] artwork The encoded artwork image
141  * @param[out] size The encoded artwork size
142  * @param[out] mime_type The mime type of artwork
143  * @return @c 0 on success,
144  *         otherwise a negative error value
145  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
146  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
147  * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
148  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
149  * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
150  * @pre Set the path to extract by calling metadata_extractor_set_path().
151  * @see metadata_extractor_create()
152  * @see metadata_extractor_destroy()
153  */
154 int metadata_extractor_get_artwork(metadata_extractor_h metadata, void **artwork, int *size, char **mime_type);
155
156 /**
157  * @brief Gets the frame of a video media file.
158  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
159  *
160  * @remarks You must release @a frame using @c free().
161  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
162  *                   For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
163  *
164  * @param[in] metadata The handle to metadata
165  * @param[out] frame The raw frame data in RGB888
166  * @param[out] size The frame data size
167  * @return @c 0 on success,
168  *         otherwise a negative error value
169  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
170  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
171  * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
172  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
173  * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
174  * @pre Set the path to extract by calling metadata_extractor_set_path().
175  * @see metadata_extractor_create()
176  * @see metadata_extractor_destroy()
177  */
178 int metadata_extractor_get_frame(metadata_extractor_h metadata, void **frame, int *size);
179
180 /**
181  * @brief Gets the synclyrics of a media file.
182  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
183  *
184  * @remarks You must release @a lyrics using @c free().
185  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
186  *                   For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
187  *
188  * @param[in] metadata The handle to metadata
189  * @param[in] index The index of time/lyrics to set
190  * @param[out] time_stamp The time information of the index
191  * @param[out] lyrics The lyrics of the index
192  * @return @c 0 on success,
193  *         otherwise a negative error value
194  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
195  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
196  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
197  * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
198  * @pre Set the path to extract by calling metadata_extractor_set_path().
199  * @pre Get the time/lyrics set number by calling metadata_extractor_get_metadata(METADATA_SYNCLYRICS_NUM).
200  * @see metadata_extractor_create()
201  * @see metadata_extractor_destroy()
202  */
203 int metadata_extractor_get_synclyrics(metadata_extractor_h metadata, int index, unsigned long *time_stamp, char **lyrics);
204
205 /**
206  * @brief Gets the frame of a video media.
207  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
208  *
209  * @remarks You must release @a frame using @c free().
210  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
211  *                   For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
212  *
213  * @param[in] metadata The handle to metadata
214  * @param[in] timestamp The timestamp in milliseconds
215  * @param[in] is_accurate If @c true the user can get an accurate frame for the given timestamp,\n
216  *                        otherwise @c false if the user can only get the nearest i-frame of the video rapidly
217  * @param[out] frame The raw frame data in RGB888
218  * @param[out] size The frame data size
219  * @return @c 0 on success,
220  *         otherwise a negative error value
221  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
222  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
223  * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
224  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
225  * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
226  * @pre Set the path to extract by calling metadata_extractor_set_path().
227  * @see metadata_extractor_create()
228  * @see metadata_extractor_destroy()
229  */
230 int metadata_extractor_get_frame_at_time(metadata_extractor_h metadata, unsigned long timestamp, bool is_accurate, void **frame, int *size);
231
232 /**
233  * @}
234  */
235
236
237 #ifdef __cplusplus
238 }
239 #endif /* __cplusplus */
240
241 #endif /* __TIZEN_MEDIA_METADATA_EXTRACTOR_H__ */
242
243