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