1 /*! \file exif.h exif/exif.h
2 * \brief Dummy header file for documentation purposes
4 * \author Hans Ulrich Niedermann, et. al.
6 * \mainpage The libexif library
8 * \section general_notes General Notes
10 * This documentation is work in progress, as is the code itself.
12 * \section using_libexif Using libexif
14 * \#include <libexif/exif-data.h>
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.
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
28 * libexif is written in C using an object-based style that defines
29 * sets of functions that operate on each data structure.
31 * \section data_structures Primary Data Structures
34 * State maintained by the loader interface while importing EXIF data
35 * from an external file or memory
38 * The entirety of EXIF data found in an image
41 * All EXIF tags in a single IFD
44 * Data found in a single EXIF tag
47 * All data found in the MakerNote tag
50 * State maintained by the logging interface
52 * \section string_conventions String Conventions
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.
63 * \section memory_management Memory Management Patterns
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.
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.
74 * \section thread_safety Thread Safety
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
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.