Exiv2::ExifData Class Reference

A container for Exif data. This is a top-level class of the Exiv2 library. 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 ()
	Destructor.
Manipulators
int	read (const std::string &path)
	Read the Exif data from file path.
int	read (const byte *buf, long len)
	Read the Exif data from a byte buffer. The data buffer must start with the TIFF header.
int	write (const std::string &path)
	Write the Exif data to file path. If an Exif data section already exists in the file, it is replaced. If there is no metadata and no thumbnail to write, the Exif data section is deleted from the file. Otherwise, an Exif data section is created. See copy(byte* buf) for further details.
int	writeExifData (const std::string &path)
	Write the Exif data to a binary file. By convention, the filename extension should be ".exv". This file format contains the Exif data as it is found in a JPEG file, starting with the APP1 marker 0xffe1, the size of the data and the string "Exif\0\0". Exv files can be read with int read(const std::string& path) just like image Exif data.
long	copy (byte *buf)
	Write the Exif data to a data buffer, return number of bytes written. The copied data starts with the TIFF header.
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, Value *pValue)
	Add a Exifdatum from the supplied key and value pair. This method copies (clones) key and value and adds a pointer to the MakerNote to the cloned key. 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	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 a Exifdatum with the given key, return an iterator to it. If multiple metadata with the same key exist, it is undefined which of the matching metadata is found.
iterator	findIfdIdIdx (IfdId ifdId, int idx)
	Find the Exifdatum with the given ifd id and idx, return an iterator to it.
long	eraseThumbnail ()
	Delete the thumbnail from the Exif data. Removes all related (Thumbnail.*.*, i.e., IFD1) metadata as well.
Accessors
int	erase (const std::string &path) const
	Erase the Exif data section from file path.
const_iterator	begin () const
	Begin of the metadata.
const_iterator	end () const
	End of the metadata.
const_iterator	findKey (const ExifKey &key) const
	Find a Exifdatum with the given key, return a const iterator to it. If multiple metadata with the same key exist, it is undefined which of the matching metadata is found.
const_iterator	findIfdIdIdx (IfdId ifdId, int idx) const
	Find the Exifdatum with the given ifd id and idx, return an iterator to it.
long	count () const
	Get the number of metadata entries.
long	size () const
	Return the approximate size of all Exif data (TIFF header plus metadata). The number returned may be bigger than the actual size of the Exif data, but it is never smaller. Only copy() returns the exact size.
ByteOrder	byteOrder () const
	Returns the byte order as specified in the TIFF header.
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 the path should not include an extension. This will overwrite an existing file of the same name.
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").
long	thumbnailSize () const
	Return the size of the thumbnail image. This is the size that the thumbnail would occupy when extracted from the Exif data.
Static Public Member Functions
std::string	strError (int rc, const std::string &path)
	Convert the return code from int read(const std::string& path), int write(const std::string& path), int writeExifData(const std::string& path), int writeThumbnail(const std::string& path) const and int erase(const std::string& path) const into an error message.

---

Detailed Description

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

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

long Exiv2::ExifData::copy (  byte *  buf  )

Write the Exif data to a data buffer, return number of bytes written. 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). Parameters: buf  The data buffer to write to. The user must ensure that the buffer has enough memory. Otherwise the call results in undefined behaviour. Returns: Number of characters written to the buffer.

int Exiv2::ExifData::erase (  const std::string &  path  )  const

Erase the Exif data section from file path. Parameters: path  Path to the file. Returns: 0 if successful.

long Exiv2::ExifData::eraseThumbnail (   )

Delete the thumbnail from the Exif data. Removes all related (Thumbnail.*.*, i.e., IFD1) metadata as well. 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.

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

Find the Exifdatum with the given ifd id 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. If multiple metadata with the same key exist, it is undefined which of the matching metadata is found.

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

Find the Exifdatum with the given ifd id 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. If multiple metadata with the same key exist, it is undefined which of the matching metadata is found.

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

Read the Exif data from a byte buffer. The data buffer must start with the TIFF header. Parameters: buf  Pointer to the data buffer to read from len  Number of bytes in the data buffer Returns: 0 if successful.

int Exiv2::ExifData::read (  const std::string &  path  )

Read the Exif data from file path. Parameters: path  Path to the file Returns: 0 if successful; 3 if the file contains no Exif data; the return code of Image::readMetadata() if the call to this function fails the return code of read(const char* buf, long len) if the call to this function fails Examples: exifcomment.cpp, and exifprint.cpp.

std::string Exiv2::ExifData::strError (  int  rc, const std::string &  path )  [static]

Convert the return code from int read(const std::string& path), int write(const std::string& path), int writeExifData(const std::string& path), int writeThumbnail(const std::string& path) const and int erase(const std::string& path) const into an error message. Todo: Implement global handling of error messages Examples: addmoddel.cpp, exifcomment.cpp, and exifprint.cpp.

int Exiv2::ExifData::write (  const std::string &  path  )

Write the Exif data to file path. If an Exif data section already exists in the file, it is replaced. If there is no metadata and no thumbnail to write, the Exif data section is deleted from the file. Otherwise, an Exif data section is created. See copy(byte* buf) for further details. Returns: 0 if successful. Examples: addmoddel.cpp, and exifcomment.cpp.

---

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

• exif.hpp
• exif.cpp

---