• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*! \file exif.h exif/exif.h
2  * \brief Dummy header file for documentation purposes
3  * \date 2007
4  * \author Hans Ulrich Niedermann, et. al.
5  *
6  * \mainpage The libexif library
7  *
8  * \section general_notes General Notes
9  *
10  * This documentation is work in progress, as is the code itself.
11  *
12  * \section using_libexif Using libexif
13  *
14  * \#include <libexif/exif-data.h>
15  *
16  * libexif provides a libexif.pc file for use with pkgconfig on the
17  * libexif installation. If you are using libtool to build your
18  * package, you can also make use of libexif-uninstalled.pc.
19  *
20  * An application using libexif would typically first create an #ExifLoader to
21  * load EXIF data into memory. From there, it would extract that data as
22  * an #ExifData to start manipulating it. Each IFD is represented by its own
23  * #ExifContent within that #ExifData, which contains all the tag data in
24  * #ExifEntry form.  If the MakerNote data is required, an #ExifMnoteData
25  * can be extracted from the #ExifData and manipulated with the MakerNote
26  * functions.
27  *
28  * libexif is written in C using an object-based style that defines
29  * sets of functions that operate on each data structure.
30  *
31  * \section data_structures Primary Data Structures
32  *
33  * #ExifLoader
34  * State maintained by the loader interface while importing EXIF data
35  * from an external file or memory
36  *
37  * #ExifData
38  * The entirety of EXIF data found in an image
39  *
40  * #ExifContent
41  * All EXIF tags in a single IFD
42  *
43  * #ExifEntry
44  * Data found in a single EXIF tag
45  *
46  * #ExifMnoteData
47  * All data found in the MakerNote tag
48  *
49  * #ExifLog
50  * State maintained by the logging interface
51  *
52  * \section string_conventions String Conventions
53  *
54  * Strings are 8 bit characters ("char*"). When libexif is compiled with
55  * NLS, character set and encoding are as set in the current locale,
56  * except for strings that come directly from the data in EXIF
57  * tags which are generally returned in raw form.  Most EXIF strings are
58  * defined to be plain 7-bit ASCII so this raw form should be acceptable in
59  * any UNIX locale, but some software ignores the specification and
60  * writes 8-bit characters.  It is up to the application to detect this
61  * and deal with it intelligently.
62  *
63  * \section memory_management Memory Management Patterns
64  *
65  * For pointers to data objects, libexif uses reference counting. The
66  * pattern is to use the foo_new() function to create a data object,
67  * foo_ref() to increase the reference counter, and foo_unref() to
68  * decrease the reference counter and possibly free(3)ing the memory.
69  *
70  * Libexif by default relies on the calloc(3), realloc(3), and free(3)
71  * functions, but the libexif user can tell libexif to use their
72  * special memory management functions at runtime.
73  *
74  * \section thread_safety Thread Safety
75  *
76  * libexif is thread safe when the underlying C library is also thread safe.
77  * Some C libraries may require defining a special macro (like _REENTRANT)
78  * to ensure this, or may require linking to a special thread-safe version of
79  * the library.
80  *
81  * The programmer must ensure that each object allocated by libexif is only
82  * used in a single thread at once. For example, an ExifData* allocated
83  * in one thread can't be used in a second thread if there is any chance
84  * that the first thread could use it at the same time. Multiple threads
85  * can use libexif without issues if they never share handles.
86  *
87  */
88