Exiv2: Exiv2::ExifData Class Reference

# Exiv2::ExifData Class Reference

A container for Exif data. This is a top-level class of the Exiv2 library. The container holds Exifdatum objects. More...

`#include <exif.hpp>`

Collaboration diagram for Exiv2::ExifData:
[legend]

List of all members.

## Public Types
typedef ExifMetadata::iterator | iterator
| ExifMetadata iterator type.
typedef ExifMetadata::const_iterator | const_iterator
| ExifMetadata const iterator type.
## Public Member Functions
Creators
| ExifData ()
| Default constructor.
| ExifData (const ExifData &rhs)
| Copy constructor (Todo: copy image data also).
| ~ExifData ()
| Destructor.
Manipulators
ExifData & | operator= (const ExifData &rhs)
| Assignment operator (Todo: assign image data also).
int | load (const byte *buf, long len)
| Load the Exif data from a byte buffer. The data buffer must start with the TIFF header. This method is deprecated. Use ImageFactory::open() instead.
DataBuf | copy ()
| Write the Exif data to a data buffer, which is returned. The caller owns this copy and DataBuf ensures that it will be deleted. The copied data starts with the TIFF header.
Exifdatum & | operator[] (const std::string &key)
| Returns a reference to the Exifdatum that is associated with a particular key. If ExifData does not already contain such an Exifdatum, operator[] adds object Exifdatum(key).
void | add (Entries::const_iterator begin, Entries::const_iterator end, ByteOrder byteOrder)
| Add all (IFD) entries in the range from iterator position begin to iterator position end to the Exif metadata. No duplicate checks are performed, i.e., it is possible to add multiple metadata with the same key.
void | add (const ExifKey &key, const Value *pValue)
| Add an Exifdatum from the supplied key and value pair. This method copies (clones) key and value. No duplicate checks are performed, i.e., it is possible to add multiple metadata with the same key.
void | add (const Exifdatum &exifdatum)
| Add a copy of the exifdatum to the Exif metadata. No duplicate checks are performed, i.e., it is possible to add multiple metadata with the same key.
iterator | erase (iterator pos)
| Delete the Exifdatum at iterator position pos, return the position of the next exifdatum. Note that iterators into the metadata, including pos, are potentially invalidated by this call.
void | clear ()
| Delete all Exifdatum instances resulting in an empty container. Note that this also removes thumbnails.
void | sortByKey ()
| Sort metadata by key.
void | sortByTag ()
| Sort metadata by tag.
iterator | begin ()
| Begin of the metadata.
iterator | end ()
| End of the metadata.
iterator | findKey (const ExifKey &key)
| Find the first Exifdatum with the given key, return an iterator to it.
iterator | findIfdIdIdx (IfdId ifdId, int idx)
| Find the first Exifdatum with the given ifdId and idx, return an iterator to it.
void | setJpegThumbnail (const std::string &path, URational xres, URational yres, uint16_t unit)
| Set the Exif thumbnail to the Jpeg image path. Set XResolution, YResolution and ResolutionUnit to xres, yres and unit, respectively.
void | setJpegThumbnail (const byte *buf, long size, URational xres, URational yres, uint16_t unit)
| Set the Exif thumbnail to the Jpeg image pointed to by buf, and size size. Set XResolution, YResolution and ResolutionUnit to xres, yres and unit, respectively.
void | setJpegThumbnail (const std::string &path)
| Set the Exif thumbnail to the Jpeg image path.
void | setJpegThumbnail (const byte *buf, long size)
| Set the Exif thumbnail to the Jpeg image pointed to by buf, and size size.
long | eraseThumbnail ()
| Delete the thumbnail from the Exif data. Removes all Exif.Thumbnail.*, i.e., IFD1 metadata.
Accessors
const_iterator | begin () const
| Begin of the metadata.
const_iterator | end () const
| End of the metadata.
const_iterator | findKey (const ExifKey &key) const
| Find the first Exifdatum with the given key, return a const iterator to it.
const_iterator | findIfdIdIdx (IfdId ifdId, int idx) const
| Find the first Exifdatum with the given ifdId and idx, return an iterator to it.
bool | empty () const
| Return true if there is no Exif metadata.
long | count () const
| Get the number of metadata entries.
ByteOrder | byteOrder () const
| Returns the byte order. Default is little endian.
int | writeThumbnail (const std::string &path) const
| Write the thumbnail image to a file. A filename extension is appended to path according to the image type of the thumbnail, so path should not include an extension. This will overwrite an existing file of the same name.
DataBuf | copyThumbnail () const
| Return the thumbnail image in a DataBuf. The caller owns the data buffer and DataBuf ensures that it will be deleted.
const char * | thumbnailFormat () const
| Return a short string describing the format of the Exif thumbnail ("TIFF", "JPEG").
const char * | thumbnailExtension () const
| Return the file extension for the Exif thumbnail depending on the format (".tif", ".jpg").
Thumbnail::AutoPtr | getThumbnail () const
| Return a thumbnail object of the correct type, corresponding to the current Exif data. Caller owns this object and the auto pointer ensures that it will be deleted.

