casacore
ByteIO.h
Go to the documentation of this file.
1 //# ByteIO.h: Abstract base class for IO on a byte stream
2 //# Copyright (C) 1996,1999,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_BYTEIO_H
29 #define CASA_BYTEIO_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/BasicSL/String.h>
34 
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 // <summary>Abstract base class for IO on a byte stream.</summary>
39 
40 // <use visibility=export>
41 
42 // <reviewed reviewer="Friso Olnon" date="1996/11/06" tests="tByteIO" demos="">
43 // </reviewed>
44 
45 // <synopsis>
46 // ByteIO is the abstract base class for all classes doing IO on
47 // byte streams. Examples of derived classes are
48 // <linkto class=RegularFileIO>RegularFileIO</linkto> and
49 // <linkto class=MemoryIO>MemoryIO</linkto>.
50 // <p>
51 // ByteIO contains two enumerations, which define the possible
52 // open and seek options on byte streams. These enumerations
53 // are used throughout the IO framework.
54 // </synopsis>
55 
56 // <motivation>
57 // Make polymorphic operations on byte streams possible.
58 // </motivation>
59 
60 
61 class ByteIO
62 {
63 public:
64  // Define the possible ByteIO open options.
65  enum OpenOption {
66  Old=1,
67  // read/write; file must exist.
69  // read/write; create file if not exist.
71  // read/write; create file if not exist.
72  New,
73  // read/write; file may not exist yet.
75  // read/write; delete file at close.
77  // read/write; file must exist; delete at close.
78  Delete
79  };
80 
81  // Define the possible seek options.
82  enum SeekOption {
83  // Seek from beginning of file.
84  Begin=1,
85  // Seek from current position.
87  // Seek from the end of the file.
88  End
89  };
90 
91 
92  // The constructor does nothing.
93  ByteIO();
94 
95  virtual ~ByteIO();
96 
97  // Write <src>size</src> bytes to the byte stream.
98  virtual void write (Int64 size, const void* buf) = 0;
99 
100  // Write <src>size</src> bytes to the byte stream at <src>offset</src>.
101  // The file offset is not changed
102  virtual void pwrite (Int64 size, Int64 offset, const void* buf);
103 
104  // Read <src>size</src> bytes from the byte stream. Returns the number of
105  // bytes actually read, or a negative number if an error occurred. Will also
106  // throw an Exception (AipsError) if the requested number of bytes could
107  // not be read unless throwException is set to False.
108  virtual Int64 read (Int64 size, void* buf, Bool throwException=True) = 0;
109 
110  // Like read but reads from offset of start of the file
111  // The file offset is not changed
112  virtual Int64 pread (Int64 size, Int64 offset, void* buf, Bool throwException=True);
113 
114  // Reopen the underlying IO stream for read/write access.
115  // Nothing will be done if the stream is writable already.
116  // Otherwise it will be reopened and an exception will be thrown
117  // if it is not possible to reopen it for read/write access.
118  // The default implementation in this base class throws a "not possible"
119  // exception if a reopen has to be done.
120  virtual void reopenRW();
121 
122  // This function sets the position on the given offset.
123  // The seek option defines from which file position the seek is done.
124  // -1 is returned if not seekable.
125  // <group>
128  // </group>
129 
130  // Flush the data to the file.
131  // The default implementation does nothing.
132  virtual void flush();
133 
134  // Fsync the file (i.e. force the data to be physically written).
135  // The default implementation does nothing.
136  virtual void fsync();
137 
138  // Resync the file (i.e. empty the current buffer).
139  // The default implementation does nothing.
140  virtual void resync();
141 
142  // Get the file name of the file attached.
143  // The default implementation returns an empty string.
144  virtual String fileName() const;
145 
146  // Get the length of the byte stream.
147  virtual Int64 length() = 0;
148 
149  // Is the byte stream readable?
150  virtual Bool isReadable() const = 0;
151 
152  // Is the byte stream writable?
153  virtual Bool isWritable() const = 0;
154 
155  // Is the byte stream seekable?
156  virtual Bool isSeekable() const = 0;
157 
158 
159 protected:
160  // Make copy constructor and assignment protected, so a user cannot
161  // use them (but a derived class can).
162  // <group>
163  ByteIO (const ByteIO& byteIO);
164  ByteIO& operator= (const ByteIO& byteIO);
165  // </group>
166 
167  virtual Int64 doSeek (Int64 offset, ByteIO::SeekOption) = 0;
168 };
169 
170 
171 
173 {}
174 
175 inline ByteIO::ByteIO (const ByteIO&)
176 {}
177 
179 {
180  return *this;
181 }
182 
184 {
185  return doSeek (offset, option);
186 }
187 inline Int64 ByteIO::seek (Int offset, ByteIO::SeekOption option)
188 {
189  return doSeek (Int64(offset), option);
190 }
191 
192 
193 } //# NAMESPACE CASACORE - END
194 
195 #endif
virtual Int64 doSeek(Int64 offset, ByteIO::SeekOption)=0
virtual void reopenRW()
Reopen the underlying IO stream for read/write access.
virtual Int64 length()=0
Get the length of the byte stream.
virtual Bool isWritable() const =0
Is the byte stream writable?
SeekOption
Define the possible seek options.
Definition: ByteIO.h:82
@ Begin
Seek from beginning of file.
Definition: ByteIO.h:84
@ Current
Seek from current position.
Definition: ByteIO.h:86
@ End
Seek from the end of the file.
Definition: ByteIO.h:88
virtual Bool isReadable() const =0
Is the byte stream readable?
ByteIO & operator=(const ByteIO &byteIO)
Definition: ByteIO.h:178
virtual String fileName() const
Get the file name of the file attached.
virtual void flush()
Flush the data to the file.
virtual Int64 read(Int64 size, void *buf, Bool throwException=True)=0
Read size bytes from the byte stream.
virtual void resync()
Resync the file (i.e.
virtual Int64 pread(Int64 size, Int64 offset, void *buf, Bool throwException=True)
Like read but reads from offset of start of the file The file offset is not changed.
Int64 seek(Int offset, ByteIO::SeekOption=ByteIO::Begin)
This function sets the position on the given offset.
Definition: ByteIO.h:187
virtual void write(Int64 size, const void *buf)=0
Write size bytes to the byte stream.
virtual void fsync()
Fsync the file (i.e.
virtual Bool isSeekable() const =0
Is the byte stream seekable?
ByteIO()
The constructor does nothing.
Definition: ByteIO.h:172
virtual void pwrite(Int64 size, Int64 offset, const void *buf)
Write size bytes to the byte stream at offset.
virtual ~ByteIO()
OpenOption
Define the possible ByteIO open options.
Definition: ByteIO.h:65
@ Scratch
read/write; delete file at close.
Definition: ByteIO.h:76
@ Delete
read/write; file must exist; delete at close.
Definition: ByteIO.h:78
@ Append
read/write; create file if not exist.
Definition: ByteIO.h:70
@ NewNoReplace
read/write; file may not exist yet.
Definition: ByteIO.h:74
@ New
read/write; create file if not exist.
Definition: ByteIO.h:72
@ Update
read/write; file must exist.
Definition: ByteIO.h:68
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43