<?php

/**
 *  PEL: PHP Exif Library.  A library with support for reading and
 *  writing all Exif headers in JPEG and TIFF images using PHP.
 *
 *  Copyright (C) 2004, 2005, 2006, 2007, 2008  Martin Geisler.
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program in the file COPYING; if not, write to the
 *  Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
 *  Boston, MA 02110-1301 USA
 */

/* $Id$ */


/**
 * Classes for dealing with Exif IFDs.
 *
 * @author Martin Geisler <mgeisler@users.sourceforge.net>
 * @version $Revision$
 * @date $Date$
 * @license http://www.gnu.org/licenses/gpl.html GNU General Public
 * License (GPL)
 * @package PEL
 */

/**#@+ Required class definitions. */
require_once('PelEntryUndefined.php');
require_once('PelEntryRational.php');
require_once('PelDataWindow.php');
require_once('PelEntryAscii.php');
require_once('PelEntryShort.php');
require_once('PelEntryByte.php');
require_once('PelEntryLong.php');
require_once('PelException.php');
require_once('PelFormat.php');
require_once('PelEntry.php');
require_once('PelTag.php');
require_once('Pel.php');
/**#@-*/


/**
 * Exception indicating a general problem with the IFD.
 *
 * @author Martin Geisler <mgeisler@users.sourceforge.net>
 * @package PEL
 * @subpackage Exception
 */
class PelIfdException extends PelException {}

/**
 * Class representing an Image File Directory (IFD).
 *
 * {@link PelTiff TIFF data} is structured as a number of Image File
 * Directories, IFDs for short.  Each IFD contains a number of {@link
 * PelEntry entries}, some data and finally a link to the next IFD.
 *
 * @author Martin Geisler <mgeisler@users.sourceforge.net>
 * @package PEL
 */
class PelIfd implements IteratorAggregate, ArrayAccess {

    /**
     * Main image IFD.
     *
     * Pass this to the constructor when creating an IFD which will be
     * the IFD of the main image.
     */
    const IFD0 = 0;

    /**
     * Thumbnail image IFD.
     *
     * Pass this to the constructor when creating an IFD which will be
     * the IFD of the thumbnail image.
     */
    const IFD1 = 1;

    /**
     * Exif IFD.
     *
     * Pass this to the constructor when creating an IFD which will be
     * the Exif sub-IFD.
     */
    const EXIF = 2;

    /**
     * GPS IFD.
     *
     * Pass this to the constructor when creating an IFD which will be
     * the GPS sub-IFD.
     */
    const GPS  = 3;

    /**
     * Interoperability IFD.
     *
     * Pass this to the constructor when creating an IFD which will be
     * the interoperability sub-IFD.
     */
    const INTEROPERABILITY = 4;

    /**
     * The entries held by this directory.
     *
     * Each tag in the directory is represented by a {@link PelEntry}
     * object in this array.
     *
     * @var array
     */
    private $entries = array();

    /**
     * The type of this directory.
     *
     * Initialized in the constructor.  Must be one of {@link IFD0},
     * {@link IFD1}, {@link EXIF}, {@link GPS}, or {@link
     * INTEROPERABILITY}.
     *
     * @var int
     */
    private $type;

    /**
     * The next directory.
     *
     * This will be initialized in the constructor, or be left as null
     * if this is the last directory.
     *
     * @var PelIfd
     */
    private $next = null;

    /**
     * Sub-directories pointed to by this directory.
     *
     * This will be an array of ({@link PelTag}, {@link PelIfd}) pairs.
     *
     * @var array
     */
    private $sub = array();

    /**
     * The thumbnail data.
     *
     * This will be initialized in the constructor, or be left as null
     * if there are no thumbnail as part of this directory.
     *
     * @var PelDataWindow
     */
    private $thumb_data = null;
    // TODO: use this format to choose between the
    // JPEG_INTERCHANGE_FORMAT and STRIP_OFFSETS tags.
    // private $thumb_format;


    /**
     * Construct a new Image File Directory (IFD).
     *
     * The IFD will be empty, use the {@link addEntry()} method to add
     * an {@link PelEntry}.  Use the {@link setNext()} method to link
     * this IFD to another.
     *
     * @param int type the type of this IFD.  Must be one of {@link
     * IFD0}, {@link IFD1}, {@link EXIF}, {@link GPS}, or {@link
     * INTEROPERABILITY}.  An {@link PelIfdException} will be thrown
     * otherwise.
     */
    function __construct($type) {
        if ($type != PelIfd::IFD0 && $type != PelIfd::IFD1 &&
        $type != PelIfd::EXIF && $type != PelIfd::GPS &&
        $type != PelIfd::INTEROPERABILITY)
        throw new PelIfdException('Unknown IFD type: %d', $type);

        $this->type = $type;
    }


