ekiga r5886 - in trunk: . lib/engine/presence/skel

[jpuydt svn gnome org]

Author: jpuydt
Date: Mon Jan  7 21:30:18 2008
New Revision: 5886
URL: http://svn.gnome.org/viewvc/ekiga?rev=5886&view=rev

Log:
Commented the presence stack

Modified:
   trunk/ChangeLog
   trunk/lib/engine/presence/skel/cluster.h
   trunk/lib/engine/presence/skel/heap.h
   trunk/lib/engine/presence/skel/presence-core.h
   trunk/lib/engine/presence/skel/presentity.h

Modified: trunk/lib/engine/presence/skel/cluster.h
==============================================================================
--- trunk/lib/engine/presence/skel/cluster.h	(original)
+++ trunk/lib/engine/presence/skel/cluster.h	Mon Jan  7 21:30:18 2008
@@ -46,18 +46,37 @@
 
   public:
 
+    /** The destructor.
+     */
     virtual ~Cluster () {}
 
+    /** Get the list of Heaps by visiting them with a callback.
+     * @param The callback used to know about heaps.
+     */
     virtual void visit_heaps (sigc::slot<void, Heap &>) = 0;
 
+    /** Populates a menu with the actions possible on the Cluster.
+     * @param The builder to populate.
+     */
     virtual bool populate_menu (MenuBuilder &) = 0;
 
+    /** Those signals are emitted whenever a new Heap is added or removed
+     * from the Cluster.
+     * @param The Heap in question.
+     */
     sigc::signal<void, Heap &> heap_added;
-    sigc::signal<void, Heap &> heap_updated;
     sigc::signal<void, Heap &> heap_removed;
+
+    /** Those signals are forwarded from the given Heap
+     * @param The Heap in question.
+     */
+    sigc::signal<void, Heap &> heap_updated;
     sigc::signal<void, Heap &, Presentity &> presentity_added;
     sigc::signal<void, Heap &, Presentity &> presentity_updated;
     sigc::signal<void, Heap &, Presentity &> presentity_removed;
+
+    /** This chain allows the Cluster to present forms to the user.
+     */
     ChainOfResponsibility<FormRequest*> questions;
   };
 

Modified: trunk/lib/engine/presence/skel/heap.h
==============================================================================
--- trunk/lib/engine/presence/skel/heap.h	(original)
+++ trunk/lib/engine/presence/skel/heap.h	Mon Jan  7 21:30:18 2008
@@ -47,19 +47,51 @@
 
   public:
 
+    /** The destructor.
+     */
     virtual ~Heap () { }
 
+    /** Returns the name of the Heap
+     * @return The Heap's name
+     */
     virtual const std::string get_name () const = 0;
 
+    /** Get the list of Presentities by visiting them with a callback.
+     * @param The callback user to know about presentities.
+     */
     virtual void visit_presentities (sigc::slot<void, Presentity &>) = 0;
 
+    /** Populates a menu with the actions possible on the Heap.
+     * @param The builder to populate.
+     */
     virtual bool populate_menu (MenuBuilder &) = 0;
 
+    /**
+     * Signals on that object
+     */
+
+    /** This signal is emitted when the Heap has been updated.
+     */
     sigc::signal<void> updated;
+
+    /** This signal is emitted when the Heap has been removed.
+     */
     sigc::signal<void> removed;
+
+    /** This signal is emitted  when a Presentity has been added to the Heap.
+     */
     sigc::signal<void, Presentity &> presentity_added;
+
+    /** This signal is emitted when a Presentity has been updated in the Heap.
+     */
     sigc::signal<void, Presentity &> presentity_updated;
+
+    /** This signal is emitted when a Presentity has been removed from the Heap.
+     */
     sigc::signal<void, Presentity &> presentity_removed;
+
+    /** This chain allows the Heap to present forms to the user
+     */
     ChainOfResponsibility<FormRequest*> questions;
   };
 

Modified: trunk/lib/engine/presence/skel/presence-core.h
==============================================================================
--- trunk/lib/engine/presence/skel/presence-core.h	(original)
+++ trunk/lib/engine/presence/skel/presence-core.h	Mon Jan  7 21:30:18 2008
@@ -41,15 +41,39 @@
 #include "services.h"
 #include "cluster.h"
 
