X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..8cd8a7feb72a8f45d5cb4d5f51fca7e73291d2b5:/interface/ffile.h?ds=sidebyside diff --git a/interface/ffile.h b/interface/ffile.h index b960defa53..da0722860e 100644 --- a/interface/ffile.h +++ b/interface/ffile.h @@ -1,34 +1,73 @@ ///////////////////////////////////////////////////////////////////////////// // Name: ffile.h -// Purpose: documentation for wxFFile class +// Purpose: interface of wxFFile // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + + +/** + Values used for both wxFile and wxFFile. + + @todo make the value names uppercase +*/ +enum wxSeekMode +{ + wxFromStart, + wxFromCurrent, + wxFromEnd +}; + +/** + See wxFFile::GetKind(). +*/ +enum wxFileKind +{ + wxFILE_KIND_UNKNOWN, + wxFILE_KIND_DISK, /**< A file supporting seeking to arbitrary offsets. */ + wxFILE_KIND_TERMINAL, /**< A terminal. */ + wxFILE_KIND_PIPE /**< A pipe. */ +}; + + /** @class wxFFile @wxheader{ffile.h} - wxFFile implements buffered file I/O. This is a very small class designed to - minimize the overhead of using it - in fact, there is hardly any overhead at - all, but using it brings you automatic error checking and hides differences - between platforms and compilers. It wraps inside it a @c FILE * handle used - by standard C IO library (also known as @c stdio). + wxFFile implements buffered file I/O. + + This is a very small class designed to minimize the overhead of using it - in fact, + there is hardly any overhead at all, but using it brings you automatic error checking + and hides differences between platforms and compilers. + + It wraps inside it a @c FILE * handle used by standard C IO library (also known as @c stdio). @library{wxbase} @category{file} - @seealso - wxFFile::IsOpened + @see wxFFile::IsOpened */ class wxFFile { public: - //@{ + wxFFile(); + /** Opens a file with the given file pointer, which has already been opened. - + + @param fp + An existing file descriptor, such as stderr. + */ + wxFFile(FILE* fp); + + /** + Opens a file with the given mode. + As there is no way to return whether the operation was successful or not from + the constructor you should test the return value of IsOpened() to check that it + didn't fail. + @param filename The filename. @param mode @@ -36,24 +75,21 @@ public: Note that you should use "b" flag if you use binary files under Windows or the results might be unexpected due to automatic newline conversion done for the text files. - @param fp - An existing file descriptor, such as stderr. */ - wxFFile(); wxFFile(const wxString& filename, const wxString& mode = "r"); - wxFFile(FILE* fp); - //@} + /** Destructor will close the file. - NB: it is not virtual so you should @e not derive from wxFFile! + + @note it is not virtual so you should @e not derive from wxFFile! */ ~wxFFile(); /** Attaches an existing file pointer to the wxFFile object. - The descriptor should be already opened and it will be closed by wxFFile - object. + + The descriptor should be already opened and it will be closed by wxFFile object. */ void Attach(FILE* fp); @@ -64,34 +100,40 @@ public: /** Get back a file pointer from wxFFile object -- the caller is responsible for - closing the file if this - descriptor is opened. IsOpened() will return @false after call to Detach(). + closing the file if this descriptor is opened. + + IsOpened() will return @false after call to Detach(). */ void Detach(); /** Returns @true if the an attempt has been made to read @e past the end of the file. - Note that the behaviour of the file descriptor based class - wxFile is different as wxFile::Eof - will return @true here as soon as the last byte of the file has been - read. + + Note that the behaviour of the file descriptor based class wxFile is different as + wxFile::Eof() will return @true here as soon as the last byte of the file has been read. + Also note that this method may only be called for opened files and may crash if the file is not opened. - + + @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD + @see IsOpened() */ - bool Eof(); + bool Eof() const; /** Returns @true if an error has occurred on this file, similar to the standard @c ferror() function. + Please note that this method may only be called for opened files and may crash if the file is not opened. - + + @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD + @see IsOpened() */ - + bool Error() const; /** Flushes the file and returns @true on success. @@ -99,25 +141,27 @@ public: bool Flush(); /** - Returns the type of the file. Possible return values are: + Returns the type of the file. + + @see wxFileKind */ - wxFileKind GetKind(); + wxFileKind GetKind() const; /** - Returns @true if the file is opened. Most of the methods of this class may - only - be used for an opened file. + Returns @true if the file is opened. + + Most of the methods of this class may only be used for an opened file. */ - bool IsOpened(); + bool IsOpened() const; /** Returns the length of the file. */ - wxFileOffset Length(); + wxFileOffset Length() const; /** Opens the file, returning @true if successful. - + @param filename The filename. @param mode @@ -126,35 +170,33 @@ public: bool Open(const wxString& filename, const wxString& mode = "r"); /** - Reads the specified number of bytes into a buffer, returning the actual number - read. - + Reads the specified number of bytes into a buffer, returning the actual number read. + @param buffer A buffer to receive the data. @param count The number of bytes to read. - + @returns The number of bytes read. */ size_t Read(void* buffer, size_t count); /** - ) Reads the entire contents of the file into a string. - + @param str String to read data into. @param conv Conversion object to use in Unicode build; by default supposes that file contents is encoded in UTF-8. - + @returns @true if file was read successfully, @false otherwise. */ - bool ReadAll(wxString* str); + bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto()); /** Seeks to the specified position and returns @true on success. - + @param ofs Offset to seek to. @param mode @@ -164,9 +206,8 @@ public: /** Moves the file pointer to the specified number of bytes before the end of the - file - and returns @true on success. - + file and returns @true on success. + @param ofs Number of bytes before the end of the file. */ @@ -175,18 +216,31 @@ public: /** Returns the current position. */ - wxFileOffset Tell(); + wxFileOffset Tell() const; /** - ) Writes the contents of the string to the file, returns @true on success. + The second argument is only meaningful in Unicode build of wxWidgets when - @e conv is used to convert @a s to multibyte representation. + @a conv is used to convert @a str to multibyte representation. */ - bool Write(const wxString& s); + bool Write(const wxString& str, const wxMBConv& conv = wxConvAuto()); + + /** + Writes the specified number of bytes from a buffer. + + @param buffer + A buffer containing the data. + @param count + The number of bytes to write. + + @returns The number of bytes written. + */ + size_t Write(const void* buffer, size_t count); /** Returns the file pointer associated with the file. */ - FILE* fp(); + FILE* fp() const; }; +