    /**
     * Load data into a Image File Directory (IFD).
     *
     * @param PelDataWindow the data window that will provide the data.
     *
     * @param int the offset within the window where the directory will
     * be found.
     */
    function load(PelDataWindow $d, $offset) {
        $thumb_offset = 0;
        $thumb_length = 0;

        Pel::debug('Constructing IFD at offset %d from %d bytes...',
        $offset, $d->getSize());

        /* Read the number of entries */
        $n = $d->getShort($offset);
        Pel::debug('Loading %d entries...', $n);

        $offset += 2;

        /* Check if we have enough data. */
        if ($offset + 12 * $n > $d->getSize()) {
            $n = floor(($offset - $d->getSize()) / 12);
            Pel::maybeThrow(new PelIfdException('Adjusted to: %d.', $n));
        }

        for ($i = 0; $i < $n; $i++) {
            // TODO: increment window start instead of using offsets.
            $tag = $d->getShort($offset + 12 * $i);
            Pel::debug('Loading entry with tag 0x%04X: %s (%d of %d)...',
            $tag, PelTag::getName($this->type, $tag), $i + 1, $n);

            switch ($tag) {
                case PelTag::EXIF_IFD_POINTER:
                case PelTag::GPS_INFO_IFD_POINTER:
                case PelTag::INTEROPERABILITY_IFD_POINTER:
                    $o = $d->getLong($offset + 12 * $i + 8);
                    Pel::debug('Found sub IFD at offset %d', $o);

                    /* Map tag to IFD type. */
                    if ($tag == PelTag::EXIF_IFD_POINTER)
                    $type = PelIfd::EXIF;
                    elseif ($tag == PelTag::GPS_INFO_IFD_POINTER)
                    $type = PelIfd::GPS;
                    elseif ($tag == PelTag::INTEROPERABILITY_IFD_POINTER)
                    $type = PelIfd::INTEROPERABILITY;

                    $this->sub[$type] = new PelIfd($type);
                    $this->sub[$type]->load($d, $o);
                    break;
                case PelTag::JPEG_INTERCHANGE_FORMAT:
                    $thumb_offset = $d->getLong($offset + 12 * $i + 8);
                    $this->safeSetThumbnail($d, $thumb_offset, $thumb_length);
                    break;
                case PelTag::JPEG_INTERCHANGE_FORMAT_LENGTH:
                    $thumb_length = $d->getLong($offset + 12 * $i + 8);
                    $this->safeSetThumbnail($d, $thumb_offset, $thumb_length);
                    break;
                default:
                    $format     = $d->getShort($offset + 12 * $i + 2);
                    $components = $d->getLong($offset + 12 * $i + 4);

                    /* The data size.  If bigger than 4 bytes, the actual data is
                     * not in the entry but somewhere else, with the offset stored
                     * in the entry.
                     */
                    $s = PelFormat::getSize($format) * $components;
                    if ($s > 0) {
                        $doff = $offset + 12 * $i + 8;
                        if ($s > 4)
                        $doff = $d->getLong($doff);

                        $data = $d->getClone($doff, $s);
                    } else {
                        $data = new PelDataWindow();
                    }

                    try {
                        $entry = $this->newEntryFromData($tag, $format, $components, $data);
                        $this->addEntry($entry);
                    } catch (PelException $e) {
                        /* Throw the exception when running in strict mode, store
                         * otherwise. */
                        Pel::maybeThrow($e);
                    }

                    /* The format of the thumbnail is stored in this tag. */
                    //         TODO: handle TIFF thumbnail.
                    //         if ($tag == PelTag::COMPRESSION) {
                    //           $this->thumb_format = $data->getShort();
                    //         }
                        break;
            }
        }

        /* Offset to next IFD */
        $o = $d->getLong($offset + 12 * $n);
        Pel::debug('Current offset is %d, link at %d points to %d.',
        $offset,  $offset + 12 * $n, $o);

        if ($o > 0) {
            /* Sanity check: we need 6 bytes  */
            if ($o > $d->getSize() - 6) {
                Pel::maybeThrow(new PelIfdException('Bogus offset to next IFD: ' .
                                            '%d > %d!',
                $o, $d->getSize() - 6));
            } else {
                if ($this->type == PelIfd::IFD1) // IFD1 shouldn't link further...
                Pel::maybeThrow(new PelIfdException('IFD1 links to another IFD!'));

                $this->next = new PelIfd(PelIfd::IFD1);
                $this->next->load($d, $o);
            }
        } else {
            Pel::debug('Last IFD.');
        }
    }