-/* declaration of a few helper classes */
+/* The presence core has several goals :
+ * - one of them is of course to list presentities, and know what happens to
+ * them ;
+ * - another one is that we may want to store presentities somewhere as dead
+ * data, but still be able to gain presence information and actions on them.
+ *
+ * This is obtained by using three types of helpers :
+ * - the abstract class PresentityDecorator, which allows to enable actions on
+ * presentities based on uris ;
+ * - the abstract class PresenceFetcher, through which it is possible to gain
+ * presence information : they allow the PresenceCore to declare some presence
+ * information is needed about an uri, or now unneeded ;
+ * - finally, a simple callback-based api allows to add detecters for supported
+ * uris : this allows for example a Presentity to know if it should declare
+ * an uri as "foo bar" or as "prtcl:foo bar". FIXME : couldn't a chain of
+ * responsibility be used there instead of a special registering magic?
+ */
+
+
 namespace Ekiga
 {
   class PresentityDecorator
   {
   public:
 
+    /** The destructor.
+     */
     virtual ~PresentityDecorator () {}
 
+    /** Completes the menu for actions available on an uri
+     * @param The uri for which actions could be made available.
+     * @param A MenuBuilder object to populate.
+     */
     virtual bool populate_menu (const std::string /*uri*/,
 				MenuBuilder &/*builder*/) = 0;
   };
@@ -58,12 +82,29 @@
   {
   public:
 
+    /** The destructor.
+     */
     virtual ~PresenceFetcher () {}
 
+    /** Triggers presence fetching for the given uri
+     * (notice: the PresenceFetcher should count how many times it was
+     * requested presence for an uri, in case several presentities share it)
+     * @param The uri for which to fetch presence information.
+     */
     virtual void fetch (const std::string /*uri*/) = 0;
 
+    /** Stops presence fetching for the given uri
+     * (notice that if some other presentity asked for presence information
+     * on the same uri, the fetching should go on until the last of them is
+     * gone)
+     * @param The uri for which to stop fetching presence information.
+     */
     virtual void unfetch (const std::string /*uri*/) = 0;
 
+    /** Those signals are emitted whenever this presence fetcher gets
+     * presence information about an uri it was required to handle.
+     * The information is given as a pair of strings (uri, data).
+     */
     sigc::signal<void, std::string, std::string> presence_received;
     sigc::signal<void, std::string, std::string> status_received;
   };
@@ -85,36 +126,63 @@
   class PresenceCore:
     public Service
   {
-    /* object basics */
   public:
 
+    /** The constructor.
+     */
     PresenceCore () {}
 
+    /** The destructor.
+     */
     ~PresenceCore ();
 
-    /* service implementation */
+    /*** Service Implementation ***/
   public:
+    /** Returns the name of the service.
+     * @return The service name.
+     */
     const std::string get_name () const
     { return "presence-core"; }
 
+    /** Returns the description of the service.
+     * @return The service description.
+     */
     const std::string get_description () const
     { return "\tPresence managing object"; }
 
-    /* api to list presentities */
+    /*** API to list presentities ***/
   public:
 
+    /** Adds a cluster to the PresenceCore service.
+     * @param The cluster to be added.
+     */
     void add_cluster (Cluster &cluster);
 
+    /** Triggers a callback for all Ekiga::Cluster clusters of the
+     * PresenceCore service.
+     * @param The callback.
+     */
     void visit_clusters (sigc::slot<void, Cluster &> visitor);
 
+    /** This signal is emitted when an Ekiga::Cluster has been added
+     * to the PresenceCore Service.
+     */
     sigc::signal<void, Cluster &> cluster_added;
+
+    /** Those signals are forwarding the heap_added, heap_updated
+     * and heap_removed from the given Cluster.
+     *
+     */
     sigc::signal<void, Cluster &, Heap &> heap_added;
     sigc::signal<void, Cluster &, Heap &> heap_updated;
     sigc::signal<void, Cluster &, Heap &> heap_removed;
+
+    /** Those signals are forwarding the presentity_added, presentity_updated
+     * and presentity_removed from the given Heap of the given Cluster.
+     */
     sigc::signal<void, Cluster &, Heap &, Presentity &> presentity_added;
     sigc::signal<void, Cluster &, Heap &, Presentity &> presentity_updated;
     sigc::signal<void, Cluster &, Heap &, Presentity &> presentity_removed;
-    ChainOfResponsibility<FormRequest*> questions;
 
   private:
 
@@ -132,11 +200,18 @@
 				Presentity &presentity,
 				Cluster *cluster);
 
-    /* act on presentities */
+    /*** API to act on presentities ***/
   public:
 
+    /** Adds a decorator to the pool of presentity decorators.
+     * @param The presentity decorator.
+     */
     void add_presentity_decorator (PresentityDecorator &decorator);
 
+    /** Populates a menu with the actions available on a given uri.
+     * @param The uri for which the decoration is needed.
+     * @param The builder to populate.
+     */
     bool populate_presentity_menu (const std::string uri,
 				   MenuBuilder &builder);
 
@@ -144,15 +219,29 @@
 
     std::set<PresentityDecorator *> presentity_decorators;
 
-    /* help presentities get presence */
+    /*** API to help presentities get presence ***/
   public:
 
+    /** Adds a fetcher to the pool of presentce fetchers.
+     * @param The presence fetcher.
+     */
     void add_presence_fetcher (PresenceFetcher &fetcher);
 
+    /** Tells the PresenceCore that someone is interested in presence
+     * information for the given uri.
+     * @param: The uri for which presence is requested.
+     */
     void fetch_presence (const std::string uri);
 
+    /** Tells the PresenceCore that someone becomes uninterested in presence
+     * information for the given uri.
+     * @param: The uri for which presence isn't requested anymore.
+     */
     void unfetch_presence (const std::string uri);
 
+    /** Those signals are emitted whenever information has been received
+     * about an uri ; the information is a pair of strings (uri, information).
+     */
     sigc::signal<void, std::string, std::string> presence_received;
     sigc::signal<void, std::string, std::string> status_received;
 
@@ -160,6 +249,7 @@
 
     std::set<PresenceFetcher *> presence_fetchers;
 
+<<<<<<< HEAD:lib/engine/presence/skel/presence-core.h
     /* help publishing presence */
   public:
 
@@ -173,21 +263,38 @@
     std::set<PresencePublisher *> presence_publishers;
 
     /* help decide whether an uri is supported by runtime */
+=======
+    /*** API to control which uri are supported by runtime ***/
+>>>>>>> Commented the presence stack:lib/engine/presence/skel/presence-core.h
   public:
 
+    /** Decides whether an uri is supported by the PresenceCore
+     * @param The uri to test for support
+     * @return True if the uri is supported
+     */
     bool is_supported_uri (const std::string uri) const;
 
+    /** Adds an uri tester to the PresenceCore
+     * @param The tester
+     */
     void add_supported_uri (sigc::slot<bool,std::string> tester);
 
   private:
 
     std::set<sigc::slot<bool, std::string> > uri_testers;
 
-    /* unsorted */
+    /*** Misc ***/
   public:
 
+    /** Create the menu of the actions available in the PresenceCore.
+     * @param A MenuBuilder object to populate.
+     */
     bool populate_menu (MenuBuilder &builder);
 
+    /** This chain allows the PresenceCore to present forms to the user
+     */
+    ChainOfResponsibility<FormRequest*> questions;
+
   };
 
 };

