From 8b319e858421c0c6e97c5849f7d51a4a149cf066 Mon Sep 17 00:00:00 2001 From: darkeye Date: Sun, 12 Nov 2000 13:31:40 +0000 Subject: [PATCH] added kdoc-style documentation comments --- darkice/trunk/src/AudioSource.h | 118 +++++++++++++++++------ darkice/trunk/src/FileSource.cpp | 34 +++---- darkice/trunk/src/FileSource.h | 150 ++++++++++++++++++++++------- darkice/trunk/src/OssDspSource.cpp | 34 +++---- darkice/trunk/src/OssDspSource.h | 149 ++++++++++++++++++++++------ darkice/trunk/src/PipeSource.cpp | 34 +++---- darkice/trunk/src/PipeSource.h | 58 ++++++++--- darkice/trunk/src/Source.h | 111 +++++++++++++++------ darkice/trunk/src/Util.cpp | 34 +++---- darkice/trunk/src/Util.h | 129 +++++++++++++++++++------ 10 files changed, 617 insertions(+), 234 deletions(-) diff --git a/darkice/trunk/src/AudioSource.h b/darkice/trunk/src/AudioSource.h index 767217d..48f5414 100644 --- a/darkice/trunk/src/AudioSource.h +++ b/darkice/trunk/src/AudioSource.h @@ -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. ------------------------------------------------------------------------------*/ #ifndef AUDIO_SOURCE_H @@ -52,18 +47,40 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * Audio data input + * + * @author $Author$ + * @version $Revision$ + */ class AudioSource : public Source { private: + /** + * Number of channels of the audio source + * (e.g. 1 for mono, 2 for stereo, etc.) + */ unsigned int channel; + + /** + * Samples per second (e.g. 44100 for 44.1kHz CD quality) + */ unsigned int sampleRate; + + /** + * Bits per sample (e.g. 8 bits, 16 bits, etc.) + */ unsigned int bitsPerSample; - + /** + * Initialize the object. + * + * @param sampleRate samples per second. + * @param bitsPerSample bits per sample. + * @param channel number of channels of the audio source. + * @exception Exception + */ inline void init ( unsigned int sampleRate, unsigned int bitsPerSample, @@ -74,7 +91,11 @@ class AudioSource : public Source this->channel = channel; } - + /** + * De-initialize the object. + * + * @exception Exception + */ inline void strip ( void ) throw ( Exception ) { @@ -83,6 +104,17 @@ class AudioSource : public Source protected: + /** + * Constructor. + * Because all values have defaults, this is also the default + * constructor. + * + * @param sampleRate samples per second (e.g. 44100 for 44.1kHz). + * @param bitsPerSample bits per sample (e.g. 16 bits). + * @param channel number of channels of the audio source + * (e.g. 1 for mono, 2 for stereo, etc.). + * @exception Exception + */ inline AudioSource ( unsigned int sampleRate = 44100, unsigned int bitsPerSample = 16, @@ -92,7 +124,12 @@ class AudioSource : public Source init ( sampleRate, bitsPerSample, channel); } - + /** + * Copy Constructor. + * + * @param source the object to copy. + * @exception Exception + */ inline AudioSource ( const AudioSource & as ) throw ( Exception ) : Source( as ) @@ -100,13 +137,23 @@ class AudioSource : public Source init ( as.sampleRate, as.bitsPerSample, as.channel); } - + /** + * Destructor. + * + * @exception Exception + */ virtual inline ~AudioSource ( void ) throw ( Exception ) { } - + /** + * Assignment operator. + * + * @param as the object to assign to this one. + * @return a reference to this object. + * @exception Exception + */ inline virtual AudioSource & operator= ( const AudioSource & as ) throw ( Exception ) { @@ -122,13 +169,22 @@ class AudioSource : public Source public: + /** + * Get the number of channels for this AudioSource. + * + * @return the number of channels. + */ inline unsigned int getChannel ( void ) const throw () { return channel; } - + /** + * Get the sample rate per seconds for this AudioSource. + * + * @return the sample rate per seconds. + */ inline unsigned int getSampleRate ( void ) const throw () { @@ -136,6 +192,11 @@ class AudioSource : public Source } + /** + * Get the number of bits per sample for this AudioSource. + * + * @return the number of bits per sample. + */ inline unsigned int getBitsPerSample ( void ) const throw () { @@ -159,6 +220,9 @@ class AudioSource : public Source $Source$ $Log$ + Revision 1.3 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + Revision 1.2 2000/11/05 17:37:24 darkeye removed clone() functions diff --git a/darkice/trunk/src/FileSource.cpp b/darkice/trunk/src/FileSource.cpp index c01e94b..2f7dfb9 100644 --- a/darkice/trunk/src/FileSource.cpp +++ b/darkice/trunk/src/FileSource.cpp @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Data input from a file - 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. ------------------------------------------------------------------------------*/ @@ -261,6 +256,9 @@ FileSource :: close ( void ) throw ( Exception ) $Source$ $Log$ + Revision 1.3 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + Revision 1.2 2000/11/05 14:08:27 darkeye changed builting to an automake / autoconf environment diff --git a/darkice/trunk/src/FileSource.h b/darkice/trunk/src/FileSource.h index 97331f1..99b4cb7 100644 --- a/darkice/trunk/src/FileSource.h +++ b/darkice/trunk/src/FileSource.h @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Data input from a file - 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_SOURCE_H @@ -52,27 +47,51 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ +/** * A data source based on a file - *----------------------------------------------------------------------------*/ + * + * @author $Author$ + * @version $Revision$ + */ class FileSource : public Source { private: + /** + * Name of the file represented by the FileSource. + */ char * fileName; - int fileDescriptor; - + /** + * 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 FileSource ( void ) throw ( Exception ) { @@ -82,59 +101,117 @@ class FileSource : public Source public: + /** + * Constructor by a file name. + * + * @param name name of the file to be represented by the object. + * @exception Exception + */ inline FileSource ( const char * name ) throw ( Exception ) { init( name); } - + /** + * Copy constructor. + * + * @param fs the FileSource to copy. + * @exception Exception + */ FileSource ( const FileSource & fs ) throw ( Exception ); - + /** + * Destructor. + * + * @exception Exception + */ inline ~FileSource ( void ) throw ( Exception ) { strip(); } - + /** + * Assignment operator. + * + * @param fs the FileSource to assign to this object. + * @return a reference to this object. + * @exception Exception + */ inline virtual FileSource & operator= ( const FileSource & fs ) throw ( Exception ); - + /** + * Get the file name this FileSource represents. + * + * @return the file name this FileSource represents. + */ inline virtual const char * getFileName ( void ) const throw () { return fileName; } - + /** + * Check for the existence of the file this FileSource represents. + * + * @return true if the file exists, false otherwise. + */ virtual bool exists ( void ) const throw (); - + /** + * Open the file. + * + * @return true if opening was successful, false otherwise. + * @exception Exception + */ virtual bool open ( void ) throw ( Exception ); - + /** + * Check if the FileSource is open. + * + * @return true if the FileSource is open, false otherwise. + */ inline virtual bool isOpen ( void ) const throw () { return fileDescriptor != 0; } - + /** + * Check if the FileSource has data available. + * 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 FileSource has data to be read, + * false otherwise. + * @exception Exception + */ virtual bool canRead ( unsigned int sec, unsigned int usec ) throw ( Exception ); - + /** + * Read from the FileSource. + * + * @param buf the buffer to read into. + * @param len the number of bytes to read into buf + * @return the number of bytes read (may be less than len). + * @exception Exception + */ virtual unsigned int read ( void * buf, unsigned int len ) throw ( Exception ); - + /** + * Close the FileSource. + * + * @exception Exception + */ virtual void close ( void ) throw ( Exception ); }; @@ -155,8 +232,11 @@ class FileSource : public Source $Source$ $Log$ - Revision 1.1 2000/11/05 10:05:51 darkeye - Initial revision + Revision 1.2 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + + Revision 1.1.1.1 2000/11/05 10:05:51 darkeye + initial version ------------------------------------------------------------------------------*/ diff --git a/darkice/trunk/src/OssDspSource.cpp b/darkice/trunk/src/OssDspSource.cpp index 59db115..12ba8b0 100644 --- a/darkice/trunk/src/OssDspSource.cpp +++ b/darkice/trunk/src/OssDspSource.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. ------------------------------------------------------------------------------*/ @@ -269,6 +264,9 @@ OssDspSource :: close ( void ) throw ( Exception ) $Source$ $Log$ + Revision 1.3 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + Revision 1.2 2000/11/05 14:08:28 darkeye changed builting to an automake / autoconf environment diff --git a/darkice/trunk/src/OssDspSource.h b/darkice/trunk/src/OssDspSource.h index a028d93..4684fa9 100644 --- a/darkice/trunk/src/OssDspSource.h +++ b/darkice/trunk/src/OssDspSource.h @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Audio data input from an OSS /dev/dsp-like device - 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 OSS_DSP_SOURCE_H @@ -52,37 +47,77 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ +/** * An audio input based on /dev/dsp-like raw devices - *----------------------------------------------------------------------------*/ + * + * @author $Author$ + * @version $Revision$ + */ class OssDspSource : public AudioSource { private: + /** + * The file name of the OSS DSP device (e.g. /dev/dsp or /dev/dsp0). + */ char * fileName; + + /** + * The low-level file descriptor of the OSS DSP device. + */ int fileDescriptor; + + /** + * Indicates wether the low-level OSS DSP device is in a recording + * state. + */ bool running; protected: + /** + * Default constructor. Always throws an Exception. + * + * @exception Exception + */ inline OssDspSource ( void ) throw ( Exception ) { throw Exception( __FILE__, __LINE__); } - + /** + * Initialize the object + * + * @param name the file name of the OSS DSP device. + * @exception Exception + */ void init ( const char * name ) throw ( Exception ); - + /** + * De-iitialize the object + * + * @exception Exception + */ void strip ( void ) throw ( Exception ); public: + /** + * Constructor. + * + * @param name the file name of the OSS DSP device + * (e.g. /dev/dsp or /dev/dsp0). + * @param sampleRate samples per second (e.g. 44100 for 44.1kHz). + * @param bitsPerSample bits per sample (e.g. 16 bits). + * @param channel number of channels of the audio source + * (e.g. 1 for mono, 2 for stereo, etc.). + * @exception Exception + */ inline OssDspSource ( const char * name, int sampleRate = 44100, @@ -95,7 +130,12 @@ class OssDspSource : public AudioSource init( name); } - + /** + * Copy Constructor. + * + * @param source the object to copy. + * @exception Exception + */ inline OssDspSource ( const OssDspSource & ds ) throw ( Exception ) : AudioSource( ds ) @@ -103,14 +143,24 @@ class OssDspSource : public AudioSource init( ds.fileName); } - + /** + * Destructor. + * + * @exception Exception + */ inline virtual ~OssDspSource ( void ) throw ( Exception ) { strip(); } - + /** + * Assignment operator. + * + * @param ds the object to assign to this one. + * @return a reference to this object. + * @exception Exception + */ inline virtual OssDspSource & operator= ( const OssDspSource & ds ) throw ( Exception ) { @@ -122,28 +172,64 @@ class OssDspSource : public AudioSource return *this; } - + /** + * Open the OssDspSource. + * This does not put the OSS DSP device into recording mode. + * To start getting samples, call either canRead() or read(). + * + * @return true if opening was successful, false otherwise + * @exception Exception + * + * @see #canRead + * @see #read + */ virtual bool open ( void ) throw ( Exception ); - + /** + * Check if the OssDspSource is open. + * + * @return true if the OssDspSource is open, false otherwise. + */ inline virtual bool isOpen ( void ) const throw () { return fileDescriptor != 0; } - + /** + * Check if the OssDspSource can be read from. + * Blocks until the specified time for data to be available. + * Puts the OSS DSP device into recording mode. + * + * @param sec the maximum seconds to block. + * @param usec micro seconds to block after the full seconds. + * @return true if the OssDspSource is ready to be read from, + * false otherwise. + * @exception Exception + */ virtual bool canRead ( unsigned int sec, unsigned int usec ) throw ( Exception ); - + /** + * Read from the OssDspSource. + * Puts the OSS DSP device into recording mode. + * + * @param buf the buffer to read into. + * @param len the number of bytes to read into buf + * @return the number of bytes read (may be less than len). + * @exception Exception + */ virtual unsigned int read ( void * buf, unsigned int len ) throw ( Exception ); - + /** + * Close the OssDspSource. + * + * @exception Exception + */ virtual void close ( void ) throw ( Exception ); }; @@ -164,6 +250,9 @@ class OssDspSource : public AudioSource $Source$ $Log$ + Revision 1.3 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + Revision 1.2 2000/11/05 17:37:24 darkeye removed clone() functions diff --git a/darkice/trunk/src/PipeSource.cpp b/darkice/trunk/src/PipeSource.cpp index 0b43c04..c4af20b 100644 --- a/darkice/trunk/src/PipeSource.cpp +++ b/darkice/trunk/src/PipeSource.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. ------------------------------------------------------------------------------*/ @@ -110,6 +105,9 @@ PipeSource :: create ( void ) throw ( Exception ) $Source$ $Log$ + Revision 1.3 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + Revision 1.2 2000/11/05 14:08:28 darkeye changed builting to an automake / autoconf environment diff --git a/darkice/trunk/src/PipeSource.h b/darkice/trunk/src/PipeSource.h index 63c819c..66540ce 100644 --- a/darkice/trunk/src/PipeSource.h +++ b/darkice/trunk/src/PipeSource.h @@ -11,7 +11,6 @@ Abstract : - FIFO pipe data input Copyright notice: @@ -52,9 +51,12 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * FIFO pipe data input + * + * @author $Author$ + * @version $Revision$ + */ class PipeSource : public FileSource { private: @@ -62,6 +64,11 @@ class PipeSource : public FileSource protected: + /** + * Default constructor. Always throws an Exception. + * + * @exception Exception + */ inline PipeSource ( void ) throw ( Exception ) { @@ -71,37 +78,63 @@ class PipeSource : public FileSource public: + /** + * Constructor by a file name. + * + * @param name name of the file to be represented by the object. + * @exception Exception + */ inline PipeSource ( const char * name ) throw ( Exception ) : FileSource( name ) { } - + /** + * Copy constructor. + * + * @param ps the PipeSource to copy. + * @exception Exception + */ inline PipeSource ( const PipeSource & ps ) throw ( Exception ) : FileSource( ps ) { } - + /** + * Assignment operator. + * + * @param ps the PipeSource to assign to this object. + * @return a reference to this object. + * @exception Exception + */ inline virtual PipeSource & - operator= ( const PipeSource & fs ) throw ( Exception ) + operator= ( const PipeSource & ps ) throw ( Exception ) { - if ( this != &fs ) { - FileSource::operator=( fs ); + if ( this != &ps ) { + FileSource::operator=( ps ); } return *this; } - + /** + * Destructor. + * + * @exception Exception + */ virtual inline ~PipeSource( void ) throw ( Exception ) { } - + /** + * Create the pipe. + * + * @return true if creation was successful, false otherwise. + * @exception Exception + */ virtual bool create ( void ) throw ( Exception ); }; @@ -122,6 +155,9 @@ class PipeSource : public FileSource $Source$ $Log$ + Revision 1.3 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + Revision 1.2 2000/11/05 17:37:24 darkeye removed clone() functions diff --git a/darkice/trunk/src/Source.h b/darkice/trunk/src/Source.h index 5f95fb6..a8cac63 100644 --- a/darkice/trunk/src/Source.h +++ b/darkice/trunk/src/Source.h @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - A general data source - 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 SOURCE_H @@ -53,27 +48,46 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * A general data source + * + * @author $Author$ + * @version $Revision$ + */ class Source : public virtual Referable { private: protected: + /** + * Default Constructor. + * + * @exception Exception + */ inline Source ( void ) throw ( Exception ) { } - + /** + * Copy Constructor. + * + * @param source the object to copy. + * @exception Exception + */ inline Source ( const Source & source ) throw ( Exception ) { } - + /** + * Assignment operator. + * + * @param source the object to assign to this one. + * @return a reference to this object. + * @exception Exception + */ inline virtual Source & operator= ( const Source & source ) throw ( Exception ) { @@ -83,30 +97,64 @@ class Source : public virtual Referable public: + /** + * Destructor. + * + * @exception Exception + */ inline virtual ~Source ( void ) throw ( Exception ) { } - + /** + * Open the Source. + * + * @return true if opening was successful, false otherwise + * @exception Exception + */ virtual bool open ( void ) throw ( Exception ) = 0; - + /** + * Check if the Source is open. + * + * @return true if the Source is open, false otherwise. + */ virtual bool isOpen ( void ) const throw () = 0; - + /** + * Check if the Source can be read from. + * 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 Source is ready to be read from, + * false otherwise. + * @exception Exception + */ virtual bool canRead ( unsigned int sec, unsigned int usec ) throw ( Exception ) = 0; - + /** + * Read from the Source. + * + * @param buf the buffer to read into. + * @param len the number of bytes to read into buf + * @return the number of bytes read (may be less than len). + * @exception Exception + */ virtual unsigned int read ( void * buf, unsigned int len ) throw ( Exception ) = 0; - + /** + * Close the Source. + * + * @exception Exception + */ virtual void close ( void ) throw ( Exception ) = 0; }; @@ -127,8 +175,11 @@ class Source : public virtual Referable $Source$ $Log$ - Revision 1.1 2000/11/05 10:05:54 darkeye - Initial revision + Revision 1.2 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + + Revision 1.1.1.1 2000/11/05 10:05:54 darkeye + initial version ------------------------------------------------------------------------------*/ diff --git a/darkice/trunk/src/Util.cpp b/darkice/trunk/src/Util.cpp index 54d486e..a7550e0 100644 --- a/darkice/trunk/src/Util.cpp +++ b/darkice/trunk/src/Util.cpp @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Widely used utilities - 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. ------------------------------------------------------------------------------*/ @@ -191,6 +186,9 @@ Util :: strToL( const char * str, $Source$ $Log$ + Revision 1.5 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + Revision 1.4 2000/11/09 22:04:33 darkeye added functions strLen strCpy and strCat diff --git a/darkice/trunk/src/Util.h b/darkice/trunk/src/Util.h index d5f7e3a..0dbf7a9 100644 --- a/darkice/trunk/src/Util.h +++ b/darkice/trunk/src/Util.h @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Widely used utilities - 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 UTIL_H @@ -52,9 +47,22 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ +/** + * Widely used utilities. + * This class can not be instantiated, but contains useful (?) static + * functions. + * + * Typical usage: + * + * 
+ *  #include "Util.h"
  *  
