1 <?php

     2 /**

     3  * Zend Framework

     4  *

     5  * LICENSE

     6  *

     7  * This source file is subject to the new BSD license that is bundled

     8  * with this package in the file LICENSE.txt.

     9  * It is also available through the world-wide-web at this URL:

    10  * http://framework.zend.com/license/new-bsd

    11  * If you did not receive a copy of the license and are unable to

    12  * obtain it through the world-wide-web, please send an email

    13  * to license@zend.com so we can send you a copy immediately.

    14  *

    15  * @category   Zend

    16  * @package    Zend_Pdf

    17  * @subpackage FileParser

    18  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    19  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    20  * @version    $Id: FileParserDataSource.php 20096 2010-01-06 02:05:09Z bkarwin $

    21  */

    22 

    23 /**

    24  * Abstract helper class for {@link Zend_Pdf_FileParser} that provides the

    25  * data source for parsing.

    26  *

    27  * Concrete subclasses allow for parsing of in-memory, filesystem, and other

    28  * sources through a common API. These subclasses also take care of error

    29  * handling and other mundane tasks.

    30  *

    31  * Subclasses must implement at minimum {@link __construct()},

    32  * {@link __destruct()}, {@link readBytes()}, and {@link readAllBytes()}.

    33  * Subclasses should also override {@link moveToOffset()} and

    34  * {@link __toString()} as appropriate.

    35  *

    36  * @package    Zend_Pdf

    37  * @subpackage FileParser

    38  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    39  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    40  */

    41 abstract class Zend_Pdf_FileParserDataSource

    42 {

    43   /**** Instance Variables ****/

    44 

    45 

    46     /**

    47      * Total size in bytes of the data source.

    48      * @var integer

    49      */

    50     protected $_size = 0;

    51 

    52     /**

    53      * Byte offset of the current read position within the data source.

    54      * @var integer

    55      */

    56     protected $_offset = 0;

    57 

    58 

    59 

    60   /**** Public Interface ****/

    61 

    62 

    63   /* Abstract Methods */

    64 

    65     /**

    66      * Object constructor. Opens the data source for parsing.

    67      *

    68      * Must set $this->_size to the total size in bytes of the data source.

    69      *

    70      * Upon return the data source can be interrogated using the primitive

    71      * methods described here.

    72      *

    73      * If the data source cannot be opened for any reason (such as insufficient

    74      * permissions, missing file, etc.), will throw an appropriate exception.

    75      *

    76      * @throws Zend_Pdf_Exception

    77      */

    78     abstract public function __construct();

    79 

    80     /**

    81      * Object destructor. Closes the data source.

    82      *

    83      * May also perform cleanup tasks such as deleting temporary files.

    84      */

    85     abstract public function __destruct();

    86 

    87     /**

    88      * Returns the specified number of raw bytes from the data source at the

    89      * byte offset of the current read position.

    90      *

    91      * Must advance the read position by the number of bytes read by updating

    92      * $this->_offset.

    93      *

    94      * Throws an exception if there is insufficient data to completely fulfill

    95      * the request or if an error occurs.

    96      *

    97      * @param integer $byteCount Number of bytes to read.

    98      * @return string

    99      * @throws Zend_Pdf_Exception

   100      */

   101     abstract public function readBytes($byteCount);

   102 

   103     /**

   104      * Returns the entire contents of the data source as a string.

   105      *

   106      * This method may be called at any time and so must preserve the byte

   107      * offset of the read position, both through $this->_offset and whatever

   108      * other additional pointers (such as the seek position of a file pointer)

   109      * that might be used.

   110      *

   111      * @return string

   112      */

   113     abstract public function readAllBytes();

   114 

   115 

   116   /* Object Magic Methods */

   117 

   118     /**

   119      * Returns a description of the object for debugging purposes.

   120      *

   121      * Subclasses should override this method to provide a more specific

   122      * description of the actual object being represented.

   123      *

   124      * @return string

   125      */

   126     public function __toString()

   127     {

   128         return get_class($this);

   129     }

   130 

   131 

   132   /* Accessors */

   133 

   134     /**

   135      * Returns the byte offset of the current read position within the data

   136      * source.

   137      *

   138      * @return integer

   139      */

   140     public function getOffset()

   141     {

   142         return $this->_offset;

   143     }

   144 

   145     /**

   146      * Returns the total size in bytes of the data source.

   147      *

   148      * @return integer

   149      */

   150     public function getSize()

   151     {

   152         return $this->_size;

   153     }

   154 

   155 

   156   /* Primitive Methods */

   157 

   158     /**

   159      * Moves the current read position to the specified byte offset.

   160      *

   161      * Throws an exception you attempt to move before the beginning or beyond

   162      * the end of the data source.

   163      *

   164      * If a subclass needs to perform additional tasks (such as performing a

   165      * fseek() on a filesystem source), it should do so after calling this

   166      * parent method.

   167      *

   168      * @param integer $offset Destination byte offset.

   169      * @throws Zend_Pdf_Exception

   170      */

   171     public function moveToOffset($offset)

   172     {

   173         if ($this->_offset == $offset) {

   174             return;    // Not moving; do nothing.

   175         }

   176         if ($offset < 0) {

   177             require_once 'Zend/Pdf/Exception.php';

   178             throw new Zend_Pdf_Exception('Attempt to move before start of data source',

   179                                          Zend_Pdf_Exception::MOVE_BEFORE_START_OF_FILE);

   180         }

   181         if ($offset >= $this->_size) {    // Offsets are zero-based.

   182             require_once 'Zend/Pdf/Exception.php';

   183             throw new Zend_Pdf_Exception('Attempt to move beyond end of data source',

   184                                          Zend_Pdf_Exception::MOVE_BEYOND_END_OF_FILE);

   185         }

   186         $this->_offset = $offset;

   187     }

   188 

   189     /**

   190      * Shifts the current read position within the data source by the specified

   191      * number of bytes.

   192      *

   193      * You may move forward (positive numbers) or backward (negative numbers).

   194      * Throws an exception you attempt to move before the beginning or beyond

   195      * the end of the data source.

   196      *

   197      * @param integer $byteCount Number of bytes to skip.

   198      * @throws Zend_Pdf_Exception

   199      */

   200     public function skipBytes($byteCount)

   201     {

   202         $this->moveToOffset($this->_offset + $byteCount);

   203     }

   204 }