Documentation on CapsContainer class has been extended and moved from .cxx to .h...

git-svn-id: svn://svn.code.sf.net/p/tigervnc/code/trunk@665 3789f03b-4d11-0410-bbf8-ca57d06f2519

diff --git a/common/rfb/CapsContainer.cxx b/common/rfb/CapsContainer.cxx
index cea5f3aaa1a758e16cae02b7777030deb584b114..a64a52486fa43974c887c9e1861a5fedea4390a0 100644 (file)
--- a/common/rfb/CapsContainer.cxx
+++ b/common/rfb/CapsContainer.cxx
@@ -18,26 +18,18 @@
 
 //
 // CapsContainer class implementation.
-// FIXME: Extend the comment.
+// Member variables and functions are documented in CapsContainer.h.
 //
 
 #include <rfb/CapsContainer.h>
 
 using namespace rfb;
 
-//
-// The constructor.
-//
-
 CapsContainer::CapsContainer(int maxCaps)
 : m_maxSize(maxCaps), m_listSize(0), m_plist(new rdr::U32[m_maxSize])
 {
 }
 
-//
-// The destructor.
-//
-
 CapsContainer::~CapsContainer()
 {
   delete[] m_plist;
@@ -49,12 +41,6 @@ CapsContainer::~CapsContainer()
   }
 }
 
-//
-// Add information about a particular capability into the object. There are
-// two functions to perform this task. These functions overwrite capability
-// records with the same code.
-//
-
 void
 CapsContainer::add(rdr::U32 code, const char *vendor, const char *name,
                    const char *desc)
@@ -85,22 +71,12 @@ CapsContainer::add(const CapabilityInfo *capinfo, const char *desc)
   m_descMap[capinfo->code] = desc_copy;
 }
 
-//
-// Check if a capability with the specified code was added earlier.
-//
-
 bool
 CapsContainer::isKnown(rdr::U32 code) const
 {
   return (m_descMap.find(code) != m_descMap.end());
 }
 
-//
-// Fill in a rfbCapabilityInfo structure with contents corresponding to the
-// specified code. Returns true on success, false if the specified code is
-// not known.
-//
-
 bool
 CapsContainer::getInfo(rdr::U32 code, CapabilityInfo *capinfo) const
 {
@@ -112,24 +88,12 @@ CapsContainer::getInfo(rdr::U32 code, CapabilityInfo *capinfo) const
   return false;
 }
 
-//
-// Get a description string for the specified capability code. Returns 0
-// either if the code is not known, or if there is no description for this
-// capability.
-//
-
 char *
 CapsContainer::getDescription(rdr::U32 code) const
 {
   return (isKnown(code)) ? m_descMap.find(code)->second : 0;
 }
 
-//
-// Mark the specified capability as "enabled". This function checks "vendor"
-// and "name" signatures in the existing record and in the argument structure
-// and enables the capability only if both records are the same.
-//
-
 bool
 CapsContainer::enable(const CapabilityInfo *capinfo)
 {
@@ -150,21 +114,12 @@ CapsContainer::enable(const CapabilityInfo *capinfo)
   return true;
 }
 
-//
-// Check if the specified capability is known and enabled.
-//
-
 bool
 CapsContainer::isEnabled(rdr::U32 code) const
 {
   return (isKnown(code)) ? m_enableMap.find(code)->second : false;
 }
 