## Detailed Description

A container for Exif data. This is a top-level class of the Exiv2 library. The container holds Exifdatum objects.

Provide high-level access to the Exif data of an image:

- read Exif information from JPEG files
- access metadata through keys and standard C++ iterators
- add, modify and delete metadata
- write Exif data to JPEG files
- extract Exif metadata to files, insert from these files
- extract and delete Exif thumbnail (JPEG and TIFF thumbnails)

Examples:

  addmoddel.cpp, exifcomment.cpp, and exifprint.cpp.

## Member Function Documentation

int Exiv2::ExifData::load | ( | const byte * | buf,
|  | long | len |
| ) |  |  |

Load the Exif data from a byte buffer. The data buffer must start with the TIFF header. This method is deprecated. Use ImageFactory::open() instead.

Parameters:

  | buf | Pointer to the data buffer to read from
  | len | Number of bytes in the data buffer

Returns:
  0 if successful.

References Exiv2::MakerNote::begin(), Exiv2::Ifd::begin(), Exiv2::MakerNote::byteOrder(), byteOrder(), clear(), Exiv2::MakerNoteFactory::create(), Exiv2::MakerNote::end(), Exiv2::Ifd::end(), Exiv2::Ifd::erase(), Exiv2::Ifd::findTag(), Exiv2::Ifd::next(), Exiv2::Ifd::offset(), Exiv2::DataBuf::pData_, Exiv2::Ifd::readSubIfd(), Exiv2::DataBuf::release(), and Exiv2::DataBuf::size_.

DataBuf Exiv2::ExifData::copy | ( |  | ) |

Write the Exif data to a data buffer, which is returned. The caller owns this copy and DataBuf ensures that it will be deleted. The copied data starts with the TIFF header.

Tries to update the original data buffer and write it back with minimal changes, in a 'non-intrusive' fashion, if possible. In this case, tag data that ExifData does not understand stand a good chance to remain valid. (In particular, if the Exif data contains a Makernote in IFD format, the offsets in its IFD will remain valid.)
If 'non-intrusive' writing is not possible, the Exif data will be re-built from scratch, in which case the absolute position of the metadata entries within the data buffer may (and in most cases will) be different from their original position. Furthermore, in this case, the Exif data is updated with the metadata from the actual thumbnail image (overriding existing metadata).

Note:
  If there is no Exif data to write, the buffer is empty, i.e., no TIFF header is written in this case.

Returns:
  A DataBuf containing the Exif data.

References Exiv2::DataBuf::alloc(), and Exiv2::DataBuf::pData_.

Exifdatum & Exiv2::ExifData::operator[] | ( | const std::string & | key | ) |

Returns a reference to the Exifdatum that is associated with a particular key. If ExifData does not already contain such an Exifdatum, operator[] adds object Exifdatum(key).

Note:
  Since operator[] might insert a new element, it can't be a const member function.

References end(), and findKey().

void Exiv2::ExifData::add | ( | const Exifdatum & | exifdatum | ) |

Add a copy of the exifdatum to the Exif metadata. No duplicate checks are performed, i.e., it is possible to add multiple metadata with the same key.

Exceptions:

  | Error | if the makernote cannot be created

References Exiv2::MakerNoteFactory::create(), Exiv2::Exifdatum::ifdId(), and Exiv2::ExifTags::isMakerIfd().

ExifData::iterator Exiv2::ExifData::findIfdIdIdx | ( | IfdId | ifdId,
|  | int | idx |
| ) |  |  |

Find the first Exifdatum with the given ifdId and idx, return an iterator to it.

This method can be used to uniquely identify an exifdatum that was created from an IFD or from the makernote (with idx greater than 0). Metadata created by an application (not read from an IFD or a makernote) all have their idx field set to 0, i.e., they cannot be uniquely identified with this method.

void Exiv2::ExifData::setJpegThumbnail | ( | const std::string & | path,
|  | URational | xres,
|  | URational | yres,
|  | uint16_t | unit |
| ) |  |  |

Set the Exif thumbnail to the Jpeg image path. Set XResolution, YResolution and ResolutionUnit to xres, yres and unit, respectively.

This results in the minimal thumbnail tags being set for a Jpeg thumbnail, as mandated by the Exif standard.

Exceptions:

  | Error | if reading the file fails.

