libexif/exif-data.h

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