    /**
     * Make a new entry from a bunch of bytes.
     *
     * This method will create the proper subclass of {@link PelEntry}
     * corresponding to the {@link PelTag} and {@link PelFormat} given.
     * The entry will be initialized with the data given.
     *
     * Please note that the data you pass to this method should come
     * from an image, that is, it should be raw bytes.  If instead you
     * want to create an entry for holding, say, an short integer, then
     * create a {@link PelEntryShort} object directly and load the data
     * into it.
     *
     * A {@link PelUnexpectedFormatException} is thrown if a mismatch is
     * discovered between the tag and format, and likewise a {@link
     * PelWrongComponentCountException} is thrown if the number of
     * components does not match the requirements of the tag.  The
     * requirements for a given tag (if any) can be found in the
     * documentation for {@link PelTag}.
     *
     * @param PelTag the tag of the entry.
     *
     * @param PelFormat the format of the entry.
     *
     * @param int the components in the entry.
     *
     * @param PelDataWindow the data which will be used to construct the
     * entry.
     *
     * @return PelEntry a newly created entry, holding the data given.
     */
    function newEntryFromData($tag, $format, $components, PelDataWindow $data) {

        /* First handle tags for which we have a specific PelEntryXXX
         * class. */

        switch ($this->type) {

            case self::IFD0:
            case self::IFD1:
            case self::EXIF:
            case self::INTEROPERABILITY:

                switch ($tag) {
                    case PelTag::DATE_TIME:
                    case PelTag::DATE_TIME_ORIGINAL:
                    case PelTag::DATE_TIME_DIGITIZED:
                        if ($format != PelFormat::ASCII)
                        throw new PelUnexpectedFormatException($this->type, $tag, $format,
                        PelFormat::ASCII);

                        if ($components != 20)
                        throw new PelWrongComponentCountException($this->type, $tag, $components, 20);

                        // TODO: handle timezones.
                        return new PelEntryTime($tag, $data->getBytes(0, -1), PelEntryTime::EXIF_STRING);

                    case PelTag::COPYRIGHT:
                        if ($format != PelFormat::ASCII)
                        throw new PelUnexpectedFormatException($this->type, $tag, $format,
                        PelFormat::ASCII);

                        $v = explode("\0", trim($data->getBytes(), ' '));
                        return new PelEntryCopyright($v[0], $v[1]);

                    case PelTag::EXIF_VERSION:
                    case PelTag::FLASH_PIX_VERSION:
                    case PelTag::INTEROPERABILITY_VERSION:
                        if ($format != PelFormat::UNDEFINED)
                        throw new PelUnexpectedFormatException($this->type, $tag, $format,
                        PelFormat::UNDEFINED);

                        return new PelEntryVersion($tag, $data->getBytes() / 100);

                    case PelTag::USER_COMMENT:
                        if ($format != PelFormat::UNDEFINED)
                        throw new PelUnexpectedFormatException($this->type, $tag, $format,
                        PelFormat::UNDEFINED);
                        if ($data->getSize() < 8) {
                            return new PelEntryUserComment();
                        } else {
                            return new PelEntryUserComment($data->getBytes(8),
                            rtrim($data->getBytes(0, 8)));
                        }

                    case PelTag::XP_TITLE:
                    case PelTag::XP_COMMENT:
                    case PelTag::XP_AUTHOR:
                    case PelTag::XP_KEYWORDS:
                    case PelTag::XP_SUBJECT:
                        if ($format != PelFormat::BYTE)
                        throw new PelUnexpectedFormatException($this->type, $tag, $format,
                        PelFormat::BYTE);

                        $v = '';
                        for ($i = 0; $i < $components; $i++) {
                            $b = $data->getByte($i);
                            /* Convert the byte to a character if it is non-null ---
                             * information about the character encoding of these entries
                             * would be very nice to have!  So far my tests have shown
                             * that characters in the Latin-1 character set are stored in
                             * a single byte followed by a NULL byte. */
                            if ($b != 0)
                            $v .= chr($b);
                        }

                        return new PelEntryWindowsString($tag, $v);
                }

            case self::GPS:

            default:
                /* Then handle the basic formats. */
                switch ($format) {
                    case PelFormat::BYTE:
                        $v =  new PelEntryByte($tag);
                        for ($i = 0; $i < $components; $i++)
                        $v->addNumber($data->getByte($i));
                        return $v;

                    case PelFormat::SBYTE:
                        $v =  new PelEntrySByte($tag);
                        for ($i = 0; $i < $components; $i++)
                        $v->addNumber($data->getSByte($i));
                        return $v;

                    case PelFormat::ASCII:
                        return new PelEntryAscii($tag, $data->getBytes(0, -1));

                    case PelFormat::SHORT:
                        $v =  new PelEntryShort($tag);
                        for ($i = 0; $i < $components; $i++)
                        $v->addNumber($data->getShort($i*2));
                        return $v;

                    case PelFormat::SSHORT:
                        $v =  new PelEntrySShort($tag);
                        for ($i = 0; $i < $components; $i++)
                        $v->addNumber($data->getSShort($i*2));
                        return $v;

                    case PelFormat::LONG:
                        $v =  new PelEntryLong($tag);
                        for ($i = 0; $i < $components; $i++)
                        $v->addNumber($data->getLong($i*4));
                        return $v;

                    case PelFormat::SLONG:
                        $v =  new PelEntrySLong($tag);
                        for ($i = 0; $i < $components; $i++)
                        $v->addNumber($data->getSLong($i*4));
                        return $v;

                    case PelFormat::RATIONAL:
                        $v =  new PelEntryRational($tag);
                        for ($i = 0; $i < $components; $i++)
                        $v->addNumber($data->getRational($i*8));
                        return $v;

                    case PelFormat::SRATIONAL:
                        $v =  new PelEntrySRational($tag);
                        for ($i = 0; $i < $components; $i++)
                        $v->addNumber($data->getSRational($i*8));
                        return $v;

                    case PelFormat::UNDEFINED:
                        return new PelEntryUndefined($tag, $data->getBytes());

                    default:
                        throw new PelException('Unsupported format: %s',
                        PelFormat::getName($format));
                }
        }
    }




