* updated license headers

* updated documentation

1 files changed, 85 insertions, 50 deletions

diff --git a/include/shared/CAmSocketHandler.h b/include/shared/CAmSocketHandler.h
index e0ea797..8df6872 100644
--- a/include/shared/CAmSocketHandler.h
+++ b/include/shared/CAmSocketHandler.h
@@ -1,9 +1,9 @@
 /** Copyright (c) 2012 GENIVI Alliance
  *  Copyright (c) 2012 BMW
  *
- *  \author Christian Mueller, BMW
+ *  \author Christian Mueller, christian.ei.mueller@bmw.de BMW 2011,2012
  *
- *  \section license
+ *  \copyright
  *  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction,
  *  including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
  *  subject to the following conditions:
@@ -12,6 +12,8 @@
  *  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
  *  THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  *
+ *  \file CAmSocketHandler.h
+ *  For further information see http://www.genivi.org/.
  */
 
 #ifndef SOCKETHANDLER_H_
@@ -34,22 +36,26 @@ static volatile sig_atomic_t gDispatchDone = 0; //this global is used to stop th
 typedef uint16_t sh_timerHandle_t; //!<this is a handle for a timer to be used with the SocketHandler
 typedef uint16_t sh_pollHandle_t; //!<this is a handle for a filedescriptor to be used with the SocketHandler
 
-class CAmShPollPrepare;
-class CAmShPollCheck;
-class CAmShPollFired;
-class CAmShPollDispatch;
-class CAmShTimerCallBack;
+class IAmShPollPrepare;
+class IAmShPollCheck;
+class IAmShPollFired;
+class IAmShPollDispatch;
+class IAmShTimerCallBack;
 
+/**
+ * The sockethandler implements a mainloop for the audiomanager. Plugins and different parts of the audiomanager add their filedescriptors to the handler to get called
+ * on communication of the filedescriptors.
+ */
 class CAmSocketHandler
 {
 public:
     CAmSocketHandler();
-    virtual ~CAmSocketHandler();
+    ~CAmSocketHandler();
 
-    am_Error_e addFDPoll(const int fd, const short event, CAmShPollPrepare *prepare, CAmShPollFired *fired, CAmShPollCheck *check, CAmShPollDispatch *dispatch, void* userData, sh_pollHandle_t& handle);
+    am_Error_e addFDPoll(const int fd, const short event, IAmShPollPrepare *prepare, IAmShPollFired *fired, IAmShPollCheck *check, IAmShPollDispatch *dispatch, void* userData, sh_pollHandle_t& handle);
     am_Error_e removeFDPoll(const sh_pollHandle_t handle);
     am_Error_e updateEventFlags(const sh_pollHandle_t handle, const short events);
-    am_Error_e addTimer(const timespec timeouts, CAmShTimerCallBack*& callback, sh_timerHandle_t& handle, void* userData);
+    am_Error_e addTimer(const timespec timeouts, IAmShTimerCallBack*& callback, sh_timerHandle_t& handle, void* userData);
     am_Error_e removeTimer(const sh_timerHandle_t handle);
     am_Error_e restartTimer(const sh_timerHandle_t handle, const timespec timeouts);
     am_Error_e stopTimer(const sh_timerHandle_t handle);
@@ -61,7 +67,7 @@ private:
         sh_timerHandle_t handle; //!<the handle of the timer
         timespec countdown; //!<the countdown, this value is decreased every time the timer is up
         timespec timeout; //!<the original timer value
-        CAmShTimerCallBack* callback; //!<the callbackfunction
+        IAmShTimerCallBack* callback; //!<the callbackfunction
         void * userData; //!<saves a void pointer together with the rest.
     };
 
@@ -71,17 +77,19 @@ private:
         timespec param;
     public:
         CAmShSubstractTime(timespec param) :
