• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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__ */
266