    /**
     * Extract thumbnail data safely.
     *
     * It is safe to call this method repeatedly with either the offset
     * or the length set to zero, since it requires both of these
     * arguments to be positive before the thumbnail is extracted.
     *
     * When both parameters are set it will check the length against the
     * available data and adjust as necessary. Only then is the
     * thumbnail data loaded.
     *
     * @param PelDataWindow the data from which the thumbnail will be
     * extracted.
     *
     * @param int the offset into the data.
     *
     * @param int the length of the thumbnail.
     */
    private function safeSetThumbnail(PelDataWindow $d, $offset, $length) {
        /* Load the thumbnail if both the offset and the length is
         * available. */
        if ($offset > 0 && $length > 0) {
            /* Some images have a broken length, so we try to carefully
             * check the length before we store the thumbnail. */
            if ($offset + $length > $d->getSize()) {
                Pel::maybeThrow(new PelIfdException('Thumbnail length %d bytes ' .
                                            'adjusted to %d bytes.',
                $length,
                $d->getSize() - $offset));
                $length = $d->getSize() - $offset;
            }

            /* Now set the thumbnail normally. */
            $this->setThumbnail($d->getClone($offset, $length));
        }
    }


    /**
     * Set thumbnail data.
     *
     * Use this to embed an arbitrary JPEG image within this IFD. The
     * data will be checked to ensure that it has a proper {@link
     * PelJpegMarker::EOI} at the end.  If not, then the length is
     * adjusted until one if found.  An {@link PelIfdException} might be
     * thrown (depending on {@link Pel::$strict}) this case.
     *
     * @param PelDataWindow the thumbnail data.
     */
    function setThumbnail(PelDataWindow $d) {
        $size = $d->getSize();
        /* Now move backwards until we find the EOI JPEG marker. */
        while ($d->getByte($size - 2) != 0xFF ||
        $d->getByte($size - 1) != PelJpegMarker::EOI) {
            $size--;
        }

        if ($size != $d->getSize())
        Pel::maybeThrow(new PelIfdException('Decrementing thumbnail size ' .
                                          'to %d bytes', $size));

        $this->thumb_data = $d->getClone(0, $size);
    }


    /**
     * Get the type of this directory.
     *
     * @return int of {@link PelIfd::IFD0}, {@link PelIfd::IFD1}, {@link
     * PelIfd::EXIF}, {@link PelIfd::GPS}, or {@link
     * PelIfd::INTEROPERABILITY}.
     */
    function getType() {
        return $this->type;
    }


    /**
     * Is a given tag valid for this IFD?
     *
     * Different types of IFDs can contain different kinds of tags ---
     * the {@link IFD0} type, for example, cannot contain a {@link
     * PelTag::GPS_LONGITUDE} tag.
     *
     * A special exception is tags with values above 0xF000.  They are
     * treated as private tags and will be allowed everywhere (use this
     * for testing or for implementing your own types of tags).
     *
     * @param PelTag the tag.
     *
     * @return boolean true if the tag is considered valid in this IFD,
     * false otherwise.
     *
     * @see getValidTags()
     */
    function isValidTag($tag) {
        return $tag > 0xF000 || in_array($tag, $this->getValidTags());
    }


