Exiv2::Ifd Class Reference

Models an IFD (Image File Directory). More...

#include <ifd.hpp>

Collaboration diagram for Exiv2::Ifd:

Collaboration graph
[legend]
List of all members.

Public Types

typedef Entries::const_iterator const_iterator
 Entries const iterator type
typedef Entries::iterator iterator
 Entries iterator type

Public Member Functions

Creators
 Ifd (IfdId ifdId=ifdIdNotSet)
 Constructor. Allows to set the IFD identifier. Memory management is enabled, offset is set to 0. Serves as default constructor.
 Ifd (IfdId ifdId, long offset)
 Constructor. Allows to set the IFD identifier and the offset of the IFD from the start of TIFF header. Memory management is enabled.
 Ifd (IfdId ifdId, long offset, bool alloc, bool hasNext=true)
 Constructor. Allows to set the IFD identifier, offset of the IFD from the start of TIFF header, choose whether or not memory management is required for the Entries, and decide whether this IFD has a next pointer.
 Ifd (const Ifd &rhs)
 Copy constructor.
 ~Ifd ()
 Destructor.
Manipulators
int read (const byte *buf, long len, long start, ByteOrder byteOrder, long shift=0)
 Read a complete IFD and its data from a data buffer.
long copy (byte *buf, ByteOrder byteOrder, long offset=0)
 Copy the IFD to a data array, update the offsets of the IFD and all its entries, return the number of bytes written.
void clear ()
 Reset the IFD. Delete all IFD entries from the class and put the object in a state where it can accept completely new entries.
void setNext (uint32_t next, ByteOrder byteOrder)
 Set the offset of the next IFD. Byte order is needed to update the underlying data buffer in non-alloc mode. This method only has an effect if the IFD was instantiated with hasNext = true.
void add (const Entry &entry)
 Add the entry to the IFD. No duplicate-check is performed, i.e., it is possible to add multiple entries with the same tag. The memory allocation mode of the entry to be added must match that of the IFD and the IFD ids of the IFD and entry must match.
int erase (uint16_t tag)
 Delete the directory entry with the given tag. Return the index of the deleted entry or 0 if no entry with tag was found.
iterator erase (iterator pos)
 Delete the directory entry at iterator position pos, return the position of the next entry. Note that iterators into the directory, including pos, are potentially invalidated by this call.
void sortByTag ()
 Sort the IFD entries by tag.
iterator begin ()
 The first entry.
iterator end ()
 End of the entries.
iterator findIdx (int idx)
 Find an IFD entry by idx, return an iterator into the entries list.
iterator findTag (uint16_t tag)
 Find an IFD entry by tag, return an iterator into the entries list.
byteupdateBase (byte *pNewBase)
 Update the base pointer of the Ifd and all entries to pNewBase.
Accessors
int readSubIfd (Ifd &dest, const byte *buf, long len, ByteOrder byteOrder, uint16_t tag) const
 Read a sub-IFD from the location pointed to by the directory entry with the given tag.
bool alloc () const
 Get the memory allocation mode, see the Ifd class description for details.
const_iterator begin () const
 The first entry.
const_iterator end () const
 End of the entries.
const_iterator findIdx (int idx) const
 Find an IFD entry by idx, return a const iterator into the entries list.
const_iterator findTag (uint16_t tag) const
 Find an IFD entry by tag, return a const iterator into the entries list.
IfdId ifdId () const
 Get the IfdId of the IFD.
long offset () const
 Get the offset of the IFD from the start of the TIFF header.
long dataOffset () const
 Get the offset of the first data entry outside of the IFD from the start of the TIFF header, return 0 if there is none. The data offset is determined when the IFD is read.
uint32_t next () const
 Get the offset to the next IFD from the start of the TIFF header.
long count () const
 Get the number of directory entries in the IFD.
long size () const
 Get the size of this IFD in bytes (IFD only, without data).
long dataSize () const
 Return the total size of the data of this IFD in bytes; sums the size of all directory entries where size is greater than four plus the size of all data areas, i.e., all data that requires memory outside the IFD directory entries is counted.
void print (std::ostream &os, const std::string &prefix="") const
 Print the IFD in human readable format to the given stream; begin each line with prefix.

