Also getSeekPosition() belongs here ... + TODOs.txt updated (--amend rocks!)
[core.git] / inc / classes / interfaces / iterator / class_SeekableWritableFileIterator.php
1 <?php
2 /**
3  * An interface for seekable iterators which also allow to write to the file
4  * in different ways.
5  *
6  * @author              Roland Haeder <webmaster@ship-simu.org>
7  * @version             0.0.0
8  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2012 Core Developer Team
9  * @license             GNU GPL 3.0 or any newer version
10  * @link                http://www.ship-simu.org
11  *
12  * This program is free software: you can redistribute it and/or modify
13  * it under the terms of the GNU General Public License as published by
14  * the Free Software Foundation, either version 3 of the License, or
15  * (at your option) any later version.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20  * GNU General Public License for more details.
21  *
22  * You should have received a copy of the GNU General Public License
23  * along with this program. If not, see <http://www.gnu.org/licenses/>.
24  */
25 interface SeekableWritableFileIterator extends SeekableIterator {
26         /**
27          * Seeks to given position
28          *
29          * @param       $seekPosition   Seek position in file
30          * @return      $status                 Status of this operation
31          */
32         function seek ($seekPosition);
33
34         /**
35          * Size of file stack
36          *
37          * @return      $size   Size (in bytes) of file
38          */
39         function size ();
40
41         /**
42          * Reads given amount of bytes from file.
43          *
44          * @param       $bytes  Amount of bytes to read
45          * @return      $data   Data read from file
46          */
47         function read ($bytes);
48
49         /**
50          * Analyzes entries in index file. This will count all found (and valid)
51          * entries, mark invalid as damaged and count gaps ("fragmentation"). If
52          * only gaps are found, the file is considered as "virgin" (no entries).
53          *
54          * @return      void
55          */
56         function analyzeFile ();
57
58         /**
59          * Checks whether the file header is initialized
60          *
61          * @return      $isInitialized  Whether the file header is initialized
62          */
63         function isFileHeaderInitialized ();
64
65         /**
66          * Creates the assigned file
67          *
68          * @return      void
69          */
70         function createFileHeader ();
71
72         /**
73          * Pre-allocates file (if enabled) with some space for later faster write access.
74          *
75          * @param       $type   Type of the file
76          * @return      void
77          */
78         function preAllocateFile ($type);
79
80         /**
81          * Initializes counter for valid entries, arrays for damaged entries and
82          * an array for gap seek positions. If you call this method on your own,
83          * please re-analyze the file structure. So you are better to call
84          * analyzeFile() instead of this method.
85          *
86          * @return      void
87          */
88         function initCountersGapsArray ();
89
90         /**
91          * Getter for header size
92          *
93          * @return      $totalEntries   Size of file header
94          */
95         function getHeaderSize ();
96
97         /**
98          * Setter for header size
99          *
100          * @param       $headerSize             Size of file header
101          * @return      void
102          */
103         function setHeaderSize ($headerSize);
104
105         /**
106          * Getter for header array
107          *
108          * @return      $totalEntries   Size of file header
109          */
110         function getHeader ();
111
112         /**
113          * Setter for header
114          *
115          * @param       $header         Array for a file header
116          * @return      void
117          */
118         function setHeader (array $header);
119
120         /**
121          * Updates seekPosition attribute from file to avoid to much access on file.
122          *
123          * @return      void
124          */
125         function updateSeekPosition ();
126
127         /**
128          * Getter for total entries
129          *
130          * @return      $totalEntries   Total entries in this file
131          */
132         function getCounter ();
133
134         /**
135          * "Getter" for file size
136          *
137          * @return      $fileSize       Size of currently loaded file
138          */
139         function getFileSize ();
140
141         /**
142          * Writes data at given position
143          *
144          * @param       $seekPosition   Seek position
145          * @param       $data                   Data to be written
146          * @param       $flushHeader    Whether to flush the header (default: flush)
147          * @return      void
148          */
149         function writeData ($seekPosition, $data, $flushHeader = TRUE);
150
151         /**
152          * Getter for seek position
153          *
154          * @return      $seekPosition   Current seek position (stored here in object)
155          */
156         function getSeekPosition ();
157 }
158
159 // [EOF]
160 ?>