    /**
     * Returns a list of valid tags for this IFD.
     *
     * @return array an array of {@link PelTag}s which are valid for
     * this IFD.
     */
    function getValidTags() {
        switch ($this->type) {
            case PelIfd::IFD0:
            case PelIfd::IFD1:
                return array(PelTag::IMAGE_WIDTH,
                PelTag::IMAGE_LENGTH,
                PelTag::BITS_PER_SAMPLE,
                PelTag::COMPRESSION,
                PelTag::PHOTOMETRIC_INTERPRETATION,
                PelTag::IMAGE_DESCRIPTION,
                PelTag::MAKE,
                PelTag::MODEL,
                PelTag::STRIP_OFFSETS,
                PelTag::ORIENTATION,
                PelTag::SAMPLES_PER_PIXEL,
                PelTag::ROWS_PER_STRIP,
                PelTag::STRIP_BYTE_COUNTS,
                PelTag::X_RESOLUTION,
                PelTag::Y_RESOLUTION,
                PelTag::PLANAR_CONFIGURATION,
                PelTag::RESOLUTION_UNIT,
                PelTag::TRANSFER_FUNCTION,
                PelTag::SOFTWARE,
                PelTag::DATE_TIME,
                PelTag::ARTIST,
                PelTag::WHITE_POINT,
                PelTag::PRIMARY_CHROMATICITIES,
                PelTag::JPEG_INTERCHANGE_FORMAT,
                PelTag::JPEG_INTERCHANGE_FORMAT_LENGTH,
                PelTag::YCBCR_COEFFICIENTS,
                PelTag::YCBCR_SUB_SAMPLING,
                PelTag::YCBCR_POSITIONING,
                PelTag::REFERENCE_BLACK_WHITE,
                PelTag::COPYRIGHT,
                PelTag::EXIF_IFD_POINTER,
                PelTag::GPS_INFO_IFD_POINTER,
                PelTag::PRINT_IM,
                PelTag::XP_TITLE,
                PelTag::XP_COMMENT,
                PelTag::XP_AUTHOR,
                PelTag::XP_KEYWORDS,
                PelTag::XP_SUBJECT);

            case PelIfd::EXIF:
                return array(PelTag::EXPOSURE_TIME,
                PelTag::FNUMBER,
                PelTag::EXPOSURE_PROGRAM,
                PelTag::SPECTRAL_SENSITIVITY,
                PelTag::ISO_SPEED_RATINGS,
                PelTag::OECF,
                PelTag::EXIF_VERSION,
                PelTag::DATE_TIME_ORIGINAL,
                PelTag::DATE_TIME_DIGITIZED,
                PelTag::COMPONENTS_CONFIGURATION,
                PelTag::COMPRESSED_BITS_PER_PIXEL,
                PelTag::SHUTTER_SPEED_VALUE,
                PelTag::APERTURE_VALUE,
                PelTag::BRIGHTNESS_VALUE,
                PelTag::EXPOSURE_BIAS_VALUE,
                PelTag::MAX_APERTURE_VALUE,
                PelTag::SUBJECT_DISTANCE,
                PelTag::METERING_MODE,
                PelTag::LIGHT_SOURCE,
                PelTag::FLASH,
                PelTag::FOCAL_LENGTH,
                PelTag::MAKER_NOTE,
                PelTag::USER_COMMENT,
                PelTag::SUB_SEC_TIME,
                PelTag::SUB_SEC_TIME_ORIGINAL,
                PelTag::SUB_SEC_TIME_DIGITIZED,
                PelTag::FLASH_PIX_VERSION,
                PelTag::COLOR_SPACE,
                PelTag::PIXEL_X_DIMENSION,
                PelTag::PIXEL_Y_DIMENSION,
                PelTag::RELATED_SOUND_FILE,
                PelTag::FLASH_ENERGY,
                PelTag::SPATIAL_FREQUENCY_RESPONSE,
                PelTag::FOCAL_PLANE_X_RESOLUTION,
                PelTag::FOCAL_PLANE_Y_RESOLUTION,
                PelTag::FOCAL_PLANE_RESOLUTION_UNIT,
                PelTag::SUBJECT_LOCATION,
                PelTag::EXPOSURE_INDEX,
                PelTag::SENSING_METHOD,
                PelTag::FILE_SOURCE,
                PelTag::SCENE_TYPE,
                PelTag::CFA_PATTERN,
                PelTag::CUSTOM_RENDERED,
                PelTag::EXPOSURE_MODE,
                PelTag::WHITE_BALANCE,
                PelTag::DIGITAL_ZOOM_RATIO,
                PelTag::FOCAL_LENGTH_IN_35MM_FILM,
                PelTag::SCENE_CAPTURE_TYPE,
                PelTag::GAIN_CONTROL,
                PelTag::CONTRAST,
                PelTag::SATURATION,
                PelTag::SHARPNESS,
                PelTag::DEVICE_SETTING_DESCRIPTION,
                PelTag::SUBJECT_DISTANCE_RANGE,
                PelTag::IMAGE_UNIQUE_ID,
                PelTag::INTEROPERABILITY_IFD_POINTER,
                PelTag::GAMMA);

            case PelIfd::GPS:
                return array(PelTag::GPS_VERSION_ID,
                PelTag::GPS_LATITUDE_REF,
                PelTag::GPS_LATITUDE,
                PelTag::GPS_LONGITUDE_REF,
                PelTag::GPS_LONGITUDE,
                PelTag::GPS_ALTITUDE_REF,
                PelTag::GPS_ALTITUDE,
                PelTag::GPS_TIME_STAMP,
                PelTag::GPS_SATELLITES,
                PelTag::GPS_STATUS,
                PelTag::GPS_MEASURE_MODE,
                PelTag::GPS_DOP,
                PelTag::GPS_SPEED_REF,
                PelTag::GPS_SPEED,
                PelTag::GPS_TRACK_REF,
                PelTag::GPS_TRACK,
                PelTag::GPS_IMG_DIRECTION_REF,
                PelTag::GPS_IMG_DIRECTION,
                PelTag::GPS_MAP_DATUM,
                PelTag::GPS_DEST_LATITUDE_REF,
                PelTag::GPS_DEST_LATITUDE,
                PelTag::GPS_DEST_LONGITUDE_REF,
                PelTag::GPS_DEST_LONGITUDE,
                PelTag::GPS_DEST_BEARING_REF,
                PelTag::GPS_DEST_BEARING,
                PelTag::GPS_DEST_DISTANCE_REF,
                PelTag::GPS_DEST_DISTANCE,
                PelTag::GPS_PROCESSING_METHOD,
                PelTag::GPS_AREA_INFORMATION,
                PelTag::GPS_DATE_STAMP,
                PelTag::GPS_DIFFERENTIAL);

            case PelIfd::INTEROPERABILITY:
                return array(PelTag::INTEROPERABILITY_INDEX,
                PelTag::INTEROPERABILITY_VERSION,
                PelTag::RELATED_IMAGE_FILE_FORMAT,
                PelTag::RELATED_IMAGE_WIDTH,
                PelTag::RELATED_IMAGE_LENGTH);

                /* TODO: Where do these tags belong?
                 PelTag::FILL_ORDER,
                 PelTag::DOCUMENT_NAME,
                 PelTag::TRANSFER_RANGE,
                 PelTag::JPEG_PROC,
                 PelTag::BATTERY_LEVEL,
                 PelTag::IPTC_NAA,
                 PelTag::INTER_COLOR_PROFILE,
                 PelTag::CFA_REPEAT_PATTERN_DIM,
                 */
        }
    }


