2 * Copyright (c) 2011 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.
19 #ifndef __TIZEN_IMAGE_META_H__
20 #define __TIZEN_IMAGE_META_H__
22 #include <media_content_type.h>
26 #endif /* __cplusplus */
29 * @brief This file contains the image metadata API and related functions to proceed with them.
30 * Functions include cloning and destroying the image metadata, getting image metadata such as width, height, \n
31 * orientation, date taken, title, burst shot id and updating image to DB.
35 * @addtogroup CAPI_CONTENT_MEDIA_IMAGE_MODULE
41 * @brief Clones the image metadata.
42 * @details The function copies the image metadata handle from a source to destination.
44 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
46 * @remarks The destination handle must be released with image_meta_destroy().
48 * @param[out] dst The destination handle to the image metadata
49 * @param[in] src The source handle to the image metadata
51 * @return @c 0 on success,
52 * otherwise a negative error value
54 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
55 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
56 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
57 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
59 * @see image_meta_destroy()
61 int image_meta_clone(image_meta_h *dst, image_meta_h src);
64 * @brief Destroys the image metadata.
65 * @details The function frees all resources related to the image metadata handle. This handle
66 * no longer can be used to perform any operation. A new handle has to
67 * be created before next usage.
69 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
71 * @param[in] image The image metadata handle
73 * @return @c 0 on success,
74 * otherwise a negative error value
76 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
77 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
79 * @pre Get a copy of image_meta handle by calling image_meta_clone().
81 * @see image_meta_clone()
83 int image_meta_destroy(image_meta_h image);
86 * @brief Gets the ID of an image.
87 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
89 * @param[in] image The image metadata handle
90 * @param[out] media_id The ID of an image
92 * @return @c 0 on success,
93 * otherwise a negative error value
95 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
96 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
97 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
99 int image_meta_get_media_id(image_meta_h image, char **media_id);
102 * @brief Gets the image width in pixels.
103 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
105 * @param[in] image The image metadata handle
106 * @param[out] width The image width in pixels
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
113 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
115 int image_meta_get_width(image_meta_h image, int *width);
118 * @brief Gets the image height in pixels.
119 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
121 * @param[in] image The image metadata handle
122 * @param[out] height The image height in pixels
124 * @return @c 0 on success,
125 * otherwise a negative error value
127 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
128 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
129 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
131 int image_meta_get_height(image_meta_h image, int *height);
134 * @brief Gets the image orientation.
135 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
137 * @param[in] image The image metadata handle
138 * @param[out] orientation The image orientation
140 * @return @c 0 on success,
141 * otherwise a negative error value
143 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
144 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
145 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
147 int image_meta_get_orientation(image_meta_h image, media_content_orientation_e *orientation);
150 * @brief Gets the image creation time.
151 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
153 * @param[in] image The image metadata handle
154 * @param[out] date_taken The time, when image was taken (in seconds, since the Epoch)
156 * @return @c 0 on success,
157 * otherwise a negative error value
159 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
160 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
161 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
163 int image_meta_get_date_taken(image_meta_h image, char **date_taken);
166 * @brief Gets the burst shot ID.
167 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
169 * @remarks You must release @a burst_id using free().
171 * @param[in] image The image metadata handle
172 * @param[out] burst_id The ID of burst shot\ n
173 * If @a burst_id is @c NULL, this is not burst shot
175 * @return @c 0 on success,
176 * otherwise a negative error value
178 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
179 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
180 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
182 int image_meta_get_burst_id(image_meta_h image, char **burst_id);
185 * @brief Gets the exposure time from exif.
186 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
188 * @remarks @a exposure time must be released with free() by you.
190 * @param[in] image The image metadata handle
191 * @param[out] exposure_time The value of exposure_time, getting from exif
193 * @return 0 on success,
194 * otherwise a negative error value
196 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
197 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
198 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
201 int image_meta_get_exposure_time(image_meta_h image, char **exposure_time);
204 * @brief Gets the fnumber from exif.
205 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
207 * @param[in] image The image metadata handle
208 * @param[out] fnumber The value of fnumber, getting from exif
210 * @return 0 on success,
211 * otherwise a negative error value
213 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
214 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
215 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
218 int image_meta_get_fnumber(image_meta_h image, double *fnumber);
221 * @brief Gets the iso from exif.
222 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
224 * @param[in] image The image metadata handle
225 * @param[out] iso The value of iso, getting from exif
227 * @return 0 on success,
228 * otherwise a negative error value
230 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
231 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
232 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
235 int image_meta_get_iso(image_meta_h image, int *iso);
238 * @brief Gets the model from exif.
239 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
241 * @remarks @a model must be released with free() by you.
243 * @param[in] image The image metadata handle
244 * @param[out] model The value of model, getting from exif
246 * @return 0 on success,
247 * otherwise a negative error value
249 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
250 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
251 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
254 int image_meta_get_model(image_meta_h image, char **model);
257 * @brief Checks whether the media is a burst shot image.
258 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
260 * @param[in] image The image metadata handle
261 * @param[out] is_burst_shot @c true if the media is a burst shot image,
262 * otherwise @c false if the media is not a burst shot image
264 * @return @c 0 on success,
265 * otherwise a negative error value
267 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
268 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
269 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
271 int image_meta_is_burst_shot(image_meta_h image, bool *is_burst_shot);
274 * @deprecated Deprecated since 4.0. This data cannot be saved to the file.
275 * @brief Sets an orientation of the image.
276 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
278 * @param[in] image The image metadata handle
279 * @param[in] orientation The image orientation
281 * @return @c 0 on success,
282 * otherwise a negative error value
284 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
285 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
286 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
288 int image_meta_set_orientation(image_meta_h image, media_content_orientation_e orientation) TIZEN_DEPRECATED_API;
291 * @deprecated Deprecated since 4.0. Related setter functions are deprecated, therefore this function is not needed anymore.
292 * @brief Updates the image to the media database.
294 * @details The function updates the given image meta in the media database. \n
295 * The function should be called after any change in image attributes, to be updated to the media database.
297 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
300 * @privilege %http://tizen.org/privilege/content.write
302 * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
304 * @param[in] image The handle to the image
306 * @return @c 0 on success,
307 * otherwise a negative error value
309 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
310 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
311 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
312 * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
313 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
314 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
315 * @retval #MEDIA_CONTENT_ERROR_NETWORK Network fail
316 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
318 * @pre This function requires opened connection to content service by media_content_connect().
320 * @see media_content_connect()
322 int image_meta_update_to_db(image_meta_h image) TIZEN_DEPRECATED_API;
331 #endif /* __cplusplus */
333 #endif /*__TIZEN_IMAGE_META_H__*/