Menu
▾
▴
[pclasses-cvs] pclasses2/include/pclasses/IO IODevice.h,1.6,1.7
|
From: Christian P. <cp...@us...> - 2005-01-30 17:09:00
|
Update of /cvsroot/pclasses/pclasses2/include/pclasses/IO In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv31053/include/pclasses/IO Modified Files: IODevice.h Log Message: added inline documentation for IODevice. removed IOListener. Index: IODevice.h =================================================================== RCS file: /cvsroot/pclasses/pclasses2/include/pclasses/IO/IODevice.h,v retrieving revision 1.6 retrieving revision 1.7 diff -u -d -r1.6 -r1.7 --- IODevice.h 17 Jan 2005 21:55:22 -0000 1.6 +++ IODevice.h 30 Jan 2005 17:08:48 -0000 1.7 @@ -1,5 +1,5 @@ /*************************************************************************** - * Copyright (C) 2004 by Christian Prochnow * + * Copyright (C) 2004,2005 by Christian Prochnow * * cp...@se... * * * * This program is free software; you can redistribute it and/or modify * @@ -29,28 +29,49 @@ namespace IO { +// forward declaration class IOFilter; -class IOListener; //! I/O Device base class +/*! + This class serves as the base class for all kinds of I/O in P::Classes. + Since mostly everything in P::Classes that can do I/O is derived from + this class, client applications can be pretty generic about doing I/O. + IODevice's do support transparent I/O filters. When an IOFilter has been + associated with an IODevice all read/write method-calls will be proxied + through the IOFilter object. + \note Keep in mind that IOFilter's may change the seekability on the + IODevice. Relying on assumptions like "Files are always seekable" + when used with IOFilters are incorrect. +*/ class PIO_EXPORT IODevice { public: - friend class IOListener; friend class IOFilter; + //! Device open mode + /*! + Since the IODevice class does not support opening, the OpenMode + is only used by its childrens. + */ enum OpenMode { OpenCreate, CreateFail, OpenFail }; + //! Access mode flags + /*! + Device access flags. Tells open() how you want to access + device data. + */ enum AccessMode { - None = 0x00, - Read = 0x01, - Write = 0x02, - ReadWrite = 0x03 + None = 0x00, /*!< No reading/writing */ + Read = 0x01, /*!< Open for reading */ + Write = 0x02, /*!< Open for writing */ + ReadWrite = 0x03 /*!< Open for reading and writing */ }; + //! Sharing mode flags enum ShareMode { AllowNone = 0x00, AllowRead = 0x01, @@ -58,6 +79,11 @@ AllowReadWrite = 0x03 }; + //! Seeking modes + /*! + Seeking modes are used to describe how to + reposition the read position. See seek(). + */ enum SeekMode { SeekSet, SeekCurrent, @@ -67,31 +93,104 @@ IODevice() throw(); virtual ~IODevice() throw(); + //! Closes the I/O device + /*! + Frees any resources associated with this object, like I/O handles. + */ void close() throw(IOError); + //! Read data from I/O device + /*! + Reads up to count bytes and stores them in buffer. Returns the number + of bytes read, which may be less than requested. In case of EOF, zero + is returned. + \param buffer buffer where to place the data to be read. + \param count number of bytes to read + \return number of bytes read, which may be less than requested. + \throw IOError + */ size_t read(char* buffer, size_t count) throw(IOError); + //! Read one line from I/O device + /*! + Reads up to one line (terminated by ASCII NL) and returns it. + In case of EOF an empy string (string.size()==0) is returned. + When called for the first time the IODevice allocates and uses + a buffer for reading. + \return a string containing the line that has been read, + or an empty string in case of EOF. + \throw IOError + */ std::string readLine() throw(IOError); + //! Write data to I/O device + /*! + Writes count bytes from buffer to this I/O device. Returns the number + of bytes written, which may be less. + \param buffer buffer containing the data to be written. + \param count number of bytes that should be written. + \return number of bytes written, which may be less than requested. + \throw IOError + */ size_t write(const char* buffer, size_t count) throw(IOError); + //! Test for seekability + /*! + Tests if the device is seekable. Returns true if the device is + seekable, false if it is not. + \return true if the device is seekable, false otherwise. + */ bool isSeekable() const throw(); + //! Move the next read position to the given offset + /*! + Tries to move the current read position to the given offset. + SeekMode determines the relative starting point of offset. + \param offset the offset the pointer should be moved by. + \param mode determines the relative starting offset. + \return the new abosulte read positing. + \throw IOError + */ offset_t seek(offset_t offset, SeekMode mode) throw(IOError); + //! Read data from I/O device without consuming them + /*! + Tries to extract up to count bytes from this object + without consuming them. The bytes are stored in + buffer, and the number of bytes read is returned. + \param buffer buffer where to place the data to be read. + \param count number of bytes to read + \return number of bytes read. + \throw IOError + */ size_t peek(char* buffer, size_t count) throw(IOError); + //! Synchronize device + /*! + Commits written data to physical device. + \throw IOError + */ void sync() const throw(IOError); offset_t getPos() throw(IOError); + //! Returns the size of the I/O device offset_t size() const throw(IOError); + //! Test if the I/O device object is valid + /*! + Test if the I/O device object is valid. + The object is valid when it has been opened and was not + already closed. + \return true if the I/O device is usable, false otherwise. + */ bool valid() const throw(); + //! Returns the allowed access to the I/O device AccessMode access() const throw(); + //! Returns if the device has reached EOF bool eof() const throw(); void setFilter(IOFilter* filter) throw(LogicError); @@ -101,30 +200,42 @@ IODevice(const IODevice& dev) throw(); IODevice& operator=(const IODevice& dev) throw(); + //! Called when device should be closed + /*! + precondition: valid()==true + */ virtual void _close() throw(IOError) = 0; + //! Read bytes from device virtual size_t _read(char* buffer, size_t count) throw(IOError) = 0; + //! Write bytes to device virtual size_t _write(const char* buffer, size_t count) throw(IOError) = 0; + //! Test for seekability virtual bool _isSeekable() const throw(); + //! Seek on device virtual offset_t _seek(offset_t offset, SeekMode mode) throw(IOError); + //! Read bytes without consuming them virtual size_t _peek(char* buffer, size_t count) throw(IOError); + //! Sync device virtual void _sync() const throw(IOError); + //! Returns the size of the device virtual offset_t _size() const throw(IOError); + //! Set I/O device valid/invalid void setValid(bool v) throw(); + + //! Set AccessMode on device void setAccess(AccessMode mode) throw(); - void setEof(bool eof) throw(); - virtual void addListener(IOListener& l); - virtual void updateListener(IOListener& l); - virtual void removeListener(IOListener& l); + //! Set EOF on device + void setEof(bool eof) throw(); private: IOFilter* _filter; @@ -139,32 +250,6 @@ char* _readBuffNext; }; -class PIO_EXPORT IOListener { - public: - enum EventFlags { - None = 0x0, - Read = 0x1, - Write = 0x2, - ReadWrite = 0x03 - }; - - IOListener(IODevice& dev, int eventMask) throw(); - virtual ~IOListener() throw(); - - IODevice& device() const throw(); - void setDevice(IODevice& dev) throw(); - - int eventMask() const throw(); - void setEventMask(int eventMask) throw(); - - virtual void onRead() = 0; - virtual void onWrite() = 0; - - private: - IODevice* _dev; - int _eventMask; -}; - } // !namespace IO } // !namespace P |