    /**
     * Get the name of an IFD type.
     *
     * @param int one of {@link PelIfd::IFD0}, {@link PelIfd::IFD1},
     * {@link PelIfd::EXIF}, {@link PelIfd::GPS}, or {@link
     * PelIfd::INTEROPERABILITY}.
     *
     * @return string the name of type.
     */
    static function getTypeName($type) {
        switch ($type) {
            case self::IFD0:
                return '0';
            case self::IFD1:
                return '1';
            case self::EXIF:
                return 'Exif';
            case self::GPS:
                return 'GPS';
            case self::INTEROPERABILITY:
                return 'Interoperability';
            default:
                throw new PelIfdException('Unknown IFD type: %d', $type);
        }
    }


    /**
     * Get the name of this directory.
     *
     * @return string the name of this directory.
     */
    function getName() {
        return $this->getTypeName($this->type);
    }


    /**
     * Adds an entry to the directory.
     *
     * @param PelEntry the entry that will be added. If the entry is not
     * valid in this IFD (as per {@link isValidTag()}) an
     * {@link PelInvalidDataException} is thrown.
     *
     * @todo The entry will be identified with its tag, so each
     * directory can only contain one entry with each tag.  Is this a
     * bug?
     */
    function addEntry(PelEntry $e) {
        if ($this->isValidTag($e->getTag())) {
            $e->setIfdType($this->type);
            $this->entries[$e->getTag()] = $e;
        } else {
            throw new PelInvalidDataException("IFD %s cannot hold\n%s",
            $this->getName(), $e->__toString());
        }
    }


    /**
     * Does a given tag exist in this IFD?
     *
     * This methods is part of the ArrayAccess SPL interface for
     * overriding array access of objects, it allows you to check for
     * existance of an entry in the IFD:
     *
     * <code>
     * if (isset($ifd[PelTag::FNUMBER]))
     *   // ... do something with the F-number.
     * </code>
     *
     * @param PelTag the offset to check.
     *
     * @return boolean whether the tag exists.
     */
    function offsetExists($tag) {
        return isset($this->entries[$tag]);
    }


    /**
     * Retrieve a given tag from this IFD.
     *
     * This methods is part of the ArrayAccess SPL interface for
     * overriding array access of objects, it allows you to read entries
     * from the IFD the same was as for an array:
     *
     * <code>
     * $entry = $ifd[PelTag::FNUMBER];
     * </code>
     *
     * @param PelTag the tag to return.  It is an error to ask for a tag
     * which is not in the IFD, just like asking for a non-existant
     * array entry.
     *
     * @return PelEntry the entry.
     */
    function offsetGet($tag) {
        return $this->entries[$tag];
    }


