framework/main/interfaces/filesystem/binary/class_BinaryFile.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Filesystem\File;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Filesystem\Filesystem;
   7
   8 /**
   9  * A virtual file system interface
  10  *
  11  * @author              Roland Haeder <webmaster@ship-simu.org>
  12  * @version             0.0.0
  13  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
  14  * @license             GNU GPL 3.0 or any newer version
  15  * @link                http://www.ship-simu.org
  16  *
  17  * This program is free software: you can redistribute it and/or modify
  18  * it under the terms of the GNU General Public License as published by
  19  * the Free Software Foundation, either version 3 of the License, or
  20  * (at your option) any later version.
  21  *
  22  * This program is distributed in the hope that it will be useful,
  23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25  * GNU General Public License for more details.
  26  *
  27  * You should have received a copy of the GNU General Public License
  28  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  29  */
  30 interface BinaryFile extends Filesystem {
  31         /**
  32          * Separator for header data
  33          */
  34         const SEPARATOR_HEADER_DATA = 0x01;
  35
  36         /**
  37          * Separator header->entries
  38          */
  39         const SEPARATOR_HEADER_ENTRIES = 0x02;
  40
  41         /**
  42          * Separator group->hash
  43          */
  44         const SEPARATOR_GROUP_HASH = 0x03;
  45
  46         /**
  47          * Separator hash->value
  48          */
  49         const SEPARATOR_HASH_VALUE = 0x04;
  50
  51         /**
  52          * Separator entry->entry
  53          */
  54         const SEPARATOR_ENTRIES = 0x05;
  55
  56         /**
  57          * Separator type->position
  58          */
  59         const SEPARATOR_TYPE_POSITION = 0x06;
  60
  61         /**
  62          * Length of count
  63          */
  64         const LENGTH_COUNT = 20;
  65
  66         /**
  67          * Length of position
  68          */
  69         const LENGTH_POSITION = 20;
  70
  71         /**
  72          * Length of group
  73          */
  74         const LENGTH_GROUP = 10;
  75
  76         /**
  77          * Maximum length of entry type
  78          */
  79         const LENGTH_TYPE = 20;
  80
  81         //***** Array elements for 'gaps' array *****
  82
  83         /**
  84          * Start of gap
  85          */
  86         const GAPS_INDEX_START = 'start';
  87
  88         /**
  89          * End of gap
  90          */
  91         const GAPS_INDEX_END = 'end';
  92
  93         // Header names
  94         const HEADER_NAME_MAGIC = 'magic';
  95         const HEADER_NAME_TOTAL_ENTRIES = 'total';
  96         const HEADER_NAME_SEEK_POSITION = 'seek';
  97
  98         // Header element counts
  99         const HEADER_INDEX_ELEMENT_COUNT = 2;
 100         const HEADER_STACK_ELEMENT_COUNT = 3;
 101
 102         /**
 103          * Reads the file header
 104          *
 105          * @return      void
 106          */
 107         function readFileHeader ();
 108
 109         /**
 110          * Flushes the file header
 111          *
 112          * @return      void
 113          */
 114         function flushFileHeader ();
 115
 116         /**
 117          * Determines whether the EOF has been reached
 118          *
 119          * @return      $isEndOfFileReached             Whether the EOF has been reached
 120          */
 121         function isEndOfFileReached ();
 122
 123         /**
 124          * Getter for header size
 125          *
 126          * @return      $totalEntries   Size of file header
 127          */
 128         function getHeaderSize ();
 129
 130         /**
 131          * Setter for header size
 132          *
 133          * @param       $headerSize             Size of file header
 134          * @return      void
 135          */
 136         function setHeaderSize (int $headerSize);
 137
 138         /**
 139          * Getter for header array
 140          *
 141          * @return      $totalEntries   Size of file header
 142          */
 143         function getHeader ();
 144
 145         /**
 146          * Setter for header
 147          *
 148          * @param       $header         Array for a file header
 149          * @return      void
 150          */
 151         function setHeader (array $header);
 152
 153         /**
 154          * Initializes counter for valid entries, arrays for damaged entries and
 155          * an array for gap seek positions. If you call this method on your own,
 156          * please re-analyze the file structure. So you are better to call
 157          * analyzeFileStructure() instead of this method.
 158          *
 159          * @return      void
 160          */
 161         function initCountersGapsArray ();
 162
 163         /**
 164          * Updates seekPosition attribute from file to avoid to much access on file.
 165          *
 166          * @return      void
 167          */
 168         function updateSeekPosition ();
 169
 170         /**
 171          * Getter for total entries
 172          *
 173          * @return      $totalEntries   Total entries in this file
 174          */
 175         function getCounter ();
 176
 177         /**
 178          * "Getter" for file size
 179          *
 180          * @return      $fileSize       Size of currently loaded file
 181          */
 182         function getFileSize ();
 183
 184         /**
 185          * Checks whether the abstracted file only contains gaps by counting all
 186          * gaps' bytes together and compare it to total length.
 187          *
 188          * @return      $isGapsOnly             Whether the abstracted file only contains gaps
 189          */
 190         function isFileGapsOnly();
 191
 192         /**
 193          * Searches for next suitable gap the given length of data can fit in
 194          * including padding bytes.
 195          *
 196          * @param       $length                 Length of raw data
 197          * @return      $seekPosition   Found next gap's seek position
 198          */
 199         function searchNextGap (int $length);
 200
 201         /**
 202          * Writes given value to the file and returns a hash and gap position for it
 203          *
 204          * @param       $groupId        Group identifier
 205          * @param       $value          Value to be added to the stack
 206          * @return      $data           Hash and gap position
 207          */
 208         function writeValueToFile (string $groupId, string $rawData);
 209
 210         /**
 211          * Writes given raw data to the file and returns a gap position and length
 212          *
 213          * @param       $groupId        Group identifier
 214          * @param       $hash           Hash from encoded value
 215          * @param       $encoded        Encoded value to be written to the file
 216          * @return      $data           Gap position and length of the raw data
 217          */
 218         function writeDataToFreeGap (string $groupId, string $hash, string $encoded);
 219
 220         /**
 221          * Writes data at given position
 222          *
 223          * @param       $seekPosition   Seek position
 224          * @param       $data                   Data to be written
 225          * @param       $flushHeader    Whether to flush the header (default: flush)
 226          * @return      void
 227          */
 228         function writeData (int $seekPosition, string $data, bool $flushHeader = true);
 229
 230         /**
 231          * Writes at given position by seeking to it.
 232          *
 233          * @param       $seekPosition   Seek position in file
 234          * @param       $dataStream             Data to be written
 235          * @return      mixed                   Number of writes bytes or false on error
 236          * @throws      InvalidArgumentException        If a parameter is not valid
 237          */
 238         function writeAtPosition (int $seekPosition, string $dataStream);
 239
 240 }