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 LIBEXIF_EXIF_DATA_H 25 #define LIBEXIF_EXIF_DATA_H 26 27 #ifdef __cplusplus 28 extern "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 */ 38 typedef struct _ExifData ExifData; 39 typedef 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 */ 46 struct _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 unsigned int remove_thumbnail; 60 }; 61 62 /*! Allocate a new #ExifData. The #ExifData contains an empty 63 * #ExifContent for each IFD and the default set of options, 64 * which has #EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS 65 * and #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION set. 66 * 67 * \return allocated #ExifData, or NULL on error 68 */ 69 ExifData *exif_data_new (void); 70 71 /*! Allocate a new #ExifData using the given memory allocator. 72 * The #ExifData contains an empty #ExifContent for each IFD and the default 73 * set of options, which has #EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS and 74 * #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION set. 75 * 76 * \return allocated #ExifData, or NULL on error 77 */ 78 ExifData *exif_data_new_mem (ExifMem *); 79 80 /*! Allocate a new #ExifData and load EXIF data from a JPEG file. 81 * Uses an #ExifLoader internally to do the loading. 82 * 83 * \param[in] path filename including path 84 * \return allocated #ExifData, or NULL on error 85 */ 86 ExifData *exif_data_new_from_file (const char *path); 87 88 /*! Allocate a new #ExifData and load EXIF data from a memory buffer. 89 * 90 * \param[in] data pointer to raw JPEG or EXIF data 91 * \param[in] size number of bytes of data at data 92 * \return allocated #ExifData, or NULL on error 93 */ 94 ExifData *exif_data_new_from_data (const unsigned char *data, 95 unsigned int size); 96 97 /*! Load the #ExifData structure from the raw JPEG or EXIF data in the given 98 * memory buffer. If the EXIF data contains a recognized MakerNote, it is 99 * loaded and stored as well for later retrieval by #exif_data_get_mnote_data. 100 * If the #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION option has been set on this 101 * #ExifData, then the tags are automatically fixed after loading (by calling 102 * #exif_data_fix). 103 * 104 * \param[in,out] data EXIF data 105 * \param[in] d pointer to raw JPEG or EXIF data 106 * \param[in] size number of bytes of data at d 107 */ 108 void exif_data_load_data (ExifData *data, const unsigned char *d, 109 unsigned int size); 110 void exif_data_load_data_general(ExifData* data, const unsigned char* d, 111 unsigned int size); 112 113 /*! Store raw EXIF data representing the #ExifData structure into a memory 114 * buffer. The buffer is allocated by this function and must subsequently be 115 * freed by the caller using the matching free function as used by the #ExifMem 116 * in use by this #ExifData. 117 * 118 * \param[in] data EXIF data 119 * \param[out] d pointer to buffer pointer containing raw EXIF data on return 120 * \param[out] ds pointer to variable to hold the number of bytes of 121 * data at d, or set to 0 on error 122 */ 123 void exif_data_save_data (ExifData *data, unsigned char **d, 124 unsigned int *ds); 125 void exif_data_save_data_general(ExifData* data, unsigned char** d, 126 unsigned int* ds); 127 128 void exif_data_ref (ExifData *data); 129 void exif_data_unref (ExifData *data); 130 void exif_data_free (ExifData *data); 131 132 /*! Return the byte order in use by this EXIF structure. 133 * 134 * \param[in] data EXIF data 135 * \return byte order 136 */ 137 ExifByteOrder exif_data_get_byte_order (ExifData *data); 138 139 /*! Set the byte order to use for this EXIF data. If any tags already exist 140 * (including MakerNote tags) they are are converted to the specified byte 141 * order. 142 * 143 * \param[in,out] data EXIF data 144 * \param[in] order byte order 145 */ 146 void exif_data_set_byte_order (ExifData *data, ExifByteOrder order); 147 148 /*! Return the MakerNote data out of the EXIF data. Only certain 149 * MakerNote formats that are recognized by libexif are supported. 150 * The pointer references a member of the #ExifData structure and must NOT be 151 * freed by the caller. 152 * 153 * \param[in] d EXIF data 154 * \return MakerNote data, or NULL if not found or not supported 155 */ 156 ExifMnoteData *exif_data_get_mnote_data (ExifData *d); 157 158 ExifMem *exif_data_get_priv_mem (ExifData *d); 159 160 void exif_data_set_priv_md (ExifData *d, ExifMnoteData *md); 161 162 /*! Fix the EXIF data to bring it into specification. Call #exif_content_fix 163 * on each IFD to fix existing entries, create any new entries that are 164 * mandatory but do not yet exist, and remove any entries that are not 165 * allowed. 166 * 167 * \param[in,out] d EXIF data 168 */ 169 void exif_data_fix (ExifData *d); 170 171 typedef void (* ExifDataForeachContentFunc) (ExifContent *, void *user_data); 172 173 /*! Execute a function on each IFD in turn. 174 * 175 * \param[in] data EXIF data over which to iterate 176 * \param[in] func function to call for each entry 177 * \param[in] user_data data to pass into func on each call 178 */ 179 void exif_data_foreach_content (ExifData *data, 180 ExifDataForeachContentFunc func, 181 void *user_data); 182 183 /*! Options to configure the behaviour of #ExifData */ 184 typedef enum { 185 /*! Act as though unknown tags are not present */ 186 EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS = 1 << 0, 187 188 /*! Fix the EXIF tags to follow the spec */ 189 EXIF_DATA_OPTION_FOLLOW_SPECIFICATION = 1 << 1, 190 191 /*! Leave the MakerNote alone, which could cause it to be corrupted */ 192 EXIF_DATA_OPTION_DONT_CHANGE_MAKER_NOTE = 1 << 2 193 } ExifDataOption; 194 195 /*! Return a short textual description of the given #ExifDataOption. 196 * 197 * \param[in] o option 198 * \return localized textual description of the option, 199 * or NULL if unknown 200 */ 201 const char *exif_data_option_get_name (ExifDataOption o); 202 203 /*! Return a verbose textual description of the given #ExifDataOption. 204 * 205 * \param[in] o option 206 * \return verbose localized textual description of the option, 207 * or NULL if unknown 208 */ 209 const char *exif_data_option_get_description (ExifDataOption o); 210 211 /*! Set the given option on the given #ExifData. 212 * 213 * \param[in] d EXIF data 214 * \param[in] o option 215 */ 216 void exif_data_set_option (ExifData *d, ExifDataOption o); 217 218 /*! Clear the given option on the given #ExifData. 219 * 220 * \param[in] d EXIF data 221 * \param[in] o option 222 */ 223 void exif_data_unset_option (ExifData *d, ExifDataOption o); 224 225 /*! Set the data type for the given #ExifData. 226 * 227 * \param[in] d EXIF data 228 * \param[in] dt data type 229 */ 230 void exif_data_set_data_type (ExifData *d, ExifDataType dt); 231 232 /*! Return the data type for the given #ExifData. 233 * 234 * \param[in] d EXIF data 235 * \return data type, or #EXIF_DATA_TYPE_UNKNOWN on error 236 */ 237 ExifDataType exif_data_get_data_type (ExifData *d); 238 239 /*! Dump all EXIF data to stdout. 240 * This is intended for diagnostic purposes only. 241 * 242 * \param[in] data EXIF data 243 */ 244 void exif_data_dump (ExifData *data); 245 246 /*! Set the log message object for all IFDs. 247 * 248 * \param[in] data EXIF data 249 * \param[in] log #ExifLog 250 */ 251 void exif_data_log (ExifData *data, ExifLog *log); 252 253 /*! Return an #ExifEntry for the given tag if found in any IFD. 254 * Each IFD is searched in turn and the first containing a tag with 255 * this number is returned. 256 * 257 * \param[in] d #ExifData 258 * \param[in] t #ExifTag 259 * \return #ExifEntry* if found, else NULL if not found 260 */ 261 #define exif_data_get_entry(d,t) \ 262 (exif_content_get_entry(d->ifd[EXIF_IFD_0],t) ? \ 263 exif_content_get_entry(d->ifd[EXIF_IFD_0],t) : \ 264 exif_content_get_entry(d->ifd[EXIF_IFD_1],t) ? \ 265 exif_content_get_entry(d->ifd[EXIF_IFD_1],t) : \ 266 exif_content_get_entry(d->ifd[EXIF_IFD_EXIF],t) ? \ 267 exif_content_get_entry(d->ifd[EXIF_IFD_EXIF],t) : \ 268 exif_content_get_entry(d->ifd[EXIF_IFD_GPS],t) ? \ 269 exif_content_get_entry(d->ifd[EXIF_IFD_GPS],t) : \ 270 exif_content_get_entry(d->ifd[EXIF_IFD_INTEROPERABILITY],t) ? \ 271 exif_content_get_entry(d->ifd[EXIF_IFD_INTEROPERABILITY],t) : NULL) 272 273 #define exif_data_get_entry_ext(d,t) \ 274 (exif_content_get_entry_ext(d->ifd[EXIF_IFD_0],t) ? \ 275 exif_content_get_entry_ext(d->ifd[EXIF_IFD_0],t) : \ 276 exif_content_get_entry_ext(d->ifd[EXIF_IFD_1],t) ? \ 277 exif_content_get_entry_ext(d->ifd[EXIF_IFD_1],t) : \ 278 exif_content_get_entry_ext(d->ifd[EXIF_IFD_EXIF],t) ? \ 279 exif_content_get_entry_ext(d->ifd[EXIF_IFD_EXIF],t) : \ 280 exif_content_get_entry_ext(d->ifd[EXIF_IFD_GPS],t) ? \ 281 exif_content_get_entry_ext(d->ifd[EXIF_IFD_GPS],t) : \ 282 exif_content_get_entry_ext(d->ifd[EXIF_IFD_INTEROPERABILITY],t) ? \ 283 exif_content_get_entry_ext(d->ifd[EXIF_IFD_INTEROPERABILITY],t) : NULL) 284 285 #ifdef __cplusplus 286 } 287 #endif /* __cplusplus */ 288 289 #endif /* !defined(LIBEXIF_EXIF_DATA_H) */ 290