    /**
     * Set or update a given tag in this IFD.
     *
     * This methods is part of the ArrayAccess SPL interface for
     * overriding array access of objects, it allows you to add new
     * entries or replace esisting entries by doing:
     *
     * <code>
     * $ifd[PelTag::EXPOSURE_BIAS_VALUE] = $entry;
     * </code>
     *
     * Note that the actual array index passed is ignored!  Instead the
     * {@link PelTag} from the entry is used.
     *
     * @param PelTag the offset to update.
     *
     * @param PelEntry the new value.
     */
    function offsetSet($tag, $e) {
        if ($e instanceof PelEntry) {
            $tag = $e->getTag();
            $this->entries[$tag] = $e;
        } else {
            throw new PelInvalidArgumentException('Argument "%s" must be a PelEntry.', $e);
        }
    }


    /**
     * Unset a given tag in this IFD.
     *
     * This methods is part of the ArrayAccess SPL interface for
     * overriding array access of objects, it allows you to delete
     * entries in the IFD by doing:
     *
     * <code>
     * unset($ifd[PelTag::EXPOSURE_BIAS_VALUE])
     * </code>
     *
     * @param PelTag the offset to delete.
     */
    function offsetUnset($tag) {
        unset($this->entries[$tag]);
    }


    /**
     * Retrieve an entry.
     *
     * @param PelTag the tag identifying the entry.
     *
     * @return PelEntry the entry associated with the tag, or null if no
     * such entry exists.
     */
    function getEntry($tag) {
        if (isset($this->entries[$tag]))
        return $this->entries[$tag];
        else
        return null;
    }


    /**
     * Returns all entries contained in this IFD.
     *
     * @return array an array of {@link PelEntry} objects, or rather
     * descendant classes.  The array has {@link PelTag}s as keys
     * and the entries as values.
     *
     * @see getEntry
     * @see getIterator
     */
    function getEntries() {
        return $this->entries;
    }


    /**
     * Return an iterator for all entries contained in this IFD.
     *
     * Used with foreach as in
     *
     * <code>
     * foreach ($ifd as $tag => $entry) {
     *   // $tag is now a PelTag and $entry is a PelEntry object.
     * }
     * </code>
     *
     * @return Iterator an iterator using the {@link PelTag tags} as
     * keys and the entries as values.
     */
    function getIterator() {
        return new ArrayIterator($this->entries);
    }


    /**
     * Returns available thumbnail data.
     *
     * @return string the bytes in the thumbnail, if any.  If the IFD
     * does not contain any thumbnail data, the empty string is
     * returned.
     *
     * @todo Throw an exception instead when no data is available?
     *
     * @todo Return the $this->thumb_data object instead of the bytes?
     */
    function getThumbnailData() {
        if ($this->thumb_data != null)
        return $this->thumb_data->getBytes();
        else
        return '';
    }


    /**
     * Make this directory point to a new directory.
     *
     * @param PelIfd the IFD that this directory will point to.
     */
    function setNextIfd(PelIfd $i) {
        $this->next = $i;
    }


    /**
     * Return the IFD pointed to by this directory.
     *
     * @return PelIfd the next IFD, following this IFD. If this is the
     * last IFD, null is returned.
     */
    function getNextIfd() {
        return $this->next;
    }


    /**
     * Check if this is the last IFD.
     *
     * @return boolean true if there are no following IFD, false
     * otherwise.
     */
    function isLastIfd() {
        return $this->next == null;
    }


    /**
     * Add a sub-IFD.
     *
     * Any previous sub-IFD of the same type will be overwritten.
     *
     * @param PelIfd the sub IFD.  The type of must be one of {@link
     * PelIfd::EXIF}, {@link PelIfd::GPS}, or {@link
     * PelIfd::INTEROPERABILITY}.
     */
    function addSubIfd(PelIfd $sub) {
        $this->sub[$sub->type] = $sub;
    }


    /**
     * Return a sub IFD.
     *
     * @param int the type of the sub IFD.  This must be one of {@link
     * PelIfd::EXIF}, {@link PelIfd::GPS}, or {@link
     * PelIfd::INTEROPERABILITY}.
     *
     * @return PelIfd the IFD associated with the type, or null if that
     * sub IFD does not exist.
     */
    function getSubIfd($type) {
        if (isset($this->sub[$type]))
        return $this->sub[$type];
        else
        return null;
    }


    /**
     * Get all sub IFDs.
     *
     * @return array an associative array with (IFD-type, {@link
     * PelIfd}) pairs.
     */
    function getSubIfds() {
        return $this->sub;
    }


