Source for file PelDataWindow.php

Documentation is available at PelDataWindow.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, 2007  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$ */
  25.  
  26.  
  27. /**
  28.  * A container for bytes with a limited window of accessible bytes.
  29.  *
  30.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  31.  * @version $Revision$
  32.  * @date $Date$
  33.  * @license http://www.gnu.org/licenses/gpl.html GNU General Public License (GPL)
  34.  * @package PEL
  35.  */
  36.  
  37. /**#@+ Required class definitions. */
  38. require_once('PelException.php');
  39. require_once('PelConvert.php');
  40. /**#@-*/
  41.  
  42.  
  43. /**
  44.  * An exception thrown when an invalid offset is encountered.
  45.  *
  46.  * @package PEL
  47.  * @subpackage Exception
  48.  */
  49. class PelDataWindowOffsetException extends PelException {}
  50.  
  51. /**
  52.  * An exception thrown when an invalid window is encountered.
  53.  *
  54.  * @package PEL
  55.  * @subpackage Exception
  56.  */
  57. class PelDataWindowWindowException extends PelException {}
  58.  
  59. /**
  60.  * The window.
  61.  *
  62.  * @package PEL
  63.  */
  64. class PelDataWindow {
  65.  
  66.   /**
  67.    * The data held by this window.
  68.    *
  69.    * The string can contain any kind of data, including binary data.
  70.    *
  71.    * @var string 
  72.    */
  73.   private $data = '';
  74.  
  75.   /**
  76.    * The byte order currently in use.
  77.    *
  78.    * This will be the byte order used when data is read using the for
  79.    * example the {@link getShort} function.  It must be one of {@link }
  80.    * PelConvert::LITTLE_ENDIAN} and {@link PelConvert::BIG_ENDIAN}.
  81.    *
  82.    * @var PelByteOrder 
  83.    * @see setByteOrder, getByteOrder
  84.    */
  85.   private $order;
  86.  
  87.   /**
  88.    * The start of the current window.
  89.    *
  90.    * All offsets used for access into the data will count from this
  91.    * offset, effectively limiting access to a window starting at this
  92.    * byte.
  93.    *
  94.    * @var int 
  95.    * @see setWindowStart
  96.    */
  97.   private $start  = 0;
  98.  
  99.   /**
  100.    * The size of the current window.
  101.    *
  102.    * All offsets used for access into the data will be limited by this
  103.    * variable.  A valid offset must be strictly less than this
  104.    * variable.
  105.    *
  106.    * @var int 
  107.    * @see setWindowSize
  108.    */
  109.   private $size   = 0;
  110.  
  111.  
  112.   /**
  113.    * Construct a new data window with the data supplied.
  114.    *
  115.    * @param mixed the data that this window will contain. This can
  116.    *  either be given as a string (interpreted litteraly as a sequence
  117.    *  of bytes) or a PHP image resource handle. The data will be copied
  118.    *  into the new data window.
  119.    *
  120.    * @param boolean the initial byte order of the window.  This must
  121.    *  be either {@link PelConvert::LITTLE_ENDIAN} or {@link }
  122.    *  PelConvert::BIG_ENDIAN}.  This will be used when integers are
  123.    *  read from the data, and it can be changed later with {@link }
  124.    *  setByteOrder()}.
  125.    */
  126.   function __construct($data = '', $endianess = PelConvert::LITTLE_ENDIAN) {
  127.     if (is_string($data)) {
  128.       $this->data = $data;
  129.     } elseif (is_resource($data) && get_resource_type($data) == 'gd') {
  130.       /* The ImageJpeg() function insists on printing the bytes
  131.        * instead of returning them in a more civil way as a string, so
  132.        * we have to buffer the output... */
  133.       ob_start();
  134.       ImageJpeg($data, null, Pel::getJPEGQuality());
  135.       $this->data = ob_get_clean();
  136.     } else {
  137.       throw new PelInvalidArgumentException('Bad type for $data: %s', 
  138.                                             gettype($data));
  139.     }
  140.  
  141.     $this->order = $endianess;
  142.     $this->size  = strlen($this->data);
  143.   }
  144.  
  145.  
  146.   /**
  147.    * Get the size of the data window.
  148.    *
  149.    * @return int the number of bytes covered by the window.  The
  150.    *  allowed offsets go from 0 up to this number minus one.
  151.    *
  152.    * @see getBytes()
  153.    */
  154.   function getSize() {
  155.     return $this->size;
  156.   }
  157.  
  158.  
  159.   /**
  160.    * Change the byte order of the data.
  161.    *
  162.    * @param PelByteOrder the new byte order.  This must be either
  163.    *  {@link PelConvert::LITTLE_ENDIAN} or {@link }
  164.    *  PelConvert::BIG_ENDIAN}.
  165.    */
  166.   function setByteOrder($o) {
  167.     $this->order = $o;
  168.   }
  169.  
  170.  
  171.   /**
  172.    * Get the currently used byte order.
  173.    *
  174.    * @return PelByteOrder this will be either {@link }
  175.    *  PelConvert::LITTLE_ENDIAN} or {@link PelConvert::BIG_ENDIAN}.
  176.    */
  177.   function getByteOrder() {
  178.     return $this->order;
  179.   }
  180.  
  181.  
  182.   /* Move the start of the window forward.
  183.    *
  184.    * @param int the new start of the window.  All new offsets will be
  185.    * calculated from this new start offset, and the size of the window
  186.    * will shrink to keep the end of the window in place.
  187.    */
  188.   function setWindowStart($start) {
  189.     if ($start < 0 || $start > $this->size)
  190.       throw new PelDataWindowWindowException('Window [%d, %d] does ' .
  191.                                              'not fit in window [0, %d]',
  192.                                              $start, $this->size, $this->size);
  193.  
  194.     $this->start += $start;
  195.     $this->size  -= $start;
  196.   }
  197.  
  198.  
  199.   /**
  200.    * Adjust the size of the window.
  201.    *
  202.    * The size can only be made smaller.
  203.    *
  204.    * @param int the desired size of the window.  If the argument is
  205.    *  negative, the window will be shrunk by the argument.
  206.    */
  207.   function setWindowSize($size) {
  208.     if ($size < 0)
  209.       $size += $this->size;
  210.  
  211.     if ($size < 0 || $size > $this->size)
  212.       throw new PelDataWindowWindowException('Window [0, %d] ' .
  213.                                              'does not fit in window [0, %d]',
  214.                                              $size, $this->size);
  215.     $this->size = $size;
  216.   }
  217.   
  218.  
  219.   /**
  220.    * Make a new data window with the same data as the this window.
  221.    *
  222.    * @param mixed if an integer is supplied, then it will be the start
  223.    *  of the window in the clone.  If left unspecified, then the clone
  224.    *  will inherit the start from this object.
  225.    *
  226.    * @param mixed if an integer is supplied, then it will be the size
  227.    *  of the window in the clone.  If left unspecified, then the clone
  228.    *  will inherit the size from this object.
  229.    *
  230.    * @return PelDataWindow a new window that operates on the same data
  231.    *  as this window, but (optionally) with a smaller window size.
  232.    */
  233.   function getClone($start = false, $size = false) {
  234.     $c = clone $this;
  235.     
  236.     if (is_int($start))
  237.       $c->setWindowStart($start);
  238.  
  239.     if (is_int($size))
  240.       $c->setWindowSize($size);
  241.  
  242.     return $c;
  243.   }
  244.  
  245.  
  246.   /**
  247.    * Validate an offset against the current window.
  248.    *
  249.    * @param int the offset to be validated.  If the offset is negative
  250.    *  or if it is greater than or equal to the current window size,
  251.    *  then a {@link PelDataWindowOffsetException} is thrown.
  252.    *
  253.    * @return void if the offset is valid nothing is returned, if it is
  254.    *  invalid a new {@link PelDataWindowOffsetException} is thrown.
  255.    */
  256.   private function validateOffset($o) {
  257.     if ($o < 0 || $o >= $this->size)
  258.       throw new PelDataWindowOffsetException('Offset %d not within [%d, %d]',
  259.                                              $o, 0, $this->size-1);
  260.   }
  261.  
  262.  
  263.   /**
  264.    * Return some or all bytes visible in the window.
  265.    *
  266.    * This method works just like the standard {@link substr()}
  267.    * function in PHP with the exception that it works within the
  268.    * window of accessible bytes and does strict range checking.
  269.    * 
  270.    * @param int the offset to the first byte returned.  If a negative
  271.    *  number is given, then the counting will be from the end of the
  272.    *  window.  Invalid offsets will result in a {@link }
  273.    *  PelDataWindowOffsetException} being thrown.
  274.    *
  275.    * @param int the size of the sub-window.  If a negative number is
  276.    *  given, then that many bytes will be omitted from the result.
  277.    *
  278.    * @return string a subset of the bytes in the window.  This will
  279.    *  always return no more than {@link getSize()} bytes.
  280.    */
  281.   function getBytes($start = false, $size = false) {
  282.     if (is_int($start)) {
  283.       if ($start < 0)
  284.         $start += $this->size;
  285.       
  286.       $this->validateOffset($start);
  287.     } else {
  288.       $start = 0;
  289.     }
  290.     
  291.     if (is_int($size)) {
  292.       if ($size <= 0)
  293.         $size += $this->size - $start;
  294.       
  295.       $this->validateOffset($start+$size);
  296.     } else {
  297.       $size = $this->size - $start;
  298.     }
  299.  
  300.     return substr($this->data, $this->start + $start, $size);
  301.   }
  302.  
  303.  
  304.   /**
  305.    * Return an unsigned byte from the data.
  306.    *
  307.    * @param int the offset into the data.  An offset of zero will
  308.    *  return the first byte in the current allowed window.  The last
  309.    *  valid offset is equal to {@link getSize()}-1.  Invalid offsets
  310.    *  will result in a {@link PelDataWindowOffsetException} being
  311.    *  thrown.
  312.    *
  313.    * @return  int  the unsigned byte found at offset.
  314.    */
  315.   function getByte($o = 0) {
  316.     /* Validate the offset --- this throws an exception if offset is
  317.      * out of range. */
  318.     $this->validateOffset($o);
  319.  
  320.     /* Translate the offset into an offset into the data. */
  321.     $o += $this->start;
  322.     
  323.     /* Return an unsigned byte. */
  324.     return PelConvert::bytesToByte($this->data, $o);
  325.   }
  326.  
  327.  
  328.   /**
  329.    * Return a signed byte from the data.
  330.    *
  331.    * @param int the offset into the data.  An offset of zero will
  332.    *  return the first byte in the current allowed window.  The last
  333.    *  valid offset is equal to {@link getSize()}-1.  Invalid offsets
  334.    *  will result in a {@link PelDataWindowOffsetException} being
  335.    *  thrown.
  336.    *
  337.    * @return  int  the signed byte found at offset.
  338.    */
  339.   function getSByte($o = 0) {
  340.     /* Validate the offset --- this throws an exception if offset is
  341.      * out of range. */
  342.     $this->validateOffset($o);
  343.  
  344.     /* Translate the offset into an offset into the data. */
  345.     $o += $this->start;
  346.     
  347.     /* Return a signed byte. */
  348.     return PelConvert::bytesToSByte($this->data, $o);
  349.   }
  350.  
  351.  
  352.   /**
  353.    * Return an unsigned short read from the data.
  354.    *
  355.    * @param int the offset into the data.  An offset of zero will
  356.    *  return the first short available in the current allowed window.
  357.    *  The last valid offset is equal to {@link getSize()}-2.  Invalid
  358.    *  offsets will result in a {@link PelDataWindowOffsetException}
  359.    *  being thrown.
  360.    *
  361.    * @return  int  the unsigned short found at offset.
  362.    */
  363.   function getShort($o = 0) {
  364.     /* Validate the offset+1 to see if we can safely get two bytes ---
  365.      * this throws an exception if offset is out of range. */
  366.     $this->validateOffset($o);
  367.     $this->validateOffset($o+1);
  368.  
  369.     /* Translate the offset into an offset into the data. */
  370.     $o += $this->start;
  371.  
  372.     /* Return an unsigned short. */
  373.     return PelConvert::bytesToShort($this->data, $o, $this->order);
  374.   }
  375.  
  376.  
  377.   /**
  378.    * Return a signed short read from the data.
  379.    *
  380.    * @param int the offset into the data.  An offset of zero will
  381.    *  return the first short available in the current allowed window.
  382.    *  The last valid offset is equal to {@link getSize()}-2.  Invalid
  383.    *  offsets will result in a {@link PelDataWindowOffsetException}
  384.    *  being thrown.
  385.    *
  386.    * @return  int  the signed short found at offset.
  387.    */
  388.   function getSShort($o = 0) {
  389.     /* Validate the offset+1 to see if we can safely get two bytes ---
  390.      * this throws an exception if offset is out of range. */
  391.     $this->validateOffset($o);
  392.     $this->validateOffset($o+1);
  393.  
  394.     /* Translate the offset into an offset into the data. */
  395.     $o += $this->start;
  396.  
  397.     /* Return a signed short. */
  398.     return PelConvert::bytesToSShort($this->data, $o, $this->order);
  399.   }
  400.  
  401.  
  402.   /**
  403.    * Return an unsigned long read from the data.
  404.    *
  405.    * @param int the offset into the data.  An offset of zero will
  406.    *  return the first long available in the current allowed window.
  407.    *  The last valid offset is equal to {@link getSize()}-4.  Invalid
  408.    *  offsets will result in a {@link PelDataWindowOffsetException}
  409.    *  being thrown.
  410.    *
  411.    * @return  int  the unsigned long found at offset.
  412.    */
  413.   function getLong($o = 0) {
  414.     /* Validate the offset+3 to see if we can safely get four bytes
  415.      * --- this throws an exception if offset is out of range. */
  416.     $this->validateOffset($o);
  417.     $this->validateOffset($o+3);
  418.    
  419.     /* Translate the offset into an offset into the data. */
  420.     $o += $this->start;
  421.  
  422.     /* Return an unsigned long. */
  423.     return PelConvert::bytesToLong($this->data, $o, $this->order);
  424.   }
  425.  
  426.  
  427.   /**
  428.    * Return a signed long read from the data.
  429.    *
  430.    * @param int the offset into the data.  An offset of zero will
  431.    *  return the first long available in the current allowed window.
  432.    *  The last valid offset is equal to {@link getSize()}-4.  Invalid
  433.    *  offsets will result in a {@link PelDataWindowOffsetException}
  434.    *  being thrown.
  435.    *
  436.    * @return  int  the signed long found at offset.
  437.    */
  438.   function getSLong($o = 0) {
  439.     /* Validate the offset+3 to see if we can safely get four bytes
  440.      * --- this throws an exception if offset is out of range. */
  441.     $this->validateOffset($o);
  442.     $this->validateOffset($o+3);
  443.    
  444.     /* Translate the offset into an offset into the data. */
  445.     $o += $this->start;
  446.  
  447.     /* Return a signed long. */
  448.     return PelConvert::bytesToSLong($this->data, $o, $this->order);
  449.   }
  450.  
  451.  
  452.   /**
  453.    * Return an unsigned rational read from the data.
  454.    *
  455.    * @param int the offset into the data.  An offset of zero will
  456.    *  return the first rational available in the current allowed
  457.    *  window.  The last valid offset is equal to {@link getSize()}-8.
  458.    *  Invalid offsets will result in a {@link }
  459.    *  PelDataWindowOffsetException} being thrown.
  460.    *
  461.    * @return array the unsigned rational found at offset.  A rational
  462.    *  number is represented as an array of two numbers: the enumerator
  463.    *  and denominator.  Both of these numbers will be unsigned longs.
  464.    */
  465.   function getRational($o = 0) {
  466.     return array($this->getLong($o), $this->getLong($o+4));
  467.   }
  468.  
  469.  
  470.   /**
  471.    * Return a signed rational read from the data.
  472.    *
  473.    * @param int the offset into the data.  An offset of zero will
  474.    *  return the first rational available in the current allowed
  475.    *  window.  The last valid offset is equal to {@link getSize()}-8.
  476.    *  Invalid offsets will result in a {@link }
  477.    *  PelDataWindowOffsetException} being thrown.
  478.    *
  479.    * @return array the signed rational found at offset.  A rational
  480.    *  number is represented as an array of two numbers: the enumerator
  481.    *  and denominator.  Both of these numbers will be signed longs.
  482.    */
  483.   function getSRational($o = 0) {
  484.     return array($this->getSLong($o), $this->getSLong($o+4));
  485.   }
  486.  
  487.  
  488.   /**
  489.    * String comparison on substrings.
  490.    *
  491.    * @param int the offset into the data.  An offset of zero will make
  492.    *  the comparison start with the very first byte available in the
  493.    *  window.  The last valid offset is equal to {@link getSize()}
  494.    *  minus the length of the string.  If the string is too long, then
  495.    *  a {@link PelDataWindowOffsetException} will be thrown.
  496.    *
  497.    * @param string the string to compare with.
  498.    *
  499.    * @return boolean true if the string given matches the data in the
  500.    *  window, at the specified offset, false otherwise.  The comparison
  501.    *  will stop as soon as a mismatch if found.
  502.    */
  503.   function strcmp($o, $str) {
  504.     /* Validate the offset of the final character we might have to
  505.      * check. */
  506.     $s = strlen($str);
  507.     $this->validateOffset($o);
  508.     $this->validateOffset($o + $s - 1);
  509.  
  510.     /* Translate the offset into an offset into the data. */
  511.     $o += $this->start;
  512.   
  513.     /* Check each character, return as soon as the answer is known. */
  514.     for ($i = 0; $i < $s; $i++) {
  515.       if ($this->data{$o + $i} != $str{$i})
  516.         return false;
  517.     }
  518.  
  519.     /* All characters matches each other, return true. */
  520.     return true;
  521.   }
  522.  
  523.  
  524.   /**
  525.    * Return a string representation of the data window.
  526.    *
  527.    * @return string a description of the window with information about
  528.    *  the number of bytes accessible, the total number of bytes, and
  529.    *  the window start and stop.
  530.    */
  531.   function __toString() {
  532.     return Pel::fmt('DataWindow: %d bytes in [%d, %d] of %d bytes',
  533.                     $this->size,
  534.                     $this->start, $this->start + $this->size,
  535.                     strlen($this->data));
  536.   }
  537.  
  538. }
  539.  
  540. ?>

Documentation generated on Thu, 05 May 2011 07:18:59 +0200 by phpDocumentor 1.4.3