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
diff --git a/common/rfb/CapsContainer.h b/common/rfb/CapsContainer.h
index c7c8ab23..cad8be9 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 @@
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;
};