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 typedef enum{
  46         MAKER_CANON             = 1,
  47         MAKER_OLYMPUS   = 2,
  48         MAKER_PENTAX            = 3,
  49         MAKER_NIKON             = 4,
  50         MAKER_CASIO             = 5,
  51         MAKER_FUJI              = 6,
  52         MAKER_SAMSUNG   = 7
  53 }Manufacturer;
  54
  55 /*! Represents the entire EXIF data found in an image */
  56 struct _ExifData
  57 {
  58         /*! Data for each IFD */
  59         ExifContent *ifd[EXIF_IFD_COUNT];
  60
  61         /*! Pointer to thumbnail image, or NULL if not available */
  62         unsigned char *data;
  63
  64         /*! Number of bytes in thumbnail image at \c data */
  65         unsigned int size;
  66
  67         ExifDataPrivate *priv;
  68 };
  69
  70 /*! Allocate a new #ExifData. The #ExifData contains an empty
  71  * #ExifContent for each IFD and the default set of options,
  72  * which has #EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS
  73  * and #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION set.
  74  *
  75  * \return allocated #ExifData, or NULL on error
  76  */
  77 ExifData *exif_data_new           (void);
  78
  79 /*! Allocate a new #ExifData using the given memory allocator.
  80  * The #ExifData contains an empty #ExifContent for each IFD and the default
  81  * set of options, which has #EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS and
  82  * #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION set.
  83  *
  84  * \return allocated #ExifData, or NULL on error
  85  */
  86 ExifData *exif_data_new_mem       (ExifMem *);
  87
  88 /*! Allocate a new #ExifData and load EXIF data from a JPEG file.
  89  * Uses an #ExifLoader internally to do the loading.
  90  *
  91  * \param[in] path filename including path
  92  * \return allocated #ExifData, or NULL on error
  93  */
  94 ExifData *exif_data_new_from_file (const char *path);
  95
  96 /*! Allocate a new #ExifData and load EXIF data from a memory buffer.
  97  *
  98  * \param[in] data pointer to raw JPEG or EXIF data
  99  * \param[in] size number of bytes of data at data
 100  * \return allocated #ExifData, or NULL on error
 101  */
 102 ExifData *exif_data_new_from_data (const unsigned char *data,
 103                                    unsigned int size);
 104
 105 /*! Load the #ExifData structure from the raw JPEG or EXIF data in the given
 106  * memory buffer. If the EXIF data contains a recognized MakerNote, it is
 107  * loaded and stored as well for later retrieval by #exif_data_get_mnote_data.
 108  * If the #EXIF_DATA_OPTION_FOLLOW_SPECIFICATION option has been set on this
 109  * #ExifData, then the tags are automatically fixed after loading (by calling
 110  * #exif_data_fix).
 111  *
 112  * \param[in,out] data EXIF data
 113  * \param[in] d pointer to raw JPEG or EXIF data
 114  * \param[in] size number of bytes of data at d
 115  */
 116 void      exif_data_load_data (ExifData *data, const unsigned char *d,
 117                                unsigned int size);
 118
 119 /*! Store raw EXIF data representing the #ExifData structure into a memory
 120  * buffer. The buffer is allocated by this function and must subsequently be
 121  * freed by the caller using the matching free function as used by the #ExifMem
 122  * in use by this #ExifData.
 123  *
 124  * \param[in] data EXIF data
 125  * \param[out] d pointer to buffer pointer containing raw EXIF data on return
 126  * \param[out] ds pointer to variable to hold the number of bytes of
 127  *   data at d, or set to 0 on error
 128  */
 129 void      exif_data_save_data (ExifData *data, unsigned char **d,
 130                                unsigned int *ds);
 131
 132 void      exif_data_ref   (ExifData *data);
 133 void      exif_data_unref (ExifData *data);
 134 void      exif_data_free  (ExifData *data);
 135
 136 /*! Return the byte order in use by this EXIF structure.
 137  *
 138  * \param[in] data EXIF data
 139  * \return byte order
 140  */
 141 ExifByteOrder exif_data_get_byte_order  (ExifData *data);
 142
 143 /*! Set the byte order to use for this EXIF data. If any tags already exist
 144  * (including MakerNote tags) they are are converted to the specified byte
 145  * order.
 146  *
 147  * \param[in,out] data EXIF data
 148  * \param[in] order byte order
 149  */
 150 void          exif_data_set_byte_order  (ExifData *data, ExifByteOrder order);
 151
 152 /*! Return the MakerNote data out of the EXIF data.  Only certain
 153  * MakerNote formats that are recognized by libexif are supported.
 154  * The pointer references a member of the #ExifData structure and must NOT be
 155  * freed by the caller.
 156  *
 157  * \param[in] d EXIF data
 158  * \return MakerNote data, or NULL if not found or not supported
 159  */
 160 ExifMnoteData *exif_data_get_mnote_data (ExifData *d);
 161
 162 ExifByteOrder exif_data_get_data_order (ExifData *d);
 163
 164 /*! Fix the EXIF data to bring it into specification. Call #exif_content_fix
 165  * on each IFD to fix existing entries, create any new entries that are
 166  * mandatory but do not yet exist, and remove any entries that are not
 167  * allowed.
 168  *
 169  * \param[in,out] d EXIF data
 170  */
 171 void           exif_data_fix (ExifData *d);
 172
 173 typedef void (* ExifDataForeachContentFunc) (ExifContent *, void *user_data);
 174
 175 /*! Execute a function on each IFD in turn.
 176  *
 177  * \param[in] data EXIF data over which to iterate
 178  * \param[in] func function to call for each entry
 179  * \param[in] user_data data to pass into func on each call
 180  */
 181 void          exif_data_foreach_content (ExifData *data,
 182                                          ExifDataForeachContentFunc func,
 183                                          void *user_data);
 184
 185 /*! Options to configure the behaviour of #ExifData */
 186 typedef enum {
 187         /*! Act as though unknown tags are not present */
 188         EXIF_DATA_OPTION_IGNORE_UNKNOWN_TAGS = 1 << 0,
 189
 190         /*! Fix the EXIF tags to follow the spec */
 191         EXIF_DATA_OPTION_FOLLOW_SPECIFICATION = 1 << 1,
 192
 193         /*! Leave the MakerNote alone, which could cause it to be corrupted */
 194         EXIF_DATA_OPTION_DONT_CHANGE_MAKER_NOTE = 1 << 2
 195 } ExifDataOption;
 196
 197 /*! Return a short textual description of the given #ExifDataOption.
 198  *
 199  * \param[in] o option
 200  * \return localized textual description of the option
 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  */
 209 const char *exif_data_option_get_description (ExifDataOption o);
 210
 211 /*! Set the given option on the given #ExifData.
 212  *
 213  * \param[in] d EXIF data
 214  * \param[in] o option
 215  */
 216 void        exif_data_set_option             (ExifData *d, ExifDataOption o);
 217
 218 /*! Clear the given option on the given #ExifData.
 219  *
 220  * \param[in] d EXIF data
 221  * \param[in] o option
 222  */
 223 void        exif_data_unset_option           (ExifData *d, ExifDataOption o);
 224
 225 /*! Set the data type for the given #ExifData.
 226  *
 227  * \param[in] d EXIF data
 228  * \param[in] dt data type
 229  */
 230 void         exif_data_set_data_type (ExifData *d, ExifDataType dt);
 231
 232 /*! Return the data type for the given #ExifData.
 233  *
 234  * \param[in] d EXIF data
 235  * \return data type, or #EXIF_DATA_TYPE_UNKNOWN on error
 236  */
 237 ExifDataType exif_data_get_data_type (ExifData *d);
 238
 239 /*! Dump all EXIF data to stdout.
 240  * This is intended for diagnostic purposes only.
 241  *
 242  * \param[in] data EXIF data
 243  */
 244 void exif_data_dump (ExifData *data);
 245
 246 /*! Set the log message object for all IFDs.
 247  *
 248  * \param[in] data EXIF data
 249  * \param[in] log #ExifLog
 250  */
 251 void exif_data_log  (ExifData *data, ExifLog *log);
 252
 253 /*!  Create new mnote data and set up related function pointers for particular manufacturer.
 254  *
 255  * \param[in,out] d EXIF data
 256  * \param[in] maker Manufacturer
 257  * \param[in] o option
 258  * \return 1 if  normal, else 0 if abnormal
 259  */
 260 int exif_data_mnote_data_new(ExifData *d,  Manufacturer maker, ExifDataOption o);
 261
 262 /*! Allocate makernote entries memory for particular manufacturer.
 263  *
 264  * \param[in,out] d EXIF Makernote data
 265  * \param[in] maker Manufacturer
 266  * \return 1 if  normal, else 0 if abnormal
 267  */
 268 int exif_data_mnote_set_mem_for_adding_entry(ExifMnoteData *md, Manufacturer maker);
 269
 270 /*! Add a makernote entry for particular manufacturer.
 271  *
 272  * \param[in,out] d EXIF Makernote data
 273  * \param[in] maker Manufacturer
 274  * \param[in] tag Manufacturer specified makernote tag
 275  * \param[in] fmt Exifformat
 276  * \param[in] components The number of components
 277  * \param[in] id Index
 278  * \return 1 if  normal, else 0 if abnormal
 279  */
 280 int exif_data_mnote_set_add_entry(ExifMnoteData *md, Manufacturer maker, int tag, ExifFormat fmt, int components, int id);
 281
 282 /*! Add a makernote entry using subtag information for particular manufacturer.
 283  *
 284  * \param[in,out] d EXIF Makernote data
 285  * \param[in] maker Manufacturer
 286  * \param[in] tag Manufacturer specified makernote tag
 287  * \param[in] fmt Exifformat
 288  * \param[in] components The number of components
 289  * \param[in] subtag1 Manufacturer specified makernote subtag
 290  * \param[in] id1 Index for subtag1
 291  * \param[in] subtag2 Manufacturer specified makernote subtag
 292  * \param[in] id2 Indoex for subtag2
 293  * \param[in] val Integer value
 294  * \return 1 if  normal, else 0 if abnormal
 295 */
 296 int exif_data_mnote_set_add_entry_subtag(ExifMnoteData* md, Manufacturer maker, int tag, ExifFormat fmt, int components, int subtag1, int id1, int subtag2, int id2, int val);
 297
 298 /*! Add a makernote entry using string information for particular manufacturer.
 299  *
 300  * \param[in,out] d EXIF Makernote data
 301  * \param[in] maker Manufacturer
 302  * \param[in] tag Manufacturer specified makernote tag
 303  * \param[in] fmt Exifformat
 304  * \param[in] components The number of components
 305  * \param[in] string String value to be written
 306  * \return 1 if  normal, else 0 if abnormal
 307  */
 308 int exif_data_mnote_set_add_entry_string(ExifMnoteData* md, Manufacturer maker, int tag, ExifFormat fmt, int components, const char* string);
 309
 310 /*! Return an #ExifEntry for the given tag if found in any IFD.
 311  * Each IFD is searched in turn and the first containing a tag with
 312  * this number is returned.
 313  *
 314  * \param[in] d #ExifData
 315  * \param[in] t #ExifTag
 316  * \return #ExifEntry* if found, else NULL if not found
 317  */
 318 #define exif_data_get_entry(d,t)                                        \
 319         (exif_content_get_entry(d->ifd[EXIF_IFD_0],t) ?                 \
 320          exif_content_get_entry(d->ifd[EXIF_IFD_0],t) :                 \
 321          exif_content_get_entry(d->ifd[EXIF_IFD_1],t) ?                 \
 322          exif_content_get_entry(d->ifd[EXIF_IFD_1],t) :                 \
 323          exif_content_get_entry(d->ifd[EXIF_IFD_EXIF],t) ?              \
 324          exif_content_get_entry(d->ifd[EXIF_IFD_EXIF],t) :              \
 325          exif_content_get_entry(d->ifd[EXIF_IFD_GPS],t) ?               \
 326          exif_content_get_entry(d->ifd[EXIF_IFD_GPS],t) :               \
 327          exif_content_get_entry(d->ifd[EXIF_IFD_INTEROPERABILITY],t) ?  \
 328          exif_content_get_entry(d->ifd[EXIF_IFD_INTEROPERABILITY],t) : NULL)
 329
 330 #ifdef __cplusplus
 331 }
 332 #endif /* __cplusplus */
 333
 334 #endif /* __EXIF_DATA_H__ */