1 /*! \file exif-content.h 2 * \brief Handling EXIF IFDs 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_CONTENT_H 26 #define LIBEXIF_EXIF_CONTENT_H 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 32 /*! Holds all EXIF tags in a single IFD */ 33 typedef struct _ExifContent ExifContent; 34 typedef struct _ExifContentPrivate ExifContentPrivate; 35 36 #include <libexif/exif-tag.h> 37 #include <libexif/exif-entry.h> 38 #include <libexif/exif-data.h> 39 #include <libexif/exif-log.h> 40 #include <libexif/exif-mem.h> 41 42 struct _ExifContent 43 { 44 ExifEntry **entries; 45 unsigned int count; 46 47 /*! Data containing this content */ 48 ExifData *parent; 49 50 ExifContentPrivate *priv; 51 }; 52 53 /* Lifecycle */ 54 55 /*! Reserve memory for and initialize a new #ExifContent. 56 * 57 * \return new allocated #ExifContent, or NULL on error 58 * 59 * \see exif_content_new_mem, exif_content_unref 60 */ 61 ExifContent *exif_content_new (void); 62 63 /*! Reserve memory for and initialize new #ExifContent using the specified 64 * memory allocator. 65 * 66 * \return new allocated #ExifContent, or NULL on error 67 * 68 * \see exif_content_new, exif_content_unref 69 */ 70 ExifContent *exif_content_new_mem (ExifMem *); 71 72 /*! Increase reference counter for #ExifContent. 73 * 74 * \param[in] content #ExifContent 75 * 76 * \see exif_content_unref 77 */ 78 void exif_content_ref (ExifContent *content); 79 80 /*! Decrease reference counter for #ExifContent. 81 * When the reference count drops to zero, free the content. 82 * 83 * \param[in] content #ExifContent 84 */ 85 void exif_content_unref (ExifContent *content); 86 87 /*! Actually free the #ExifContent. 88 * 89 * \deprecated Should not be called directly. Use #exif_content_ref and 90 * #exif_content_unref instead. 91 * 92 * \param[in] content #ExifContent 93 */ 94 void exif_content_free (ExifContent *content); 95 96 /*! Add an EXIF tag to an IFD. 97 * If this tag already exists in the IFD, this function does nothing. 98 * \pre The "tag" member of the entry must be set on entry. 99 * 100 * \param[out] c IFD 101 * \param[in] entry EXIF entry to add 102 */ 103 void exif_content_add_entry (ExifContent *c, ExifEntry *entry); 104 105 /*! Remove an EXIF tag from an IFD. 106 * If this tag does not exist in the IFD, this function does nothing. 107 * 108 * \param[out] c IFD 109 * \param[in] e EXIF entry to remove 110 */ 111 void exif_content_remove_entry (ExifContent *c, ExifEntry *e); 112 113 /*! Return the #ExifEntry in this IFD corresponding to the given tag. 114 * This is a pointer into a member of the #ExifContent array and must NOT be 115 * freed or unrefed by the caller. 116 * 117 * \param[in] content EXIF content for an IFD 118 * \param[in] tag EXIF tag to return 119 * \return #ExifEntry of the tag, or NULL on error 120 */ 121 ExifEntry *exif_content_get_entry (ExifContent *content, ExifTag tag); 122 ExifEntry *exif_content_get_entry_ext (ExifContent *content, ExifTag tag); 123 ExifEntry *exif_content_get_huawei_makenote_entry (ExifContent *content); 124 125 /*! Fix the IFD to bring it into specification. Call #exif_entry_fix on 126 * each entry in this IFD to fix existing entries, create any new entries 127 * that are mandatory in this IFD but do not yet exist, and remove any 128 * entries that are not allowed in this IFD. 129 * 130 * \param[in,out] c EXIF content for an IFD 131 */ 132 void exif_content_fix (ExifContent *c); 133 134 typedef void (* ExifContentForeachEntryFunc) (ExifEntry *, void *user_data); 135 136 /*! Executes function on each EXIF tag in this IFD in turn. 137 * The tags will not necessarily be visited in numerical order. 138 * 139 * \param[in,out] content IFD over which to iterate 140 * \param[in] func function to call for each entry 141 * \param[in] user_data data to pass into func on each call 142 */ 143 void exif_content_foreach_entry (ExifContent *content, 144 ExifContentForeachEntryFunc func, 145 void *user_data); 146 147 /*! Return the IFD number in which the given #ExifContent is found. 148 * 149 * \param[in] c an #ExifContent* 150 * \return IFD number, or #EXIF_IFD_COUNT on error 151 */ 152 ExifIfd exif_content_get_ifd (ExifContent *c); 153 154 /*! Return a textual representation of the EXIF data for a tag. 155 * 156 * \param[in] c #ExifContent* for an IFD 157 * \param[in] t #ExifTag to return 158 * \param[out] v char* buffer in which to store value 159 * \param[in] m unsigned int length of the buffer v 160 * \return the v pointer, or NULL on error 161 */ 162 #define exif_content_get_value(c,t,v,m) \ 163 (exif_content_get_entry (c,t) ? \ 164 exif_entry_get_value (exif_content_get_entry (c,t),v,m) : NULL) 165 166 /*! Dump contents of the IFD to stdout. 167 * This is intended for diagnostic purposes only. 168 * 169 * \param[in] content IFD data 170 * \param[in] indent how many levels deep to indent the data 171 */ 172 void exif_content_dump (ExifContent *content, unsigned int indent); 173 174 /*! Set the log message object for this IFD. 175 * 176 * \param[in] content IFD 177 * \param[in] log #ExifLog* 178 */ 179 void exif_content_log (ExifContent *content, ExifLog *log); 180 181 #ifdef __cplusplus 182 } 183 #endif /* __cplusplus */ 184 185 #endif /* !defined(LIBEXIF_EXIF_CONTENT_H) */ 186