From 469ff7b60c80cfb0b900ae0049368a04b9f6408e Mon Sep 17 00:00:00 2001 From: darkeye Date: Sat, 11 Nov 2000 12:33:13 +0000 Subject: [PATCH] added kdoc-style documentation --- darkice/trunk/src/BufferedSink.cpp | 37 ++--- darkice/trunk/src/BufferedSink.h | 231 +++++++++++++++++++++++------ darkice/trunk/src/Exception.cpp | 38 ++--- darkice/trunk/src/Exception.h | 179 +++++++++++++++++----- darkice/trunk/src/FileSink.cpp | 34 ++--- darkice/trunk/src/FileSink.h | 158 +++++++++++++++----- darkice/trunk/src/PipeSink.cpp | 34 ++--- darkice/trunk/src/PipeSink.h | 95 ++++++++---- darkice/trunk/src/Ref.h | 177 ++++++++++++++-------- darkice/trunk/src/Referable.h | 100 ++++++++----- darkice/trunk/src/Sink.h | 132 ++++++++++++----- 11 files changed, 854 insertions(+), 361 deletions(-) diff --git a/darkice/trunk/src/BufferedSink.cpp b/darkice/trunk/src/BufferedSink.cpp index cb1c77f..7395a2d 100644 --- a/darkice/trunk/src/BufferedSink.cpp +++ b/darkice/trunk/src/BufferedSink.cpp @@ -9,13 +9,6 @@ Author : $Author$ Location : $Source$ - Abstract : - - A Sink with a First-In First-Out buffer - This buffer can always be written to, it overwrites any - data contained if needed - The class is not thread-safe - the buffer is filled like this: buffer bufferEnd @@ -34,20 +27,19 @@ Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ @@ -380,6 +372,9 @@ BufferedSink :: close ( void ) throw ( Exception ) $Source$ $Log$ + Revision 1.4 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + Revision 1.3 2000/11/10 20:16:21 darkeye first real tests with multiple streaming diff --git a/darkice/trunk/src/BufferedSink.h b/darkice/trunk/src/BufferedSink.h index 543e19b..e4f1bd2 100644 --- a/darkice/trunk/src/BufferedSink.h +++ b/darkice/trunk/src/BufferedSink.h @@ -9,29 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - A Sink First-In First-Out buffer - This buffer can always be written to, it overwrites any - data contained if needed - The class is not thread-safe - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ #ifndef BUFFERED_SINK_H @@ -56,38 +48,96 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * A Sink First-In First-Out buffer. + * This buffer can always be written to, it overwrites any + * data contained if needed. + * The class is not thread-safe. + * + * @author $Author$ + * @version $Revision$ + */ class BufferedSink : public Sink { private: + /** + * The buffer. + */ unsigned char * buffer; + + /** + * The end of the buffer. + */ unsigned char * bufferEnd; + + /** + * The size of the buffer. + */ unsigned int bufferSize; + + /** + * The highest usage of the buffer. + */ unsigned int peak; + /** + * All data written to this BufferedSink is handled by chuncks + * of this size. + */ unsigned int chunkSize; + + /** + * Number of bytes the underlying stream is misaligned with + * chunkSize. (It needs this many bytes more to be aligned.) + */ unsigned int misalignment; + /** + * Start of free territory in buffer. + */ unsigned char * inp; + + /** + * Start of sensible data in buffer. + */ unsigned char * outp; + /** + * The underlying Sink. + */ Ref sink; - + /** + * Initialize the object. + * + * @param sink the Sink to attach this BufferedSink to. + * @param size the size of the internal buffer to use. + * @param chunkSize size of chunks to handle data in. + * @exception Exception + */ void init ( Sink * sink, unsigned int size, unsigned int chunkSize ) throw ( Exception ); - + /** + * De-initialize the object. + * + * @exception Exception + */ void strip ( void ) throw ( Exception ); - + /** + * Slide a pointer in the internal buffer by offset. If the pointer + * would reach beyond the end of the buffer, it goes wraps around. + * + * @param p the pointer to slide. + * @param offset the amount to slide with. + * @return pointer p + offset, wrapped around if needed. + */ inline unsigned char * slidePointer ( unsigned char * p, @@ -101,9 +151,13 @@ class BufferedSink : public Sink return p; } - + /** + * Update the peak buffer usage indicator. + * + * @see #peak + */ inline void - updatePeak ( void ) + updatePeak ( void ) throw () { unsigned int u; @@ -113,7 +167,13 @@ class BufferedSink : public Sink } } - + /** + * If the underlying Sink is misaligned on chunkSize, write as + * many 0s as needed to get it aligned. + * + * @see #misalignment + * @see #chunkSize + */ inline bool align ( void ) { @@ -139,20 +199,37 @@ class BufferedSink : public Sink protected: + /** + * Default constructor. Always throws an Exception. + * + * @exception Exception + */ inline BufferedSink ( void ) throw ( Exception ) { throw Exception( __FILE__, __LINE__); } - + /** + * Get the size of the buffer. + * + * @return the size of the buffer. + */ inline unsigned int getSize ( void ) const throw () { return bufferSize; } - + /** + * Store data in the internal buffer. If there is not enough space, + * discard all in the buffer and the beginning of the supplied + * buffer if needed. + * + * @param buffer the data to store. + * @param bufferSize the amount of data to store in bytes. + * @return number of bytes really stored. + */ unsigned int store ( const void * buffer, unsigned int bufferSize ) throw ( Exception ); @@ -160,6 +237,15 @@ class BufferedSink : public Sink public: + /** + * Constructor by an underlying Sink, buffer size and chunk size. + * + * @param sink the Sink to attach this BufferSink to. + * @param size the size of the buffer to use for buffering. + * @param chunkSize hanlde all data in write() as chunks of + * chunkSize + * @exception Exception + */ inline BufferedSink ( Sink * sink, unsigned int size, @@ -168,42 +254,78 @@ class BufferedSink : public Sink init( sink, size, chunkSize); } - + /** + * Copy constructor. + * + * @param buffer the object to copy. + * @exception Exception + */ BufferedSink ( const BufferedSink & buffer ) throw ( Exception ); - + /** + * Destructor. + * + * @exception Exception + */ inline virtual ~BufferedSink ( void ) throw ( Exception ) { strip(); } - + /** + * Assignment operator. + * + * @param bs the object to assign to this one. + * @return a reference to this object. + * @exception Exception + */ virtual BufferedSink & operator= ( const BufferedSink & bs ) throw ( Exception ); - + /** + * Get the peak usage of the internal buffer. + * + * @return the peak usage of the internal buffer. + */ inline unsigned int getPeak ( void ) const throw () { return peak; } - + /** + * Open the BufferedSink. Opens the underlying Sink. + * + * @return true if opening was successful, false otherwise. + * @exception Exception + */ inline virtual bool open ( void ) throw ( Exception ) { return sink->open(); } - + /** + * Check if a BufferedSink is open. + * + * @return true if the BufferedSink is open, false otherwise. + */ inline virtual bool - isOpen ( void ) const throw ( Exception ) + isOpen ( void ) const throw () { return sink->isOpen(); } - + /** + * Check if the BufferedSink is ready to accept data. + * Always returns true immediately. + * + * @param sec the maximum seconds to block. + * @param usec micro seconds to block after the full seconds. + * @return true + * @exception Exception + */ inline virtual bool canWrite ( unsigned int sec, unsigned int usec ) throw ( Exception ) @@ -211,12 +333,28 @@ class BufferedSink : public Sink return true; } - + /** + * Write data to the BufferedSink. + * Always reads the maximum number of chunkSize chunks buf + * holds. If the data can not be written to the underlying + * stream, it is buffered. If the buffer overflows, the oldest + * data is discarded. + * + * @param buf the data to write. + * @param len number of bytes to write from buf. + * @return the number of bytes written (may be less than len). + * @exception Exception + */ virtual unsigned int write ( const void * buf, unsigned int len ) throw ( Exception ); - + /** + * Flush all data that was written to the BufferedSink to the + * underlying Sink. + * + * @exception Exception + */ inline virtual void flush ( void ) throw ( Exception ) { @@ -225,7 +363,11 @@ class BufferedSink : public Sink write( b, 0); } - + /** + * Close the BufferedSink. Closes the underlying Sink. + * + * @exception Exception + */ virtual void close ( void ) throw ( Exception ); }; @@ -246,6 +388,9 @@ class BufferedSink : public Sink $Source$ $Log$ + Revision 1.4 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + Revision 1.3 2000/11/10 20:16:21 darkeye first real tests with multiple streaming diff --git a/darkice/trunk/src/Exception.cpp b/darkice/trunk/src/Exception.cpp index ddac0e3..d0855d9 100644 --- a/darkice/trunk/src/Exception.cpp +++ b/darkice/trunk/src/Exception.cpp @@ -9,30 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - An exception class - - This class should not depend on any other class - (note: Cloneable is an interface) and should not throw - any exceptions itself - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ @@ -212,6 +203,9 @@ Exception :: strip ( void ) throw () $Source$ $Log$ + Revision 1.4 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + Revision 1.3 2000/11/09 22:05:44 darkeye added multiple-string constructors diff --git a/darkice/trunk/src/Exception.h b/darkice/trunk/src/Exception.h index d4fa0f6..1b0cc08 100644 --- a/darkice/trunk/src/Exception.h +++ b/darkice/trunk/src/Exception.h @@ -9,30 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - An exception class - - This class should not depend on any other class - (note: Cloneable is an interface) and should not throw - any exceptions itself - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ #ifndef EXCEPTION_H @@ -56,26 +47,62 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * An exception class. + * + * This class should not depend on any other class + * should not throw any exceptions itself. + * + * Typical usage: + * + * 
+ *  throw Exception( __FILE__, __LINE__, "describe the exception", code);
+ *
+ * + * @author $Author$ + * @version $Revision$ + */ class Exception { private: + /** + * Source file the exception was thrown in. + */ char * file; + + /** + * Line number in the source file the exception was thrown in. + */ unsigned int line; + + /** + * Textual description of the exception. + */ char * description; + + /** + * Numerical error code. + */ int code; - + /** + * Initalize the object. + * + * @param file the source file the exception was thrown in. + * @param line the line in the source file. + * @param description textual description of the exception. + * @param code numerical error code. + */ void init ( const char * file, unsigned int line, const char * description, int code ) throw (); - + /** + * De-initalize the object. + */ void strip () throw (); @@ -85,20 +112,30 @@ class Exception public: + /** + * Default constructor. + */ inline Exception ( void ) throw () { init( 0, 0, 0, 0); } - + /** + * Copy constructor. + */ inline Exception ( const Exception & e ) throw () { init( e.file, e.line, e.description, e.code); } - + /** + * Construct by a description and error code. + * + * @param description textual description of the exception. + * @param code numerical error code. + */ inline Exception ( const char * description, int code = 0 ) throw () @@ -106,7 +143,14 @@ class Exception init( 0, 0, description, code); } - + /** + * Construct by source file information, a description and error code. + * + * @param file the source file the exception was thrown in. + * @param line the line in the source file. + * @param description textual description of the exception. + * @param code numerical error code. + */ inline Exception ( const char * file, unsigned int line, @@ -116,14 +160,35 @@ class Exception init( file, line, description, code); } - + /** + * Construct by source file information, a description and error code. + * The description is constructed from two strings, any of which + * may be NULL. + * + * @param file the source file the exception was thrown in. + * @param line the line in the source file. + * @param description1 textual description of the exception part 1. + * @param description2 textual description of the exception part 2. + * @param code numerical error code. + */ Exception ( const char * file, unsigned int line, const char * description1, const char * description2, int code = 0 ) throw (); - + /** + * Construct by source file information, a description and error code. + * The description is constructed from three strings, any of + * which may be NULL. + * + * @param file the source file the exception was thrown in. + * @param line the line in the source file. + * @param description1 textual description of the exception part 1. + * @param description2 textual description of the exception part 2. + * @param description3 textual description of the exception part 3. + * @param code numerical error code. + */ Exception ( const char * file, unsigned int line, const char * description1, @@ -131,14 +196,21 @@ class Exception const char * description3, int code = 0 ) throw (); - + /** + * Desctructor. + */ inline ~Exception ( void ) throw () { strip(); } - + /** + * Assignment operator. + * + * @param e the Exception to assign this to. + * @return a reference to this Exception. + */ inline Exception & operator= ( const Exception & e ) throw () { @@ -150,33 +222,51 @@ class Exception return *this; } - + /** + * Return the textual description of the Exception. + * + * @return the textual description of the Exception. + */ inline const char * getDescription( void ) const throw () { return description; } + /** + * Return the line number in the source file this Exception was + * thrown in. + * + * @return the line number in the source file this Exception was + * thrown in. + */ inline unsigned int getLine ( void ) const throw () { return line; } - + /** + * Return the source file this Exception was thrown in. + * + * @return the source file this Exception was thrown in. + */ inline const char * getFile ( void ) const throw () { return file; } - + /** + * Return the numerical code of the Exception. + * + * @return the numerical code of the Exception. + */ inline int getCode ( void ) const throw () { return code; } - }; @@ -185,9 +275,13 @@ class Exception /* ====================================================== function prototypes */ -/*------------------------------------------------------------------------------ - * Print a Exception to an ostream - *----------------------------------------------------------------------------*/ +/** + * Print an Exception to an ostream. + * + * @param os the output stream to print to. + * @param e the Exception to print. + * @return a reference to the supplied output stream. + */ inline ostream & operator<< ( ostream & os, const Exception & e ) @@ -206,6 +300,9 @@ operator<< ( ostream & os, $Source$ $Log$ + Revision 1.4 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + Revision 1.3 2000/11/09 22:05:44 darkeye added multiple-string constructors diff --git a/darkice/trunk/src/FileSink.cpp b/darkice/trunk/src/FileSink.cpp index 7ad476e..f6a74a8 100644 --- a/darkice/trunk/src/FileSink.cpp +++ b/darkice/trunk/src/FileSink.cpp @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - File data output - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ @@ -311,6 +306,9 @@ FileSink :: close ( void ) throw ( Exception ) $Source$ $Log$ + Revision 1.3 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + Revision 1.2 2000/11/05 14:08:27 darkeye changed builting to an automake / autoconf environment diff --git a/darkice/trunk/src/FileSink.h b/darkice/trunk/src/FileSink.h index 5aff0cd..2eecf38 100644 --- a/darkice/trunk/src/FileSink.h +++ b/darkice/trunk/src/FileSink.h @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - File data output - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ #ifndef FILE_SINK_H @@ -52,29 +47,51 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * File data output + * + * @author $Author$ + * @version $Revision$ + */ class FileSink : public Sink { private: + /** + * Name of the file represented by the FileSink. + */ char * fileName; - + /** + * Initialize the object. + * + * @param name name of the file to be represented by the object. + * @exception Exception + */ void init ( const char * name ) throw ( Exception ); - + /** + * De-initialize the object. + * + * @exception Exception + */ void strip ( void ) throw ( Exception ); protected: + /** + * Low-level file descriptor for the file represented by this object. + */ int fileDescriptor; - + /** + * Default constructor. Always throws an Exception. + * + * @exception Exception + */ inline FileSink ( void ) throw ( Exception ) { @@ -84,69 +101,135 @@ class FileSink : public Sink public: + /** + * Constructor by a file name. + * + * @param name name of the file to be represented by the object. + * @exception Exception + */ inline FileSink( const char * name ) throw ( Exception ) { init( name); } - + /** + * Copy constructor. + * + * @param fsink the FileSink to copy. + * @exception Exception + */ FileSink( const FileSink & fsink ) throw ( Exception ); - + /** + * Destructor. + * + * @exception Exception + */ inline virtual ~FileSink( void ) throw ( Exception ) { strip(); } - + /** + * Assignment operator. + * + * @param fs the FileSink to assign to this object. + * @return a reference to this object. + * @exception Exception + */ virtual FileSink & operator= ( const FileSink & fs ) throw ( Exception ); - + /** + * Get the file name this FileSink represents. + * + * @return the file name this FileSink represents. + */ inline const char * getFileName ( void ) const throw () { return fileName; } - + /** + * Check for the existence of the file this FileSink represents. + * + * @return true if the file exists, false otherwise. + */ virtual bool exists ( void ) const throw (); - + /** + * Create the file. + * + * @return true if creation was successful, false otherwise. + * @exception Exception + */ virtual bool create ( void ) throw ( Exception ); - + /** + * Open the file. Truncates the file. + * + * @return true if opening was successful, false otherwise. + * @exception Exception + */ virtual bool open ( void ) throw ( Exception ); - + /** + * Check if the FileSink is open. + * + * @return true if the FileSink is open, false otherwise. + */ inline virtual bool isOpen ( void ) const throw () { return fileDescriptor != 0; } - + /** + * Check if the FileSink is ready to accept data. + * Blocks until the specified time for data to be available. + * + * @param sec the maximum seconds to block. + * @param usec micro seconds to block after the full seconds. + * @return true if the Sink is ready to accept data, false otherwise. + * @exception Exception + */ virtual bool canWrite ( unsigned int sec, unsigned int usec ) throw ( Exception ); - + /** + * Write data to the FileSink. + * + * @param buf the data to write. + * @param len number of bytes to write from buf. + * @return the number of bytes written (may be less than len). + * @exception Exception + */ virtual unsigned int write ( const void * buf, unsigned int len ) throw ( Exception ); - + /** + * This is a no-op in this FileSink. + * + * @exception Exception + */ inline virtual void flush ( void ) throw ( Exception ) { } - + /** + * Close the FileSink. + * + * @exception Exception + */ virtual void close ( void ) throw ( Exception ); }; @@ -167,6 +250,9 @@ class FileSink : public Sink $Source$ $Log$ + Revision 1.3 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + Revision 1.2 2000/11/05 17:37:24 darkeye removed clone() functions diff --git a/darkice/trunk/src/PipeSink.cpp b/darkice/trunk/src/PipeSink.cpp index cc5d4d1..766782a 100644 --- a/darkice/trunk/src/PipeSink.cpp +++ b/darkice/trunk/src/PipeSink.cpp @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Audio data input - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ @@ -129,6 +124,9 @@ PipeSink :: open ( void ) throw ( Exception ) $Source$ $Log$ + Revision 1.4 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + Revision 1.3 2000/11/10 20:10:46 darkeye changed from non-blocking to blocking diff --git a/darkice/trunk/src/PipeSink.h b/darkice/trunk/src/PipeSink.h index 25a4fc9..4904519 100644 --- a/darkice/trunk/src/PipeSink.h +++ b/darkice/trunk/src/PipeSink.h @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - FIFO pipe data output - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ #ifndef PIPE_SINK_H @@ -52,9 +47,12 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * FIFO pipe data output + * + * @author $Author$ + * @version $Revision$ + */ class PipeSink : public FileSink { private: @@ -62,6 +60,11 @@ class PipeSink : public FileSink protected: + /** + * Default constructor. Always throws an Exception. + * + * @exception Exception + */ inline PipeSink ( void ) throw ( Exception ) { @@ -71,41 +74,72 @@ class PipeSink : public FileSink public: + /** + * Constructor by a pipe name. + * + * @param name name of the pipe to be represented by the object. + * @exception Exception + */ inline PipeSink ( const char * name ) throw ( Exception ) : FileSink( name ) { } - + /** + * Copy constructor. + * + * @param fsink the PipeSink to copy. + * @exception Exception + */ inline PipeSink ( const PipeSink & ps ) throw ( Exception ) : FileSink( ps ) { } - + /** + * Assignment operator. + * + * @param ps the PipeSink to assign to this object. + * @return a reference to this object. + * @exception Exception + */ inline virtual PipeSink & - operator= ( const PipeSink & fs ) throw ( Exception ) + operator= ( const PipeSink & ps ) throw ( Exception ) { - if ( this != &fs ) { - FileSink::operator=( fs ); + if ( this != &ps ) { + FileSink::operator=( ps ); } return *this; } - + /** + * Destructor. + * + * @exception Exception + */ virtual inline ~PipeSink( void ) throw ( Exception ) { } - + /** + * Create the pipe. + * + * @return true if creation was successful, false otherwise. + * @exception Exception + */ virtual bool create ( void ) throw ( Exception ); - + /** + * Open the pipe. + * + * @return true if opening was successful, false otherwise. + * @exception Exception + */ virtual bool open ( void ) throw ( Exception ); }; @@ -126,6 +160,9 @@ class PipeSink : public FileSink $Source$ $Log$ + Revision 1.3 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + Revision 1.2 2000/11/05 17:37:24 darkeye removed clone() functions diff --git a/darkice/trunk/src/Ref.h b/darkice/trunk/src/Ref.h index dcf7a93..67666f5 100644 --- a/darkice/trunk/src/Ref.h +++ b/darkice/trunk/src/Ref.h @@ -9,48 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Java-like object reference class - Objects used with this reference class have to be descandents - of class Referable - - sample usage: - - #include "Ref.h" - #include "Referable.h" - - class A : public virtual Referable; - - ... - - A * a = new A(); - Ref ref1 = a; // 1 reference to a - Ref ref2 = ref1; // 2 references to a - - ref1 = 0; // 1 reference to a - ref2 = 0; // at this point object a is destroyed - - - Based on Tima Saarinen's work, - http://gamma.nic.fi/~timosa/comp/refcount.html - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ #ifndef REF_H @@ -74,14 +47,46 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ +/** + * Java-like object reference class. + * Objects used with this reference class have to be descandents + * of class Referable. + * + * sample usage: + * + * 
+ *  #include "Ref.h"
+ *  #include "Referable.h"
+ *
+ *  class  A : public virtual Referable;
+ *
+ *  ...
+ *   
+ *  A        * a = new A();
+ *  Ref     ref1 = a;       // 1 reference to a
+ *  Ref     ref2 = ref1;    // 2 references to a
+ *
+ *  ref1 = 0;      // 1 reference to a
+ *  ref2 = 0;      // at this point object a is destroyed
+ *
+ * + * Based on Tima Saarinen's work, + * http://gamma.nic.fi/~timosa/comp/refcount.html + * + * @ref Referable * - *----------------------------------------------------------------------------*/ + * @author $Author$ + * @version $Revision$ + */ template class Ref { private: + /** + * The object referenced by this Ref. + * Must be a descandant of Referable. + */ T* object; @@ -90,13 +95,21 @@ class Ref public: + /** + * Default constructor. + */ inline Ref ( void ) throw () { object = NULL; } - + /** + * Copy constructor. + * + * @param other the Ref to copy. + * @exception Exception + */ inline Ref ( const Ref & other ) throw ( Exception ) { @@ -104,7 +117,12 @@ class Ref set( other.object); } - + /** + * Constructor based on an object to reference. + * + * @param obj the object to reference. + * @exception Exception + */ inline Ref ( T * obj ) throw ( Exception ) { @@ -112,14 +130,22 @@ class Ref obj->increaseReferenceCount(); } - + /** + * Destructor. + * + * @exception Exception + */ inline virtual ~Ref ( void ) throw ( Exception ) { set( 0 ); } - + /** + * Operator overload to make the reference seem like a pointer. + * + * @return the pointer to the object referenced. + */ inline T* operator->() const throw () { @@ -130,14 +156,27 @@ class Ref return object; } - + /** + * Assignment operator. + * + * @param other the Ref to assign to this one. + * @return a reference to this Ref. + * @exception Exception + */ inline Ref & operator= ( Ref other ) throw ( Exception ) { set( other.object); + return this; } - + /** + * Assignment operator. + * + * @param obj pointer to the object to assign to this Ref. + * @return a reference to this Ref. + * @exception Exception + */ inline Ref & operator= ( T* obj ) throw ( Exception ) { @@ -145,7 +184,13 @@ class Ref return *this; } - + /** + * Set the object referenced. + * Deletes the old referenced object is this was it's last reference. + * + * @param newobj pointer to the object to reference by this Ref. + * @exception Exception + */ inline void set ( T* newobj ) throw ( Exception ) { @@ -170,17 +215,16 @@ class Ref object = newobj; } - /** - * Return object pointer. This method should be used with - * care because it breaks the encapsulation. - * Typically this method is needed for the method calls - * which require literal object pointer. + * Return object pointer. This method should be used with + * care because it breaks the encapsulation. + * Typically this method is needed for the method calls + * which require literal object pointer. * - *

It may not be bad idea to pass the Ref - * objects as method arguments.

+ * It may not be bad idea to pass the Ref + * objects as method arguments. * - * @return Object pointer or NULL. + * @return Object pointer or NULL. */ inline T* get ( void ) const throw () @@ -188,14 +232,26 @@ class Ref return object; } - + /** + * Equality operator. + * + * @param other the Ref to compare this with. + * @return true is the two Refs refer to the same object, + * false otherwise. + */ inline bool operator== ( const Ref & other ) const throw () { return object == other.object; } - + /** + * Unequality operator. + * + * @param other the Ref to compare this with. + * @return false is the two Refs refer to the same object, + * true otherwise. + */ inline bool operator!= ( const Ref & other ) const throw () { @@ -218,8 +274,11 @@ class Ref $Source$ $Log$ - Revision 1.1 2000/11/05 10:05:54 darkeye - Initial revision + Revision 1.2 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + + Revision 1.1.1.1 2000/11/05 10:05:54 darkeye + initial version ------------------------------------------------------------------------------*/ diff --git a/darkice/trunk/src/Referable.h b/darkice/trunk/src/Referable.h index 4b25687..87ef065 100644 --- a/darkice/trunk/src/Referable.h +++ b/darkice/trunk/src/Referable.h @@ -9,34 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Base class for an object for which references can be made - with the reference class Ref (see Ref.h) - - usage: - - class A : public virtual Referable - { - ... - }; - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ #ifndef REFERABLE_H @@ -60,21 +47,45 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ +/** + * Base class for an object for which references can be made + * with the reference class Ref. + * + * usage: + * + * 
+ *  class A : public virtual Referable
+ *  {
+ *     ...
+ *  };
+ *
* - *----------------------------------------------------------------------------*/ + * @ref Ref + * + * @author $Author$ + * @version $Revision$ + */ class Referable { private: - + + /** + * Number of references to the object. + */ unsigned int referenceCount; + /** + * Maximum number of references before an overflow occurs. + */ static const unsigned int maxCount = ~((unsigned int)0); protected: + /** + * Default constructor. + */ inline Referable ( void ) throw () { @@ -82,6 +93,11 @@ class Referable } + /** + * Desctructor. + * + * @exception Exception + */ inline virtual ~Referable ( void ) throw ( Exception ) { @@ -95,6 +111,12 @@ class Referable public: + /** + * Increase reference count. + * + * @return the new reference count. + * @exception Exception + */ inline unsigned int increaseReferenceCount ( void ) throw ( Exception ) { @@ -107,7 +129,12 @@ class Referable return ++referenceCount; } - + /** + * Decrease reference count. + * + * @return the new reference count. + * @exception Exception + */ inline unsigned int decreaseReferenceCount ( void ) throw ( Exception ) { @@ -119,7 +146,11 @@ class Referable return --referenceCount; } - + /** + * Get the reference count. + * + * @return the reference count. + */ inline unsigned int getReferenceCount ( void ) const throw () { @@ -143,8 +174,11 @@ class Referable $Source$ $Log$ - Revision 1.1 2000/11/05 10:05:54 darkeye - Initial revision + Revision 1.2 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + + Revision 1.1.1.1 2000/11/05 10:05:54 darkeye + initial version ------------------------------------------------------------------------------*/ diff --git a/darkice/trunk/src/Sink.h b/darkice/trunk/src/Sink.h index d4b0c6f..63c79ed 100644 --- a/darkice/trunk/src/Sink.h +++ b/darkice/trunk/src/Sink.h @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - A general data sink - Copyright notice: - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, - USA. + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------*/ #ifndef SINK_H @@ -42,6 +37,7 @@ /* ============================================================ include files */ #include "Referable.h" +#include "Exception.h" /* ================================================================ constants */ @@ -52,9 +48,12 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * A general data sink + * + * @author $Author$ + * @version $Revision$ + */ class Sink : public virtual Referable { private: @@ -62,20 +61,32 @@ class Sink : public virtual Referable protected: + /** + * Default constructor. + */ inline - Sink ( void ) + Sink ( void ) throw () { } - + /** + * Copy constructor. + * + * @param sink the Sink to copy. + */ inline - Sink ( const Sink & sink ) + Sink ( const Sink & sink ) throw () { } - + /** + * Assignment operator. + * + * @param sink the Sink to assign this to. + * @return a reference to this Sink. + */ inline virtual Sink & - operator= ( const Sink & sink ) + operator= ( const Sink & sink ) throw () { return *this; } @@ -83,36 +94,72 @@ class Sink : public virtual Referable public: + /** + * Destructor. + */ inline virtual - ~Sink ( void ) + ~Sink ( void ) throw () { } - + /** + * Open the sink. + * + * @return true if opening was successfull, false otherwise. + * @exception Exception + */ virtual bool - open ( void ) = 0; - + open ( void ) throw ( Exception ) = 0; + /** + * Check if a Sink is open. + * + * @return true if the Sink is open, false otherwise. + */ virtual bool - isOpen ( void ) const = 0; - + isOpen ( void ) const throw () = 0; + /** + * Check if the Sink is ready to accept data. + * Blocks until the specified time for data to be available. + * + * @param sec the maximum seconds to block. + * @param usec micro seconds to block after the full seconds. + * @return true if the Sink is ready to accept data, false otherwise. + * @exception Exception + */ virtual bool canWrite ( unsigned int sec, - unsigned int usec ) = 0; - + unsigned int usec ) throw ( Exception ) = 0; + /** + * Write data to the Sink. + * + * @param buf the data to write. + * @param len number of bytes to write from buf. + * @return the number of bytes written (may be less than len). + * @exception Exception + */ virtual unsigned int write ( const void * buf, - unsigned int len ) = 0; - + unsigned int len ) throw ( Exception ) = 0; + /** + * Flush all data that was written to the Sink to the underlying + * construct. + * + * @exception Exception + */ virtual void - flush ( void ) = 0; - + flush ( void ) throw ( Exception ) = 0; + /** + * Close the Sink. + * + * @exception Exception + */ virtual void - close ( void ) = 0; + close ( void ) throw ( Exception ) = 0; }; @@ -131,8 +178,11 @@ class Sink : public virtual Referable $Source$ $Log$ - Revision 1.1 2000/11/05 10:05:54 darkeye - Initial revision + Revision 1.2 2000/11/11 12:33:13 darkeye + added kdoc-style documentation + + Revision 1.1.1.1 2000/11/05 10:05:54 darkeye + initial version ------------------------------------------------------------------------------*/