X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FFileHandle.hh;h=9a8c7e7d5b7d015353e74589b9f57094729cc40b;hb=032707d24b1059febe83ce56b11fd79df106c6e2;hp=3bbbb9b606783967bf06f95ae172b219c3620d0c;hpb=558583531d5042ece06b19fcd10132d2d1bc5ad0;p=senf.git diff --git a/Socket/FileHandle.hh b/Socket/FileHandle.hh index 3bbbb9b..9a8c7e7 100644 --- a/Socket/FileHandle.hh +++ b/Socket/FileHandle.hh @@ -20,15 +20,6 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - -/** \mainpage The SENF Socket Library - -\section arch Overall Architecture - -\image html "../../SocketLibrary-classes.png" Class Diagram - - */ - #ifndef HH_FileHandle_ #define HH_FileHandle_ 1 @@ -40,10 +31,40 @@ ///////////////////////////////hh.p//////////////////////////////////////// #include "FileHandle.ih" -namespace satcom { -namespace lib { +namespace senf { + - /** \brief + /** \brief Basic file handle wrapper + + senf::FileHandle provides a simple wrapper for arbitrary file handles. It exposes only a + minimal interface which does \e not include reading or writing (since some filehandles are + not readable or writable or only using special function calls like sendto). + + The FileHandle class provides handle/body handling and uses automatic reference + counting. The senf::FileHandle istance is very lightweight and should be used like a + built-in type. + + \attention You should mostly pass around senf::FileHandle objects by \e value und not by + reference. + + The FileHandle abstraction is only applicable to real filehandles. It is \e not possible to + wrap any provider or consumer into a filehandle like interface using this wrapper. The + wrapper will forward some calls directly to the underlying API without relying on virtual + methods. This allows important members to be inlined. + + It is not possible to use the senf::FileHandle class directly since it does not have any + public constructor. The FileHandle class is however the baseclass of all handle classes of + the socket library. + + \section filehandle_new Writing senf::FileHandle derived classes + + To build a new FileHandle type you need to derive from senf::FileHandle. The derived class + will have to call the protocted FileHandle constructor passing a new senf::FileBody + instance. This instance may either be a simple senf::FileBody or a class derived from + senf::FileBody. + + \todo Add public default constructor to allow declaration of (empty) senf::FileHandle + variables. */ class FileHandle : public SafeBool @@ -65,37 +86,54 @@ namespace lib { ///@} /////////////////////////////////////////////////////////////////////////// - - void close(); - void terminate(); - bool readable() const; - void waitReadable() const; - bool writeable() const; - void waitWriteable() const; + void close(); ///< Close filehandle + /**< \throws senf::SystemException */ + void terminate(); ///< Close filehandle ignoring error conditions + + bool readable() const; ///< Check, wether a read on the handle would not block + ///< (ignoring blocking state) + void waitReadable() const; ///< Wait, until read on the handle would not block (ignoring + ///< blocking state) + bool writeable() const; ///< Check, wether a write on the handle would not block + ///< (ignoring blocking state) + void waitWriteable() const; ///< Wait, until a write on the handle would not block + ///< (ignoring blocking state) - bool blocking() const; - void blocking(bool status); + bool blocking() const; ///< Return current blocking state + void blocking(bool status); ///< Set blocking state - bool eof() const; - bool valid() const; + bool eof() const; ///< Check EOF condition + /**< Depending on the socket type, this might never return \p + true */ + bool valid() const; ///< Check filehandle validity + /**< Any operation besides valid() will fail on an invalid + FileHandle */ - bool boolean_test() const; + bool boolean_test() const; ///< Short for valid() && ! eof() + /**< This is called when using a FileHandle instance in a boolen + context */ - int fd() const; + int fd() const; ///< Return the raw FileHandle - static FileHandle cast_static(FileHandle handle); - static FileHandle cast_dynamic(FileHandle handle); + static FileHandle cast_static(FileHandle handle); ///< \internal + static FileHandle cast_dynamic(FileHandle handle); ///< \internal protected: explicit FileHandle(std::auto_ptr body); + ///< create new FileHandle instance + /**< The FileHandle instance will take over ownership over the + given FileBody instance which must have been allocated using + \c new. To configure the FileHandle behavior, A derived class + may provide any class derived from FileBody here. */ - FileBody & body(); - FileBody const & body() const; - static FileBody & body(FileHandle & handle); - static FileBody const & body(FileHandle const & handle); + FileBody & body(); ///< Access body + FileBody const & body() const; ///< Access body in const context + static FileBody & body(FileHandle & handle); ///< Access body of another FileHandle instance + static FileBody const & body(FileHandle const & handle); ///< Access body of another + ///< FileHandle instance in const context - void fd(int fd); + void fd(int fd); ///< Set raw filehandle private: FileBody::ptr body_; @@ -103,7 +141,7 @@ namespace lib { int retrieve_filehandle(FileHandle handle); -}} +} ///////////////////////////////hh.e//////////////////////////////////////// #include "FileHandle.cci" @@ -114,5 +152,6 @@ namespace lib { // Local Variables: // mode: c++ -// c-file-style: "satcom" +// c-file-style: "senf" +// fill-column: 100 // End: