Source for file PelEntry.php

Documentation is available at PelEntry.php

  1. <?php
  2.  
  3. /*  PEL: PHP Exif Library.  A library with support for reading and
  4.  *  writing all Exif headers in JPEG and TIFF images using PHP.
  5.  *
  6.  *  Copyright (C) 2004, 2005, 2006  Martin Geisler.
  7.  *
  8.  *  This program is free software; you can redistribute it and/or modify
  9.  *  it under the terms of the GNU General Public License as published by
  10.  *  the Free Software Foundation; either version 2 of the License, or
  11.  *  (at your option) any later version.
  12.  *
  13.  *  This program is distributed in the hope that it will be useful,
  14.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16.  *  GNU General Public License for more details.
  17.  *
  18.  *  You should have received a copy of the GNU General Public License
  19.  *  along with this program in the file COPYING; if not, write to the
  20.  *  Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  21.  *  Boston, MA 02110-1301 USA
  22.  */
  23.  
  24. /* $Id: PelEntry.php 442 2006-09-17 12:45:10Z mgeisler $ */
  25.  
  26.  
  27. /**
  28.  * Classes for dealing with Exif entries.
  29.  *
  30.  * This file defines two exception classes and the abstract class
  31.  * {@link PelEntry} which provides the basic methods that all Exif
  32.  * entries will have.  All Exif entries will be represented by
  33.  * descendants of the {@link PelEntry} class --- the class itself is
  34.  * abstract and so it cannot be instantiated.
  35.  *
  36.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  37.  * @version $Revision: 442 $
  38.  * @date $Date: 2006-09-17 14:45:10 +0200 (Sun, 17 Sep 2006) $
  39.  * @license http://www.gnu.org/licenses/gpl.html GNU General Public
  40.  *  License (GPL)
  41.  * @package PEL
  42.  */
  43.  
  44. /**#@+ Required class definitions. */
  45. require_once('PelException.php');
  46. require_once('PelFormat.php');
  47. require_once('PelTag.php');
  48. require_once('Pel.php');
  49. /**#@-*/
  50.  
  51.  
  52.  * Exception indicating a problem with an entry.
  53.  *
  54.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  55.  * @package PEL
  56.  * @subpackage Exception
  57.  */
  58. class PelEntryException extends PelException {
  59.  
  60.   /**
  61.    * The IFD type (if known).
  62.    *
  63.    * @var int 
  64.    */
  65.   protected $type;
  66.  
  67.   /**
  68.    * The tag of the entry (if known).
  69.    *
  70.    * @var PelTag 
  71.    */
  72.   protected $tag;
  73.  
  74.   /**
  75.    * Get the IFD type associated with the exception.
  76.    *
  77.    * @return int one of {@link PelIfd::IFD0}, {@link PelIfd::IFD1},
  78.    *  {@link PelIfd::EXIF}, {@link PelIfd::GPS}, or {@link }
  79.    *  PelIfd::INTEROPERABILITY}.  If no type is set, null is returned.
  80.    */
  81.   function getIfdType() {
  82.     return $this->type;
  83.   }
  84.  
  85.  
  86.   /**
  87.    * Get the tag associated with the exception.
  88.    *
  89.    * @return PelTag the tag.  If no tag is set, null is returned.
  90.    */
  91.   function getTag() {
  92.     return $this->tag;
  93.   }
  94.  
  95. }
  96.  
  97.  
  98. /**
  99.  * Exception indicating that an unexpected format was found.
  100.  *
  101.  * The documentation for each tag in {@link PelTag} will detail any
  102.  * constrains.
  103.  *
  104.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  105.  * @package PEL
  106.  * @subpackage Exception
  107.  */
  108. class PelUnexpectedFormatException extends PelEntryException {
  109.  
  110.   /**
  111.    * Construct a new exception indicating an invalid format.
  112.    *
  113.    * @param int the type of IFD.
  114.    *
  115.    * @param PelTag the tag for which the violation was found.
  116.    *
  117.    * @param PelFormat the format found.
  118.    *
  119.    * @param PelFormat the expected format.
  120.    */
  121.   function __construct($type, $tag, $found, $expected) {
  122.     parent::__construct('Unexpected format found for %s tag: PelFormat::%s. ' .
  123.                         'Expected PelFormat::%s instead.',
  124.                         PelTag::getName($type, $tag),
  125.                         strtoupper(PelFormat::getName($found)),
  126.                         strtoupper(PelFormat::getName($expected)));
  127.     $this->tag  = $tag;
  128.     $this->type = $type;
  129.   }
  130. }
  131.  
  132.  
  133. /**
  134.  * Exception indicating that an unexpected number of components was
  135.  * found.
  136.  *
  137.  * Some tags have strict limits as to the allowed number of
  138.  * components, and this exception is thrown if the data violates such
  139.  * a constraint.  The documentation for each tag in {@link PelTag}
  140.  * explains the expected number of components.
  141.  *
  142.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  143.  * @package PEL
  144.  * @subpackage Exception
  145.  */
  146. class PelWrongComponentCountException extends PelEntryException {
  147.  
  148.   /**
  149.    * Construct a new exception indicating a wrong number of
  150.    * components.
  151.    *
  152.    * @param int the type of IFD.
  153.    *
  154.    * @param PelTag the tag for which the violation was found.
  155.    *
  156.    * @param int the number of components found.
  157.    *
  158.    * @param int the expected number of components.
  159.    */
  160.   function __construct($type, $tag, $found, $expected) {
  161.     parent::__construct('Wrong number of components found for %s tag: %d. ' .
  162.                         'Expected %d.',
  163.                         PelTag::getName($type, $tag), $found, $expected);
  164.     $this->tag  = $tag;
  165.     $this->type = $type;
  166.   }
  167. }
  168.  
  169.  
  170. /**
  171.  * Common ancestor class of all {@link PelIfd} entries.
  172.  *
  173.  * As this class is abstract you cannot instantiate objects from it.
  174.  * It only serves as a common ancestor to define the methods common to
  175.  * all entries.  The most important methods are {@link getValue()} and
  176.  * {@link setValue()}, both of which is abstract in this class.  The
  177.  * descendants will give concrete implementations for them.
  178.  *
  179.  * If you have some data coming from an image (some raw bytes), then
  180.  * the static method {@link newFromData()} is helpful --- it will look
  181.  * at the data and give you a proper decendent of {@link PelEntry}
  182.  * back.
  183.  *
  184.  * If you instead want to have an entry for some data which take the
  185.  * form of an integer, a string, a byte, or some other PHP type, then
  186.  * don't use this class.  You should instead create an object of the
  187.  * right subclass ({@link PelEntryShort} for short integers, {@link }
  188.  * PelEntryAscii} for strings, and so on) directly.
  189.  *
  190.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  191.  * @package PEL
  192.  */
  193. abstract class PelEntry {
  194.  
  195.   /**
  196.    * Type of IFD containing this tag.
  197.    *
  198.    * This must be one of the constants defined in {@link PelIfd}:
  199.    * {@link PelIfd::IFD0} for the main image IFD, {@link PelIfd::IFD1}
  200.    * for the thumbnail image IFD, {@link PelIfd::EXIF} for the Exif
  201.    * sub-IFD, {@link PelIfd::GPS} for the GPS sub-IFD, or {@link }
  202.    * PelIfd::INTEROPERABILITY} for the interoperability sub-IFD.
  203.    *
  204.    * @var int 
  205.    */
  206.   protected $ifd_type;
  207.  
  208.   /**
  209.    * The bytes representing this entry.
  210.    *
  211.    * Subclasses must either override {@link getBytes()} or, if
  212.    * possible, maintain this property so that it always contains a
  213.    * true representation of the entry.
  214.    *
  215.    * @var string 
  216.    */
  217.   protected $bytes = '';
  218.  
  219.   /**
  220.    * The {@link PelTag} of this entry.
  221.    *
  222.    * @var PelTag 
  223.    */
  224.   protected $tag;
  225.  
  226.   /**
  227.    * The {@link PelFormat} of this entry.
  228.    *
  229.    * @var PelFormat 
  230.    */
  231.   protected $format;
  232.  
  233.   /**
  234.    * The number of components of this entry.
  235.    *
  236.    * @var int 
  237.    */
  238.   protected $components;
  239.  
  240.  
  241.   /**
  242.    * Return the tag of this entry.
  243.    *
  244.    * @return PelTag the tag of this entry.
  245.    */
  246.   function getTag() {
  247.     return $this->tag;
  248.   }
  249.  
  250.  
  251.   /**
  252.    * Return the type of IFD which holds this entry.
  253.    *
  254.    * @return int one of the constants defined in {@link PelIfd}:
  255.    *  {@link PelIfd::IFD0} for the main image IFD, {@link PelIfd::IFD1}
  256.    *  for the thumbnail image IFD, {@link PelIfd::EXIF} for the Exif
  257.    *  sub-IFD, {@link PelIfd::GPS} for the GPS sub-IFD, or {@link }
  258.    *  PelIfd::INTEROPERABILITY} for the interoperability sub-IFD.
  259.    */
  260.   function getIfdType() {
  261.     return $this->ifd_type;
  262.   }
  263.  
  264.  
  265.   /**
  266.    * Update the IFD type.
  267.    *
  268.    * @param int must be one of the constants defined in {@link }
  269.    *  PelIfd}: {@link PelIfd::IFD0} for the main image IFD, {@link }
  270.    *  PelIfd::IFD1} for the thumbnail image IFD, {@link PelIfd::EXIF}
  271.    *  for the Exif sub-IFD, {@link PelIfd::GPS} for the GPS sub-IFD, or
  272.    *  {@link PelIfd::INTEROPERABILITY} for the interoperability
  273.    *  sub-IFD.
  274.    */
  275.   function setIfdType($type) {
  276.     $this->ifd_type = $type;
  277.   }
  278.  
  279.  
  280.   /**
  281.    * Return the format of this entry.
  282.    *
  283.    * @return PelFormat the format of this entry.
  284.    */
  285.   function getFormat() {
  286.     return $this->format;
  287.   }
  288.  
  289.  
  290.   /**
  291.    * Return the number of components of this entry.
  292.    *
  293.    * @return int the number of components of this entry.
  294.    */
  295.   function getComponents() {
  296.     return $this->components;
  297.   }
  298.  
  299.  
  300.   /**
  301.    * Turn this entry into bytes.
  302.    *
  303.    * @param PelByteOrder the desired byte order, which must be either
  304.    *  {@link Convert::LITTLE_ENDIAN} or {@link Convert::BIG_ENDIAN}.
  305.    *
  306.    * @return string bytes representing this entry.
  307.    */
  308.   function getBytes($o) {
  309.     return $this->bytes;
  310.   }
  311.  
  312.  
  313.   /**
  314.    * Get the value of this entry as text.
  315.    *
  316.    * The value will be returned in a format suitable for presentation,
  317.    * e.g., rationals will be returned as 'x/y', ASCII strings will be
  318.    * returned as themselves etc.
  319.    *
  320.    * @param boolean some values can be returned in a long or more
  321.    *  brief form, and this parameter controls that.
  322.    *
  323.    * @return string the value as text.
  324.    */
  325.   abstract function getText($brief = false);
  326.  
  327.  
  328.   /**
  329.    * Get the value of this entry.
  330.    *
  331.    * The value returned will generally be the same as the one supplied
  332.    * to the constructor or with {@link setValue()}.  For a formatted
  333.    * version of the value, one should use {@link getText()} instead.
  334.    *
  335.    * @return mixed the unformatted value.
  336.    */
  337.   abstract function getValue();
  338.  
  339.  
  340.   /**
  341.    * Set the value of this entry.
  342.    *
  343.    * The value should be in the same format as for the constructor.
  344.    *
  345.    * @param mixed the new value.
  346.    *
  347.    * @abstract
  348.    */
  349.   function setValue($value) {
  350.     /* This (fake) abstract method is here to make it possible for the
  351.      * documentation to refer to PelEntry::setValue().
  352.      *
  353.      * It cannot declared abstract in the proper PHP way, for then PHP
  354.      * wont allow subclasses to define it with two arguments (which is
  355.      * what PelEntryCopyright does).
  356.      */
  357.     throw new PelException('setValue() is abstract.');
  358.   }
  359.  
  360.  
  361.   /**
  362.    * Turn this entry into a string.
  363.    *
  364.    * @return string a string representation of this entry.  This is
  365.    *  mostly for debugging.
  366.    */
  367.   function __toString() {
  368.     $str = Pel::fmt("  Tag: 0x%04X (%s)\n",
  369.                     $this->tag, PelTag::getName($this->ifd_type, $this->tag));
  370.     $str .= Pel::fmt("    Format    : %d (%s)\n",
  371.                      $this->format, PelFormat::getName($this->format));
  372.     $str .= Pel::fmt("    Components: %d\n", $this->components);
  373.     if ($this->getTag() != PelTag::MAKER_NOTE &&
  374.         $this->getTag() != PelTag::PRINT_IM)
  375.       $str .= Pel::fmt("    Value     : %s\n", print_r($this->getValue(), true));
  376.     $str .= Pel::fmt("    Text      : %s\n", $this->getText());
  377.     return $str;
  378.   }
  379. }
  380.  
  381. ?>

Documentation generated on Tue, 19 Dec 2006 01:08:17 +0100 by phpDocumentor 1.3.0 SourceForge.net Logo