2 * \brief Defines the ExifData type and the associated functions.
5 * \author Lutz Mueller <lutz@users.sourceforge.net>
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 * Boston, MA 02110-1301 USA.
24 #ifndef __EXIF_DATA_H__
25 #define __EXIF_DATA_H__
29 #endif /* __cplusplus */
31 #include <libexif/exif-byte-order.h>
32 #include <libexif/exif-data-type.h>
33 #include <libexif/exif-ifd.h>
34 #include <libexif/exif-log.h>
35 #include <libexif/exif-tag.h>
37 /*! Represents the entire EXIF data found in an image */
38 typedef struct _ExifData ExifData;
39 typedef struct _ExifDataPrivate ExifDataPrivate;
41 #include <libexif/exif-content.h>
42 #include <libexif/exif-mnote-data.h>
43 #include <libexif/exif-mem.h>
45 /*! Represents the entire EXIF data found in an image */
48 /*! Data for each IFD */
49 ExifContent *ifd[EXIF_IFD_COUNT];
51 /*! Pointer to thumbnail image, or NULL if not available */
54 /*! Number of bytes in thumbnail image at \c data */
57 ExifDataPrivate *priv;
60 /*! Allocate a new #ExifData. The #ExifData contains an empty
61 * #ExifContent for each IFD and the default set of options,
62 * which has #EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS
63 * and #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION set.
65 * \return allocated #ExifData, or NULL on error
67 ExifData *exif_data_new (void);
69 /*! Allocate a new #ExifData using the given memory allocator.
70 * The #ExifData contains an empty #ExifContent for each IFD and the default
71 * set of options, which has #EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS and
72 * #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION set.
74 * \return allocated #ExifData, or NULL on error
76 ExifData *exif_data_new_mem (ExifMem *);
78 /*! Allocate a new #ExifData and load EXIF data from a JPEG file.
79 * Uses an #ExifLoader internally to do the loading.
81 * \param[in] path filename including path
82 * \return allocated #ExifData, or NULL on error
84 ExifData *exif_data_new_from_file (const char *path);
86 /*! Allocate a new #ExifData and load EXIF data from a memory buffer.
88 * \param[in] data pointer to raw JPEG or EXIF data
89 * \param[in] size number of bytes of data at data
90 * \return allocated #ExifData, or NULL on error
92 ExifData *exif_data_new_from_data (const unsigned char *data,
95 /*! Load the #ExifData structure from the raw JPEG or EXIF data in the given
96 * memory buffer. If the EXIF data contains a recognized MakerNote, it is
97 * loaded and stored as well for later retrieval by #exif_data_get_mnote_data.
98 * If the #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION option has been set on this
99 * #ExifData, then the tags are automatically fixed after loading (by calling
102 * \param[in,out] data EXIF data
103 * \param[in] d pointer to raw JPEG or EXIF data
104 * \param[in] size number of bytes of data at d
106 void exif_data_load_data (ExifData *data, const unsigned char *d,
109 /*! Store raw EXIF data representing the #ExifData structure into a memory
110 * buffer. The buffer is allocated by this function and must subsequently be
111 * freed by the caller using the matching free function as used by the #ExifMem
112 * in use by this #ExifData.
114 * \param[in] data EXIF data
115 * \param[out] d pointer to buffer pointer containing raw EXIF data on return
116 * \param[out] ds pointer to variable to hold the number of bytes of
117 * data at d, or set to 0 on error
119 void exif_data_save_data (ExifData *data, unsigned char **d,
122 void exif_data_ref (ExifData *data);
123 void exif_data_unref (ExifData *data);
124 void exif_data_free (ExifData *data);
126 /*! Return the byte order in use by this EXIF structure.
128 * \param[in] data EXIF data
131 ExifByteOrder exif_data_get_byte_order (ExifData *data);
133 /*! Set the byte order to use for this EXIF data. If any tags already exist
134 * (including MakerNote tags) they are are converted to the specified byte
137 * \param[in,out] data EXIF data
138 * \param[in] order byte order
140 void exif_data_set_byte_order (ExifData *data, ExifByteOrder order);
142 /*! Return the MakerNote data out of the EXIF data. Only certain
143 * MakerNote formats that are recognized by libexif are supported.
144 * The pointer references a member of the #ExifData structure and must NOT be
145 * freed by the caller.
147 * \param[in] d EXIF data
148 * \return MakerNote data, or NULL if not found or not supported
150 ExifMnoteData *exif_data_get_mnote_data (ExifData *d);
152 /*! Fix the EXIF data to bring it into specification. Call #exif_content_fix
153 * on each IFD to fix existing entries, create any new entries that are
154 * mandatory but do not yet exist, and remove any entries that are not
157 * \param[in,out] d EXIF data
159 void exif_data_fix (ExifData *d);
161 typedef void (* ExifDataForeachContentFunc) (ExifContent *, void *user_data);
163 /*! Execute a function on each IFD in turn.
165 * \param[in] data EXIF data over which to iterate
166 * \param[in] func function to call for each entry
167 * \param[in] user_data data to pass into func on each call
169 void exif_data_foreach_content (ExifData *data,
170 ExifDataForeachContentFunc func,
173 /*! Options to configure the behaviour of #ExifData */
175 /*! Act as though unknown tags are not present */
176 EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS = 1 << 0,
178 /*! Fix the EXIF tags to follow the spec */
179 EXIF_DATA_OPTION_FOLLOW_SPECIFICATION = 1 << 1,
181 /*! Leave the MakerNote alone, which could cause it to be corrupted */
182 EXIF_DATA_OPTION_DONT_CHANGE_MAKER_NOTE = 1 << 2
185 /*! Return a short textual description of the given #ExifDataOption.
187 * \param[in] o option
188 * \return localized textual description of the option
190 const char *exif_data_option_get_name (ExifDataOption o);
192 /*! Return a verbose textual description of the given #ExifDataOption.
194 * \param[in] o option
195 * \return verbose localized textual description of the option
197 const char *exif_data_option_get_description (ExifDataOption o);
199 /*! Set the given option on the given #ExifData.
201 * \param[in] d EXIF data
202 * \param[in] o option
204 void exif_data_set_option (ExifData *d, ExifDataOption o);
206 /*! Clear the given option on the given #ExifData.
208 * \param[in] d EXIF data
209 * \param[in] o option
211 void exif_data_unset_option (ExifData *d, ExifDataOption o);
213 /*! Set the data type for the given #ExifData.
215 * \param[in] d EXIF data
216 * \param[in] dt data type
218 void exif_data_set_data_type (ExifData *d, ExifDataType dt);
220 /*! Return the data type for the given #ExifData.
222 * \param[in] d EXIF data
223 * \return data type, or #EXIF_DATA_TYPE_UNKNOWN on error
225 ExifDataType exif_data_get_data_type (ExifData *d);
227 /*! Dump all EXIF data to stdout.
228 * This is intended for diagnostic purposes only.
230 * \param[in] data EXIF data
232 void exif_data_dump (ExifData *data);
234 /*! Set the log message object for all IFDs.
236 * \param[in] data EXIF data
237 * \param[in] log #ExifLog
239 void exif_data_log (ExifData *data, ExifLog *log);
241 /*! Return an #ExifEntry for the given tag if found in any IFD.
242 * Each IFD is searched in turn and the first containing a tag with
243 * this number is returned.
245 * \param[in] d #ExifData
246 * \param[in] t #ExifTag
247 * \return #ExifEntry* if found, else NULL if not found
249 #define exif_data_get_entry(d,t) \
250 (exif_content_get_entry(d->ifd[EXIF_IFD_0],t) ? \
251 exif_content_get_entry(d->ifd[EXIF_IFD_0],t) : \
252 exif_content_get_entry(d->ifd[EXIF_IFD_1],t) ? \
253 exif_content_get_entry(d->ifd[EXIF_IFD_1],t) : \
254 exif_content_get_entry(d->ifd[EXIF_IFD_EXIF],t) ? \
255 exif_content_get_entry(d->ifd[EXIF_IFD_EXIF],t) : \
256 exif_content_get_entry(d->ifd[EXIF_IFD_GPS],t) ? \
257 exif_content_get_entry(d->ifd[EXIF_IFD_GPS],t) : \
258 exif_content_get_entry(d->ifd[EXIF_IFD_INTEROPERABILITY],t) ? \
259 exif_content_get_entry(d->ifd[EXIF_IFD_INTEROPERABILITY],t) : NULL)
263 #endif /* __cplusplus */
265 #endif /* __EXIF_DATA_H__ */