- *----------------------------------------------------------------------------*/
+ *  char  * str = Util::strDup( otherStr);
+ *
+ * + * @author $Author$ + * @version $Revision$ + */ class Util { private: @@ -62,29 +70,47 @@ class Util protected: + /** + * Default constructor. Always throws an Exception. + * + * @exception Exception + */ inline Util ( void ) throw ( Exception ) { throw Exception( __FILE__, __LINE__); } - + /** + * Copy constructor. Always throws an Exception. + * + * @exception Exception + */ inline Util ( const Util & e ) throw ( Exception ) { throw Exception( __FILE__, __LINE__); } - + /** + * Destructor. Always throws an Exception. + * + * @exception Exception + */ inline ~Util ( void ) throw ( Exception ) { throw Exception( __FILE__, __LINE__); } - + /** + * Assignment operator. Always throws an Exception. + * + * @param u the object to assign to this one. + * @exception Exception + */ inline Util & - operator= ( const Util & e ) throw ( Exception ) + operator= ( const Util & u ) throw ( Exception ) { throw Exception( __FILE__, __LINE__); } @@ -93,29 +119,71 @@ class Util public: + /** + * Determine a C string's length. + * + * @param str a zero-terminated C string. + * @return length of str + * @exception Exception + */ static unsigned int strLen ( const char * str ) throw ( Exception ); - + /** + * Copy a C string into another. + * + * @param dest place for the copy. Storage size must be at least + * Util::strLen(src) + 1 long. + * @param str the string to copy. + * @exception Exception + */ static void strCpy ( char * dest, const char * src ) throw ( Exception ); - + /** + * Concatenate a string to another's end. + * + * @param dest the string to concatenate to. + * Storage size of dest must be at least + * Util::strLen(dest) + Util::strLen(src) + 1 long. + * @param str the string to concatenate. + * @exception Exception + */ static void strCat ( char * dest, const char * src ) throw ( Exception ); - + /** + * Duplicate a string by allocating space with new[]. + * The returned string must be freed with delete[]. + * + * @param str the string to duplicate. + * @exception Exception + */ static char * strDup ( const char * str ) throw ( Exception ); - + /** + * Determine wether two string are equal. + * + * @param str1 one of the strings. + * @param str2 the other string. + * @return true if the two strings are equal, false othersize. + * @exception Exception + */ static bool strEq ( const char * str1, const char * str2 ) throw ( Exception ); - + /** + * Convert a string to long. + * + * @param str the string to convert. + * @param base numeric base of number in str. + * @return the value of str as a long int + * @exception Exception + */ static long int strToL ( const char * str, int base = 10 ) throw ( Exception ); @@ -137,6 +205,9 @@ class Util $Source$ $Log$ + Revision 1.4 2000/11/12 13:31:40 darkeye + added kdoc-style documentation comments + Revision 1.3 2000/11/09 22:04:33 darkeye added functions strLen strCpy and strCat