libexif/exif.h

   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  */