Debug infos with var()=%d are for length and can be decimal.
[core.git] / inc / classes / main / file_directories / binary / class_BaseBinaryFile.php
1 <?php
2 /**
3  * A general binary file class
4  *
5  * @author              Roland Haeder <webmaster@ship-simu.org>
6  * @version             0.0.0
7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2015 Core Developer Team
8  * @license             GNU GPL 3.0 or any newer version
9  * @link                http://www.ship-simu.org
10  *
11  * This program is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation, either version 3 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
23  */
24 class BaseBinaryFile extends BaseAbstractFile {
25         /**
26          * Separator for header data
27          */
28         const SEPARATOR_HEADER_DATA = 0x01;
29
30         /**
31          * Separator header->entries
32          */
33         const SEPARATOR_HEADER_ENTRIES = 0x02;
34
35         /**
36          * Separator group->hash
37          */
38         const SEPARATOR_GROUP_HASH = 0x03;
39
40         /**
41          * Separator hash->value
42          */
43         const SEPARATOR_HASH_VALUE = 0x04;
44
45         /**
46          * Separator entry->entry
47          */
48         const SEPARATOR_ENTRIES = 0x05;
49
50         /**
51          * Separator type->position
52          */
53         const SEPARATOR_TYPE_POSITION = 0x06;
54
55         /**
56          * Length of count
57          */
58         const LENGTH_COUNT = 20;
59
60         /**
61          * Length of position
62          */
63         const LENGTH_POSITION = 20;
64
65         /**
66          * Length of group
67          */
68         const LENGTH_GROUP = 10;
69
70         /**
71          * Maximum length of entry type
72          */
73         const LENGTH_TYPE = 20;
74
75         //***** Array elements for 'gaps' array *****
76
77         /**
78          * Start of gap
79          */
80         const GAPS_INDEX_START = 'start';
81
82         /**
83          * End of gap
84          */
85         const GAPS_INDEX_END = 'end';
86
87         /**
88          * Current seek position
89          */
90         private $seekPosition = 0;
91
92         /**
93          * Size of header
94          */
95         private $headerSize = 0;
96
97         /**
98          * File header
99          */
100         private $header = array();
101
102         /**
103          * Seek positions for gaps ("fragmentation")
104          */
105         private $gaps = array();
106
107         /**
108          * Seek positions for damaged entries (e.g. mismatching hash sum, ...)
109          */
110         private $damagedEntries = array();
111
112         /**
113          * Back-buffer
114          */
115         private $backBuffer = '';
116
117         /**
118          * Currently loaded block (will be returned by current())
119          */
120         private $currentBlock = '';
121
122         /**
123          * Protected constructor
124          *
125          * @param       $className      Name of the class
126          * @return      void
127          */
128         protected function __construct ($className) {
129                 // Call parent constructor
130                 parent::__construct($className);
131
132                 // Init counters and gaps array
133                 $this->initCountersGapsArray();
134         }
135
136         /**
137          * Checks whether the abstracted file only contains gaps by counting all
138          * gaps' bytes together and compare it to total length.
139          *
140          * @return      $isGapsOnly             Whether the abstracted file only contains gaps
141          */
142         private function isFileOnlyGaps () {
143                 // First/last gap found?
144                 /* Only for debugging
145                 if (isset($this->gaps[0])) {
146                         // Output first and last gap
147                         self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] this->gaps[0]=%s,this->gaps[%s]=%s', __METHOD__, __LINE__, print_r($this->gaps[0], TRUE), (count($this->gaps) - 1), print_r($this->gaps[count($this->gaps) - 1], TRUE)));
148                 } // END - if
149                 */
150
151                 // Now count every gap
152                 $gapsSize = 0;
153                 foreach ($this->gaps as $gap) {
154                         // Calculate size of found gap: end-start including both
155                         $gapsSize += ($gap[self::GAPS_INDEX_END] - $gap[self::GAPS_INDEX_START]);
156                 } // END - if
157
158                 // Debug output
159                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] gapsSize=%s,this->headerSize=%s', __METHOD__, __LINE__, $gapsSize, $this->getHeaderSize()));
160
161                 // Total gap size + header size must be same as file size
162                 $isGapsOnly = (($this->getHeaderSize() + $gapsSize) == $this->getFileSize());
163
164                 // Return status
165                 return $isGapsOnly;
166         }
167
168         /**
169          * Initializes counter for valid entries, arrays for damaged entries and
170          * an array for gap seek positions. If you call this method on your own,
171          * please re-analyze the file structure. So you are better to call
172          * analyzeFile() instead of this method.
173          *
174          * @return      void
175          */
176         public function initCountersGapsArray () {
177                 // Init counter and seek position
178                 $this->setCounter(0);
179                 $this->setSeekPosition(0);
180
181                 // Init arrays
182                 $this->gaps = array();
183                 $this->damagedEntries = array();
184         }
185
186         /**
187          * Getter for header size
188          *
189          * @return      $totalEntries   Size of file header
190          */
191         public final function getHeaderSize () {
192                 // Get it
193                 return $this->headerSize;
194         }
195
196         /**
197          * Setter for header size
198          *
199          * @param       $headerSize             Size of file header
200          * @return      void
201          */
202         public final function setHeaderSize ($headerSize) {
203                 // Set it
204                 $this->headerSize = $headerSize;
205         }
206
207         /**
208          * Getter for header array
209          *
210          * @return      $totalEntries   Size of file header
211          */
212         public final function getHeader () {
213                 // Get it
214                 return $this->header;
215         }
216
217         /**
218          * Setter for header
219          *
220          * @param       $header         Array for a file header
221          * @return      void
222          */
223         public final function setHeader (array $header) {
224                 // Set it
225                 $this->header = $header;
226         }
227
228         /**
229          * Getter for seek position
230          *
231          * @return      $seekPosition   Current seek position (stored here in object)
232          */
233         public final function getSeekPosition () {
234                 // Get it
235                 return $this->seekPosition;
236         }
237
238         /**
239          * Setter for seek position
240          *
241          * @param       $seekPosition   Current seek position (stored here in object)
242          * @return      void
243          */
244         protected final function setSeekPosition ($seekPosition) {
245                 // And set it
246                 $this->seekPosition = $seekPosition;
247         }
248
249         /**
250          * Updates seekPosition attribute from file to avoid to much access on file.
251          *
252          * @return      void
253          */
254         public function updateSeekPosition () {
255                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
256
257                 // Get key (= seek position)
258                 $seekPosition = $this->key();
259                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] Setting seekPosition=%s', __METHOD__, __LINE__, $seekPosition));
260
261                 // And set it here
262                 $this->setSeekPosition($seekPosition);
263
264                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] EXIT!', __METHOD__, __LINE__));
265         }
266
267         /**
268          * Seeks to beginning of file, updates seek position in this object and
269          * flushes the header.
270          *
271          * @return      void
272          */
273         protected function rewindUpdateSeekPosition () {
274                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
275
276                 // flushFileHeader must be callable
277                 assert(is_callable(array($this, 'flushFileHeader')));
278
279                 // Seek to beginning of file
280                 $this->rewind();
281
282                 // And update seek position ...
283                 $this->updateSeekPosition();
284
285                 // ... to write it back into the file
286                 $this->flushFileHeader();
287
288                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] EXIT!', __METHOD__, __LINE__));
289         }
290
291         /**
292          * Seeks to old position
293          *
294          * @return      void
295          */
296         protected function seekToOldPosition () {
297                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
298
299                 // Seek to currently ("old") saved position
300                 $this->seek($this->getSeekPosition());
301
302                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] EXIT!', __METHOD__, __LINE__));
303         }
304
305         /**
306          * Checks whether the block separator has been found
307          *
308          * @param       $str            String to look in
309          * @return      $isFound        Whether the block separator has been found
310          */
311         public static function isBlockSeparatorFound ($str) {
312                 // Determine it
313                 $isFound = (strpos($str, chr(self::SEPARATOR_ENTRIES)) !== FALSE);
314
315                 // Return result
316                 return $isFound;
317         }
318
319         /**
320          * Initializes the back-buffer by setting it to an empty string.
321          *
322          * @return      void
323          */
324         private function initBackBuffer () {
325                 // Simply call the setter
326                 $this->setBackBuffer('');
327         }
328
329         /**
330          * Setter for backBuffer field
331          *
332          * @param       $backBuffer             Characters to "store" in back-buffer
333          * @return      void
334          */
335         private function setBackBuffer ($backBuffer) {
336                 // Cast to string (so no arrays or objects)
337                 $backBuffer = (string) $backBuffer;
338
339                 // ... and set it
340                 $this->backBuffer = $backBuffer;
341         }
342
343         /**
344          * Getter for backBuffer field
345          *
346          * @return      $backBuffer             Characters "stored" in back-buffer
347          */
348         private function getBackBuffer () {
349                 return $this->backBuffer;
350         }
351
352         /**
353          * Setter for currentBlock field
354          *
355          * @param       $currentBlock           Characters to set a currently loaded block
356          * @return      void
357          */
358         private function setCurrentBlock ($currentBlock) {
359                 // Cast to string (so no arrays or objects)
360                 $currentBlock = (string) $currentBlock;
361
362                 // ... and set it
363                 $this->currentBlock = $currentBlock;
364         }
365
366         /**
367          * Gets currently read data
368          *
369          * @return      $current        Currently read data
370          */
371         public function getCurrentBlock () {
372                 // Return it
373                 return $this->currentBlock;
374         }
375
376         /**
377          * Initializes this file class
378          *
379          * @param       $fileName       Name of this abstract file
380          * @return      void
381          */
382         protected function initFile ($fileName) {
383                 // Get a file i/o pointer instance
384                 $pointerInstance = ObjectFactory::createObjectByConfiguredName('file_raw_input_output_class', array($fileName));
385
386                 // ... and set it here
387                 $this->setPointerInstance($pointerInstance);
388         }
389
390         /**
391          * Writes data at given position
392          *
393          * @param       $seekPosition   Seek position
394          * @param       $data                   Data to be written
395          * @param       $flushHeader    Whether to flush the header (default: flush)
396          * @return      void
397          */
398         public function writeData ($seekPosition, $data, $flushHeader = TRUE) {
399                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] seekPosition=%s,data()=%d - CALLED!', __METHOD__, __LINE__, $seekPosition, strlen($data)));
400
401                 // Write data at given position
402                 $this->getPointerInstance()->writeAtPosition($seekPosition, $data);
403
404                 // Increment counter
405                 $this->incrementCounter();
406
407                 // Update seek position
408                 $this->updateSeekPosition();
409
410                 // Flush the header?
411                 if ($flushHeader === TRUE) {
412                         // Flush header
413                         $this->flushFileHeader();
414
415                         // Seek to old position
416                         $this->seekToOldPosition();
417                 } // END - if
418
419                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] EXIT!', __METHOD__, __LINE__));
420         }
421
422         /**
423          * Marks the currently loaded block as empty (with length of the block)
424          *
425          * @param       $length         Length of the block
426          * @return      void
427          */
428         protected function markCurrentBlockAsEmpty ($length) {
429                 // Get current seek position
430                 $currentPosition = $this->key();
431
432                 // Now add it as gap entry
433                 array_push($this->gaps, array(
434                         self::GAPS_INDEX_START  => ($currentPosition - $length),
435                         self::GAPS_INDEX_END    => $currentPosition,
436                 ));
437         }
438
439         /**
440          * Checks whether the file header is initialized
441          *
442          * @return      $isInitialized  Whether the file header is initialized
443          */
444         public function isFileHeaderInitialized () {
445                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
446
447                 // Default is not initialized
448                 $isInitialized = FALSE;
449
450                 // Is the file initialized?
451                 if ($this->isFileInitialized()) {
452                         // Some bytes has been written, so rewind to start of it.
453                         $rewindStatus = $this->rewind();
454                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] rewindStatus=%s', __METHOD__, __LINE__, $rewindStatus));
455
456                         // Is the rewind() call successfull?
457                         if ($rewindStatus != 1) {
458                                 // Something bad happened
459                                 self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] Could not rewind().', __METHOD__, __LINE__));
460                         } // END - if
461
462                         // Read file header
463                         $this->readFileHeader();
464
465                         // The above method does already check the header
466                         $isInitialized = TRUE;
467                 } // END - if
468
469                 // Return result
470                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] isInitialized=%d - EXIT!', __METHOD__, __LINE__, intval($isInitialized)));
471                 return $isInitialized;
472         }
473
474         /**
475          * Checks whether the assigned file has been initialized
476          *
477          * @return      $isInitialized          Whether the file's size is zero
478          */
479         public function isFileInitialized () {
480                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
481
482                 // Get it from iterator which holds the pointer instance. If FALSE is returned
483                 $fileSize = $this->size();
484                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] fileSize=%s', __METHOD__, __LINE__, $fileSize));
485
486                 /*
487                  * The returned file size should not be FALSE or NULL as this means
488                  * that the pointer class does not work correctly.
489                  */
490                 assert(is_int($fileSize));
491
492                 // Is more than 0 returned?
493                 $isInitialized = ($fileSize > 0);
494
495                 // Return result
496                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] isInitialized=%d - EXIT!', __METHOD__, __LINE__, intval($isInitialized)));
497                 return $isInitialized;
498         }
499
500         /**
501          * Creates the assigned file
502          *
503          * @return      void
504          */
505         public function createFileHeader () {
506                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
507
508                 // The file's header should not be initialized here
509                 assert(!$this->isFileHeaderInitialized());
510
511                 // Simple flush file header which will create it.
512                 $this->flushFileHeader();
513
514                 // Rewind seek position (to beginning of file) and update/flush file header
515                 $this->rewindUpdateSeekPosition();
516
517                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] EXIT!', __METHOD__, __LINE__));
518         }
519
520         /**
521          * Pre-allocates file (if enabled) with some space for later faster write access.
522          *
523          * @param       $type   Type of the file
524          * @return      void
525          */
526         public function preAllocateFile ($type) {
527                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
528
529                 // Is it enabled?
530                 if ($this->getConfigInstance()->getConfigEntry($type . '_pre_allocate_enabled') != 'Y') {
531                         // Not enabled
532                         self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] Not pre-allocating file.', __METHOD__, __LINE__));
533
534                         // Don't continue here.
535                         return;
536                 } // END - if
537
538                 // Message to user
539                 self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] Pre-allocating file ...', __METHOD__, __LINE__));
540
541                 // Calculate minimum length for one entry
542                 $minLengthEntry = $this->getBlockInstance()->calculateMinimumBlockLength();
543                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] minLengthEntry=%s', __METHOD__, __LINE__, $minLengthEntry));
544
545                 // Calulcate seek position
546                 $seekPosition = $minLengthEntry * $this->getConfigInstance()->getConfigEntry($type . '_pre_allocate_count');
547                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] seekPosition=%s', __METHOD__, __LINE__, $seekPosition));
548
549                 // Now simply write a NUL there. This will pre-allocate the file.
550                 $this->writeData($seekPosition, chr(0));
551
552                 // Rewind seek position (to beginning of file) and update/flush file header
553                 $this->rewindUpdateSeekPosition();
554
555                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] EXIT!', __METHOD__, __LINE__));
556         }
557
558         /**
559          * Determines seek position
560          *
561          * @return      $seekPosition   Current seek position
562          */
563         public function determineSeekPosition () {
564                 // Call pointer instance
565                 return $this->getPointerInstance()->determineSeekPosition();
566         }
567
568         /**
569          * Seek to given offset (default) or other possibilities as fseek() gives.
570          *
571          * @param       $offset         Offset to seek to (or used as "base" for other seeks)
572          * @param       $whence         Added to offset (default: only use offset to seek to)
573          * @return      $status         Status of file seek: 0 = success, -1 = failed
574          */
575         public function seek ($offset, $whence = SEEK_SET) {
576                 // Call pointer instance
577                 return $this->getPointerInstance()->seek($offset, $whence);
578         }
579
580         /**
581          * Reads given amount of bytes from file.
582          *
583          * @param       $bytes  Amount of bytes to read
584          * @return      $data   Data read from file
585          */
586         public function read ($bytes = NULL) {
587                 // $bytes shall be integer
588                 assert(is_int($bytes));
589
590                 // Call pointer instance
591                 return $this->getPointerInstance()->read($bytes);
592         }
593
594         /**
595          * Rewinds to the beginning of the file
596          *
597          * @return      $status         Status of this operation
598          */
599         public function rewind () {
600                 // Call pointer instance
601                 return $this->getPointerInstance()->rewind();
602         }
603
604         /**
605          * Analyzes entries in index file. This will count all found (and valid)
606          * entries, mark invalid as damaged and count gaps ("fragmentation"). If
607          * only gaps are found, the file is considered as "virgin" (no entries).
608          *
609          * @return      void
610          */
611         public function analyzeFile () {
612                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
613
614                 // Make sure the file is initialized
615                 assert($this->isFileInitialized());
616
617                 // Init counters and gaps array
618                 $this->initCountersGapsArray();
619
620                 // Output message (as this may take some time)
621                 self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] Analyzing file structure ... (this may take some time)', __METHOD__, __LINE__));
622
623                 // First rewind to the begining
624                 $this->rewind();
625
626                 // Then try to load all entries
627                 while ($this->valid()) {
628                         // Go to next entry
629                         $this->next();
630
631                         // Get current entry
632                         $current = $this->getCurrentBlock();
633
634                         /*
635                          * If the block is empty, maybe the whole file is? This could mean
636                          * that the file has been pre-allocated.
637                          */
638                         if (empty($current)) {
639                                 // Then skip this part
640                                 continue;
641                         } // END - if
642
643                         // Debug message
644                         /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] current()=%d', __METHOD__, __LINE__, strlen($current)));
645                 } // END - while
646
647                 // If the last read block is empty, check gaps
648                 if (empty($current)) {
649                         // Output message
650                         self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] Found a total of %s gaps.', __METHOD__, __LINE__, count($this->gaps)));
651
652                         // Check gaps, if the whole file is empty.
653                         if ($this->isFileOnlyGaps()) {
654                                 // Only gaps, so don't continue here.
655                                 return;
656                         } // END - if
657
658                         /*
659                          * The above call has calculated a total size of all gaps. If the
660                          * percentage of gaps passes a "soft" limit and last
661                          * defragmentation is to far in the past, or if a "hard" limit has
662                          * reached, run defragmentation.
663                          */
664                         if ($this->isDefragmentationNeeded()) {
665                                 // Run "defragmentation"
666                                 $this->doRunDefragmentation();
667                         } // END - if
668                 } // END - if
669                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] EXIT!', __METHOD__, __LINE__));
670         }
671
672         /**
673          * Advances to next "block" of bytes
674          *
675          * @return      void
676          */
677         public function next () {
678                 // Is there nothing to read?
679                 if (!$this->valid()) {
680                         // Nothing to read
681                         return;
682                 } // END - if
683
684                 // Debug message
685                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d] key()=%d', __FUNCTION__, __LINE__, $this->key()));
686
687                 // Make sure the block instance is set
688                 assert($this->getBlockInstance() instanceof CalculatableBlock);
689
690                 // First calculate minimum block length
691                 $length = $this->getBlockInstance()->calculateMinimumBlockLength();
692                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d] length=%s', __FUNCTION__, __LINE__, $length));
693
694                 // Short be more than zero!
695                 assert($length > 0);
696
697                 // Read possibly back-buffered bytes from previous call of next().
698                 $data = $this->getBackBuffer();
699
700                 /*
701                  * Read until a entry/block separator has been found. The next read
702                  * "block" may not fit, so this loop will continue until the EOB or EOF
703                  * has been reached whatever comes first.
704                  */
705                 while ((!$this->isEndOfFileReached()) && (!self::isBlockSeparatorFound($data))) {
706                         // Then read the next possible block
707                         $block = $this->read($length);
708
709                         // Debug message
710                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d] block()=%d,length=%s', __FUNCTION__, __LINE__, strlen($block), $length));
711
712                         // Is it all empty?
713                         if (strlen(trim($block)) == 0) {
714                                 // Mark this block as empty
715                                 $this->markCurrentBlockAsEmpty(strlen($block));
716
717                                 // Skip to next block
718                                 continue;
719                         } // END - if
720
721                         // At this block then
722                         $data .= $block;
723
724                         // A debug message
725                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d] data()=%d', __FUNCTION__, __LINE__, strlen($data)));
726                 } // END - while
727
728                 // EOF reached?
729                 if ($this->isEndOfFileReached()) {
730                         // Set whole data as current read block
731                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('Calling setCurrentBlock(' . strlen($data) . ') ...');
732                         $this->setCurrentBlock($data);
733
734                         // Then abort here silently
735                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('EOF reached.');
736                         return;
737                 } // END - if
738
739                 /*
740                  * Init back-buffer which is the data that has been found beyond the
741                  * separator.
742                  */
743                 $this->initBackBuffer();
744
745                 // Separate data
746                 $dataArray = explode(chr(self::SEPARATOR_ENTRIES), $data);
747
748                 // This array must contain two elements
749                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('dataArray=' . print_r($dataArray, TRUE));
750                 assert(count($dataArray) == 2);
751
752                 // Left part is the actual block, right one the back-buffer data
753                 $this->setCurrentBlock($dataArray[0]);
754                 $this->setBackBuffer($dataArray[1]);
755         }
756
757         /**
758          * Checks wether the current entry is valid (not at the end of the file).
759          * This method will return TRUE if an emptied (nulled) entry has been found.
760          *
761          * @return      $isValid        Whether the next entry is valid
762          */
763         public function valid () {
764                 // Make sure the block instance is set
765                 assert($this->getBlockInstance() instanceof Block);
766
767                 // First calculate minimum block length
768                 $length = $this->getBlockInstance()->calculateMinimumBlockLength();
769
770                 // Short be more than zero!
771                 assert($length > 0);
772
773                 // Get current seek position
774                 $seekPosition = $this->key();
775
776                 // Then try to read it
777                 $data = $this->read($length);
778
779                 // If some bytes could be read, all is fine
780                 $isValid = ((is_string($data)) && (strlen($data) > 0));
781
782                 // Get header size
783                 $headerSize = $this->getHeaderSize();
784
785                 // Is the seek position at or beyond the header?
786                 if ($seekPosition >= $headerSize) {
787                         // Seek back to old position
788                         $this->seek($seekPosition);
789                 } else {
790                         // Seek directly behind the header
791                         $this->seek($headerSize);
792                 }
793
794                 // Return result
795                 return $isValid;
796         }
797
798         /**
799          * Gets current seek position ("key").
800          *
801          * @return      $key    Current key in iteration
802          */
803         public function key () {
804                 // Call pointer instance
805                 return $this->getPointerInstance()->determineSeekPosition();
806         }
807
808         /**
809          * Reads the file header
810          *
811          * @return      void
812          */
813         public function readFileHeader () {
814                 // Make sure the block instance is set
815                 assert($this->getBlockInstance() instanceof Block);
816
817                 // Call block instance
818                 $this->getBlockInstance()->readFileHeader();
819         }
820
821         /**
822          * Flushes the file header
823          *
824          * @return      void
825          */
826         public function flushFileHeader () {
827                 // Make sure the block instance is set
828                 assert($this->getBlockInstance() instanceof Block);
829
830                 // Call block instance
831                 $this->getBlockInstance()->flushFileHeader();
832         }
833
834         /**
835          * Searches for next suitable gap the given length of data can fit in
836          * including padding bytes.
837          *
838          * @param       $length                 Length of raw data
839          * @return      $seekPosition   Found next gap's seek position
840          */
841         public function searchNextGap ($length) {
842                 // If the file is only gaps, no need to seek
843                 if ($this->isFileOnlyGaps()) {
844                         // The first empty block is the first one right after the header
845                         return ($this->getHeaderSize() + 1);
846                 } // END - if
847
848                 // @TODO Unfinished
849                 $this->partialStub('length=' . $length);
850         }
851 }
852
853 // [EOF]
854 ?>