added doxygen class documentation

beginning of the sems documentation initiative...


git-svn-id: http://svn.berlios.de/svnroot/repos/sems/trunk@83 8eb893ce-cfd4-0310-b710-fb5ebe64c474

core/AmAdvancedAudio.h

@@ -36,6 +36,9 @@
 using namespace std;
 #include "SampleArray.h"
 
+/**
+ * \brief Entry in an AudioQueue
+ */
 struct AudioQueueEntry {
     AmAudio* audio;
     bool put;
@@ -45,8 +48,9 @@ struct AudioQueueEntry {
 };
 
 /**
- * AmAudioQueue can hold AmAudios in input and output queue.
+ * \brief Holds AmAudios and reads/writes through all
  * 
+ * AmAudioQueue can hold AmAudios in input and output queue.
  * Audio will be read through the whole output queue,
  * and written through the whole input queue.
  */

core/AmApi.h

@@ -38,11 +38,12 @@ using std::map;
 using std::string;
 
 /**
- * Multi-purpose plugin class
+ * \brief interface of the DynInvoke API
  */
 class AmDynInvoke
 {
 public:
+    /** \brief NotImplemented result for DI API calls */
     struct NotImplemented {
 	string what;
 	NotImplemented(const string& w)
@@ -55,7 +56,7 @@ public:
 };
 
 /**
- * Base class for plugin factories
+ * \brief Base interface for plugin factories
  */
 class AmPluginFactory
 {
@@ -79,7 +80,10 @@ public:
 };
 
 /**
- * Factory for multi-purpose plugin classes
+ * \brief Interface of factory for plugins that provide a DI API
+ * 
+ * Factory for multi-purpose plugin classes,
+ * classes that provide a DynInvoke (DI) API
  */
 class AmDynInvokeFactory: public AmPluginFactory
 {
@@ -91,7 +95,9 @@ public:
 
 class AmSession;
 class AmSessionEventHandler;
-
+/**
+ * \brief Interface for PluginFactories that can handle events in sessions
+ */
 class AmSessionEventHandlerFactory: public AmPluginFactory
 {
 public:
@@ -105,7 +111,7 @@ public:
     virtual bool onInvite(const AmSipRequest& req)=0;
 };
 
-
+/** \brief Interface for plugins to create sessions */
 class AmSessionFactory: public AmPluginFactory
 {
 

core/AmArg.h

@@ -6,6 +6,7 @@
 #include <vector>
 using std::vector;
 
+/** \brief variable type argument for DynInvoke APIs */
 class AmArg
 {
 public:
@@ -64,6 +65,7 @@ public:
     const char* asCStr()   const { return v_cstr; }
 };
 
+/** \brief array of variable args for DI APIs*/
 class AmArgArray
 {
     vector<AmArg> v;

core/AmAudio.h

@@ -42,6 +42,7 @@ using std::string;
 #define PCM16_B2S(b) ((b) >> 1)
 #define PCM16_S2B(s) ((s) << 1)
 
+/** \brief Audio Event */
 class AmAudioEvent: public AmEvent
 {
 public:
@@ -88,7 +89,7 @@ struct amci_subtype_t;
 class AmAudio;
 
 /**
- * Audio format structure.
+ * \brief Audio format structure.
  * Holds a description of the format.
  * @todo Create two child class:
  * <ul>
@@ -146,6 +147,7 @@ private:
     void operator = (const AmAudioFormat& r);
 };
 
+/** \brief simple audio format */
 class AmAudioSimpleFormat: public AmAudioFormat
 {
     int codec_id;
@@ -157,6 +159,7 @@ public:
     AmAudioSimpleFormat(int codec_id);
 };
 
+/** \brief file audio format */
 class AmAudioFileFormat: public AmAudioFormat
 {
     /** == "" if not yet initialized. */
@@ -203,6 +206,7 @@ public:
     }
 };
 
+/** \brief RTP audio format */
 class AmAudioRtpFormat: public AmAudioFormat
 {
   /** ==-1 if not yet initialized. */
@@ -326,7 +330,9 @@ public:
     int  incRecordTime(unsigned int samples);
 };
 
-
+/**
+ * \brief AmAudio implementation for file access
+ */
 class AmAudioFile: public AmAudio
 {
 public:

core/AmB2BSession.h

@@ -10,6 +10,7 @@ enum { B2BTerminateLeg,
        B2BSipRequest, 
        B2BSipReply };
 
+/** \brief base class for event in B2B session */
 struct B2BEvent: public AmEvent
 {
     B2BEvent(int ev_id) 
@@ -17,6 +18,7 @@ struct B2BEvent: public AmEvent
     {}
 };
 
+/** \brief base class for SIP event in B2B session */
 struct B2BSipEvent: public B2BEvent
 {
     bool forward;
@@ -27,6 +29,7 @@ struct B2BSipEvent: public B2BEvent
     {}
 };
 
+/** \brief SIP request in B2B session */
 struct B2BSipRequestEvent: public B2BSipEvent
 {
     AmSipRequest req;
@@ -37,6 +40,7 @@ struct B2BSipRequestEvent: public B2BSipEvent
     {}
 };
 
+/** \brief SIP reply in B2B session */
 struct B2BSipReplyEvent: public B2BSipEvent
 {
     AmSipReply reply;
@@ -47,6 +51,7 @@ struct B2BSipReplyEvent: public B2BSipEvent
     {}
 };
 
+/** \brief trigger connecting the callee leg in B2B session */
 struct B2BConnectEvent: public B2BEvent
 {
     string remote_party;
@@ -64,6 +69,11 @@ struct B2BConnectEvent: public B2BEvent
     {}
 };
 
+/**
+ * \brief Base class for Sessions in B2BUA mode.
+ * 
+ * It has two legs: Callee- and caller-leg.
+ */
 class AmB2BSession: public AmSession
 {
 protected:
@@ -125,6 +135,7 @@ protected:
 
 class AmB2BCalleeSession;
 
+/** \brief Caller leg of a B2B session */
 class AmB2BCallerSession: public AmB2BSession
 {
 public:
@@ -167,6 +178,7 @@ public:
     void set_sip_relay_only(bool r) { sip_relay_only = r; }
 };
 
+/** \brief Callee leg of a B2B session */
 class AmB2BCalleeSession: public AmB2BSession
 {
 public:

core/AmConferenceChannel.h

@@ -4,6 +4,12 @@
 #include "AmAudio.h"
 #include "AmConferenceStatus.h"
 
+/** 
+ * \brief one channel of a conference
+ * 
+ * A ConferenceChannel is one channel, i.e. to/from one 
+ * participant, in a conference. 
+ */
 class AmConferenceChannel: public AmAudio
 {
     bool                own_channel;
@@ -30,6 +36,4 @@ public:
     string getConfID() { return conf_id; }
 };
 
-
-
 #endif

core/AmConferenceStatus.h

@@ -43,6 +43,7 @@ class AmConferenceChannel;
 enum { ConfNewParticipant = 1,
        ConfParticipantLeft };
 
+/** \brief event in a conference*/
 struct ConferenceEvent: public AmEvent
 {
     unsigned int participants;
@@ -57,7 +58,11 @@ struct ConferenceEvent: public AmEvent
     {}
 };
 
-
+/**
+ * \brief One conference (room).
+ * 
+ * The ConferenceStatus manages one conference.
+ */
 class AmConferenceStatus
 {
     static map<string,AmConferenceStatus*> cid2status;

core/AmConfig.h

@@ -101,7 +101,7 @@ struct AmConfig
 };
 
 class AmConfigReader;
-
+/** \brief config for the session timer */
 class AmSessionTimerConfig {
   /** Session Timer: enable? */
   int EnableSessionTimer;

core/AmConfigReader.h

@@ -8,6 +8,13 @@ using std::map;
 
 
 #define MAX_CONFIG_LINE 512
+/**
+ * \brief configuration file reader
+ * 
+ * Reads configuration file into internal map, 
+ * which subsequently can be queried for the value of
+ * specific configuration values.
+ */
 
 class AmConfigReader
 {

core/AmCtrlInterface.h

@@ -49,6 +49,12 @@ public:
     virtual ~AmCtrlUserData(){}
 };
 
+/**
+ * \brief Base class for the control interfaces.
+ * 
+ * The AmCtrlInterface defines the interface for 
+ * SER-SEMS communication interface (unix socket/fifo). 
+ */
 
 class AmCtrlInterface
 {
@@ -117,7 +123,7 @@ public:
     virtual void close();
 };
 
-
+/** \brief control interface through FIFO */
 class AmFifoCtrlInterface: public AmCtrlInterface
 {
     FILE*  fp_fifo;
@@ -144,6 +150,7 @@ public:
 
 };
 
+/** \brief UNIX socket control interface  */
 class AmUnixCtrlInterface: public AmCtrlInterface
 {
     char   msg_buf[CTRL_MSGBUF_SIZE];

core/AmDtmfDetector.h

@@ -329,6 +329,10 @@ public:
     void putDtmfAudio(const unsigned char *, int size, int user_ts);
 };
 
+/** 
+ * \brief DTMF Event handler (aggregated output)
+ * posts DTMF events to session
+ */
 class AmDtmfHandler : public AmEventHandler
 {
 private:

core/AmEvent.h

@@ -8,6 +8,7 @@ using std::string;
 
 #define E_PLUGIN 100
 
+/** \brief base event class */
 struct AmEvent
 {
     int event_id;
@@ -17,6 +18,11 @@ struct AmEvent
     virtual ~AmEvent();
 };
 
+/** 
+ * \brief named event for inter-plugin-API 
+ *
+ * Optionally the AmPluginEvent also holds a dynamic argument array.
+ */
 struct AmPluginEvent: public AmEvent
 {
     string      name;
@@ -30,7 +36,7 @@ struct AmPluginEvent: public AmEvent
 };
 
 
-
+/** \brief event handler interface */
 class AmEventHandler
 {
 public:

core/AmEventQueue.h

@@ -33,6 +33,14 @@
 #include <queue>
 using std::queue;
 
+/** 
+ * \brief Asynchronous event queue implementation 
+ * 
+ * This class implements an event queue; a queue into which
+ * \ref AmEvent can safely be posted at any time from any 
+ * thread, which are then processed by the registered event
+ *  handler.
+ */
 class AmEventQueue
 {
 protected:

core/AmIcmpWatcher.h

@@ -10,6 +10,7 @@ using std::map;
 
 class AmRtpStream;
 
+/** \brief thread that watches ICMP reports  */
 class AmIcmpWatcher: public AmThread
 {
     static AmIcmpWatcher* _instance;
@@ -36,6 +37,7 @@ public:
     void removeStream(int localport);
 };
 
+/** \brief one-shot thread: report an ICMP error to the rtp stream */
 class IcmpReporter: public AmThread
 {
     AmRtpStream* rtp_str;

core/AmInterfaceHandler.h

@@ -11,7 +11,7 @@ using std::string;
 using std::map;
 
 class AmCtrlInterface;
-
+/** \brief interface of an InterfaceHandler */
 class AmInterfaceHandler
 {
 public:
@@ -24,7 +24,9 @@ public:
 };
 
 /**
- * Derive your class from AmServerFct if you want
+ * \brief interface of a Server function
+ *
+ * Derive your class from this if you want
  * to implement a request handler.
  */
 class AmRequestHandlerFct
@@ -34,6 +36,11 @@ public:
     virtual ~AmRequestHandlerFct(){}
 };
 
+/**
+ * \brief SIP request handler
+ *
+ * Handles SIP requests that are received by the Server
+ */
 class AmRequestHandler: public AmInterfaceHandler, 
 			public AmRequestHandlerFct
 {
@@ -51,6 +58,11 @@ public:
     void registerFct(const string& name, AmRequestHandlerFct* fct);
 };
 
+/**
+ * \brief SIP reply handler
+ *
+ * Handles SIP replys that are received by the Server
+ */
 class AmReplyHandler: public AmInterfaceHandler
 {
     static AmReplyHandler* _instance;

core/AmMultiPartyMixer.h

@@ -41,6 +41,12 @@
 #include <map>
 using std::map;
 
+/**
+ * \brief Mixer for one conference.
+ * 
+ * AmMultiPartyMixer mixes the audio from all channels,
+ * and returns the audio of all other channels. 
+ */
 class AmMultiPartyMixer
 {
     typedef map<int,SampleArrayShort*> ChannelMap;

core/AmPlaylist.h

@@ -7,7 +7,7 @@
 
 #include <deque>
 using std::deque;
-
+/** \brief entry in an \ref AmPlaylist */
 struct AmPlaylistItem
 {
 
@@ -19,7 +19,14 @@ struct AmPlaylistItem
 	: play(play), record(record) {}
 };
 
-
+/**
+ * \brief AmAudio component that plays entries serially 
+ * 
+ * This class can be plugged to the Input or Output of a 
+ * session. Entries can be added or removed from the playlist,
+ * and the current entry is played until it is finished,
+ * then the next entry is played.
+ */
 class AmPlaylist: public AmAudio
 {
     

core/AmPlayoutBuffer.cpp

@@ -270,7 +270,7 @@ short* find_best_corr(short *ts, short *sr_beg,short* sr_end)
     return best_sr;
 }
 
-unsigned int AmAdaptivePlayout::time_scale(unsigned int ts, float factor)
+u_int32_t AmAdaptivePlayout::time_scale(u_int32_t ts, float factor)
 {
     short p_buf[PACKET_SAMPLES*4];
     short merge_buf[TEMPLATE_SEG];

core/AmPlayoutBuffer.h

@@ -17,6 +17,7 @@ using std::multiset;
 #define WSOLA_START_OFF  80
 #define WSOLA_SCALED_WIN 50
 
+/** \brief base class for Playout buffer */
 class AmPlayoutBuffer
 {
     // Playout buffer
@@ -37,6 +38,7 @@ public:
     virtual u_int32_t read(u_int32_t ts, int16_t* buf, u_int32_t len);
 };
 
+/** \brief adaptive playout buffer */
 class AmAdaptivePlayout: public AmPlayoutBuffer
 {
     // Order statistics delay estimation

core/AmRtpAudio.h

@@ -37,6 +37,10 @@
 // Note: plc result get stored in our back buffer
 #define PLC_MAX_SAMPLES (160*4) 
 
+/** 
+ * \brief binds together a \ref AmRtpStream and an \ref AmAudio for a session 
+ */
+
 class AmRtpAudio: public AmRtpStream, public AmAudio
 {
     auto_ptr<AmPlayoutBuffer> playout_buffer;

core/AmRtpPacket.h

@@ -33,6 +33,7 @@
 
 class AmRtpPacketTracer;
 
+/** RTP packet implementation */
 class AmRtpPacket {
 
     unsigned char  buffer[4096];

core/AmRtpReceiver.h

@@ -38,6 +38,12 @@ using std::greater;
 
 class AmRtpStream;
 
+/**
+ * \brief receiver for RTP for all streams
+ * The RtpReceiver receives RTP packets for all streams 
+ * that are registered to it. It places the received packets in 
+ * the stream's buffer. 
+ */
 class AmRtpReceiver: public AmThread {
 
     typedef map<int, AmRtpStream*, greater<int> > Streams;

core/AmRtpStream.h

@@ -235,7 +235,7 @@ public:
      */
     void bufferPacket(const AmRtpPacket* p);
 };
-
+/** \brief represents info about an \ref AmRtpStream */
 struct AmRtpStreamInfo
 {
     enum StreamType { 

core/AmSdp.h

@@ -76,7 +76,10 @@ struct SdpOrigin
     unsigned int sessV;
     SdpConnection conn;
 };
-
+/** 
+ * \brief sdp payload
+ * this binds together pt, name, rate and parameters
+ */
 struct SdpPayload
 {
     int    int_pt; // internal payload type

core/AmServer.h

@@ -64,7 +64,12 @@ struct IfaceDesc
     {}
 };
 
-
+/**
+ * \brief singleton, serve requests from ctrl interface
+ *
+ * The Server polls requests from the control interface and feeds 
+ * them to registered handlers.
+ */
 class AmServer
 {
  private:

core/AmSession.h

@@ -52,6 +52,11 @@ using std::pair;
 class AmSessionFactory;
 class AmDtmfEvent;
 
+/** 
+ * \brief DTMF Event in Session 
+ * This is a DTMF event that should be processed 
+ * by the Session.
+ */
 class AmSessionDtmfEvent : public AmEvent {
   int duration_msec;
 public:
@@ -100,15 +105,14 @@ public:
 
 
 /**
- * The session class.
- * It implements the behavior.
+ * \brief Implements the behavior of one session
+ * 
  * The session is identified by Call-ID, From-Tag and To-Tag.
  */
 class AmSession : public AmThread,
 		  public AmEventQueue, 
 		  public AmEventHandler,
 		  public AmSipDialogEventHandler
-// 		  public AmDialogState
 {
     AmMutex      audio_mut;
     AmAudio*     input;
@@ -149,6 +153,11 @@ protected:
 public:
     AmSipDialog         dlg;
 
+    /** 
+     * \brief Exception occured in a Session
+     * 
+     * Session (creation) should be aborted and replied with code/reason.
+     */
     struct Exception {
 	int code;
 	string reason;

core/AmSessionScheduler.cpp

@@ -32,6 +32,7 @@
 #include <sys/time.h>
 #include <signal.h>
 
+/** \brief Request event to the SessionScheduler (remove,...) */
 struct SchedRequest :
     public AmEvent
 {

core/AmSessionScheduler.h

@@ -39,6 +39,13 @@ using std::multimap;
 
 struct SchedRequest;
 
+/**
+ * \brief Media processing thread
+ * 
+ * This class implements a media processing thread.
+ * It processes the media and triggers the sending of RTP
+ * of all sessions added to it.
+ */
 class AmSessionSchedulerThread :
   public AmThread,
   public AmEventHandler
@@ -68,10 +75,15 @@ public:
   unsigned int getLoad();
 };
 
+/**
+ * \brief Media processing thread manager
+ * 
+ * This class implements the manager that assigns and removes 
+ * the Sessions to the various \ref SessionSchedulerThreads, 
+ * according to their call group. This class contains the API 
+ * for the SessionScheduler.
+ */
 class AmSessionScheduler
-/*: 
-    public AmThread,
-    public AmEventHandler */
 {
   static AmSessionScheduler* _instance;
 

core/AmSipDialog.h

@@ -13,7 +13,7 @@ using std::map;
 
 #define CONTACT_USER_PREFIX "sems"
 
-
+/** \brief SIP transaction representation */
 struct AmSipTransaction
 {
     string       method;
@@ -34,6 +34,9 @@ struct AmSipTransaction
 
 typedef map<int,AmSipTransaction> TransMap;
 
+/**
+ * \brief base class for SIP request/reply event handler 
+ */
 class AmSipDialogEventHandler 
 {
 public:
@@ -52,7 +55,9 @@ public:
     virtual ~AmSipDialogEventHandler() {};
 };
 
-
+/**
+ * \brief implements the dialog state machine
+ */
 class AmSipDialog
 {
     int status;

core/AmSipEvent.h

@@ -5,6 +5,7 @@
 #include "AmSipReply.h"
 #include "AmSipRequest.h"
 
+/** \brief SIP event */
 class AmSipEvent: public AmEvent
 {
 public:
@@ -13,6 +14,7 @@ public:
     {}
 };
 
+/** \brief SIP request event */
 class AmSipRequestEvent: public AmSipEvent
 {
 public:
@@ -23,6 +25,7 @@ public:
     {}
 };
 
+/** \brief SIP reply event */
 class AmSipReplyEvent: public AmSipEvent
 {
 public:

core/AmSipReply.h

@@ -7,7 +7,7 @@
 #include <string>
 using std::string;
 
-
+/** \brief represents a SIP reply */
 struct AmSipReply
 {
     unsigned int code;

core/AmSipRequest.h

@@ -6,7 +6,7 @@
 #include <string>
 using std::string;
 
-
+/** \brief represents a SIP request */
 class AmSipRequest
 {
 public:

core/AmStats.h

@@ -4,6 +4,11 @@
 #include <sys/types.h>
 #include <math.h>
 
+/** 
+ * \brief math mean implementation 
+ *
+ * The mean of all previously stored values is calculated (no reset).
+ */
 class MeanValue
 {
 protected:
@@ -27,6 +32,12 @@ public:
     }
 };
 
+/** 
+ * \brief math stddev implementation 
+ *
+ * The standard deviation of previously stored 
+ * values is calculated.
+ */
 class StddevValue
 {
  protected:
@@ -54,6 +65,11 @@ class StddevValue
     }
 };
 
+/** 
+ * \brief math mean implementation (n values)
+ *
+ * The mean of n previously stored values is calculated
+ */
 class MeanArray: public MeanValue
 {
     double *buffer;

core/AmUAC.h

@@ -34,6 +34,7 @@
 #include <string>
 using std::string; 
 
+/** \brief API for UAC support */
 class AmUAC {
  public:
   static AmSession* dialout(const string& user,

core/EmailTemplate.h

@@ -37,6 +37,7 @@ class AmMail;
 
 typedef map<string,string> EmailTmplDict;
 
+/** \brief loads, processes and outputs an email template file */
 class EmailTemplate
 {
  public:

core/LowcFE.h

@@ -45,7 +45,7 @@ typedef float Float;
 #define ATTENFAC      ((Float).2)                   /* attenu. factor per 10 ms frame */
 #define ATTENINCR     (ATTENFAC/FRAMESZ)            /* attenuation per sample */
 
-
+/** \brief LowcFE erased frame generator for fec (plc) */
 class LowcFE {
 
 public:

core/SampleArray.h

@@ -30,13 +30,14 @@
 
 /* MUST be a power of 2 */
 #define SIZE_MIX_BUFFER   (1<<14)
-
+/** \brief comparator for timestamps */
 struct ts_less
 {
     bool operator()(const unsigned int& l, 
 		    const unsigned int& r) const;
 };
 
+/** \brief timed array of samples */
 template <typename T>
 class SampleArray
 {