libexif/exif-content.h

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