Friends

bool cmpPreEntriesByOffset (const PreEntry &, const PreEntry &)
 cmpPreEntriesByOffset needs to know about PreEntry, that's all.

Classes

struct  PreEntry
 Helper structure to build IFD entries.

Detailed Description

Models an IFD (Image File Directory).

This class models an IFD as described in the TIFF 6.0 specification.

An instance of class Ifd can operate in two modes, one that allocates and deallocates the memory required to store data, and one that doesn't perform such memory management.
An external data buffer (not managed by Ifd) is needed for an instance of Ifd which operates in no memory management mode. The Ifd will maintain only pointers into this buffer.
The mode without memory management is used to make "non-intrusive write support" possible. This allows writing to Exif data of an image without changing the data layout of the Exif data, to maximize chances that tag data, which the Exif reader may not understand (e.g., the Makernote) remains valid. A "non-intrusive write operation" is the modification of tag data without increasing the data size.

Note:
Use the mode with memory management (the default) if you are unsure or if these memory management considerations are of no concern to you.

The two different modes imply completely different copy and assignment behaviours, with the first resulting in entirely separate classes and the second mode resulting in multiple classes using one and the same data buffer.


Member Function Documentation

long Exiv2::Ifd::copy ( byte buf,
ByteOrder  byteOrder,
long  offset = 0 
)

Copy the IFD to a data array, update the offsets of the IFD and all its entries, return the number of bytes written.

First the number of IFD entries is written (2 bytes), followed by all directory entries: tag (2), type (2), number of data components (4) and offset to the data or the data, if it occupies not more than four bytes (4). The directory entries are followed by the offset of the next IFD (4). All these fields are encoded according to the byte order argument. Data that doesn't fit into the offset fields follows immediately after the IFD entries. The offsets in the IFD are set to correctly point to the data fields, using the offset parameter or the offset of the IFD.

Parameters:
buf Pointer to the data buffer. The user must ensure that the buffer has enough memory. Otherwise the call results in undefined behaviour.
byteOrder Applicable byte order (little or big endian).
offset Target offset from the start of the TIFF header of the data array. The IFD offsets will be adjusted as necessary. If not given, then it is assumed that the IFD will remain at its original position, i.e., the offset of the IFD will be used.
Returns:
Returns the number of characters written.

int Exiv2::Ifd::read ( const byte buf,
long  len,
long  start,
ByteOrder  byteOrder,
long  shift = 0 
)

Read a complete IFD and its data from a data buffer.

Parameters:
buf Pointer to the Exif data buffer that contains the IFD to decode. Usually, the buffer will contain all Exif data starting from the TIFF header.
len Number of bytes in the Exif data buffer.
start IFD starts at buf + start.
byteOrder Applicable byte order (little or big endian).
shift IFD offsets are relative to buf + shift.
Returns:
0 if successful;
6 if the data buffer is too small, e.g., if an offset points beyond the provided buffer. The IFD is cleared in this case.

int Exiv2::Ifd::readSubIfd ( Ifd dest,
const byte buf,
long  len,
ByteOrder  byteOrder,
uint16_t  tag 
) const

Read a sub-IFD from the location pointed to by the directory entry with the given tag.

Parameters:
dest References the destination IFD.
buf The data buffer to read from. The buffer must contain all Exif data starting from the TIFF header.
len Number of bytes in the data buffer
byteOrder Applicable byte order (little or big endian).
tag Tag to look for.
Returns:
0 if successful;
6 if reading the sub-IFD failed (see read() above) or the location pointed to by the directory entry with the given tag is outside of the data buffer.
Note:
It is not considered an error if the tag cannot be found in the IFD. 0 is returned and no action is taken in this case.

byte* Exiv2::Ifd::updateBase ( byte pNewBase  ) 

Update the base pointer of the Ifd and all entries to pNewBase.

Allows to re-locate the underlying data buffer to a new location pNewBase. This method only has an effect in non-alloc mode.

Parameters:
pNewBase Pointer to the new data buffer
Returns:
Old base pointer or 0 if called in alloc mode


The documentation for this class was generated from the following file:
Generated on Fri Jun 6 18:18:32 2008 for Exiv2 by  doxygen 1.4.7