1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: ffile.tex 3%% Purpose: wxFFile documentation 4%% Author: Vadim Zeitlin 5%% Modified by: 6%% Created: 14.01.02 (extracted from file.tex) 7%% RCS-ID: $Id: ffile.tex 33428 2005-04-08 14:34:30Z MW $ 8%% Copyright: (c) Vadim Zeitlin 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxFFile}}\label{wxffile} 13 14wxFFile implements buffered file I/O. This is a very small class designed to 15minimize the overhead of using it - in fact, there is hardly any overhead at 16all, but using it brings you automatic error checking and hides differences 17between platforms and compilers. It wraps inside it a {\tt FILE *} handle used 18by standard C IO library (also known as {\tt stdio}). 19 20\wxheading{Derived from} 21 22None. 23 24\wxheading{Include files} 25 26<wx/ffile.h> 27 28\twocolwidtha{7cm} 29\begin{twocollist}\itemsep=0pt% 30\twocolitem{{\bf wxFromStart}}{Count offset from the start of the file} 31\twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer} 32\twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)} 33\end{twocollist} 34 35\latexignore{\rtfignore{\wxheading{Members}}} 36 37 38\membersection{wxFFile::wxFFile}\label{wxffilector} 39 40\func{}{wxFFile}{\void} 41 42Default constructor. 43 44\func{}{wxFFile}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}} 45 46Opens a file with the given mode. As there is no way to return whether the 47operation was successful or not from the constructor you should test the 48return value of \helpref{IsOpened}{wxffileisopened} to check that it didn't 49fail. 50 51\func{}{wxFFile}{\param{FILE*}{ fp}} 52 53Opens a file with the given file pointer, which has already been opened. 54 55\wxheading{Parameters} 56 57\docparam{filename}{The filename.} 58 59\docparam{mode}{The mode in which to open the file using standard C strings. 60Note that you should use {\tt "b"} flag if you use binary files under Windows 61or the results might be unexpected due to automatic newline conversion done 62for the text files.} 63 64\docparam{fp}{An existing file descriptor, such as stderr.} 65 66 67\membersection{wxFFile::\destruct{wxFFile}}\label{wxffiledtor} 68 69\func{}{\destruct{wxFFile}}{\void} 70 71Destructor will close the file. 72 73NB: it is not virtual so you should {\it not} derive from wxFFile! 74 75 76\membersection{wxFFile::Attach}\label{wxffileattach} 77 78\func{void}{Attach}{\param{FILE*}{ fp}} 79 80Attaches an existing file pointer to the wxFFile object. 81 82The descriptor should be already opened and it will be closed by wxFFile 83object. 84 85 86\membersection{wxFFile::Close}\label{wxffileclose} 87 88\func{bool}{Close}{\void} 89 90Closes the file and returns \true on success. 91 92 93\membersection{wxFFile::Detach}\label{wxffiledetach} 94 95\func{void}{Detach}{\void} 96 97Get back a file pointer from wxFFile object -- the caller is responsible for closing the file if this 98descriptor is opened. \helpref{IsOpened()}{wxffileisopened} will return \false after call to Detach(). 99 100 101\membersection{wxFFile::fp}\label{wxffilefp} 102 103\constfunc{FILE *}{fp}{\void} 104 105Returns the file pointer associated with the file. 106 107 108\membersection{wxFFile::Eof}\label{wxffileeof} 109 110\constfunc{bool}{Eof}{\void} 111 112Returns \true if the an attempt has been made to read {\it past} 113the end of the file. 114 115Note that the behaviour of the file descriptor based class 116\helpref{wxFile}{wxfile} is different as \helpref{wxFile::Eof}{wxfileeof} 117will return \true here as soon as the last byte of the file has been 118read. 119 120Also note that this method may only be called for opened files and may crash if 121the file is not opened. 122 123\wxheading{See also} 124 125\helpref{IsOpened}{wxffileisopened} 126 127 128\membersection{wxFFile::Error}\label{wxffileerror} 129 130Returns \true if an error has occurred on this file, similar to the standard 131\texttt{ferror()} function. 132 133Please note that this method may only be called for opened files and may crash 134if the file is not opened. 135 136\wxheading{See also} 137 138\helpref{IsOpened}{wxffileisopened} 139 140 141\membersection{wxFFile::Flush}\label{wxffileflush} 142 143\func{bool}{Flush}{\void} 144 145Flushes the file and returns \true on success. 146 147 148\membersection{wxFFile::GetKind}\label{wxffilegetfilekind} 149 150\constfunc{wxFileKind}{GetKind}{\void} 151 152Returns the type of the file. Possible return values are: 153 154\begin{verbatim} 155enum wxFileKind 156{ 157 wxFILE_KIND_UNKNOWN, 158 wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets 159 wxFILE_KIND_TERMINAL, // a tty 160 wxFILE_KIND_PIPE // a pipe 161}; 162 163\end{verbatim} 164 165 166\membersection{wxFFile::IsOpened}\label{wxffileisopened} 167 168\constfunc{bool}{IsOpened}{\void} 169 170Returns \true if the file is opened. Most of the methods of this class may only 171be used for an opened file. 172 173 174\membersection{wxFFile::Length}\label{wxffilelength} 175 176\constfunc{wxFileOffset}{Length}{\void} 177 178Returns the length of the file. 179 180 181\membersection{wxFFile::Open}\label{wxffileopen} 182 183\func{bool}{Open}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}} 184 185Opens the file, returning \true if successful. 186 187\wxheading{Parameters} 188 189\docparam{filename}{The filename.} 190 191\docparam{mode}{The mode in which to open the file.} 192 193 194\membersection{wxFFile::Read}\label{wxffileread} 195 196\func{size\_t}{Read}{\param{void*}{ buffer}, \param{size\_t}{ count}} 197 198Reads the specified number of bytes into a buffer, returning the actual number read. 199 200\wxheading{Parameters} 201 202\docparam{buffer}{A buffer to receive the data.} 203 204\docparam{count}{The number of bytes to read.} 205 206\wxheading{Return value} 207 208The number of bytes read. 209 210 211\membersection{wxFFile::ReadAll}\label{wxffilereadall} 212 213\func{bool}{ReadAll}{\param{wxString *}{ str}, \param{wxMBConv\&}{ conv = wxConvUTF8}} 214 215Reads the entire contents of the file into a string. 216 217\wxheading{Parameters} 218 219\docparam{str}{String to read data into.} 220 221\docparam{conv}{Conversion object to use in Unicode build; by default supposes 222that file contents is encoded in UTF-8.} 223 224\wxheading{Return value} 225 226\true if file was read successfully, \false otherwise. 227 228 229\membersection{wxFFile::Seek}\label{wxffileseek} 230 231\func{bool}{Seek}{\param{wxFileOffset }{ofs}, \param{wxSeekMode }{mode = wxFromStart}} 232 233Seeks to the specified position and returns \true on success. 234 235\wxheading{Parameters} 236 237\docparam{ofs}{Offset to seek to.} 238 239\docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.} 240 241 242\membersection{wxFFile::SeekEnd}\label{wxffileseekend} 243 244\func{bool}{SeekEnd}{\param{wxFileOffset }{ofs = 0}} 245 246Moves the file pointer to the specified number of bytes before the end of the file 247and returns \true on success. 248 249\wxheading{Parameters} 250 251\docparam{ofs}{Number of bytes before the end of the file.} 252 253 254\membersection{wxFFile::Tell}\label{wxffiletell} 255 256\constfunc{wxFileOffset}{Tell}{\void} 257 258Returns the current position. 259 260 261\membersection{wxFFile::Write}\label{wxffilewrite} 262 263\func{size\_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}} 264 265Writes the specified number of bytes from a buffer. 266 267\wxheading{Parameters} 268 269\docparam{buffer}{A buffer containing the data.} 270 271\docparam{count}{The number of bytes to write.} 272 273\wxheading{Return value} 274 275Number of bytes written. 276 277 278\membersection{wxFFile::Write}\label{wxffilewrites} 279 280\func{bool}{Write}{\param{const wxString\& }{s}, \param{wxMBConv\&}{ conv = wxConvUTF8}} 281 282Writes the contents of the string to the file, returns \true on success. 283 284The second argument is only meaningful in Unicode build of wxWidgets when 285{\it conv} is used to convert {\it s} to multibyte representation. 286 287 288