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.
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.
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.
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.
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.
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.
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 as time_t structure.
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.
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 Checks whether the media is a burst shot image.
188 * @param[in] image The image metadata handle
189 * @param[out] is_burst_shot @c true if the media is a burst shot image,
190 * otherwise @c false if the media is not a burst shot image
192 * @return @c 0 on success,
193 * otherwise a negative error value
195 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
196 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
197 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
199 int image_meta_is_burst_shot(image_meta_h image, bool *is_burst_shot);
202 * @brief Sets an orientation of the image.
205 * @param[in] image The image metadata handle
206 * @param[in] orientation The image orientation
208 * @return @c 0 on success,
209 * otherwise a negative error value
211 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
212 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
213 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
215 * @post image_meta_update_to_db()
217 int image_meta_set_orientation(image_meta_h image, media_content_orientation_e orientation);
220 * @brief Updates the image to the media database.
222 * @details The function updates the given image meta in the media database. The function should be called after any change in image attributes, to be updated to the media
223 * database. For example, after using image_meta_set_orientation() for setting the orientation of the image, the image_meta_update_to_db() function should be called so as to update
224 * the given image attributes in the media database.
229 * @privilege %http://tizen.org/privilege/content.write
231 * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
233 * @param[in] image The handle to the image
235 * @return @c 0 on success,
236 * otherwise a negative error value
238 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
239 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
240 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
242 * @pre This function requires opened connection to content service by media_content_connect().
244 * @see media_content_connect()
245 * @see image_meta_set_orientation()
247 int image_meta_update_to_db(image_meta_h image);
256 #endif /* __cplusplus */
258 #endif /*__TIZEN_IMAGE_META_H__*/