From 56b7fa1c91fc7e215b7498fa7b1c93cad85eb4fe Mon Sep 17 00:00:00 2001 From: Constantin Kaplinsky Date: Tue, 12 Sep 2006 05:15:44 +0000 Subject: [PATCH] Documentation on CapsContainer class has been extended and moved from .cxx to .h file. git-svn-id: svn://svn.code.sf.net/p/tigervnc/code/trunk@665 3789f03b-4d11-0410-bbf8-ca57d06f2519 --- common/rfb/CapsContainer.cxx | 47 +--------------------------- common/rfb/CapsContainer.h | 60 +++++++++++++++++++++++++++++++++--- 2 files changed, 57 insertions(+), 50 deletions(-) diff --git a/common/rfb/CapsContainer.cxx b/common/rfb/CapsContainer.cxx index cea5f3aa..a64a5248 100644 --- 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 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 c7c8ab23..cad8be97 100644 --- 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 m_infoMap; + // Mapping capability codes to corresponding descriptions. std::map m_descMap; + // Mapping codes to boolean flags, true for enabled capabilities. std::map 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; }; -- 2.39.5