Modified: trunk/lib/engine/presence/skel/presentity.h
==============================================================================
--- trunk/lib/engine/presence/skel/presentity.h	(original)
+++ trunk/lib/engine/presence/skel/presentity.h	Mon Jan  7 21:30:18 2008
@@ -50,24 +50,55 @@
   {
   public:
 
+    /** The destructor.
+     */
     virtual ~Presentity () {}
 
+    /** Returns the name of the Presentity.
+     * @return The Presentity's name.
+     */
     virtual const std::string get_name () const = 0;
 
+    /** Returns the presence of the Presentity.
+    * @return The Presentity's presence.
+    */
     virtual const std::string get_presence () const = 0;
 
+    /** Returns the status of the Presentity.
+     * @return The Presentity's status.
+     */
     virtual const std::string get_status () const = 0;
 
+    /** Returns the avatar of the Presentity.
+     * @return The Presentity's avatar.
+     */
     virtual const std::string get_avatar () const = 0;
 
+    /** Returns the set of groups the Presentity belongs to.
+     * @return The Presentity's set of groups.
+     */
     virtual const std::set<std::string> get_groups () const = 0;
 
+    /** Returns the uri of the Presentity.
+     * @return The presentity's uri.
+     */
     virtual const std::string get_uri () const = 0;
 
+    /** Populates a menu with the actions possible on the Presentity.
+     * @param The builder to populate.
+     */
     virtual bool populate_menu (MenuBuilder &) = 0;
 
+    /** This signal is emitted when the Presentity has been updated.
+     */
     sigc::signal<void> updated;
+
+    /** This signal is emitted when the Presentity has been removed.
+     */
     sigc::signal<void> removed;
+
+    /** This chain allows the Presentity to present forms to the user
+     */
     ChainOfResponsibility<FormRequest*> questions;
   };