-//
-// Return the capability code at the specified index.
-// If the index is not valid, return 0.
-//
-
 rdr::U32
 CapsContainer::getByOrder(int idx) const
 {

diff --git a/common/rfb/CapsContainer.h b/common/rfb/CapsContainer.h
index c7c8ab2387fe0cc8ac93245c8f0a232fd518d96b..cad8be9757daf16027a6c170c40f402e128a24d2 100644 (file)
--- a/common/rfb/CapsContainer.h
+++ b/common/rfb/CapsContainer.h
@@ -31,8 +31,9 @@
 namespace rfb {
 
   //
-  // Structure used to describe protocol options such as tunneling methods,
-  // authentication schemes and message types (protocol versions 3.7t/3.8t).
+  // CapabilityInfo - structure used to describe protocol options such as
+  // tunneling methods, authentication schemes, message types and encoding
+  // types (protocol versions 3.7 and 3.8 with TightVNC extensions).
   //
 
   struct CapabilityInfo {
@@ -41,37 +42,88 @@ namespace rfb {
     rdr::U8 nameSignature[8];     // abbreviated option name
   };
 
-
   //
   // CapsContainer - a container class to maintain a list of protocol
   // capabilities.
   //
+  // Typical usage is as follows. First, the client creates an instance
+  // of the CapsContainer class for each type of capabilities (e.g.
+  // authentication methods). It adds information about capabilities it
+  // supports, by calling add() functions. Then, the client receives
+  // information about supported capabilities from the server, and tries
+  // to "enable" each capability advertised by the server. Particular
+  // capability becomes enabled if it is known (added by the client) and
+  // matches that one received from the server. Finally, the client can
+  // check if a given capability is enabled, and also get the list of
+  // capabilities in the order they were enabled.
+  //
 
-  class CapsContainer {
+  class CapsContainer
+  {
   public:
+
+    // Constructor. The maxCaps argument is the maximum number of records
+    // in the list used by getByOrder() function. Remaining functions do not
+    // impose limitations on the number of capabilities.
     CapsContainer(int maxCaps = 64);
+
+    // Destructor.
     virtual ~CapsContainer();
 
+    // Add information about a particular capability into the object. These
+    // functions overwrite existing capability records with the same code.
+    // NOTE: Value 0 should not be used for capability codes.
     void add(const CapabilityInfo *capinfo, const char *desc = 0);
     void add(rdr::U32 code, const char *vendor, const char *name,
              const char *desc = 0);
 
+    // Check if a capability with the specified code was added earlier.
     bool isKnown(rdr::U32 code) const;
+
+    // Fill in an rfbCapabilityInfo structure with contents corresponding to
+    // the specified code. Returns true on success, false if the specified
+    // code is not known.
     bool getInfo(rdr::U32 code, CapabilityInfo *capinfo) const;
+
+    // Get an optional description string for the specified capability code.
+    // Returns 0 either if the code is not known, or if there is no
+    // description for the given capability. Otherwise, the return value
+    // is a pointer valid until either add() is called again for the same
+    // capability, or the CapsContaner object is destroyed.
     char *getDescription(rdr::U32 code) const;
 
+    // Mark the specified capability as "enabled". This function compares
+    // "vendor" and "name" signatures in the existing record and in the
+    // argument structure and enables the capability only if both records
+    // are the same.
     bool enable(const CapabilityInfo *capinfo);
+
+    // Check if the specified capability is known and enabled.
     bool isEnabled(rdr::U32 code) const;
+
+    // Return the number of enabled capabilities.
     int numEnabled() const { return m_listSize; }
+
+    // Return the capability code at the specified index, from the list of
+    // enabled capabilities. Capabilities are indexed in the order they were
+    // enabled, index 0 points to the capability which was enabled first.
+    // If the index is not valid, this function returns 0.
     rdr::U32 getByOrder(int idx) const;
 
   private:
+
+    // Mapping codes to corresponding CapabilityInfo structures.
     std::map<rdr::U32,CapabilityInfo> m_infoMap;
+    // Mapping capability codes to corresponding descriptions.
     std::map<rdr::U32,char*> m_descMap;
+    // Mapping codes to boolean flags, true for enabled capabilities.
     std::map<rdr::U32,bool> m_enableMap;
 
+    // Allocated size of m_plist[].
     int m_maxSize;
+    // Number of valid elements in m_plist[].
     int m_listSize;
+    // Array of enabled capabilities (allocated in constructor).
     rdr::U32 *m_plist;
   };