1/*! \file exif-data.h 2 * \brief Defines the ExifData type and the associated functions. 3 */ 4/* 5 * \author Lutz Mueller <lutz@users.sourceforge.net> 6 * \date 2001-2005 7 * 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. 12 * 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. 17 * 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. 22 */ 23 24#ifndef __EXIF_DATA_H__ 25#define __EXIF_DATA_H__ 26 27#ifdef __cplusplus 28extern "C" { 29#endif /* __cplusplus */ 30 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> 36 37/*! Represents the entire EXIF data found in an image */ 38typedef struct _ExifData ExifData; 39typedef struct _ExifDataPrivate ExifDataPrivate; 40 41#include <libexif/exif-content.h> 42#include <libexif/exif-mnote-data.h> 43#include <libexif/exif-mem.h> 44 45/*! Represents the entire EXIF data found in an image */ 46struct _ExifData 47{ 48 /*! Data for each IFD */ 49 ExifContent *ifd[EXIF_IFD_COUNT]; 50 51 /*! Pointer to thumbnail image, or NULL if not available */ 52 unsigned char *data; 53 54 /*! Number of bytes in thumbnail image at \c data */ 55 unsigned int size; 56 57 ExifDataPrivate *priv; 58}; 59 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. 64 * 65 * \return allocated #ExifData, or NULL on error 66 */ 67ExifData *exif_data_new (void); 68 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. 73 * 74 * \return allocated #ExifData, or NULL on error 75 */ 76ExifData *exif_data_new_mem (ExifMem *); 77 78/*! Allocate a new #ExifData and load EXIF data from a JPEG file. 79 * Uses an #ExifLoader internally to do the loading. 80 * 81 * \param[in] path filename including path 82 * \return allocated #ExifData, or NULL on error 83 */ 84ExifData *exif_data_new_from_file (const char *path); 85 86/*! Allocate a new #ExifData and load EXIF data from a memory buffer. 87 * 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 91 */ 92ExifData *exif_data_new_from_data (const unsigned char *data, 93 unsigned int size); 94 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 100 * #exif_data_fix). 101 * 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 105 */ 106void exif_data_load_data (ExifData *data, const unsigned char *d, 107 unsigned int size); 108 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. 113 * 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 118 */ 119void exif_data_save_data (ExifData *data, unsigned char **d, 120 unsigned int *ds); 121 122void exif_data_ref (ExifData *data); 123void exif_data_unref (ExifData *data); 124void exif_data_free (ExifData *data); 125 126/*! Return the byte order in use by this EXIF structure. 127 * 128 * \param[in] data EXIF data 129 * \return byte order 130 */ 131ExifByteOrder exif_data_get_byte_order (ExifData *data); 132 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 135 * order. 136 * 137 * \param[in,out] data EXIF data 138 * \param[in] order byte order 139 */ 140void exif_data_set_byte_order (ExifData *data, ExifByteOrder order); 141 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. 146 * 147 * \param[in] d EXIF data 148 * \return MakerNote data, or NULL if not found or not supported 149 */ 150ExifMnoteData *exif_data_get_mnote_data (ExifData *d); 151 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 155 * allowed. 156 * 157 * \param[in,out] d EXIF data 158 */ 159void exif_data_fix (ExifData *d); 160 161typedef void (* ExifDataForeachContentFunc) (ExifContent *, void *user_data); 162 163/*! Execute a function on each IFD in turn. 164 * 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 168 */ 169void exif_data_foreach_content (ExifData *data, 170 ExifDataForeachContentFunc func, 171 void *user_data); 172 173/*! Options to configure the behaviour of #ExifData */ 174typedef enum { 175 /*! Act as though unknown tags are not present */ 176 EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS = 1 << 0, 177 178 /*! Fix the EXIF tags to follow the spec */ 179 EXIF_DATA_OPTION_FOLLOW_SPECIFICATION = 1 << 1, 180 181 /*! Leave the MakerNote alone, which could cause it to be corrupted */ 182 EXIF_DATA_OPTION_DONT_CHANGE_MAKER_NOTE = 1 << 2 183} ExifDataOption; 184 185/*! Return a short textual description of the given #ExifDataOption. 186 * 187 * \param[in] o option 188 * \return localized textual description of the option 189 */ 190const char *exif_data_option_get_name (ExifDataOption o); 191 192/*! Return a verbose textual description of the given #ExifDataOption. 193 * 194 * \param[in] o option 195 * \return verbose localized textual description of the option 196 */ 197const char *exif_data_option_get_description (ExifDataOption o); 198 199/*! Set the given option on the given #ExifData. 200 * 201 * \param[in] d EXIF data 202 * \param[in] o option 203 */ 204void exif_data_set_option (ExifData *d, ExifDataOption o); 205 206/*! Clear the given option on the given #ExifData. 207 * 208 * \param[in] d EXIF data 209 * \param[in] o option 210 */ 211void exif_data_unset_option (ExifData *d, ExifDataOption o); 212 213/*! Set the data type for the given #ExifData. 214 * 215 * \param[in] d EXIF data 216 * \param[in] dt data type 217 */ 218void exif_data_set_data_type (ExifData *d, ExifDataType dt); 219 220/*! Return the data type for the given #ExifData. 221 * 222 * \param[in] d EXIF data 223 * \return data type, or #EXIF_DATA_TYPE_UNKNOWN on error 224 */ 225ExifDataType exif_data_get_data_type (ExifData *d); 226 227/*! Dump all EXIF data to stdout. 228 * This is intended for diagnostic purposes only. 229 * 230 * \param[in] data EXIF data 231 */ 232void exif_data_dump (ExifData *data); 233 234/*! Set the log message object for all IFDs. 235 * 236 * \param[in] data EXIF data 237 * \param[in] log #ExifLog 238 */ 239void exif_data_log (ExifData *data, ExifLog *log); 240 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. 244 * 245 * \param[in] d #ExifData 246 * \param[in] t #ExifTag 247 * \return #ExifEntry* if found, else NULL if not found 248 */ 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) 260 261#ifdef __cplusplus 262} 263#endif /* __cplusplus */ 264 265#endif /* __EXIF_DATA_H__ */ 266