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
27extern "C" {
28#endif /* __cplusplus */
29
30/*! Holds all EXIF tags in a single IFD */
31typedef struct _ExifContent        ExifContent;
32typedef 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
40struct _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 */
52ExifContent *exif_content_new     (void);
53ExifContent *exif_content_new_mem (ExifMem *);
54void         exif_content_ref     (ExifContent *content);
55void         exif_content_unref   (ExifContent *content);
56void         exif_content_free    (ExifContent *content);
57
58/*! Add an EXIF tag to an IFD.
59 * If this tag already exists in the IFD, this function does nothing.
60 * \pre The "tag" member of the entry must be set on entry.
61 *
62 * \param[out] c IFD
63 * \param[in] entry EXIF entry to add
64 */
65void         exif_content_add_entry    (ExifContent *c, ExifEntry *entry);
66
67/*! Remove an EXIF tag from an IFD.
68 * If this tag does not exist in the IFD, this function does nothing.
69 *
70 * \param[out] c IFD
71 * \param[in] e EXIF entry to remove
72 */
73void         exif_content_remove_entry (ExifContent *c, ExifEntry *e);
74
75/*! Return the #ExifEntry in this IFD corresponding to the given tag.
76 * This is a pointer into a member of the #ExifContent array and must NOT be
77 * freed or unrefed by the caller.
78 *
79 * \param[in] content EXIF content for an IFD
80 * \param[in] tag EXIF tag to return
81 * \return #ExifEntry of the tag, or NULL on error
82 */
83ExifEntry   *exif_content_get_entry    (ExifContent *content, ExifTag tag);
84
85/*! Fix the IFD to bring it into specification. Call #exif_entry_fix on
86 * each entry in this IFD to fix existing entries, create any new entries
87 * that are mandatory in this IFD but do not yet exist, and remove any
88 * entries that are not allowed in this IFD.
89 *
90 * \param[in,out] c EXIF content for an IFD
91 */
92void         exif_content_fix          (ExifContent *c);
93
94typedef void (* ExifContentForeachEntryFunc) (ExifEntry *, void *user_data);
95
96/*! Executes function on each EXIF tag in this IFD in turn.
97 * The tags will not necessarily be visited in numerical order.
98 *
99 * \param[in,out] content IFD over which to iterate
100 * \param[in] func function to call for each entry
101 * \param[in] user_data data to pass into func on each call
102 */
103void         exif_content_foreach_entry (ExifContent *content,
104					 ExifContentForeachEntryFunc func,
105					 void *user_data);
106
107/*! Return the IFD number in which the given #ExifContent is found.
108 *
109 * \param[in] c an #ExifContent*
110 * \return IFD number, or #EXIF_IFD_COUNT on error
111 */
112ExifIfd exif_content_get_ifd (ExifContent *c);
113
114/*! Return a textual representation of the EXIF data for a tag.
115 *
116 * \param[in] c #ExifContent* for an IFD
117 * \param[in] t #ExifTag to return
118 * \param[out] v char* buffer in which to store value
119 * \param[in] m unsigned int length of the buffer v
120 * \return the v pointer, or NULL on error
121 */
122#define exif_content_get_value(c,t,v,m)					\
123	(exif_content_get_entry (c,t) ?					\
124	 exif_entry_get_value (exif_content_get_entry (c,t),v,m) : NULL)
125
126/*! Dump contents of the IFD to stdout.
127 * This is intended for diagnostic purposes only.
128 *
129 * \param[in] content IFD data
130 * \param[in] indent how many levels deep to indent the data
131 */
132void exif_content_dump  (ExifContent *content, unsigned int indent);
133
134/*! Set the log message object for this IFD.
135 *
136 * \param[in] content IFD
137 * \param[in] log #ExifLog*
138 */
139void exif_content_log   (ExifContent *content, ExifLog *log);
140
141#ifdef __cplusplus
142}
143#endif /* __cplusplus */
144
145#endif /* __EXIF_CONTENT_H__ */
146