1 /*! \file exif-data.h 2 * \brief Defines the ExifData type and the associated functions. 3 */ 4 /* 5 * Copyright (c) 2001-2008 Lutz Mueller <lutz@users.sourceforge.net> 6 * 7 * This library is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Lesser General Public 9 * License as published by the Free Software Foundation; either 10 * version 2 of the License, or (at your option) any later version. 11 * 12 * This library is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public 18 * License along with this library; if not, write to the 19 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 20 * Boston, MA 02110-1301 USA. 21 * 22 * SPDX-License-Identifier: LGPL-2.0-or-later 23 */ 24 25 #ifndef LIBEXIF_EXIF_DATA_H 26 #define LIBEXIF_EXIF_DATA_H 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 32 #include <libexif/exif-byte-order.h> 33 #include <libexif/exif-data-type.h> 34 #include <libexif/exif-ifd.h> 35 #include <libexif/exif-log.h> 36 #include <libexif/exif-tag.h> 37 38 /*! Represents the entire EXIF data found in an image */ 39 typedef struct _ExifData ExifData; 40 typedef struct _ExifDataPrivate ExifDataPrivate; 41 42 #include <libexif/exif-content.h> 43 #include <libexif/exif-mnote-data.h> 44 #include <libexif/exif-mem.h> 45 46 /*! Represents the entire EXIF data found in an image */ 47 struct _ExifData 48 { 49 /*! Data for each IFD */ 50 ExifContent *ifd[EXIF_IFD_COUNT]; 51 52 /*! Pointer to thumbnail image, or NULL if not available */ 53 unsigned char *data; 54 55 /*! Number of bytes in thumbnail image at \c data */ 56 unsigned int size; 57 58 ExifDataPrivate *priv; 59 60 unsigned int remove_thumbnail; 61 }; 62 63 /*! Allocate a new #ExifData. The #ExifData contains an empty 64 * #ExifContent for each IFD and the default set of options, 65 * which has #EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS 66 * and #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION set. 67 * 68 * \return allocated #ExifData, or NULL on error 69 */ 70 ExifData *exif_data_new (void); 71 72 /*! Allocate a new #ExifData using the given memory allocator. 73 * The #ExifData contains an empty #ExifContent for each IFD and the default 74 * set of options, which has #EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS and 75 * #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION set. 76 * 77 * \return allocated #ExifData, or NULL on error 78 */ 79 ExifData *exif_data_new_mem (ExifMem *); 80 81 /*! Allocate a new #ExifData and load EXIF data from a JPEG file. 82 * Uses an #ExifLoader internally to do the loading. 83 * 84 * \param[in] path filename including path 85 * \return allocated #ExifData, or NULL on error 86 */ 87 ExifData *exif_data_new_from_file (const char *path); 88 89 /*! Allocate a new #ExifData and load EXIF data from a memory buffer. 90 * 91 * \param[in] data pointer to raw JPEG or EXIF data 92 * \param[in] size number of bytes of data at data 93 * \return allocated #ExifData, or NULL on error 94 */ 95 ExifData *exif_data_new_from_data (const unsigned char *data, 96 unsigned int size); 97 98 /*! Load the #ExifData structure from the raw JPEG or EXIF data in the given 99 * memory buffer. If the EXIF data contains a recognized MakerNote, it is 100 * loaded and stored as well for later retrieval by #exif_data_get_mnote_data. 101 * If the #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION option has been set on this 102 * #ExifData, then the tags are automatically fixed after loading (by calling 103 * #exif_data_fix). 104 * 105 * \param[in,out] data EXIF data 106 * \param[in] d pointer to raw JPEG or EXIF data 107 * \param[in] size number of bytes of data at d 108 */ 109 void exif_data_load_data (ExifData *data, const unsigned char *d, 110 unsigned int size); 111 void exif_data_load_data_general(ExifData* data, const unsigned char* d, 112 unsigned int size); 113 114 /*! Store raw EXIF data representing the #ExifData structure into a memory 115 * buffer. The buffer is allocated by this function and must subsequently be 116 * freed by the caller using the matching free function as used by the #ExifMem 117 * in use by this #ExifData. 118 * 119 * \param[in] data EXIF data 120 * \param[out] d pointer to buffer pointer containing raw EXIF data on return 121 * \param[out] ds pointer to variable to hold the number of bytes of 122 * data at d, or set to 0 on error 123 */ 124 void exif_data_save_data (ExifData *data, unsigned char **d, 125 unsigned int *ds); 126 void exif_data_save_data_general(ExifData* data, unsigned char** d, 127 unsigned int* ds); 128 129 void exif_data_ref (ExifData *data); 130 void exif_data_unref (ExifData *data); 131 void exif_data_free (ExifData *data); 132 133 /*! Return the byte order in use by this EXIF structure. 134 * 135 * \param[in] data EXIF data 136 * \return byte order 137 */ 138 ExifByteOrder exif_data_get_byte_order (ExifData *data); 139 140 /*! Set the byte order to use for this EXIF data. If any tags already exist 141 * (including MakerNote tags) they are are converted to the specified byte 142 * order. 143 * 144 * \param[in,out] data EXIF data 145 * \param[in] order byte order 146 */ 147 void exif_data_set_byte_order (ExifData *data, ExifByteOrder order); 148 149 /*! Return the MakerNote data out of the EXIF data. Only certain 150 * MakerNote formats that are recognized by libexif are supported. 151 * The pointer references a member of the #ExifData structure and must NOT be 152 * freed by the caller. 153 * 154 * \param[in] d EXIF data 155 * \return MakerNote data, or NULL if not found or not supported 156 */ 157 ExifMnoteData *exif_data_get_mnote_data (ExifData *d); 158 159 ExifMem *exif_data_get_priv_mem (ExifData *d); 160 161 void exif_data_set_priv_md (ExifData *d, ExifMnoteData *md); 162 163 /*! Fix the EXIF data to bring it into specification. Call #exif_content_fix 164 * on each IFD to fix existing entries, create any new entries that are 165 * mandatory but do not yet exist, and remove any entries that are not 166 * allowed. 167 * 168 * \param[in,out] d EXIF data 169 */ 170 void exif_data_fix (ExifData *d); 171 172 typedef void (* ExifDataForeachContentFunc) (ExifContent *, void *user_data); 173 174 /*! Execute a function on each IFD in turn. 175 * 176 * \param[in] data EXIF data over which to iterate 177 * \param[in] func function to call for each entry 178 * \param[in] user_data data to pass into func on each call 179 */ 180 void exif_data_foreach_content (ExifData *data, 181 ExifDataForeachContentFunc func, 182 void *user_data); 183 184 /*! Options to configure the behaviour of #ExifData */ 185 typedef enum { 186 /*! Act as though unknown tags are not present */ 187 EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS = 1 << 0, 188 189 /*! Fix the EXIF tags to follow the spec */ 190 EXIF_DATA_OPTION_FOLLOW_SPECIFICATION = 1 << 1, 191 192 /*! Leave the MakerNote alone, which could cause it to be corrupted */ 193 EXIF_DATA_OPTION_DONT_CHANGE_MAKER_NOTE = 1 << 2 194 } ExifDataOption; 195 196 /*! Return a short textual description of the given #ExifDataOption. 197 * 198 * \param[in] o option 199 * \return localized textual description of the option, 200 * or NULL if unknown 201 */ 202 const char *exif_data_option_get_name (ExifDataOption o); 203 204 /*! Return a verbose textual description of the given #ExifDataOption. 205 * 206 * \param[in] o option 207 * \return verbose localized textual description of the option, 208 * or NULL if unknown 209 */ 210 const char *exif_data_option_get_description (ExifDataOption o); 211 212 /*! Set the given option on the given #ExifData. 213 * 214 * \param[in] d EXIF data 215 * \param[in] o option 216 */ 217 void exif_data_set_option (ExifData *d, ExifDataOption o); 218 219 /*! Clear the given option on the given #ExifData. 220 * 221 * \param[in] d EXIF data 222 * \param[in] o option 223 */ 224 void exif_data_unset_option (ExifData *d, ExifDataOption o); 225 226 /*! Set the data type for the given #ExifData. 227 * 228 * \param[in] d EXIF data 229 * \param[in] dt data type 230 */ 231 void exif_data_set_data_type (ExifData *d, ExifDataType dt); 232 233 /*! Return the data type for the given #ExifData. 234 * 235 * \param[in] d EXIF data 236 * \return data type, or #EXIF_DATA_TYPE_UNKNOWN on error 237 */ 238 ExifDataType exif_data_get_data_type (ExifData *d); 239 240 /*! Dump all EXIF data to stdout. 241 * This is intended for diagnostic purposes only. 242 * 243 * \param[in] data EXIF data 244 */ 245 void exif_data_dump (ExifData *data); 246 247 /*! Set the log message object for all IFDs. 248 * 249 * \param[in] data EXIF data 250 * \param[in] log #ExifLog 251 */ 252 void exif_data_log (ExifData *data, ExifLog *log); 253 254 /*! Return an #ExifEntry for the given tag if found in any IFD. 255 * Each IFD is searched in turn and the first containing a tag with 256 * this number is returned. 257 * 258 * \param[in] d #ExifData 259 * \param[in] t #ExifTag 260 * \return #ExifEntry* if found, else NULL if not found 261 */ 262 #define exif_data_get_entry(d,t) \ 263 (exif_content_get_entry(d->ifd[EXIF_IFD_0],t) ? \ 264 exif_content_get_entry(d->ifd[EXIF_IFD_0],t) : \ 265 exif_content_get_entry(d->ifd[EXIF_IFD_1],t) ? \ 266 exif_content_get_entry(d->ifd[EXIF_IFD_1],t) : \ 267 exif_content_get_entry(d->ifd[EXIF_IFD_EXIF],t) ? \ 268 exif_content_get_entry(d->ifd[EXIF_IFD_EXIF],t) : \ 269 exif_content_get_entry(d->ifd[EXIF_IFD_GPS],t) ? \ 270 exif_content_get_entry(d->ifd[EXIF_IFD_GPS],t) : \ 271 exif_content_get_entry(d->ifd[EXIF_IFD_INTEROPERABILITY],t) ? \ 272 exif_content_get_entry(d->ifd[EXIF_IFD_INTEROPERABILITY],t) : NULL) 273 274 #define exif_data_get_entry_ext(d,t) \ 275 (exif_content_get_entry_ext(d->ifd[EXIF_IFD_0],t) ? \ 276 exif_content_get_entry_ext(d->ifd[EXIF_IFD_0],t) : \ 277 exif_content_get_entry_ext(d->ifd[EXIF_IFD_1],t) ? \ 278 exif_content_get_entry_ext(d->ifd[EXIF_IFD_1],t) : \ 279 exif_content_get_entry_ext(d->ifd[EXIF_IFD_EXIF],t) ? \ 280 exif_content_get_entry_ext(d->ifd[EXIF_IFD_EXIF],t) : \ 281 exif_content_get_entry_ext(d->ifd[EXIF_IFD_GPS],t) ? \ 282 exif_content_get_entry_ext(d->ifd[EXIF_IFD_GPS],t) : \ 283 exif_content_get_entry_ext(d->ifd[EXIF_IFD_INTEROPERABILITY],t) ? \ 284 exif_content_get_entry_ext(d->ifd[EXIF_IFD_INTEROPERABILITY],t) : NULL) 285 286 /*! Return the number of entries in the MakerNote section of the EXIF data. 287 * 288 * This function retrieves the count of MakerNote entries present in the EXIF data structure. 289 * 290 * \param[in] data EXIF data 291 * \return Number of MakerNote entries 292 */ 293 int exif_data_get_maker_note_entry_count (ExifData *data); 294 #ifdef __cplusplus 295 } 296 #endif /* __cplusplus */ 297 298 #endif /* !defined(LIBEXIF_EXIF_DATA_H) */ 299