X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FFileHandle.ih;h=24c05283c9abc66c67f1f5fc85d4e5dea757e6a9;hb=70256cc93f59f5d2c9b3428775a181e5e225bfc5;hp=8e59737689a24d396f0cd4c307fea22ec801bccb;hpb=c52cd7d87dbb525c1267aad27391b8b7365dbb57;p=senf.git

diff --git a/Socket/FileHandle.ih b/Socket/FileHandle.ih
index 8e59737..24c0528 100644
--- a/Socket/FileHandle.ih
+++ b/Socket/FileHandle.ih
@@ -20,6 +20,10 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief senf::FileHandle internal header
+ */
+
 #ifndef IH_FileHandle_
 #define IH_FileHandle_ 1
 
@@ -29,13 +33,35 @@
 
 ///////////////////////////////ih.p////////////////////////////////////////
 
-namespace satcom {
-namespace lib {
+namespace senf {
+
+
+    /** \brief senf::FileHandle referenced body
+	
+	\internal
+
+	The senf::FileBody class formes the body part of the handle/body structure of the FileHandle
+	interface. It manages the FileHandle data and is referenced by senf::FileHandle. It is
+	automatically managed using reference counting.
+
+	Since the senf::FileHandle class forwards most calls directly to the underlying
+	senf::FileBody instance, most members are documented in senf::FileHandle.
+
+	\section filebody_new Writing senf::FileBody derived classes
+
+	It is possible to write customized senf::FileBody derived body implementations. This
+	implementation can then be used be a senf::FileHandle derived class to customize the
+	FileHandle behavior. Handling the body directly by the handle class ensures, that no invalid
+	handles can be created (a senf::FileHandle derived handle expecting a specific body type but
+	pointing to a different body type).
+
+	To customize the behavior, a virtual interface is provided. This interface only covers some
+	basic funcionality which is only used infrequently during the lifetime of a FileHandle
+	instance.
 
-    /** \brief
       */
     class FileBody
-        : public satcom::lib::intrusive_refcount
+        : public senf::intrusive_refcount
     {
     public:
         ///////////////////////////////////////////////////////////////////////////
@@ -47,7 +73,11 @@ namespace lib {
         ///\name Structors and default members
         ///@{
         
-        explicit FileBody(int fd=-1);
+        explicit FileBody(int fd=-1);	///< Create new instance
+					/**< You need to pass a real file descriptor to this
+					   constructor not some arbitrary id even if you overload
+					   all the virtual members. If the file descriptor is -1 the
+					   resulting body/handle is not valid() */
         virtual ~FileBody();
 
         // no copy
@@ -77,11 +107,23 @@ namespace lib {
         ///////////////////////////////////////////////////////////////////////////
         // Virtual interface for subclasses to override
 
-        virtual void v_close();
-        virtual void v_terminate();
-        virtual bool v_eof() const;
-        virtual bool v_valid() const;
-        
+        virtual void v_close();		///< Called to close the file descriptor
+					/**< You should probably always call the global ::close()
+					   function in this member, however you might want to do
+					   some additional cleanup here. If the operation fails, you
+					   are allowed to throw (preferably a
+					   senf::SystemException).
+
+					\throws senf::SystemException */
+        virtual void v_terminate();	///< Called to forcibly close the file descriptor
+					/**< This member is called by the destructor (and by
+					   terminate()) to close the descriptor. This member must \e
+					   never throw, it should probably just ignore error
+					   conditions (there's not much else you can do) */
+        virtual bool v_eof() const;	///< Called by eof()
+        virtual bool v_valid() const;	///< Called by valid()
+					/**< This member is only called, if the file descriptor is
+					   not -1 */
 
     protected:
         
@@ -91,7 +133,7 @@ namespace lib {
         int fd_;
     };
 
-}}
+}
 
 ///////////////////////////////ih.e////////////////////////////////////////
 #endif
@@ -99,5 +141,6 @@ namespace lib {
 
 // Local Variables:
 // mode: c++
-// c-file-style: "satcom"
+// c-file-style: "senf"
+// fill-column: 100
 // End: