1 /*! \file exif-entry.h 2 * \brief Handling EXIF entries 3 */ 4 /* 5 * Copyright (c) 2001 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_ENTRY_H 26 #define LIBEXIF_EXIF_ENTRY_H 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 32 /*! Data found in one EXIF tag. 33 * The #exif_entry_get_value function can provide access to the 34 * formatted contents, or the struct members can be used directly to 35 * access the raw contents. 36 */ 37 typedef struct _ExifEntry ExifEntry; 38 typedef struct _ExifEntryPrivate ExifEntryPrivate; 39 40 #include <libexif/exif-content.h> 41 #include <libexif/exif-format.h> 42 #include <libexif/exif-mem.h> 43 44 /*! Data found in one EXIF tag */ 45 struct _ExifEntry { 46 /*! EXIF tag for this entry */ 47 ExifTag tag; 48 49 /*! Type of data in this entry */ 50 ExifFormat format; 51 52 /*! Number of elements in the array, if this is an array entry. 53 * Contains 1 for non-array data types. */ 54 unsigned long components; 55 56 /*! Pointer to the raw EXIF data for this entry. It is allocated 57 * by #exif_entry_initialize and is NULL beforehand. Data contained 58 * here may be manipulated using the functions in exif-utils.h */ 59 unsigned char *data; 60 61 /*! Number of bytes in the buffer at \c data. This must be no less 62 * than exif_format_get_size(format)*components */ 63 unsigned int size; 64 65 unsigned long offset; 66 67 /*! #ExifContent containing this entry. 68 * \see exif_entry_get_ifd */ 69 ExifContent *parent; 70 71 /*! Internal data to be used by libexif itself */ 72 ExifEntryPrivate *priv; 73 }; 74 75 /* Lifecycle */ 76 77 /*! Reserve memory for and initialize a new #ExifEntry. 78 * No memory is allocated for the \c data element of the returned #ExifEntry. 79 * 80 * \return new allocated #ExifEntry, or NULL on error 81 * 82 * \see exif_entry_new_mem, exif_entry_unref 83 */ 84 ExifEntry *exif_entry_new (void); 85 86 /*! Reserve memory for and initialize new #ExifEntry using the specified 87 * memory allocator. 88 * No memory is allocated for the \c data element of the returned #ExifEntry. 89 * 90 * \return new allocated #ExifEntry, or NULL on error 91 * 92 * \see exif_entry_new, exif_entry_unref 93 */ 94 ExifEntry *exif_entry_new_mem (ExifMem *); 95 96 /*! Increase reference counter for #ExifEntry. 97 * 98 * \param[in] entry #ExifEntry 99 * 100 * \see exif_entry_unref 101 */ 102 void exif_entry_ref (ExifEntry *entry); 103 104 /*! Decrease reference counter for #ExifEntry. 105 * When the reference count drops to zero, free the entry. 106 * 107 * \param[in] entry #ExifEntry 108 */ 109 void exif_entry_unref (ExifEntry *entry); 110 111 /*! Actually free the #ExifEntry. 112 * 113 * \deprecated Should not be called directly. Use #exif_entry_ref and 114 * #exif_entry_unref instead. 115 * 116 * \param[in] entry EXIF entry 117 */ 118 void exif_entry_free (ExifEntry *entry); 119 120 /*! Initialize an empty #ExifEntry with default data in the correct format 121 * for the given tag. If the entry is already initialized, this function 122 * does nothing. 123 * This call allocates memory for the \c data element of the given #ExifEntry. 124 * That memory is freed at the same time as the #ExifEntry. 125 * 126 * \param[out] e entry to initialize 127 * \param[in] tag tag number to initialize as 128 */ 129 void exif_entry_initialize (ExifEntry *e, ExifTag tag); 130 131 /*! Fix the type or format of the given EXIF entry to bring it into spec. 132 * If the data for this EXIF tag is in of the wrong type or is in an invalid 133 * format according to the EXIF specification, then it is converted to make it 134 * valid. This may involve, for example, converting an EXIF_FORMAT_LONG into a 135 * EXIF_FORMAT_SHORT. If the tag is unknown, its value is untouched. 136 * 137 * \note Unfortunately, some conversions are to a type with a more restricted 138 * range, which could have the side effect that the converted data becomes 139 * invalid. This is unlikely as the range of each tag in the standard is 140 * designed to encompass all likely data. 141 * 142 * \param[in,out] entry EXIF entry 143 */ 144 void exif_entry_fix (ExifEntry *entry); 145 146 147 /* For your convenience */ 148 149 /*! Return a localized textual representation of the value of the EXIF entry. 150 * This is meant for display to the user. The format of each tag is subject 151 * to change between locales and in newer versions of libexif. Users who 152 * require the tag data in an unambiguous form should access the data members 153 * of the #ExifEntry structure directly. 154 * 155 * \warning The character set of the returned string may be in 156 * the encoding of the current locale or the native encoding 157 * of the camera. 158 * \bug The EXIF_TAG_XP_* tags are currently always returned in UTF-8, 159 * regardless of locale, and code points above U+FFFF are not 160 * supported. 161 * 162 * \param[in] entry EXIF entry 163 * \param[out] val buffer in which to store value; if entry is valid and 164 * maxlen > 0 then this string will be NUL-terminated 165 * \param[in] maxlen length of the buffer val 166 * \return val pointer 167 */ 168 const char *exif_entry_get_value (ExifEntry *entry, char *val, 169 unsigned int maxlen); 170 171 /*! Dump text representation of #ExifEntry to stdout. 172 * This is intended for diagnostic purposes only. 173 * 174 * \param[in] entry EXIF tag data 175 * \param[in] indent how many levels deep to indent the data 176 */ 177 void exif_entry_dump (ExifEntry *entry, unsigned int indent); 178 179 /*! Return the IFD number of the given #ExifEntry 180 * 181 * \param[in] e an #ExifEntry* 182 * \return #ExifIfd, or #EXIF_IFD_COUNT on error 183 */ 184 #define exif_entry_get_ifd(e) ((e)?exif_content_get_ifd((e)->parent):EXIF_IFD_COUNT) 185 186 #ifdef __cplusplus 187 } 188 #endif /* __cplusplus */ 189 190 #endif /* !defined(LIBEXIF_EXIF_ENTRY_H) */ 191