Note:
  No checks on the file format or size are performed.

  Additional existing Exif thumbnail tags are not modified.

  The Jpeg image inserted as thumbnail image should not itself contain Exif data (or other metadata), as existing applications may have problems with that. (The preview application that comes with OS X for one.) - David Harvey.

References Exiv2::DataBuf::pData_, Exiv2::readFile(), and Exiv2::DataBuf::size_.

Referenced by Action::Insert::insertThumbnail(), and setJpegThumbnail().

void Exiv2::ExifData::setJpegThumbnail | ( | const byte * | buf,
|  | long | size,
|  | URational | xres,
|  | URational | yres,
|  | uint16_t | unit |
| ) |  |  |

Set the Exif thumbnail to the Jpeg image pointed to by buf, and size size. Set XResolution, YResolution and ResolutionUnit to xres, yres and unit, respectively.

This results in the minimal thumbnail tags being set for a Jpeg thumbnail, as mandated by the Exif standard.

Exceptions:

  | Error | if reading the file fails.

Note:
  No checks on the image format or size are performed.

  Additional existing Exif thumbnail tags are not modified.

  The Jpeg image inserted as thumbnail image should not itself contain Exif data (or other metadata), as existing applications may have problems with that. (The preview application that comes with OS X for one.) - David Harvey.

References setJpegThumbnail().

void Exiv2::ExifData::setJpegThumbnail | ( | const std::string & | path | ) |

Set the Exif thumbnail to the Jpeg image path.

This sets only the Compression, JPEGInterchangeFormat and JPEGInterchangeFormatLength tags, which is not all the thumbnail Exif information mandatory according to the Exif standard. (But it's enough to work with the thumbnail.)

Exceptions:

  | Error | if reading the file fails.

Note:
  No checks on the file format or size are performed.

  Additional existing Exif thumbnail tags are not modified.

References Exiv2::DataBuf::pData_, Exiv2::readFile(), setJpegThumbnail(), and Exiv2::DataBuf::size_.

void Exiv2::ExifData::setJpegThumbnail | ( | const byte * | buf,
|  | long | size |
| ) |  |  |

Set the Exif thumbnail to the Jpeg image pointed to by buf, and size size.

This sets only the Compression, JPEGInterchangeFormat and JPEGInterchangeFormatLength tags, which is not all the thumbnail Exif information mandatory according to the Exif standard. (But it's enough to work with the thumbnail.)

Note:
  No checks on the image format or size are performed.

  Additional existing Exif thumbnail tags are not modified.

References Exiv2::Exifdatum::setDataArea().

long Exiv2::ExifData::eraseThumbnail | ( |  | ) |

Delete the thumbnail from the Exif data. Removes all Exif.Thumbnail.*, i.e., IFD1 metadata.

Returns:
  The number of bytes of thumbnail data erased from the original Exif data. Note that the original image size may differ from the size of the image after deleting the thumbnail by more than this number. This is the case if the Exif data contains extra bytes (often at the end of the Exif block) or gaps and the thumbnail is not located at the end of the Exif block so that non-intrusive writing of a truncated Exif block is not possible. Instead it is in this case necessary to write the Exif data, without the thumbnail, from the metadata and all extra bytes and gaps are lost, resulting in a smaller image.

References begin(), byteOrder(), Exiv2::Ifd::clear(), Exiv2::Ifd::dataSize(), end(), erase(), Exiv2::Ifd::next(), Exiv2::Ifd::setNext(), and Exiv2::Ifd::size().

Referenced by clear(), and Action::Erase::eraseThumbnail().

ExifData::const_iterator Exiv2::ExifData::findIfdIdIdx | ( | IfdId | ifdId,
|  | int | idx |
| ) |  |  | const

Find the first Exifdatum with the given ifdId and idx, return an iterator to it.

This method can be used to uniquely identify a Exifdatum that was created from an IFD or from the makernote (with idx greater than 0). Metadata created by an application (not read from an IFD or a makernote) all have their idx field set to 0, i.e., they cannot be uniquely identified with this method.

int Exiv2::ExifData::writeThumbnail | ( | const std::string & | path | ) | const

Write the thumbnail image to a file. A filename extension is appended to path according to the image type of the thumbnail, so path should not include an extension. This will overwrite an existing file of the same name.

Parameters:

  | path | Path of the filename without image type extension

Exceptions:

  | Error | if writing to the file fails.

Returns:
  0 if successful;
  8 if the Exif data does not contain a thumbnail.

References getThumbnail(), Exiv2::FileIo::open(), Exiv2::strError(), and Exiv2::FileIo::write().

Referenced by Action::Extract::writeThumbnail().

The documentation for this class was generated from the following files:

- exif.hpp
- exif.cpp