Moved CPrimaryScreen and CSecondaryScreen to the lib/synergy

and the platform specific implementations to lib/platform.
Added an lib/arch method to query the platform's native wide
character encoding and changed CUnicode to use it.  All
platform dependent code is now in lib/arch, lib/platform,
and the programs under cmd.  Also added more documentation.

lib/arch/CArch.cpp

@@ -130,6 +130,8 @@ CArch::~CArch()
 CArch*
 CArch::getInstance()
 {
+	assert(s_instance != NULL);
+
 	return s_instance;
 }
 
@@ -569,6 +571,12 @@ CArch::convWCToMB(char* dst, wchar_t src, CArchMBState state)
 	return m_string->convWCToMB(dst, src, state);
 }
 
+IArchString::EWideCharEncoding
+CArch::getWideCharEncoding()
+{
+	return m_string->getWideCharEncoding();
+}
+
 double
 CArch::time()
 {

lib/arch/CArch.h

@@ -25,10 +25,24 @@
 #include "IArchString.h"
 #include "IArchTime.h"
 
+/*!
+\def ARCH
+This macro evaluates to the singleton CArch object.
+*/
 #define ARCH	(CArch::getInstance())
 
 #define ARCH_ARGS
 
+//! Delegating mplementation of architecture dependent interfaces
+/*!
+This class is a centralized interface to all architecture dependent
+interface implementations (except miscellaneous functions).  It
+instantiates an implementation of each interface and delegates calls
+to each method to those implementations.  Clients should use the
+\c ARCH macro to access this object.  Clients must also instantiate
+exactly one of these objects before attempting to call any method,
+typically at the beginning of \c main().
+*/
 class CArch : public IArchConsole,
 				public IArchDaemon,
 				public IArchFile,
@@ -46,6 +60,11 @@ public:
 	// accessors
 	//
 
+	//! Return the singleton instance
+	/*!
+	The client must have instantiated exactly once CArch object before
+	calling this function.
+	*/
 	static CArch*		getInstance();
 
 	// IArchConsole overrides
@@ -142,6 +161,8 @@ public:
 	virtual bool		isInitMBState(CArchMBState);
 	virtual int			convMBToWC(wchar_t*, const char*, int, CArchMBState);
 	virtual int			convWCToMB(char*, wchar_t, CArchMBState);
+	virtual EWideCharEncoding
+						getWideCharEncoding();
 
 	// IArchTime overrides
 	virtual double		time();

lib/arch/CArchConsoleUnix.h

@@ -19,6 +19,7 @@
 
 #define ARCH_CONSOLE CArchConsoleUnix
 
+//! Unix implementation of IArchConsole
 class CArchConsoleUnix : public IArchConsole {
 public:
 	CArchConsoleUnix();

lib/arch/CArchConsoleWindows.h

@@ -23,6 +23,7 @@
 
 #define ARCH_CONSOLE CArchConsoleWindows
 
+//! Win32 implementation of IArchConsole
 class CArchConsoleWindows : public IArchConsole {
 public:
 	CArchConsoleWindows();

lib/arch/CArchDaemonNone.h

@@ -19,6 +19,13 @@
 
 #define ARCH_DAEMON CArchDaemonNone
 
+//! Dummy implementation of IArchDaemon
+/*!
+This class implements IArchDaemon for a platform that does not have
+daemons.  The install and uninstall functions do nothing, the query
+functions return false, and \c daemonize() simply calls the passed
+function and returns its result.
+*/
 class CArchDaemonNone : public IArchDaemon {
 public:
 	CArchDaemonNone();

lib/arch/CArchDaemonUnix.h

@@ -20,6 +20,7 @@
 #undef ARCH_DAEMON
 #define ARCH_DAEMON CArchDaemonUnix
 
+//! Unix implementation of IArchDaemon
 class CArchDaemonUnix : public CArchDaemonNone {
 public:
 	CArchDaemonUnix();

lib/arch/CArchDaemonWindows.h

@@ -25,6 +25,7 @@
 
 #define ARCH_DAEMON CArchDaemonWindows
 
+//! Win32 implementation of IArchDaemon
 class CArchDaemonWindows : public IArchDaemon {
 public:
 	typedef int			(*RunFunc)(void);

lib/arch/CArchFileUnix.h

@@ -19,6 +19,7 @@
 
 #define ARCH_FILE CArchFileUnix
 
+//! Unix implementation of IArchFile
 class CArchFileUnix : public IArchFile {
 public:
 	CArchFileUnix();

lib/arch/CArchFileWindows.h

@@ -19,6 +19,7 @@
 
 #define ARCH_FILE CArchFileWindows
 
+//! Win32 implementation of IArchFile
 class CArchFileWindows : public IArchFile {
 public:
 	CArchFileWindows();

lib/arch/CArchLogUnix.h

@@ -19,6 +19,7 @@
 
 #define ARCH_LOG CArchLogUnix
 
+//! Unix implementation of IArchLog
 class CArchLogUnix : public IArchLog {
 public:
 	CArchLogUnix();

lib/arch/CArchLogWindows.h

@@ -22,6 +22,7 @@
 
 #define ARCH_LOG CArchLogWindows
 
+//! Win32 implementation of IArchLog
 class CArchLogWindows : public IArchLog {
 public:
 	CArchLogWindows();

lib/arch/CArchMiscWindows.h

@@ -15,6 +15,7 @@
 #ifndef CARCHMISCWINDOWS_H
 #define CARCHMISCWINDOWS_H
 
+//! Miscellaneous win32 functions.
 class CArchMiscWindows {
 public:
 	typedef int			(*RunFunc)(void);

lib/arch/CArchMultithreadPosix.h

@@ -31,6 +31,7 @@ public:
 	pthread_mutex_t		m_mutex;
 };
 
+//! Posix implementation of IArchMultithread
 class CArchMultithreadPosix : public IArchMultithread {
 public:
 	CArchMultithreadPosix();

lib/arch/CArchMultithreadWindows.cpp

@@ -575,7 +575,7 @@ CArchMultithreadWindows::refThread(CArchThreadImpl* thread)
 }
 
 void
-CArchMultithreadWindows::testCancelThreadImpl(CArchThread thread)
+CArchMultithreadWindows::testCancelThreadImpl(CArchThreadImpl* thread)
 {
 	assert(thread != NULL);
 

lib/arch/CArchMultithreadWindows.h

@@ -37,6 +37,7 @@ public:
 	CRITICAL_SECTION	m_mutex;
 };
 
+//! Win32 implementation of IArchMultithread
 class CArchMultithreadWindows : public IArchMultithread {
 public:
 	CArchMultithreadWindows();

lib/arch/CArchNetworkBSD.h

@@ -50,6 +50,7 @@ public:
 	socklen_t			m_len;
 };
 
+//! Berkeley (BSD) sockets implementation of IArchNetwork
 class CArchNetworkBSD : public IArchNetwork {
 public:
 	CArchNetworkBSD();

lib/arch/CArchNetworkWinsock.cpp

@@ -35,7 +35,7 @@ static int (PASCAL FAR *getsockopt_winsock)(SOCKET s, int level, int optname, vo
 static u_short (PASCAL FAR *htons_winsock)(u_short v);
 static char FAR * (PASCAL FAR *inet_ntoa_winsock)(struct in_addr in);
 static unsigned long (PASCAL FAR *inet_addr_winsock)(const char FAR * cp);
-static int (PASCAL FAR *ioctl_winsock)(SOCKET s, int cmd, void FAR *);
+static int (PASCAL FAR *ioctl_winsock)(SOCKET s, int cmd, void FAR * data);
 static int (PASCAL FAR *listen_winsock)(SOCKET s, int backlog);
 static u_short (PASCAL FAR *ntohs_winsock)(u_short v);
 static int (PASCAL FAR *recv_winsock)(SOCKET s, void FAR * buf, int len, int flags);
@@ -47,7 +47,7 @@ static SOCKET (PASCAL FAR *socket_winsock)(int af, int type, int protocol);
 static struct hostent FAR * (PASCAL FAR *gethostbyaddr_winsock)(const char FAR * addr, int len, int type);
 static struct hostent FAR * (PASCAL FAR *gethostbyname_winsock)(const char FAR * name);
 static int (PASCAL FAR *WSACleanup_winsock)(void);
-static int (PASCAL FAR *WSAFDIsSet_winsock)(SOCKET, fd_set FAR *);
+static int (PASCAL FAR *WSAFDIsSet_winsock)(SOCKET, fd_set FAR * fdset);
 
 #undef FD_ISSET
 #define FD_ISSET(fd, set) WSAFDIsSet_winsock((SOCKET)(fd), (fd_set FAR *)(set))

lib/arch/CArchNetworkWinsock.h

@@ -44,6 +44,7 @@ public:
 	int					m_len;
 };
 
+//! Win32 implementation of IArchNetwork
 class CArchNetworkWinsock : public IArchNetwork {
 public:
 	CArchNetworkWinsock();

lib/arch/CArchSleepUnix.h

@@ -19,6 +19,7 @@
 
 #define ARCH_SLEEP CArchSleepUnix
 
+//! Unix implementation of IArchSleep
 class CArchSleepUnix : public IArchSleep {
 public:
 	CArchSleepUnix();

lib/arch/CArchSleepWindows.h

@@ -19,6 +19,7 @@
 
 #define ARCH_SLEEP CArchSleepWindows
 
+//! Win32 implementation of IArchSleep
 class CArchSleepWindows : public IArchSleep {
 public:
 	CArchSleepWindows();

lib/arch/CArchStringUnix.cpp

@@ -32,3 +32,9 @@ CArchStringUnix::~CArchStringUnix()
 }
 
 #include "vsnprintf.cpp"
+
+IArchString::EWideCharEncoding
+CArchStringUnix::getWideCharEncoding()
+{
+	return kUCS4;
+}

lib/arch/CArchStringUnix.h

@@ -19,6 +19,7 @@
 
 #define ARCH_STRING CArchStringUnix
 
+//! Unix implementation of IArchString
 class CArchStringUnix : public IArchString {
 public:
 	CArchStringUnix();
@@ -33,6 +34,8 @@ public:
 	virtual bool		isInitMBState(CArchMBState);
 	virtual int			convMBToWC(wchar_t*, const char*, int, CArchMBState);
 	virtual int			convWCToMB(char*, wchar_t, CArchMBState);
+	virtual EWideCharEncoding
+						getWideCharEncoding();
 };
 
 #endif

lib/arch/CArchStringWindows.cpp

@@ -36,3 +36,9 @@ CArchStringWindows::~CArchStringWindows()
 #define HAVE_VSNPRINTF 1
 #define ARCH_VSNPRINTF _vsnprintf
 #include "vsnprintf.cpp"
+
+IArchString::EWideCharEncoding
+CArchStringWindows::getWideCharEncoding()
+{
+	return kUTF16;
+}

lib/arch/CArchStringWindows.h

@@ -19,6 +19,7 @@
 
 #define ARCH_STRING CArchStringWindows
 
+//! Win32 implementation of IArchString
 class CArchStringWindows : public IArchString {
 public:
 	CArchStringWindows();
@@ -33,6 +34,8 @@ public:
 	virtual bool		isInitMBState(CArchMBState);
 	virtual int			convMBToWC(wchar_t*, const char*, int, CArchMBState);
 	virtual int			convWCToMB(char*, wchar_t, CArchMBState);
+	virtual EWideCharEncoding
+						getWideCharEncoding();
 };
 
 #endif

lib/arch/CArchTimeUnix.h

@@ -19,6 +19,7 @@
 
 #define ARCH_TIME CArchTimeUnix
 
+//! Generic Unix implementation of IArchTime
 class CArchTimeUnix : public IArchTime {
 public:
 	CArchTimeUnix();

lib/arch/CArchTimeWindows.h

@@ -19,6 +19,7 @@
 
 #define ARCH_TIME CArchTimeWindows
 
+//! Win32 implementation of IArchTime
 class CArchTimeWindows : public IArchTime {
 public:
 	CArchTimeWindows();

lib/arch/IArchConsole.h

@@ -17,6 +17,11 @@
 
 #include "IInterface.h"
 
+//! Interface for architecture dependent console output
+/*!
+This interface defines the console operations required by
+synergy.  Each architecture must implement this interface.
+*/
 class IArchConsole : public IInterface {
 public:
 	//! @name manipulators

lib/arch/IArchFile.h

@@ -18,6 +18,11 @@
 #include "IInterface.h"
 #include "stdstring.h"
 
+//! Interface for architecture dependent file system operations
+/*!
+This interface defines the file system operations required by
+synergy.  Each architecture must implement this interface.
+*/
 class IArchFile : public IInterface {
 public:
 	//! @name manipulators

lib/arch/IArchLog.h

@@ -17,9 +17,24 @@
 
 #include "IInterface.h"
 
+//! Interface for architecture dependent logging
+/*!
+This interface defines the logging operations required by
+synergy.  Each architecture must implement this interface.
+*/
 class IArchLog : public IInterface {
 public:
-	enum ELevel { kERROR, kWARNING, kNOTE, kINFO, kDEBUG };
+	//! Log levels
+	/*!
+	The logging priority levels in order of highest to lowest priority.
+	*/
+	enum ELevel {
+		kERROR,			//!< For serious or fatal errors
+		kWARNING,		//!< For minor errors and warnings
+		kNOTE,			//!< For messages about notable events
+		kINFO,			//!< For informational messages
+		kDEBUG			//!< For debugging messages
+	};
 
 	//! @name manipulators
 	//@{

lib/arch/IArchMultithread.h

@@ -17,11 +17,47 @@
 
 #include "IInterface.h"
 
+/*!      
+\class CArchCondImpl
+\brief Internal condition variable data.
+An architecture dependent type holding the necessary data for a
+condition variable.
+*/
 class CArchCondImpl;
-class CArchMutexImpl;
-class CArchThreadImpl;
+
+/*!      
+\var CArchCond
+\brief Opaque condition variable type.
+An opaque type representing a condition variable.
+*/
 typedef CArchCondImpl* CArchCond;
+
+/*!      
+\class CArchMutexImpl
+\brief Internal mutex data.
+An architecture dependent type holding the necessary data for a mutex.
+*/
+class CArchMutexImpl;
+
+/*!      
+\var CArchMutex
+\brief Opaque mutex type.
+An opaque type representing a mutex.
+*/
 typedef CArchMutexImpl* CArchMutex;
+
+/*!      
+\class CArchThreadImpl
+\brief Internal thread data.
+An architecture dependent type holding the necessary data for a thread.
+*/
+class CArchThreadImpl;
+
+/*!      
+\var CArchThread
+\brief Opaque thread type.
+An opaque type representing a thread.
+*/
 typedef CArchThreadImpl* CArchThread;
 
 //! Interface for architecture dependent multithreading
@@ -31,7 +67,9 @@ synergy.  Each architecture must implement this interface.
 */
 class IArchMultithread : public IInterface {
 public:
+	//! Type of thread entry point
 	typedef void* (*ThreadFunc)(void*);
+	//! Type of thread identifier
 	typedef unsigned int ThreadID;
 
 	//! @name manipulators
@@ -41,38 +79,172 @@ public:
 	// condition variable methods
 	//
 
+	//! Create a condition variable
+	/*!
+	The condition variable is an opaque data type.
+	*/
 	virtual CArchCond	newCondVar() = 0;
+
+	//! Destroy a condition variable
 	virtual void		closeCondVar(CArchCond) = 0;
+
+	//! Signal a condition variable
+	/*!
+	Signalling a condition variable releases one waiting thread.
+	*/
 	virtual void		signalCondVar(CArchCond) = 0;
+
+	//! Broadcast a condition variable
+	/*!
+	Broadcasting a condition variable releases all waiting threads.
+	*/
 	virtual void		broadcastCondVar(CArchCond) = 0;
+
+	//! Wait on a condition variable
+	/*!
+	Waiting on a conditation variable for up to \c timeout seconds.
+	If \c timeout is < 0 then there is no timeout.  The mutex must
+	be locked when this method is called.  The mutex is unlocked
+	during the wait and locked again before returning.
+
+	(Cancellation point)
+	*/
 	virtual bool		waitCondVar(CArchCond, CArchMutex, double timeout) = 0;
 
 	//
 	// mutex methods
 	//
 
+	//! Create a non-recursive mutex
+	/*!
+	Creates a non-recursive mutex.  A thread must not lock a
+	non-recursive mutex when it already holds a lock on that mutex.
+	If it does it will deadlock.  The mutex is an opaque data type.
+	*/
 	virtual CArchMutex	newMutex() = 0;
+
+	//! Destroy a mutex
 	virtual void		closeMutex(CArchMutex) = 0;
+
+	//! Lock a mutex
+	/*!
+	(Cancellation point)
+	*/
 	virtual void		lockMutex(CArchMutex) = 0;
+
+	//! Unlock a mutex
 	virtual void		unlockMutex(CArchMutex) = 0;
 
 	//
 	// thread methods
 	//
 
-	virtual CArchThread	newThread(ThreadFunc, void*) = 0;
+	//! Start a new thread
+	/*!
+	Creates and starts a new thread, using \c func as the entry point
+	and passing it \c userData.  The thread is an opaque data type.
+	*/
+	virtual CArchThread	newThread(ThreadFunc func, void* userData) = 0;
+
+	//! Get a reference to the calling thread
+	/*!
+	Returns a thread representing the current (i.e. calling) thread.
+	*/
 	virtual CArchThread	newCurrentThread() = 0;
-	virtual CArchThread	copyThread(CArchThread) = 0;
+
+	//! Copy a thread object
+	/*!
+	Returns a reference to to thread referred to by \c thread.
+	*/
+	virtual CArchThread	copyThread(CArchThread thread) = 0;
+
+	//! Release a thread reference
+	/*!
+	Deletes the given thread object.  This does not destroy the thread
+	the object referred to, even if there are no remaining references.
+	Use cancelThread() and waitThread() to stop a thread and wait for
+	it to exit.
+	*/
 	virtual void		closeThread(CArchThread) = 0;
-	virtual void		cancelThread(CArchThread) = 0;
+
+	//! Force a thread to exit
+	/*!
+	Causes \c thread to exit when it next calls a cancellation point.
+	A thread avoids cancellation as long as it nevers calls a
+	cancellation point.  Once it begins the cancellation process it
+	must always let cancellation go to completion but may take as
+	long as necessary to clean up.
+	*/
+	virtual void		cancelThread(CArchThread thread) = 0;
+
+	//! Change thread priority
+	/*!
+	Changes the priority of \c thread by \c n.  If \c n is positive
+	the thread has a lower priority and if negative a higher priority.
+	Some architectures may not support either or both directions.
+	*/
 	virtual void		setPriorityOfThread(CArchThread, int n) = 0;
+
+	//! Cancellation point
+	/*!
+	This method does nothing but is a cancellation point.  Clients
+	can make their own functions cancellation points by calling this
+	method at appropriate times.
+	*/
 	virtual void		testCancelThread() = 0;
-	virtual bool		wait(CArchThread, double timeout) = 0;
+
+	//! Wait for a thread to exit
+	/*!
+	Waits for up to \c timeout seconds for \c thread to exit (normally
+	or by cancellation).  Waits forever if \c timeout < 0.  Returns
+	true if the thread exited, false otherwise.  Waiting on the current
+	thread returns immediately with false.
+
+	(Cancellation point)
+	*/
+	virtual bool		wait(CArchThread thread, double timeout) = 0;
+
+	//! Wait for a user event
+	/*!
+	Waits for up to \c timeout seconds for a pending user event.
+	Returns true if an event occurred, false otherwise.
+
+	This method is not required by all platforms.
+
+	(Cancellation point)
+	*/
 	virtual bool		waitForEvent(double timeout) = 0;
+
+	//! Compare threads
+	/*!
+	Returns true iff two thread objects refer to the same thread.
+	Note that comparing thread objects directly is meaningless.
+	*/
 	virtual bool		isSameThread(CArchThread, CArchThread) = 0;
-	virtual bool		isExitedThread(CArchThread) = 0;
-	virtual void*		getResultOfThread(CArchThread) = 0;
-	virtual ThreadID	getIDOfThread(CArchThread) = 0;
+
+	//! Test if thread exited
+	/*!
+	Returns true iff \c thread has exited.
+	*/
+	virtual bool		isExitedThread(CArchThread thread) = 0;
+
+	//! Returns the exit code of a thread
+	/*!
+	Waits indefinitely for \c thread to exit (if it hasn't yet) then
+	returns the thread's exit code.
+
+	(Cancellation point)
+	*/
+	virtual void*		getResultOfThread(CArchThread thread) = 0;
+
+	//! Returns an ID for a thread
+	/*!
+	Returns some ID number for \c thread.  This is for logging purposes.
+	All thread objects referring to the same thread return the same ID.
+	However, clients should us isSameThread() to compare thread objects
+	instead of comparing IDs.
+	*/
+	virtual ThreadID	getIDOfThread(CArchThread thread) = 0;
 
 	//@}
 };

lib/arch/IArchNetwork.h

@@ -18,9 +18,33 @@
 #include "IInterface.h"
 #include "stdstring.h"
 
+/*!      
+\class CArchSocketImpl
+\brief Internal socket data.
+An architecture dependent type holding the necessary data for a socket.
+*/
 class CArchSocketImpl;
-class CArchNetAddressImpl;
+
+/*!      
+\var CArchSocket
+\brief Opaque socket type.
+An opaque type representing a socket.
+*/
 typedef CArchSocketImpl* CArchSocket;
+
+/*!      
+\class CArchNetAddressImpl
+\brief Internal network address data.
+An architecture dependent type holding the necessary data for a network
+address.
+*/
+class CArchNetAddressImpl;
+
+/*!      
+\var CArchNetAddress
+\brief Opaque network address type.
+An opaque type representing a network address.
+*/
 typedef CArchNetAddressImpl* CArchNetAddress;
 
 //! Interface for architecture dependent networking
@@ -30,47 +54,171 @@ synergy.  Each architecture must implement this interface.
 */
 class IArchNetwork : public IInterface {
 public:
+	//! Supported address families
 	enum EAddressFamily {
 		kUNKNOWN,
 		kINET,
 	};
 
+	//! Supported socket types
 	enum ESocketType {
 		kDGRAM,
 		kSTREAM
 	};
 
+	//! Events for \c poll()
+	/*!
+	Events for \c poll() are bitmasks and can be combined using the
+	bitwise operators.
+	*/
 	enum {
-		kPOLLIN   = 1,
-		kPOLLOUT  = 2,
-		kPOLLERR  = 4,
-		kPOLLNVAL = 8
+		kPOLLIN   = 1,		//!< Socket is readable
+		kPOLLOUT  = 2,		//!< Socket is writable
+		kPOLLERR  = 4,		//!< The socket is in an error state
+		kPOLLNVAL = 8		//!< The socket is invalid
 	};
 
+	//! A socket query for \c poll()
 	class CPollEntry {
 	public:
+		//! The socket to query
 		CArchSocket		m_socket;
+
+		//! The events to query for
+		/*!
+		The events to query for can be any combination of kPOLLIN and
+		kPOLLOUT.
+		*/
 		unsigned short	m_events;
+
+		//! The result events
 		unsigned short	m_revents;
 	};
 
 	//! @name manipulators
 	//@{
 
+	//! Create a new socket
+	/*!
+	The socket is an opaque data type.
+	*/
 	virtual CArchSocket	newSocket(EAddressFamily, ESocketType) = 0;
+
+	//! Copy a socket object
+	/*!
+	Returns a reference to to socket referred to by \c s.
+	*/
 	virtual CArchSocket	copySocket(CArchSocket s) = 0;
+
+	//! Release a socket reference
+	/*!
+	Deletes the given socket object.  This does not destroy the socket
+	the object referred to until there are no remaining references for
+	the socket.
+	*/
 	virtual void		closeSocket(CArchSocket s) = 0;
+
+	//! Close socket for further reads
+	/*!
+	Calling this disallows future reads on socket \c s.
+	*/
 	virtual void		closeSocketForRead(CArchSocket s) = 0;
+
+	//! Close socket for further writes
+	/*!
+	Calling this disallows future writes on socket \c s.
+	*/
 	virtual void		closeSocketForWrite(CArchSocket s) = 0;
+
+	//! Bind socket to address
+	/*!
+	Binds socket \c s to the address \c addr.
+	*/
 	virtual void		bindSocket(CArchSocket s, CArchNetAddress addr) = 0;
+
+	//! Listen for connections on socket
+	/*!
+	Causes the socket \c s to begin listening for incoming connections.
+	*/
 	virtual void		listenOnSocket(CArchSocket s) = 0;
+
+	//! Accept connection on socket
+	/*!
+	Accepts a connection on socket \c s, returning a new socket for the
+	connection and filling in \c addr with the address of the remote
+	end.  \c addr may be NULL if the remote address isn't required.
+	The original socket \c s is unaffected and remains in the listening
+	state.  The new socket shares most of the properties of \c s except
+	it's not in the listening state, it's connected, and is not
+	non-blocking even is \c s is.
+
+	This call blocks if \c s is not non-blocking and there are no
+	pending connection requests.
+
+	(Cancellation point)
+	*/
 	virtual CArchSocket	acceptSocket(CArchSocket s, CArchNetAddress* addr) = 0;
-	virtual void		connectSocket(CArchSocket s, CArchNetAddress name) = 0;
+
+	//! Connect socket
+	/*!
+	Connects the socket \c s to the remote address \c addr.  This call
+	blocks if \c s is not non-blocking.  If \c s is non-blocking then
+	the client can \c poll() for writability to detect a connection.
+
+	(Cancellation point)
+	*/
+	virtual void		connectSocket(CArchSocket s, CArchNetAddress addr) = 0;
+
+	//! Check socket state
+	/*!
+	Tests the state of \c num sockets for readability and/or writability.
+	Waits up to \c timeout seconds for some socket to become readable
+	and/or writable (or indefinitely if \c timeout < 0).  Returns the
+	number of sockets that were readable (if readability was being
+	queried) or writable (if writablility was being queried) and sets
+	the \c m_revents members of the entries.  \c kPOLLERR and \c kPOLLNVAL
+	are set in \c m_revents as appropriate.  If a socket indicates
+	\c kPOLLERR then \c throwErrorOnSocket() can be used to determine
+	the type of error.
+
+	(Cancellation point)
+	*/
 	virtual int			pollSocket(CPollEntry[], int num, double timeout) = 0;
+
+	//! Read data from socket
+	/*!
+	Read up to \c len bytes from socket \c s in \c buf and return the
+	number of bytes read.  The number of bytes can be less than \c len
+	if not enough data is available.  Returns 0 if the remote end has
+	disconnected and there is no more queued received data.  Blocks if
+	the socket is not non-blocking and there is no queued received data.
+	If non-blocking and there is no queued received data then throws
+	XArchNetworkWouldBlock.
+
+	(Cancellation point)
+	*/
 	virtual size_t		readSocket(CArchSocket s, void* buf, size_t len) = 0;
+
+	//! Write data from socket
+	/*!
+	Write up to \c len bytes to socket \c s from \c buf and return the
+	number of bytes written.  The number of bytes can be less than
+	\c len if the remote end disconnected or the socket is non-blocking
+	and the internal buffers are full.  If non-blocking and the internal
+	buffers are full before any data is written then throws
+	XArchNetworkWouldBlock.
+
+	(Cancellation point)
+	*/
 	virtual size_t		writeSocket(CArchSocket s,
 							const void* buf, size_t len) = 0;
-	virtual void		throwErrorOnSocket(CArchSocket) = 0;
+
+	//! Check error on socket
+	/*!
+	If the socket \c s is in an error state then throws an appropriate
+	XArchNetwork exception.
+	*/
+	virtual void		throwErrorOnSocket(CArchSocket s) = 0;
 
 	//! Set socket to (non-)blocking operation
 	/*!
@@ -87,17 +235,42 @@ public:
 	*/
 	virtual bool		setNoDelayOnSocket(CArchSocket, bool noDelay) = 0;
 
+	//! Return local host's name
 	virtual std::string		getHostName() = 0;
+
+	//! Create an "any" network address
 	virtual CArchNetAddress	newAnyAddr(EAddressFamily) = 0;
+
+	//! Copy a network address
 	virtual CArchNetAddress	copyAddr(CArchNetAddress) = 0;
+
+	//! Convert a name to a network address
 	virtual CArchNetAddress	nameToAddr(const std::string&) = 0;
+
+	//! Destroy a network address
 	virtual void			closeAddr(CArchNetAddress) = 0;
+
+	//! Convert an address to a host name
 	virtual std::string		addrToName(CArchNetAddress) = 0;
+
+	//! Convert an address to a string
 	virtual std::string		addrToString(CArchNetAddress) = 0;
+
+	//! Get an address's family
 	virtual EAddressFamily	getAddrFamily(CArchNetAddress) = 0;
+
+	//! Set the port of an address
 	virtual void			setAddrPort(CArchNetAddress, int port) = 0;
+
+	//! Get the port of an address
 	virtual int				getAddrPort(CArchNetAddress) = 0;
-	virtual bool			isAnyAddr(CArchNetAddress) = 0;
+
+	//! Test for the "any" address
+	/*!
+	Returns true if \c addr is the "any" address.  \c newAnyAddr()
+	returns an "any" address.
+	*/
+	virtual bool			isAnyAddr(CArchNetAddress addr) = 0;
 
 	//@}
 };

lib/arch/IArchSleep.h

@@ -17,6 +17,11 @@
 
 #include "IInterface.h"
 
+//! Interface for architecture dependent sleeping
+/*!
+This interface defines the sleep operations required by
+synergy.  Each architecture must implement this interface.
+*/
 class IArchSleep : public IInterface {
 public:
 	//! @name manipulators

lib/arch/IArchString.h

@@ -18,11 +18,39 @@
 #include "IInterface.h"
 #include <stdarg.h>
 
+/*!      
+\class CArchMBStateImpl
+\brief Internal multibyte conversion data.
+An architecture dependent type holding the necessary data for a
+multibyte to/from wide character conversion.
+*/
 class CArchMBStateImpl;
+
+/*!      
+\var CArchMBState
+\brief Opaque multibyte conversion state type.
+An opaque type representing multibyte conversion state.
+*/
 typedef CArchMBStateImpl* CArchMBState;
 
+//! Interface for architecture dependent string operations
+/*!
+This interface defines the string operations required by
+synergy.  Each architecture must implement this interface.
+*/
 class IArchString : public IInterface {
 public:
+	//! Wide character encodings
+	/*!
+	The known wide character encodings
+	*/
+	enum EWideCharEncoding {
+		kUCS2,		//!< The UCS-2 encoding
+		kUCS4,		//!< The UCS-4 encoding
+		kUTF16,		//!< The UTF-16 encoding
+		kUTF32		//!< The UTF-32 encoding
+	};
+
 	//! @name manipulators
 	//@{
 
@@ -55,6 +83,10 @@ public:
 	//! Convert wide character to multibyte
 	virtual int			convWCToMB(char*, wchar_t, CArchMBState) = 0;
 
+	//! Return the architecture's native wide character encoding
+	virtual EWideCharEncoding
+						getWideCharEncoding() = 0;
+
 	//@}
 };
 

lib/arch/IArchTime.h

@@ -17,6 +17,11 @@
 
 #include "IInterface.h"
 
+//! Interface for architecture dependent time operations
+/*!
+This interface defines the time operations required by
+synergy.  Each architecture must implement this interface.
+*/
 class IArchTime : public IInterface {
 public:
 	//! @name manipulators

lib/arch/Makefile.am

@@ -61,7 +61,6 @@ libarch_a_SOURCES =				\
 	IArchString.h				\
 	IArchTime.h					\
 	XArch.h						\
-	XArchImpl.h					\
 	$(NULL)
 EXTRA_libarch_a_SOURCES =		\
 	CArchConsoleUnix.cpp		\

lib/arch/XArchImpl.h

@@ -1,25 +0,0 @@
-/*
- * synergy -- mouse and keyboard sharing utility
- * Copyright (C) 2002 Chris Schoeneman
- * 
- * This package is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License
- * found in the file COPYING that should have accompanied this file.
- * 
- * This package is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- */
-
-#ifndef XARCHIMPL_H
-#define XARCHIMPL_H
-
-// include appropriate architecture implementation
-#if WINDOWS_LIKE
-#	include "XArchWindows.h"
-#elif UNIX_LIKE
-#	include "XArchUnix.h"
-#endif
-
-#endif

lib/arch/arch.dsp

@@ -179,10 +179,6 @@ SOURCE=.\XArch.h
 # End Source File
 # Begin Source File
 
-SOURCE=.\XArchImpl.h
-# End Source File
-# Begin Source File
-
 SOURCE=.\XArchWindows.h
 # End Source File
 # End Group