libexif/exif-entry.h

   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., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #ifndef __EXIF_ENTRY_H__
  24 #define __EXIF_ENTRY_H__
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif /* __cplusplus */
  29
  30 /*! Data found in one EXIF tag */
  31 typedef struct _ExifEntry        ExifEntry;
  32 typedef struct _ExifEntryPrivate ExifEntryPrivate;
  33
  34 #include <libexif/exif-content.h>
  35 #include <libexif/exif-format.h>
  36 #include <libexif/exif-mem.h>
  37
  38 /*! */
  39 struct _ExifEntry {
  40         ExifTag tag;
  41         ExifFormat format;
  42         unsigned long components;
  43
  44         unsigned char *data;
  45         unsigned int size;
  46
  47         /* Content containing this entry */
  48         ExifContent *parent;
  49
  50         ExifEntryPrivate *priv;
  51 };
  52
  53 /* Lifecycle */
  54
  55 /*! Reserve memory for and initialize new #ExifEntry.
  56  * \return new allocated #ExifEntry
  57  */
  58 ExifEntry  *exif_entry_new     (void);
  59
  60 ExifEntry  *exif_entry_new_mem (ExifMem *);
  61
  62 /*! Increase reference counter for #ExifEntry.
  63  *
  64  * \param[in] entry #ExifEntry
  65  */
  66 void        exif_entry_ref     (ExifEntry *entry);
  67
  68 /*! Decrease reference counter for #ExifEntry.
  69  * When the reference count drops to zero, free the entry.
  70  *
  71  * \param[in] entry #ExifEntry
  72  */
  73 void        exif_entry_unref   (ExifEntry *entry);
  74
  75 /*! Actually free the #ExifEntry.
  76  *
  77  * \deprecated Should not be called directly. Use #exif_entry_ref and
  78  *             #exif_entry_unref instead.
  79  *
  80  * \param[in] entry EXIF entry
  81  */
  82 void        exif_entry_free  (ExifEntry *entry);
  83
  84 /*! Initialize an empty #ExifEntry with default data in the correct format
  85  * for the given tag. If the entry is already initialized, this function
  86  * does nothing.
  87  *
  88  * \param[out] e entry to initialize
  89  * \param[in] tag tag number to initialize as
  90  */
  91 void        exif_entry_initialize (ExifEntry *e, ExifTag tag);
  92
  93 /*! When necessary and possible, fix the type or format of the given
  94  * EXIF entry when it is of the wrong type or in an invalid format.
  95  *
  96  * \param[in,out] entry EXIF entry
  97  */
  98 void        exif_entry_fix        (ExifEntry *entry);
  99
 100 /* For your convenience */
 101
 102 /*! Return a textual representation of the value of the EXIF entry.
 103  *
 104  * \warning The character set of the returned string may be in
 105  *          the encoding of the current locale or the native encoding
 106  *          of the camera.
 107  *
 108  * \param[in] entry EXIF entry
 109  * \param[out] val buffer in which to store value
 110  * \param[in] maxlen length of the buffer val
 111  * \return val pointer
 112  */
 113 const char *exif_entry_get_value (ExifEntry *entry, char *val,
 114                                   unsigned int maxlen);
 115
 116 /*! Dump text representation of #ExifEntry to stdout.
 117  * This is intended for diagnostic purposes only.
 118  *
 119  * \param[in] entry EXIF tag data
 120  * \param[in] indent how many levels deep to indent the data
 121  */
 122 void        exif_entry_dump      (ExifEntry *entry, unsigned int indent);
 123
 124 /*! Returns the IFD number of the given #ExifEntry
 125  *
 126  * \param[in] e an #ExifEntry*
 127  * \return #ExifIfd, or #EXIF_IFD_COUNT on error
 128  */
 129 #define exif_entry_get_ifd(e) ((e)?exif_content_get_ifd((e)->parent):EXIF_IFD_COUNT)
 130
 131 #ifdef __cplusplus
 132 }
 133 #endif /* __cplusplus */
 134
 135 #endif /* __EXIF_ENTRY_H__ */