From ace84836f36a7c0daef3b4101dc57a54c64f27ec Mon Sep 17 00:00:00 2001 From: darkeye Date: Mon, 13 Nov 2000 18:46:50 +0000 Subject: [PATCH] added kdoc-style documentation comments --- darkice/trunk/src/Config.cpp | 41 +++---- darkice/trunk/src/Config.h | 140 ++++++++++++++++------- darkice/trunk/src/ConfigSection.cpp | 41 +++---- darkice/trunk/src/ConfigSection.h | 120 ++++++++++++++------ darkice/trunk/src/Connector.cpp | 38 +++---- darkice/trunk/src/Connector.h | 170 ++++++++++++++++++++++------ darkice/trunk/src/DarkIce.cpp | 33 +++--- darkice/trunk/src/DarkIce.h | 120 +++++++++++++++----- 8 files changed, 471 insertions(+), 232 deletions(-) diff --git a/darkice/trunk/src/Config.cpp b/darkice/trunk/src/Config.cpp index c942149..2f89e31 100644 --- a/darkice/trunk/src/Config.cpp +++ b/darkice/trunk/src/Config.cpp @@ -9,33 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - A configuration file representation. The file is of the syntax: - - # this is a whole line comment - key = value - an ugly key name = long value # this end is a comment too - - also empty lines are ignored and all white space is removed - from the front and end of keys / values - 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. ------------------------------------------------------------------------------*/ @@ -172,6 +160,9 @@ Config :: read ( istream & is ) throw ( Exception ) $Source$ $Log$ + Revision 1.2 2000/11/13 18:46:50 darkeye + added kdoc-style documentation comments + Revision 1.1 2000/11/08 17:29:50 darkeye added configuration file reader diff --git a/darkice/trunk/src/Config.h b/darkice/trunk/src/Config.h index 0ac1c27..f13740a 100644 --- a/darkice/trunk/src/Config.h +++ b/darkice/trunk/src/Config.h @@ -9,40 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - A configuration file representation. The file is of the syntax: - - [section1] - # this is a whole line comment - key = value - an ugly key name = long value # this end is a comment too - - [section2] - # this is a whole line comment in section 2 - key = value - an ugly key name = long value # this end is a comment too - - - also empty lines are ignored and all white space is removed - from the front and end of keys / values - 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 CONFIG_H @@ -72,17 +53,50 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * A configuration file representation. The file is of the syntax: + * + * 
+ *  [section1]
+ *  # this is a whole line comment
+ *  key = value
+ *  an ugly key name = long value    # this end is a comment too
+ *
+ *  [section2]
+ *  # this is a whole line comment in section 2
+ *  key = value
+ *  an ugly key name = long value    # this end is a comment too
+ *
+ * + * also empty lines are ignored and all white space is removed + * from the front and end of keys / values + * + * Knwon problem: you can't use '#' in any part of a key / value pair + * + * @author $Author$ + * @version $Revision$ + */ class Config : public virtual Referable { private: + /** + * Type declaration of the hash table type. + */ typedef hash_map TableType; + + /** + * Hash table holding the configuration sections. + * + * @see ConfigSection + */ TableType table; - + /** + * Hash table holding the configuration sections. + * + * @see ConfigSection + */ string currentSection; @@ -91,26 +105,41 @@ class Config : public virtual Referable public: + /** + * Default constructor. + * + * @exception Exception + */ inline Config ( void ) throw ( Exception ) { } - + /** + * Constructor based on an input stream. + * + * @param is configuration will be read from this input stream + * until end of stream is reached. + * @exception Exception + */ inline Config ( istream & is ) throw ( Exception ) { read( is ); } - + /** + * Destructor. + * + * @exception Exception + */ inline virtual ~Config ( void ) throw ( Exception ) { } -/* +/* TODO inline Config ( const Config & di ) throw ( Exception ) @@ -124,6 +153,12 @@ class Config : public virtual Referable } */ + /** + * Delete the configuration information stored in the object. + * Resets the object to a clean state. + * + * @exception Exception + */ inline virtual void reset ( void ) throw ( Exception ) { @@ -131,15 +166,33 @@ class Config : public virtual Referable currentSection = ""; } - + /** + * Read a line of confiugration information. + * + * @param line the line to read. + * @return true if the line was correct, false otherwise. + * @exception Exception + */ virtual bool addLine ( const char * line ) throw ( Exception ); - + /** + * Read a line of confiugration information. + * + * @param line the line to read. + * @return true if the line was correct, false otherwise. + * @exception Exception + */ virtual void read ( istream & is ) throw ( Exception ); - + /** + * Get a ConfigSection by name. + * + * @param key the name of the ConfigSection + * @return the ConfigSection requested, or NULL if it doesn't exists. + * @exception Exception + */ virtual const ConfigSection * get ( const char * key ) const throw ( Exception ); }; @@ -160,6 +213,9 @@ class Config : public virtual Referable $Source$ $Log$ + Revision 1.3 2000/11/13 18:46:50 darkeye + added kdoc-style documentation comments + Revision 1.2 2000/11/09 22:07:19 darkeye added constructor with istream diff --git a/darkice/trunk/src/ConfigSection.cpp b/darkice/trunk/src/ConfigSection.cpp index 9ed0b3c..4ac69c9 100644 --- a/darkice/trunk/src/ConfigSection.cpp +++ b/darkice/trunk/src/ConfigSection.cpp @@ -9,33 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - A configuration file representation. The file is of the syntax: - - # this is a whole line comment - key = value - an ugly key name = long value # this end is a comment too - - also empty lines are ignored and all white space is removed - from the front and end of keys / values - 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. ------------------------------------------------------------------------------*/ @@ -180,6 +168,9 @@ ConfigSection :: addLine ( const char * line ) throw ( Exception ) $Source$ $Log$ + Revision 1.3 2000/11/13 18:46:50 darkeye + added kdoc-style documentation comments + Revision 1.2 2000/11/09 22:08:17 darkeye added function getForSure diff --git a/darkice/trunk/src/ConfigSection.h b/darkice/trunk/src/ConfigSection.h index 23b2827..da553e8 100644 --- a/darkice/trunk/src/ConfigSection.h +++ b/darkice/trunk/src/ConfigSection.h @@ -9,33 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - A configuration file representation. The file is of the syntax: - - # this is a whole line comment - key = value - an ugly key name = long value # this end is a comment too - - also empty lines are ignored and all white space is removed - from the front and end of keys / values - 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 CONFIG_SECTION_H @@ -62,39 +50,65 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * A configuration file representation. The file is of the syntax: + * + * 
+ *  # this is a whole line comment
+ *  key = value
+ *  an ugly key name = long value    # this end is a comment too
+ *
+ * + * also empty lines are ignored and all white space is removed + * from the front and end of keys / values + * + * Knwon problem: you can't use '#' in any part of a key / value pair + * + * @author $Author$ + * @version $Revision$ + */ class ConfigSection : public virtual Referable { private: + /** + * Type of the hash table used in this class. + */ typedef hash_map TableType; + + /** + * Hash table holding the configuration information. + */ TableType table; - void - init ( void ) throw ( Exception ); - - protected: public: + /** + * Default constructor. + * + * @exception Exception + */ inline ConfigSection ( void ) throw ( Exception ) { } - + /** + * Destructor. + * + * @exception Exception + */ inline virtual ~ConfigSection ( void ) throw ( Exception ) { } -/* +/* TODO inline ConfigSection ( const ConfigSection & di ) throw ( Exception ) @@ -108,15 +122,38 @@ class ConfigSection : public virtual Referable } */ + /** + * Add a key / value pair to the configuration information. + * + * @param key the key to add the value by + * @param value the value to add for the key + * @return true if adding was successful, false otherwise + * @exception Exception + */ virtual bool add ( const char * key, const char * value ) throw ( Exception ); - + /** + * Get a value for a key. + * + * @param key the key to get the value for + * @return the value for the key, or NULL if the key doesn't exist. + * @exception Exception + */ virtual const char * get ( const char * key ) const throw ( Exception ); - + /** + * Get a value for a key, or throw an Exception. + * + * @param key the key to get the value for + * @param message1 message part 1 of the Exception to be thrown. + * @param message2 message part 2 of the Exception to be thrown. + * @param code error code of the Exception to be thrown. + * @return the value for the key. The return value is never NULL. + * @exception Exception + */ virtual const char * getForSure ( const char * key, const char * message1 = 0, @@ -124,7 +161,13 @@ class ConfigSection : public virtual Referable int code = 0 ) const throw ( Exception ); - + /** + * Add a line of configuration information. + * + * @param line the line to add. + * @return true if a new key was added, false otherwise. + * @exception Exception + */ virtual bool addLine ( const char * line ) throw ( Exception ); }; @@ -145,6 +188,9 @@ class ConfigSection : public virtual Referable $Source$ $Log$ + Revision 1.3 2000/11/13 18:46:50 darkeye + added kdoc-style documentation comments + Revision 1.2 2000/11/09 22:08:17 darkeye added function getForSure diff --git a/darkice/trunk/src/Connector.cpp b/darkice/trunk/src/Connector.cpp index efca964..4391a8b 100644 --- a/darkice/trunk/src/Connector.cpp +++ b/darkice/trunk/src/Connector.cpp @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Connects a source to a 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. ------------------------------------------------------------------------------*/ @@ -333,8 +328,11 @@ Connector :: close ( void ) throw ( Exception ) $Source$ $Log$ - Revision 1.1 2000/11/05 10:05:49 darkeye - Initial revision + Revision 1.2 2000/11/13 18:46:50 darkeye + added kdoc-style documentation comments + + Revision 1.1.1.1 2000/11/05 10:05:49 darkeye + initial version ------------------------------------------------------------------------------*/ diff --git a/darkice/trunk/src/Connector.h b/darkice/trunk/src/Connector.h index 957fa49..cfc310b 100644 --- a/darkice/trunk/src/Connector.h +++ b/darkice/trunk/src/Connector.h @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Connects a source to a 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 CONNECTOR_H @@ -55,30 +50,56 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * Connects a source to one or more sinks. + * + * @author $Author$ + * @version $Revision$ + */ class Connector : public virtual Referable { private: + /** + * The source to read from. + */ Ref source; - + /** + * The sinks to connect the source to. + */ Ref * sinks; + + /** + * Total number of sinks. + */ unsigned int numSinks; - + /** + * Initialize the object. + * + * @param source the source to read from. + * @exception Exception + */ void init ( Source * source ) throw ( Exception ); - + /** + * De-initialize the object. + * + * @exception Exception + */ void strip ( void ) throw ( Exception ); protected: + /** + * Default constructor. Always throws an Exception. + * + * @exception Exception + */ inline Connector ( void ) throw ( Exception ) { @@ -88,13 +109,25 @@ class Connector : public virtual Referable public: + /** + * Constructor based on a Source. + * + * @param source the source to connect to the sinks. + * @exception Exception + */ inline Connector ( Source * source ) throw ( Exception ) { init( source); } - + /** + * Constructor based on a Source and a Sink. + * + * @param source the source to connect to the sinks. + * @param sink a sink to connect to the source. + * @exception Exception + */ inline Connector ( Source * source, Sink * sink ) throw ( Exception ) @@ -103,47 +136,107 @@ class Connector : public virtual Referable attach( sink); } - + /** + * Copy constructor. + * + * @param connector the object to copy. + * @exception Exception + */ Connector ( const Connector & connector ) throw ( Exception ); - + /** + * Destructor. + * + * @exception Exception + */ inline virtual - ~Connector( void ) + ~Connector( void ) throw ( Exception ) { strip(); } - + /** + * Assignment operator. + * + * @param connector the object to assign to this one. + * @return a reference to this object. + * @exception Exception + */ virtual Connector & operator= ( const Connector & connector ) throw ( Exception ); - + /** + * Get the number of Sinks in the Connector. + * + * @return the number of Sinks in the Connector. + * @exception Exception + */ inline unsigned int getNumSinks ( void ) const throw () { return numSinks; } - + /** + * Attach a Sink to the Source of this Connector. + * + * @param sink the Sink to attach. + * @exception Exception + */ void attach ( Sink * sink ) throw ( Exception ); - + /** + * Detach an already attached Sink from the Source of this Connector. + * + * @param sink the Sink to detach. + * @return true if the detachment was successful, false otherwise. + * @exception Exception + */ bool detach ( Sink * sink ) throw ( Exception ); - + /** + * Open the connector. Opens the Source and the Sinks if necessary. + * + * @return true if opening was successful, false otherwise. + * @exception Exception + */ bool open ( void ) throw ( Exception ); - + /** + * Transfer a given amount of data from the Source to all the + * Sinks attached. + * If an attached Sink closes or encounteres an error during the + * process, it is detached and the function carries on with the + * rest of the Sinks. If no Sinks remain, or an error is encountered + * with the Source, the function returns prematurely. + * + * @param bytes the amount of data to transfer, in bytes + * @param bufSize the size of the buffer to use for transfering. + * This amount of data is read from the Source and + * written to each Sink on each turn. + * @param sec the number of seconds to wait for the Source to have + * data available in each turn, and the number of seconds + * to wait for the Sinks to accept data. + * @param usec the number of micros seconds to wait for the Source to + * have data available in each turn, and the number of + * micro seconds to wait for the Sinks to accept data. + * @return the number of bytes read from the Source. + * @exception Exception + */ unsigned int transfer ( unsigned int bytes, unsigned int bufSize, unsigned int sec, unsigned int usec ) throw ( Exception ); - + /** + * Close the Connector. The Source and all Sinks are closed. + * + * @exception Exception + */ void close ( void ) throw ( Exception ); }; @@ -164,8 +257,11 @@ class Connector : public virtual Referable $Source$ $Log$ - Revision 1.1 2000/11/05 10:05:49 darkeye - Initial revision + Revision 1.2 2000/11/13 18:46:50 darkeye + added kdoc-style documentation comments + + Revision 1.1.1.1 2000/11/05 10:05:49 darkeye + initial version ------------------------------------------------------------------------------*/ diff --git a/darkice/trunk/src/DarkIce.cpp b/darkice/trunk/src/DarkIce.cpp index e0ebc87..7082372 100644 --- a/darkice/trunk/src/DarkIce.cpp +++ b/darkice/trunk/src/DarkIce.cpp @@ -9,26 +9,22 @@ Author : $Author$ Location : $Source$ - Abstract : - - Program main object 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. ------------------------------------------------------------------------------*/ @@ -432,6 +428,9 @@ DarkIce :: run ( void ) throw ( Exception ) $Source$ $Log$ + Revision 1.6 2000/11/13 18:46:50 darkeye + added kdoc-style documentation comments + Revision 1.5 2000/11/10 20:16:21 darkeye first real tests with multiple streaming diff --git a/darkice/trunk/src/DarkIce.h b/darkice/trunk/src/DarkIce.h index 05e8248..3b94266 100644 --- a/darkice/trunk/src/DarkIce.h +++ b/darkice/trunk/src/DarkIce.h @@ -9,26 +9,21 @@ Author : $Author$ Location : $Source$ - Abstract : - - Program main object - 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 DARK_ICE_H @@ -75,15 +70,24 @@ /* =============================================================== data types */ -/*------------------------------------------------------------------------------ - * - *----------------------------------------------------------------------------*/ +/** + * Program main object. + * + * @author $Author$ + * @version $Revision$ + */ class DarkIce : public virtual Referable { private: + /** + * The maximum number of supported outputs. + */ static const unsigned int maxOutput = 8; + /** + * Type describing each output. + */ typedef struct { Ref encInPipe; Ref encIn; @@ -95,23 +99,58 @@ class DarkIce : public virtual Referable pid_t pid; } Output; - + /** + * Duration of playing, in seconds. + */ unsigned int duration; + + /** + * The dsp to record from. + */ Ref dsp; + + /** + * The encoding Connector, connecting the dsp to the encoders. + */ Ref encConnector; + /** + * The outputs. + */ Output outputs[maxOutput]; + + /** + * Number of outputs. + */ unsigned int noOutputs; - + /** + * Initialize the object. + * + * @param config the config Object to read initialization + * information from. + * @exception Exception + */ void init ( const Config & config ) throw ( Exception ); - + /** + * Start encoding. Spawns all encoders, opens the dsp and + * starts sending data to the encoders. + * + * @return if encoding was successful. + * @exception Exception + */ bool encode ( void ) throw ( Exception ); - + /** + * Start shouting. fork()-s a process for each output, reads + * the output of the encoders and sends them to an IceCast server. + * + * @return if shouting was successful. + * @exception Exception + */ bool shout ( unsigned int ) throw ( Exception ); @@ -124,23 +163,37 @@ class DarkIce : public virtual Referable public: + /** + * Default constructor. + * + * @exception Exception + */ inline DarkIce ( void ) throw ( Exception ) { } - + /** + * Constructor based on command line parameters. + * + * @param argc number of arguments + * @param argv the command line arguments. + * @exception Exception + */ DarkIce ( int argc, char * argv[] ) throw ( Exception ); - + /** + * Destructor. + * + * @exception Exception + */ inline virtual ~DarkIce ( void ) throw ( Exception ) { } - -/* +/* TODO inline DarkIce ( const DarkIce & di ) throw ( Exception ) @@ -154,6 +207,12 @@ class DarkIce : public virtual Referable } */ + /** + * Run the process of recording / encoding / sending to the servers. + * + * @return 0 on success + * @exception Exception + */ virtual int run ( void ) throw ( Exception ); @@ -175,6 +234,9 @@ class DarkIce : public virtual Referable $Source$ $Log$ + Revision 1.4 2000/11/13 18:46:50 darkeye + added kdoc-style documentation comments + Revision 1.3 2000/11/10 20:16:21 darkeye first real tests with multiple streaming