-                param(param){}
+                param(param)
+        {
+        }
         void operator()(sh_timer_s& t) const;
     };
 
     struct sh_poll_s //!<struct that holds information about polls
     {
         sh_pollHandle_t handle; //!<handle to uniquely adress a filedesriptor
-        CAmShPollPrepare *prepareCB;
-        CAmShPollFired *firedCB;
-        CAmShPollCheck *checkCB;
-        CAmShPollDispatch *dispatchCB;
+        IAmShPollPrepare *prepareCB;
+        IAmShPollFired *firedCB;
+        IAmShPollCheck *checkCB;
+        IAmShPollDispatch *dispatchCB;
         pollfd pollfdValue; //!<the array for polling the filedescriptors
         void *userData; //!<userdata saved together with the callback.
     };
@@ -95,7 +103,9 @@ private:
         mListPollfd_t& mArray;
     public:
         CAmShCopyPollfd(mListPollfd_t& dest) :
-                mArray(dest){}
+                mArray(dest)
+        {
+        }
         void operator()(const sh_poll_s& row);
     };
 
@@ -106,12 +116,12 @@ private:
     timespec* insertTime(timespec& buffertime);
     static bool compareCountdown(const sh_timer_s& a, const sh_timer_s& b)
     {
-        return (a.countdown.tv_sec == b.countdown.tv_sec) ? (a.countdown.tv_nsec < b.countdown.tv_nsec) : (a.countdown.tv_sec < b.countdown.tv_sec);
+        return ((a.countdown.tv_sec == b.countdown.tv_sec) ? (a.countdown.tv_nsec < b.countdown.tv_nsec) : (a.countdown.tv_sec < b.countdown.tv_sec));
     }
 
     static bool onlyFiredEvents(const pollfd& a)
     {
-        return a.revents == 0 ? false : true;
+        return (a.revents == 0 ? false : true);
     }
 
     //todo: maybe we could simplify mListActiveTimer to hold only the handle and the countdown ....
@@ -127,56 +137,68 @@ private:
 };
 
 /**
- * classic functor for the BasicTimerCallback
+ * prototype for the timer callback
  */
-class CAmShTimerCallBack
+class IAmShTimerCallBack
 {
 public:
     virtual void Call(const sh_timerHandle_t handle, void* userData)=0;
-    virtual ~CAmShTimerCallBack(){};
+    virtual ~IAmShTimerCallBack(){};
 };
 
-class CAmShPollPrepare
+/**
+ * prototype for poll prepared callback
+ */
+class IAmShPollPrepare
 {
 public:
     virtual void Call(const sh_pollHandle_t handle, void* userData)=0;
-    virtual ~CAmShPollPrepare(){};
+    virtual ~IAmShPollPrepare(){};
 };
 
-class CAmShPollFired
+/**
+ * prototype for poll fired callback
+ */
+class IAmShPollFired
 {
 public:
     virtual void Call(const pollfd pollfd, const sh_pollHandle_t handle, void* userData)=0;
-    virtual ~ CAmShPollFired(){};
+    virtual ~ IAmShPollFired(){};
 };
 
-class CAmShPollCheck
+/**
+ * prototype for poll check callback
+ */
+class IAmShPollCheck
 {
 public:
     virtual bool Call(const sh_pollHandle_t handle, void* userData)=0;
-    virtual ~ CAmShPollCheck(){};
+    virtual ~ IAmShPollCheck(){};
 };
 
-class CAmShPollDispatch
+/**
+ * prototype for dispatch callback
+ */
+class IAmShPollDispatch
 {
 public:
     virtual bool Call(const sh_pollHandle_t handle, void* userData)=0;
-    virtual ~ CAmShPollDispatch() {};
+    virtual ~ IAmShPollDispatch(){};
 };
 
 /**
  * template to create the functor for a class
  */