    /**
     * Turn this directory into bytes.
     *
     * This directory will be turned into a byte string, with the
     * specified byte order.  The offsets will be calculated from the
     * offset given.
     *
     * @param int the offset of the first byte of this directory.
     *
     * @param PelByteOrder the byte order that should be used when
     * turning integers into bytes.  This should be one of {@link
     * PelConvert::LITTLE_ENDIAN} and {@link PelConvert::BIG_ENDIAN}.
     */
    function getBytes($offset, $order) {
        $bytes = '';
        $extra_bytes = '';

        Pel::debug('Bytes from IDF will start at offset %d within Exif data',
        $offset);

        $n = count($this->entries) + count($this->sub);
        if ($this->thumb_data != null) {
            /* We need two extra entries for the thumbnail offset and
             * length. */
            $n += 2;
        }

        $bytes .= PelConvert::shortToBytes($n, $order);

        /* Initialize offset of extra data.  This included the bytes
         * preceding this IFD, the bytes needed for the count of entries,
         * the entries themselves (and sub entries), the extra data in the
         * entries, and the IFD link.
         */
        $end = $offset + 2 + 12 * $n + 4;

        foreach ($this->entries as $tag => $entry) {
            /* Each entry is 12 bytes long. */
            $bytes .= PelConvert::shortToBytes($entry->getTag(), $order);
            $bytes .= PelConvert::shortToBytes($entry->getFormat(), $order);
            $bytes .= PelConvert::longToBytes($entry->getComponents(), $order);

            /*
             * Size? If bigger than 4 bytes, the actual data is not in
             * the entry but somewhere else.
             */
            $data = $entry->getBytes($order);
            $s = strlen($data);
            if ($s > 4) {
                Pel::debug('Data size %d too big, storing at offset %d instead.',
                $s, $end);
                $bytes .= PelConvert::longToBytes($end, $order);
                $extra_bytes .= $data;
                $end += $s;
            } else {
                Pel::debug('Data size %d fits.', $s);
                /* Copy data directly, pad with NULL bytes as necessary to
                 * fill out the four bytes available.*/
                $bytes .= $data . str_repeat(chr(0), 4 - $s);
            }
        }

        if ($this->thumb_data != null) {
            Pel::debug('Appending %d bytes of thumbnail data at %d',
            $this->thumb_data->getSize(), $end);
            // TODO: make PelEntry a class that can be constructed with
            // arguments corresponding to the newt four lines.
            $bytes .= PelConvert::shortToBytes(PelTag::JPEG_INTERCHANGE_FORMAT_LENGTH,
            $order);
            $bytes .= PelConvert::shortToBytes(PelFormat::LONG, $order);
            $bytes .= PelConvert::longToBytes(1, $order);
            $bytes .= PelConvert::longToBytes($this->thumb_data->getSize(),
            $order);

            $bytes .= PelConvert::shortToBytes(PelTag::JPEG_INTERCHANGE_FORMAT,
            $order);
            $bytes .= PelConvert::shortToBytes(PelFormat::LONG, $order);
            $bytes .= PelConvert::longToBytes(1, $order);
            $bytes .= PelConvert::longToBytes($end, $order);

            $extra_bytes .= $this->thumb_data->getBytes();
            $end += $this->thumb_data->getSize();
        }


        /* Find bytes from sub IFDs. */
        $sub_bytes = '';
        foreach ($this->sub as $type => $sub) {
            if ($type == PelIfd::EXIF)
            $tag = PelTag::EXIF_IFD_POINTER;
            elseif ($type == PelIfd::GPS)
            $tag = PelTag::GPS_INFO_IFD_POINTER;
            elseif ($type == PelIfd::INTEROPERABILITY)
            $tag = PelTag::INTEROPERABILITY_IFD_POINTER;

            /* Make an aditional entry with the pointer. */
            $bytes .= PelConvert::shortToBytes($tag, $order);
            /* Next the format, which is always unsigned long. */
            $bytes .= PelConvert::shortToBytes(PelFormat::LONG, $order);
            /* There is only one component. */
            $bytes .= PelConvert::longToBytes(1, $order);

            $data = $sub->getBytes($end, $order);
            $s = strlen($data);
            $sub_bytes .= $data;

            $bytes .= PelConvert::longToBytes($end, $order);
            $end += $s;
        }

        /* Make link to next IFD, if any*/
        if ($this->isLastIFD()) {
            $link = 0;
        } else {
            $link = $end;
        }

        Pel::debug('Link to next IFD: %d', $link);

        $bytes .= PelConvert::longtoBytes($link, $order);

        $bytes .= $extra_bytes . $sub_bytes;

        if (!$this->isLastIfd())
        $bytes .= $this->next->getBytes($end, $order);

        return $bytes;
    }


    /**
     * Turn this directory into text.
     *
     * @return string information about the directory, mainly for
     * debugging.
     */
    function __toString() {
        $str = Pel::fmt("Dumping IFD %s with %d entries...\n",
        $this->getName(), count($this->entries));

        foreach ($this->entries as $entry)
        $str .= $entry->__toString();

        $str .= Pel::fmt("Dumping %d sub IFDs...\n", count($this->sub));

        foreach ($this->sub as $type => $ifd)
        $str .= $ifd->__toString();

        if ($this->next != null)
        $str .= $this->next->__toString();

        return $str;
    }


}

