Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Examples

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:

Collaboration graph
[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.
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.
Exifdatumoperator[] (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 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 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
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 an 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 ifdId and idx, return an iterator to it.
long count () const
 Get the number of metadata entries.
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 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.

Static Public Member Functions

static std::string strError (int rc, const std::string &path)
 Convert the return code rc 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. The container holds Exifdatum objects.

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

Examples:

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


Member Function Documentation

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 ("Inconsistent MakerNote") if exifdatum is a MakerNote tag for a different MakerNote than that of the ExifData.

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).

Returns:
A DataBuf containing the Exif data.

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 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.

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

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

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.

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:
addmoddel.cpp, exifcomment.cpp, and exifprint.cpp.

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.

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.)

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

Additional existing Exif thumbnail tags are not modified.

Exceptions:
Error ("Couldn't open input file") if fopen fails,
Error ("Couldn't stat input file") if stat fails, or
Error ("Couldn't read input file") if fread fails.

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.

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

Additional existing Exif thumbnail tags are not modified.

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.

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

Additional existing Exif thumbnail tags are not modified.

Exceptions:
Error ("Couldn't open input file") if fopen fails,
Error ("Couldn't stat input file") if stat fails, or
Error ("Couldn't read input file") if fread fails.

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

Convert the return code rc 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:
exifcomment.cpp.

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
Returns:
0 if successful;
-1 if opening the file failed;
4 if writing to the output stream failed;
8 if the Exif data does not contain a thumbnail


The documentation for this class was generated from the following files:
Generated on Sat Mar 5 19:54:21 2005 for Exiv2 by  doxygen 1.4.1