00001 //# ByteIO.h: Abstract base class for IO on a byte stream 00002 //# Copyright (C) 1996,1999,2001 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef CASA_BYTEIO_H 00029 #define CASA_BYTEIO_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/BasicSL/String.h> 00034 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 // <summary>Abstract base class for IO on a byte stream.</summary> 00039 00040 // <use visibility=export> 00041 00042 // <reviewed reviewer="Friso Olnon" date="1996/11/06" tests="tByteIO" demos=""> 00043 // </reviewed> 00044 00045 // <synopsis> 00046 // ByteIO is the abstract base class for all classes doing IO on 00047 // byte streams. Examples of derived classes are 00048 // <linkto class=RegularFileIO>RegularFileIO</linkto> and 00049 // <linkto class=MemoryIO>MemoryIO</linkto>. 00050 // <p> 00051 // ByteIO contains two enumerations, which define the possible 00052 // open and seek options on byte streams. These enumerations 00053 // are used throughout the IO framework. 00054 // </synopsis> 00055 00056 // <motivation> 00057 // Make polymorphic operations on byte streams possible. 00058 // </motivation> 00059 00060 00061 class ByteIO 00062 { 00063 public: 00064 // Define the possible ByteIO open options. 00065 enum OpenOption { 00066 Old=1, 00067 // read/write; file must exist. 00068 Update, 00069 // read/write; create file if not exist. 00070 Append, 00071 // read/write; create file if not exist. 00072 New, 00073 // read/write; file may not exist yet. 00074 NewNoReplace, 00075 // read/write; delete file at close. 00076 Scratch, 00077 // read/write; file must exist; delete at close. 00078 Delete 00079 }; 00080 00081 // Define the possible seek options. 00082 enum SeekOption { 00083 // Seek from beginning of file. 00084 Begin=1, 00085 // Seek from current position. 00086 Current, 00087 // Seek from the end of the file. 00088 End 00089 }; 00090 00091 00092 // The constructor does nothing. 00093 ByteIO(); 00094 00095 virtual ~ByteIO(); 00096 00097 // Write <src>size</src> bytes to the byte stream. 00098 virtual void write (Int64 size, const void* buf) = 0; 00099 00100 // Write <src>size</src> bytes to the byte stream at <src>offset</src>. 00101 // The file offset is not changed 00102 virtual void pwrite (Int64 size, Int64 offset, const void* buf); 00103 00104 // Read <src>size</src> bytes from the byte stream. Returns the number of 00105 // bytes actually read, or a negative number if an error occurred. Will also 00106 // throw an Exception (AipsError) if the requested number of bytes could 00107 // not be read unless throwException is set to False. 00108 virtual Int64 read (Int64 size, void* buf, Bool throwException=True) = 0; 00109 00110 // Like read but reads from offset of start of the file 00111 // The file offset is not changed 00112 virtual Int64 pread (Int64 size, Int64 offset, void* buf, Bool throwException=True); 00113 00114 // Reopen the underlying IO stream for read/write access. 00115 // Nothing will be done if the stream is writable already. 00116 // Otherwise it will be reopened and an exception will be thrown 00117 // if it is not possible to reopen it for read/write access. 00118 // The default implementation in this base class throws a "not possible" 00119 // exception if a reopen has to be done. 00120 virtual void reopenRW(); 00121 00122 // This function sets the position on the given offset. 00123 // The seek option defines from which file position the seek is done. 00124 // -1 is returned if not seekable. 00125 // <group> 00126 Int64 seek (Int offset, ByteIO::SeekOption = ByteIO::Begin); 00127 Int64 seek (Int64 offset, ByteIO::SeekOption = ByteIO::Begin); 00128 // </group> 00129 00130 // Flush the data to the file. 00131 // The default implementation does nothing. 00132 virtual void flush(); 00133 00134 // Fsync the file (i.e. force the data to be physically written). 00135 // The default implementation does nothing. 00136 virtual void fsync(); 00137 00138 // Resync the file (i.e. empty the current buffer). 00139 // The default implementation does nothing. 00140 virtual void resync(); 00141 00142 // Get the file name of the file attached. 00143 // The default implementation returns an empty string. 00144 virtual String fileName() const; 00145 00146 // Get the length of the byte stream. 00147 virtual Int64 length() = 0; 00148 00149 // Is the byte stream readable? 00150 virtual Bool isReadable() const = 0; 00151 00152 // Is the byte stream writable? 00153 virtual Bool isWritable() const = 0; 00154 00155 // Is the byte stream seekable? 00156 virtual Bool isSeekable() const = 0; 00157 00158 00159 protected: 00160 // Make copy constructor and assignment protected, so a user cannot 00161 // use them (but a derived class can). 00162 // <group> 00163 ByteIO (const ByteIO& byteIO); 00164 ByteIO& operator= (const ByteIO& byteIO); 00165 // </group> 00166 00167 virtual Int64 doSeek (Int64 offset, ByteIO::SeekOption) = 0; 00168 }; 00169 00170 00171 00172 inline ByteIO::ByteIO() 00173 {} 00174 00175 inline ByteIO::ByteIO (const ByteIO&) 00176 {} 00177 00178 inline ByteIO& ByteIO::operator= (const ByteIO&) 00179 { 00180 return *this; 00181 } 00182 00183 inline Int64 ByteIO::seek (Int64 offset, ByteIO::SeekOption option) 00184 { 00185 return doSeek (offset, option); 00186 } 00187 inline Int64 ByteIO::seek (Int offset, ByteIO::SeekOption option) 00188 { 00189 return doSeek (Int64(offset), option); 00190 } 00191 00192 00193 } //# NAMESPACE CASACORE - END 00194 00195 #endif