-template<class TClass> class TAmShTimerCallBack: public CAmShTimerCallBack
+template<class TClass> class TAmShTimerCallBack: public IAmShTimerCallBack
 {
 private:
     TClass* mInstance;
     void (TClass::*mFunction)(sh_timerHandle_t handle, void* userData);
 
 public:
-    TAmShTimerCallBack(TClass* instance, void(TClass::*function)(sh_timerHandle_t handle, void* userData)) :
-            mInstance(instance),//
-            mFunction(function) {};
+    TAmShTimerCallBack(TClass* instance, void (TClass::*function)(sh_timerHandle_t handle, void* userData)) :
+            mInstance(instance), //
+            mFunction(function){};
 
     virtual void Call(sh_timerHandle_t handle, void* userData)
     {
@@ -185,74 +207,87 @@ public:
 };
 
 /**
- * template to create the functor for a class
+ * template for a callback
  */
-template<class TClass> class TAmShPollPrepare: public CAmShPollPrepare
+template<class TClass> class TAmShPollPrepare: public IAmShPollPrepare
 {
 private:
     TClass* mInstance;
     void (TClass::*mFunction)(const sh_timerHandle_t handle, void* userData);
 
 public:
-    TAmShPollPrepare(TClass* instance, void(TClass::*function)(const sh_timerHandle_t handle, void* userData)) :
+    TAmShPollPrepare(TClass* instance, void (TClass::*function)(const sh_timerHandle_t handle, void* userData)) :
             mInstance(instance), //
             mFunction(function){};
 
     virtual void Call(const sh_timerHandle_t handle, void* userData)
     {
         (*mInstance.*mFunction)(handle, userData);
-    };
+    }
+    ;
 };
 
-template<class TClass> class TAmShPollFired: public CAmShPollFired
+/**
+ * template for a callback
+ */
+template<class TClass> class TAmShPollFired: public IAmShPollFired
 {
 private:
     TClass* mInstance;
     void (TClass::*mFunction)(const pollfd pollfd, const sh_pollHandle_t handle, void* userData);
 
 public:
-    TAmShPollFired(TClass* instance, void(TClass::*function)(const pollfd pollfd, const sh_pollHandle_t handle, void* userData)) :
+    TAmShPollFired(TClass* instance, void (TClass::*function)(const pollfd pollfd, const sh_pollHandle_t handle, void* userData)) :
             mInstance(instance), //
             mFunction(function){};
 
     virtual void Call(const pollfd pollfd, const sh_pollHandle_t handle, void* userData)
     {
         (*mInstance.*mFunction)(pollfd, handle, userData);
-    };
+    }
+    ;
 };
 
-template<class TClass> class TAmShPollCheck: public CAmShPollCheck
+/**
+ * template for a callback
+ */
+template<class TClass> class TAmShPollCheck: public IAmShPollCheck
 {
 private:
     TClass* mInstance;
     bool (TClass::*mFunction)(const sh_pollHandle_t handle, void* userData);
 
 public:
-    TAmShPollCheck(TClass* instance, bool(TClass::*function)(const sh_pollHandle_t handle, void* userData)) :
+    TAmShPollCheck(TClass* instance, bool (TClass::*function)(const sh_pollHandle_t handle, void* userData)) :
             mInstance(instance), //
             mFunction(function){};
 
     virtual bool Call(const sh_pollHandle_t handle, void* userData)
     {
-        return (*mInstance.*mFunction)(handle, userData);
-    };
+        return ((*mInstance.*mFunction)(handle, userData));
+    }
+    ;
 };
 
-template<class TClass> class TAmShPollDispatch: public CAmShPollDispatch
+/**
+ * template for a callback
+ */
+template<class TClass> class TAmShPollDispatch: public IAmShPollDispatch
 {
 private:
     TClass* mInstance;
     bool (TClass::*mFunction)(const sh_pollHandle_t handle, void* userData);
 
 public:
-    TAmShPollDispatch(TClass* instance, bool(TClass::*function)(const sh_pollHandle_t handle, void* userData)) :
+    TAmShPollDispatch(TClass* instance, bool (TClass::*function)(const sh_pollHandle_t handle, void* userData)) :
             mInstance(instance), //
-            mFunction(function) {};
+            mFunction(function){};
 
     virtual bool Call(const sh_pollHandle_t handle, void* userData)
     {
-        return (*mInstance.*mFunction)(handle, userData);
-    };
+        return ((*mInstance.*mFunction)(handle, userData));
+    }
+    ;
 };
 } /* namespace am */
 #endif /* SOCKETHANDLER_H_ */