Detailed Description

Abstract base class defining the interface for an image. This is the top-level interface to the Exiv2 library.

Image has containers to store image metadata and subclasses implement read and save metadata from and to specific image formats.
Most client apps will obtain an Image instance by calling a static ImageFactory method. The Image class can then be used to to read, write, and save metadata.

Member Function Documentation

virtual void Exiv2::Image::readMetadata

(

)

[pure virtual]

Read all metadata supported by a specific image format from the image. Before this method is called, the image metadata will be cleared.

This method returns success even if no metadata is found in the image. Callers must therefore check the size of individual metadata types before accessing the data.

Exceptions:

Error

if opening or reading of the file fails or the image data is not valid (does not look like data of the specific image type).

All existing metadata sections in the image are either created, replaced, or erased. If values for a given metadata type have been assigned, a section for that metadata type will either be created or replaced. If no values have been assigned to a given metadata type, any exists section for that metadata type will be removed from the image.

Assign a raw XMP packet. The new XMP packet is not written to the image until the writeMetadata() method is called.

Subsequent calls to writeMetadata() write the XMP packet from the buffered raw XMP packet rather than from buffered parsed XMP data. In order to write from parsed XMP data again, use either writeXmpFromPacket(false) or setXmpData().

Parameters:

xmpPacket

A string containing the raw XMP packet.

virtual void Exiv2::Image::clearXmpPacket

(

)

[virtual]

Erase the buffered XMP packet. XMP data is not removed from the actual image until the writeMetadata() method is called.

This has the same effect as clearXmpData() but operates on the buffered raw XMP packet only, not the parsed XMP data.

Subsequent calls to writeMetadata() write the XMP packet from the buffered raw XMP packet rather than from buffered parsed XMP data. In order to write from parsed XMP data again, use either writeXmpFromPacket(false) or setXmpData().

Assign new XMP data. The new XMP data is not written to the image until the writeMetadata() method is called.

Subsequent calls to writeMetadata() encode the XMP data to a raw XMP packet and write the newly encoded packet to the image. In the process, the buffered raw XMP packet is updated. In order to write directly from the raw XMP packet, use writeXmpFromPacket(true) or setXmpPacket().

Erase any buffered XMP data. XMP data is not removed from the actual image until the writeMetadata() method is called.

This has the same effect as clearXmpPacket() but operates on the buffered parsed XMP data.

Subsequent calls to writeMetadata() encode the XMP data to a raw XMP packet and write the newly encoded packet to the image. In the process, the buffered raw XMP packet is updated. In order to write directly from the raw XMP packet, use writeXmpFromPacket(true) or setXmpPacket().

virtual void Exiv2::Image::setComment

(

const std::string &

comment

)

[virtual]

Set the image comment. The new comment is not written to the image until the writeMetadata() method is called.

The contained Exif data may have been read from the image by a previous call to readMetadata() or added directly. The Exif data in the returned instance will be written to the image when writeMetadata() is called.

The contained IPTC data may have been read from the image by a previous call to readMetadata() or added directly. The IPTC data in the returned instance will be written to the image when writeMetadata() is called.

The contained XMP data may have been read from the image by a previous call to readMetadata() or added directly. The XMP data in the returned instance will be written to the image when writeMetadata() is called.

Depending on the setting of this flag, writeMetadata() writes XMP from the buffered raw XMP packet or from parsed XMP data. The default is to write from parsed XMP data. The switch is also set by all functions to set and clear the buffered raw XMP packet and parsed XMP data, so using this function should usually not be necessary.

If Exiv2 was compiled without XMP support, the default for this flag is true and it will never be changed in order to preserve access to the raw XMP packet.

The setting is only used when new Exif metadata is created and may not be applicable at all for some image formats. If the target image already contains Exif metadata, the byte order of the existing data is used. If byte order is not set when writeMetadata() is called, little-endian byte order (II) is used by default.

For each supported image format, the library knows only one MIME type. This may not be the most specific MIME type for that format. In particular, several RAW formats are variants of the TIFF format with the same magic as TIFF itself. Class TiffImage handles most of them and thus they all have MIME type "image/tiff", although a more specific MIME type may exist (e.g., "image/x-nikon-nef").

The Exif data may have been read from the image by a previous call to readMetadata() or added directly. The Exif data in the returned instance will be written to the image when writeMetadata() is called.

The contained IPTC data may have been read from the image by a previous call to readMetadata() or added directly. The IPTC data in the returned instance will be written to the image when writeMetadata() is called.

The contained XMP data may have been read from the image by a previous call to readMetadata() or added directly. The XMP data in the returned instance will be written to the image when writeMetadata() is called.

This refence is particularly useful to reading the results of operations on a MemIo instance. For example after metadata has been modified and the writeMetadata() method has been called, this method can be used to get access to the modified image.

Returns:

BasicIo instance that can be used to read or write image data directly.

Note:

If the returned BasicIo is used to write to the image, the Image class will not see those changes until the readMetadata() method is called.