From 8913acac345c93129a6df19f6f0fb0684895f219 Mon Sep 17 00:00:00 2001 From: crs Date: Tue, 30 Jul 2002 14:59:36 +0000 Subject: [PATCH] Added doxygen comments for all relevant headers in client and server. --- client/CClient.h | 46 ++++- client/CMSWindowsSecondaryScreen.h | 1 + client/CSecondaryScreen.h | 301 ++++++++++++++++++++++------ client/CServerProxy.cpp | 6 +- client/CServerProxy.h | 51 ++++- client/CXWindowsSecondaryScreen.h | 1 + server/CClientProxy.h | 26 ++- server/CClientProxy1_0.h | 1 + server/CConfig.h | 156 +++++++++++---- server/CHTTPServer.cpp | 23 ++- server/CHTTPServer.h | 32 ++- server/CMSWindowsPrimaryScreen.h | 1 + server/CPrimaryClient.h | 47 ++++- server/CPrimaryScreen.h | 305 +++++++++++++++++++++-------- server/CServer.h | 66 +++++-- server/CXWindowsPrimaryScreen.h | 1 + synergy/IClient.h | 14 +- synergy/IScreen.h | 3 +- synergy/IScreenReceiver.h | 3 +- synergy/IServer.h | 3 +- 20 files changed, 848 insertions(+), 239 deletions(-) diff --git a/client/CClient.h b/client/CClient.h index 2e8e2256..7b3925e0 100644 --- a/client/CClient.h +++ b/client/CClient.h @@ -13,31 +13,57 @@ class CThread; class IDataSocket; class IScreenReceiver; +//! Synergy client +/*! +This class implements the top-level client algorithms for synergy. +*/ class CClient : public IScreenReceiver, public IClient { public: + /*! + This client will attempt to connect the server using \c clientName + as its name. + */ CClient(const CString& clientName); ~CClient(); - // manipulators + //! @name manipulators + //@{ - // turn camping on or off. when camping the client will keep - // trying to connect to the server until it succeeds. this - // is useful if the client may start before the server. do - // not call this while in run(). + //! Set camping state + /*! + Turns camping on or off. When camping the client will keep + trying to connect to the server until it succeeds. This + is useful if the client may start before the server. Do + not call this while in run(). + */ void camp(bool on); - // set the server's address that the client should connect to + //! Set server address + /*! + Sets the server's address that the client should connect to. + */ void setAddress(const CNetworkAddress& serverAddress); - // tell client to exit run() gracefully. this must only be called - // after a successful open(). + //! Exit event loop + /*! + Force run() to return. This call can return before + run() does (i.e. asynchronously). This may only be + called between a successful open() and close(). + */ void quit(); - // accessors + //@} + //! @name accessors + //@{ - // returns true if the server rejected us + //! + /*! + Returns true if the server rejected our connection. + */ bool wasRejected() const; + //@} + // IScreenReceiver overrides virtual void onError(); virtual void onInfoChanged(const CClientInfo&); diff --git a/client/CMSWindowsSecondaryScreen.h b/client/CMSWindowsSecondaryScreen.h index b98a4251..67d24694 100644 --- a/client/CMSWindowsSecondaryScreen.h +++ b/client/CMSWindowsSecondaryScreen.h @@ -16,6 +16,7 @@ class CMSWindowsScreen; class IScreenReceiver; +//! Microsoft windows secondary screen implementation class CMSWindowsSecondaryScreen : public CSecondaryScreen, public IMSWindowsScreenEventHandler { public: diff --git a/client/CSecondaryScreen.h b/client/CSecondaryScreen.h index 4db665f1..5c4d9fe8 100644 --- a/client/CSecondaryScreen.h +++ b/client/CSecondaryScreen.h @@ -9,126 +9,305 @@ class IClipboard; class IScreen; -// platform independent base class for secondary screen implementations. -// each platform will derive a class from CSecondaryScreen to handle -// platform dependent operations. +//! Generic client-side screen +/*! +This is a platform independent base class for secondary screen +implementations. A secondary screen is a client-side screen. +Each platform will derive a class from CSecondaryScreen to handle +platform dependent operations. +*/ class CSecondaryScreen { public: CSecondaryScreen(); virtual ~CSecondaryScreen(); - // manipulators + //! @name manipulators + //@{ - // enter the screen's message loop. this returns when it detects - // the application should terminate or when stop() is called. - // run() may only be called between open() and close(). - void run(); - - // cause run() to return - void stop(); - - // initialize the screen, hide the cursor, and disable the screen - // saver. start reporting events to the IScreenReceiver (which is - // set through some other interface). + //! Open screen + /*! + Opens the screen. This includes initializing the screen, + hiding the cursor, and disabling the screen saver. It also causes + events to the reported to an IScreenReceiver (which is set through + some other interface). Calls close() before returning (rethrowing) + if it fails for any reason. + */ void open(); - // close the screen. should restore the screen saver. it should - // also simulate key up events for any keys that have simulate key - // down events without a matching key up. without this the client - // will leave its keyboard in the wrong logical state. + //! Run event loop + /*! + Run the screen's event loop. This returns when it detects + the application should terminate or when stop() is called. + run() may only be called between open() and close(). + */ + void run(); + + //! Exit event loop + /*! + Force run() to return. This call can return before + run() does (i.e. asynchronously). + */ + void stop(); + + //! Close screen + /*! + Closes the screen. This restores the screen saver, shows the cursor + and closes the screen. It also synthesizes key up events for any + keys that are logically down; without this the client will leave + its keyboard in the wrong logical state. + */ void close(); - // called when the user navigates to this secondary screen. warps - // the cursor to the given absoltue coordinates and unhide it. prepare to - // simulate input events. + //! Enter screen + /*! + Called when the user navigates to this secondary screen. Warps + the cursor to the absolute coordinates \c x,y and unhides + it. Also prepares to synthesize input events. + */ void enter(SInt32 x, SInt32 y, KeyModifierMask mask); - // called when the user navigates off the secondary screen. clean - // up input event simulation and hide the cursor. + //! Leave screen + /*! + Called when the user navigates off the secondary screen. Cleans + up input event synthesis and hides the cursor. + */ void leave(); - // set the screen's clipboard contents. this is usually called - // soon after an enter(). + //! Set clipboard + /*! + Sets the system's clipboard contents. This is usually called + soon after an enter(). + */ void setClipboard(ClipboardID, const IClipboard*); - // synergy should own the clipboard + //! Grab clipboard + /*! + Grabs (i.e. take ownership of) the system clipboard. + */ void grabClipboard(ClipboardID); - // activate or deactivate the screen saver + //! Activate/deactivate screen saver + /*! + Forcibly activates the screen saver if \c activate is true otherwise + forcibly deactivates it. + */ void screensaver(bool activate); - // keyboard input event synthesis - virtual void keyDown(KeyID, KeyModifierMask) = 0; - virtual void keyRepeat(KeyID, KeyModifierMask, SInt32 count) = 0; - virtual void keyUp(KeyID, KeyModifierMask) = 0; + //! Notify of key press + /*! + Synthesize key events to generate a press of key \c id. If possible + match the given modifier mask. + */ + virtual void keyDown(KeyID id, KeyModifierMask) = 0; - // mouse input event synthesis - virtual void mouseDown(ButtonID) = 0; - virtual void mouseUp(ButtonID) = 0; - virtual void mouseMove(SInt32 xAbsolute, SInt32 yAbsolute) = 0; + //! Notify of key repeat + /*! + Synthesize key events to generate a press and release of key \c id + \c count times. If possible match the given modifier mask. + */ + virtual void keyRepeat(KeyID id, KeyModifierMask, SInt32 count) = 0; + + //! Notify of key release + /*! + Synthesize key events to generate a release of key \c id. If possible + match the given modifier mask. + */ + virtual void keyUp(KeyID id, KeyModifierMask) = 0; + + //! Notify of mouse press + /*! + Synthesize mouse events to generate a press of mouse button \c id. + */ + virtual void mouseDown(ButtonID id) = 0; + + //! Notify of mouse release + /*! + Synthesize mouse events to generate a release of mouse button \c id. + */ + virtual void mouseUp(ButtonID id) = 0; + + //! Notify of mouse motion + /*! + Synthesize mouse events to generate mouse motion to the absolute + screen position \c xAbs,yAbs. + */ + virtual void mouseMove(SInt32 xAbs, SInt32 yAbs) = 0; + + //! Notify of mouse wheel motion + /*! + Synthesize mouse events to generate mouse wheel motion of \c delta. + \c delta is positive for motion away from the user and negative for + motion towards the user. Each wheel click should generate a delta + of +/-120. + */ virtual void mouseWheel(SInt32 delta) = 0; - // accessors + //@} + //! @name accessors + //@{ - // returns true iff the screen is active (i.e. the user has entered - // the screen) + //! Test if active + /*! + Returns true iff the screen is active (i.e. the user has entered + the screen). Note this is the reverse of a primary screen. + */ bool isActive() const; - // return the contents of the given clipboard - void getClipboard(ClipboardID, IClipboard*) const; + //! Get clipboard + /*! + Saves the contents of the system clipboard indicated by \c id. + */ + void getClipboard(ClipboardID id, IClipboard*) const; - // returns the size of the zone on the edges of the screen that - // causes the cursor to jump to another screen. + //! Get jump zone size + /*! + Return the jump zone size, the size of the regions on the edges of + the screen that cause the cursor to jump to another screen. + */ virtual SInt32 getJumpZoneSize() const = 0; - // get the shape (position of upper-left corner and size) of the - // screen + //! Get screen shape + /*! + Return the position of the upper-left corner of the screen in \c x and + \c y and the size of the screen in \c width and \c height. + */ virtual void getShape(SInt32& x, SInt32& y, SInt32& width, SInt32& height) const; - // get the position of the mouse on the screen + //! Get cursor position + /*! + Return the current position of the cursor in \c x,y. + */ virtual void getCursorPos(SInt32& x, SInt32& y) const; - // get the platform dependent screen object + //! Get screen + /*! + Return the platform dependent screen. + */ virtual IScreen* getScreen() const = 0; + //@} + protected: - // template method hooks. these are called on entry/exit to the - // named method. override to do platform specific operations. - // defaults do nothing. + //! Pre-run() hook + /*! + Called on entry to run(). Override to perform platform specific + operations. Default does nothing. May throw. + */ virtual void onPreRun(); + + //! Post-run() hook + /*! + Called on exit from run(). Override to perform platform specific + operations. Default does nothing. May \b not throw. + */ virtual void onPostRun(); + + //! Pre-open() hook + /*! + Called on entry to open(). Override to perform platform specific + operations. Default does nothing. May throw. + */ virtual void onPreOpen(); + + //! Post-open() hook + /*! + Called on exit from open() iff the open was successful. Default + does nothing. May throw. + */ virtual void onPostOpen(); + + //! Pre-close() hook + /*! + Called on entry to close(). Override to perform platform specific + operations. Default does nothing. May \b not throw. + */ virtual void onPreClose(); + + //! Post-close() hook + /*! + Called on exit from close(). Override to perform platform specific + operations. Default does nothing. May \b not throw. + */ virtual void onPostClose(); + + //! Pre-enter() hook + /*! + Called on entry to enter() after desktop synchronization. Override + to perform platform specific operations. Default does nothing. May + \b not throw. + */ virtual void onPreEnter(); + + //! Post-enter() hook + /*! + Called on exit from enter(). Override to perform platform specific + operations. Default does nothing. May \b not throw. + */ virtual void onPostEnter(); + + //! Pre-leave() hook + /*! + Called on entry to leave() after desktop synchronization. Override + to perform platform specific operations. Default does nothing. May + \b not throw. + */ virtual void onPreLeave(); + + //! Post-leave() hook + /*! + Called on exit from leave(). Override to perform platform specific + operations. Default does nothing. May \b not throw. + */ virtual void onPostLeave(); - // create/destroy the window. this window is generally used to - // receive events and hide the cursor. + //! Create window + /*! + Called to create the window. This window is generally used to + receive events and hide the cursor. + */ virtual void createWindow() = 0; + + //! Destroy window + /*! + Called to destroy the window created by createWindow(). + */ virtual void destroyWindow() = 0; - // called when the user navigates off the secondary screen. hide - // the cursor. + //! Show window + /*! + Called when the user navigates off this secondary screen. It needn't + actually show the window created by createWindow() but it must hide + the cursor and clean up event synthesis. + */ virtual void showWindow() = 0; - // called when the user navigates to this secondary screen. show - // the cursor and prepare to synthesize input events. + //! Hide window + /*! + Called when the user navigates to this secondary screen. It should + hide the window (if shown), show the cursor, and prepare to synthesize + input events. + */ virtual void hideWindow() = 0; - // warp the cursor to the given absolute coordinates + //! Warp cursor + /*! + Warp the cursor to the absolute coordinates \c x,y. + */ virtual void warpCursor(SInt32 x, SInt32 y) = 0; - // check the current keyboard state. normally a screen will save - // the keyboard state in this method and use this shadow state - // when synthesizing events. + //! Synchronize key state + /*! + Check the current keyboard state. Normally a screen will save + the keyboard state in this method and use this shadow state + when synthesizing events. + */ virtual void updateKeys() = 0; - // toggle modifiers that don't match the given state + //! Synchronize toggle key state + /*! + Toggle modifiers that don't match the given state so that they do. + */ virtual void setToggleState(KeyModifierMask) = 0; private: diff --git a/client/CServerProxy.cpp b/client/CServerProxy.cpp index b8a9a3b3..bec9d1ce 100644 --- a/client/CServerProxy.cpp +++ b/client/CServerProxy.cpp @@ -15,10 +15,10 @@ // CServerProxy::CServerProxy(IClient* client, - IInputStream* input, IOutputStream* output) : + IInputStream* adoptedInput, IOutputStream* adoptedOutput) : m_client(client), - m_input(input), - m_output(output), + m_input(adoptedInput), + m_output(adoptedOutput), m_seqNum(0) { assert(m_client != NULL); diff --git a/client/CServerProxy.h b/client/CServerProxy.h index e7f48d19..d0eecc21 100644 --- a/client/CServerProxy.h +++ b/client/CServerProxy.h @@ -8,31 +8,60 @@ class IClient; class IInputStream; class IOutputStream; +//! Proxy for server +/*! +This class acts a proxy for the server, converting calls into messages +to the server and messages from the server to calls on the client. +*/ class CServerProxy : public IScreenReceiver { public: + /*! \c adoptedInput is the stream from the server and + \c adoptedOutput is the stream to the server. This object + takes ownership of both and destroys them in the d'tor. + Messages from the server are converted to calls on \c client. + */ CServerProxy(IClient* client, IInputStream* adoptedInput, IOutputStream* adoptedOutput); ~CServerProxy(); - // manipulators + //! @name manipulators + //@{ - // handle messages. returns true iff server didn't reject our - // connection. + //! Run event loop + /*! + Run the event loop and return when the server disconnects or + requests the client to disconnect. Return true iff the server + didn't reject our connection. + + (cancellation point) + */ bool run(); - // accessors + //@} + //! @name accessors + //@{ - // get the client + //! Get client + /*! + Returns the client passed to the c'tor. + */ IClient* getClient() const; - // get the client name - CString getName() const; - - // get the input and output streams for the server + //! Get input stream + /*! + Return the input stream passed to the c'tor. + */ IInputStream* getInputStream() const; + + //! Get output stream + /*! + Return the output stream passed to the c'tor. + */ IOutputStream* getOutputStream() const; + //@} + // IScreenReceiver overrides virtual void onError(); virtual void onInfoChanged(const CClientInfo&); @@ -40,6 +69,10 @@ public: virtual void onClipboardChanged(ClipboardID, const CString& data); private: + + // get the client name (from the client) + CString getName() const; + // if compressing mouse motion then send the last motion now void flushCompressedMouse(); diff --git a/client/CXWindowsSecondaryScreen.h b/client/CXWindowsSecondaryScreen.h index 07ddb346..113eb03e 100644 --- a/client/CXWindowsSecondaryScreen.h +++ b/client/CXWindowsSecondaryScreen.h @@ -14,6 +14,7 @@ class CXWindowsScreen; class IScreenReceiver; +//! X11 secondary screen implementation class CXWindowsSecondaryScreen : public CSecondaryScreen, public IScreenEventHandler { public: diff --git a/server/CClientProxy.h b/server/CClientProxy.h index 8eb07a93..7d7c4c31 100644 --- a/server/CClientProxy.h +++ b/server/CClientProxy.h @@ -8,24 +8,40 @@ class IInputStream; class IOutputStream; class IServer; +//! Generic proxy for client class CClientProxy : public IClient { public: + /*! + \c name is the name of the client. + */ CClientProxy(IServer* server, const CString& name, IInputStream* adoptedInput, IOutputStream* adoptedOutput); ~CClientProxy(); - // manipulators + //! @name accessors + //@{ - // accessors - - // get the server + //! Get server + /*! + Returns the server passed to the c'tor. + */ IServer* getServer() const; - // get the input and output streams for the client + //! Get input stream + /*! + Returns the input stream passed to the c'tor. + */ IInputStream* getInputStream() const; + + //! Get output stream + /*! + Returns the output stream passed to the c'tor. + */ IOutputStream* getOutputStream() const; + //@} + // IClient overrides virtual bool open() = 0; virtual void run() = 0; diff --git a/server/CClientProxy1_0.h b/server/CClientProxy1_0.h index 80b20cb1..0f5679a0 100644 --- a/server/CClientProxy1_0.h +++ b/server/CClientProxy1_0.h @@ -5,6 +5,7 @@ #include "ProtocolTypes.h" #include "CMutex.h" +//! Proxy for client implementing protocol version 1.0 class CClientProxy1_0 : public CClientProxy { public: CClientProxy1_0(IServer* server, const CString& name, diff --git a/server/CConfig.h b/server/CConfig.h index a67d211f..dfbd4b50 100644 --- a/server/CConfig.h +++ b/server/CConfig.h @@ -20,6 +20,16 @@ struct iterator_traits { }; }; +//! Server configuration +/*! +This class holds server configuration information. That includes +the names of screens and their aliases, the links between them, +and network addresses. + +Note that case is preserved in screen names but is ignored when +comparing names. Screen names and their aliases share a +namespace and must be unique. +*/ class CConfig { private: class CCell { @@ -59,79 +69,155 @@ public: CConfig(); virtual ~CConfig(); - // manipulators + //! @name manipulators + //@{ - // note that case is preserved in screen names but is ignored when - // comparing names. screen names and their aliases share a - // namespace and must be unique. - - // add/remove screens. addScreen() returns false if the name - // already exists. the remove methods automatically remove - // aliases for the named screen and disconnect any connections - // to the removed screen(s). + //! Add screen + /*! + Adds a screen, returning true iff successful. If a screen or + alias with the given name exists then it fails. + */ bool addScreen(const CString& name); + + //! Remove screen + /*! + Removes a screen. This also removes aliases for the screen and + disconnects any connections to the screen. \c name may be an + alias. + */ void removeScreen(const CString& name); + + //! Remove all screens + /*! + Removes all screens, aliases, and connections. + */ void removeAllScreens(); - // add/remove alias for a screen name. an alias can be used - // any place the canonical screen name can (except addScreen). - // addAlias() returns false if the alias name already exists - // or the canonical name is unknown. removeAlias() fails if - // the alias is unknown or a canonical name. + //! Add alias + /*! + Adds an alias for a screen name. An alias can be used + any place the canonical screen name can (except addScreen()). + Returns false if the alias name already exists or the canonical + name is unknown, otherwise returns true. + */ bool addAlias(const CString& canonical, const CString& alias); + + //! Remove alias + /*! + Removes an alias for a screen name. It returns false if the + alias is unknown or a canonical name, otherwise returns true. + */ bool removeAlias(const CString& alias); + + //! Remove all aliases + /*! + This removes all aliases but not the screens. + */ void removeAllAliases(); - // connect/disconnect edges. both return false if srcName is - // unknown. + //! Connect screens + /*! + Establishes a one-way connection between opposite edges of two + screens. The user will be able to jump from the \c srcSide of + screen \c srcName to the opposite side of screen \c dstName + when both screens are connected to the server and the user + isn't locked to a screen. Returns false if \c srcName is + unknown. + */ bool connect(const CString& srcName, EDirection srcSide, const CString& dstName); + + //! Disconnect screens + /*! + Removes a connection created by connect(). Returns false if + \c srcName is unknown. + */ bool disconnect(const CString& srcName, EDirection srcSide); - // set the synergy and http listen addresses. there are no - // default addresses. + //! Set server address + /*! + Set the synergy listen addresses. There is no default address so + this must be called to run a server using this configuration. + */ void setSynergyAddress(const CNetworkAddress&); + + //! Set HTTP server address + /*! + Set the HTTP listen addresses. There is no default address so + this must be called to run an HTTP server using this configuration. + */ void setHTTPAddress(const CNetworkAddress&); - // accessors + //@} + //! @name accessors + //@{ - // returns true iff the given name is a valid screen name. - bool isValidScreenName(const CString&) const; + //! Test screen name validity + /*! + Returns true iff \c name is a valid screen name. + */ + bool isValidScreenName(const CString& name) const; - // iterators over (canonical) screen names + //! Get beginning (canonical) screen name iterator const_iterator begin() const; + //! Get ending (canonical) screen name iterator const_iterator end() const; - // returns true iff name names a screen + //! Test for screen name + /*! + Returns true iff \c name names a screen. + */ bool isScreen(const CString& name) const; - // returns true iff name is the canonical name of a screen + //! Test for canonical screen name + /*! + Returns true iff \c name is the canonical name of a screen. + */ bool isCanonicalName(const CString& name) const; - // returns the canonical name of a screen or the empty string if - // the name is unknown. returns the canonical name if one is given. + //! Get canonical name + /*! + Returns the canonical name of a screen or the empty string if + the name is unknown. Returns the canonical name if one is given. + */ CString getCanonicalName(const CString& name) const; - // get the neighbor in the given direction. returns the empty string - // if there is no neighbor in that direction. returns the canonical - // screen name. + //! Get neighbor + /*! + Returns the canonical screen name of the neighbor in the given + direction (set through connect()). Returns the empty string + if there is no neighbor in that direction. + */ CString getNeighbor(const CString&, EDirection) const; - // get the listen addresses + //! Get the server address const CNetworkAddress& getSynergyAddress() const; + //! Get the HTTP server address const CNetworkAddress& getHTTPAddress() const; - // read/write a configuration. operator>> will throw XConfigRead - // on error. + //! Read configuration + /*! + Reads a configuration from a stream. Throws XConfigRead on error. + */ friend std::istream& operator>>(std::istream&, CConfig&); + + //! Write configuration + /*! + Writes a configuration to a stream. + */ friend std::ostream& operator<<(std::ostream&, const CConfig&); - // get the name of a direction (for debugging) + //! Get direction name + /*! + Returns the name of a direction (for debugging). + */ static const char* dirName(EDirection); + //@} + private: static bool readLine(std::istream&, CString&); void readSection(std::istream&); @@ -149,6 +235,10 @@ private: CNetworkAddress m_httpAddress; }; +//! Configuration stream read exception +/*! +Thrown when a configuration stream cannot be parsed. +*/ class XConfigRead : public XBase { public: XConfigRead(const CString&); diff --git a/server/CHTTPServer.cpp b/server/CHTTPServer.cpp index 1ac810ac..e5066fe4 100644 --- a/server/CHTTPServer.cpp +++ b/server/CHTTPServer.cpp @@ -53,8 +53,15 @@ CHTTPServer::processRequest(IDataSocket* socket) request->m_uri = request->m_uri.substr(n); } - // process + // prepare reply CHTTPReply reply; + reply.m_majorVersion = request->m_majorVersion; + reply.m_minorVersion = request->m_minorVersion; + reply.m_status = 200; + reply.m_reason = "OK"; + reply.m_method = request->m_method; + + // process doProcessRequest(*request, reply); // send reply @@ -93,21 +100,19 @@ CHTTPServer::processRequest(IDataSocket* socket) void CHTTPServer::doProcessRequest(CHTTPRequest& request, CHTTPReply& reply) { - reply.m_majorVersion = request.m_majorVersion; - reply.m_minorVersion = request.m_minorVersion; - reply.m_status = 200; - reply.m_reason = "OK"; - reply.m_method = request.m_method; - reply.m_headers.push_back(std::make_pair(CString("Content-Type"), - CString("text/html"))); - // switch based on uri if (request.m_uri == "/editmap") { if (request.m_method == "GET" || request.m_method == "HEAD") { doProcessGetEditMap(request, reply); + reply.m_headers.push_back(std::make_pair( + CString("Content-Type"), + CString("text/html"))); } else if (request.m_method == "POST") { doProcessPostEditMap(request, reply); + reply.m_headers.push_back(std::make_pair( + CString("Content-Type"), + CString("text/html"))); } else { throw XHTTPAllow("GET, HEAD, POST"); diff --git a/server/CHTTPServer.h b/server/CHTTPServer.h index f8c9b241..041f029a 100644 --- a/server/CHTTPServer.h +++ b/server/CHTTPServer.h @@ -11,26 +11,52 @@ class CHTTPRequest; class CHTTPReply; class IDataSocket; +//! Simple HTTP server +/*! +This class implements a simple HTTP server for interacting with the +synergy server. +*/ class CHTTPServer { public: CHTTPServer(CServer*); virtual ~CHTTPServer(); - // manipulators + //! @name manipulators + //@{ - // synchronously process an HTTP request on the given socket + //! Process HTTP request + /*! + Synchronously processes an HTTP request on the given socket. + */ void processRequest(IDataSocket*); - // accessors + //@} protected: + //! Process HTTP request + /*! + Processes a successfully read HTTP request. The reply is partially + filled in (version, method, status (200) and reason (OK)). This + method checks the URI and handles the request, filling in the rest + of the reply. If the request cannot be satisfied it throws an + appropriate XHTTP exception. + */ virtual void doProcessRequest(CHTTPRequest&, CHTTPReply&); + //! Process request for map virtual void doProcessGetEditMap(CHTTPRequest&, CHTTPReply&); + + //! Process request for changing map virtual void doProcessPostEditMap(CHTTPRequest&, CHTTPReply&); + //! Parse coordinate string static bool parseXY(const CString&, SInt32& x, SInt32& y); + //! Screen map helper + /*! + This class represents the screen map as a resizable array. It's + used to handle map requests. + */ class CScreenArray { public: CScreenArray(); diff --git a/server/CMSWindowsPrimaryScreen.h b/server/CMSWindowsPrimaryScreen.h index 3dc2d161..30c06f5d 100644 --- a/server/CMSWindowsPrimaryScreen.h +++ b/server/CMSWindowsPrimaryScreen.h @@ -11,6 +11,7 @@ class CMSWindowsScreen; class IScreenReceiver; class IPrimaryScreenReceiver; +//! Microsoft windows primary screen implementation class CMSWindowsPrimaryScreen : public CPrimaryScreen, public IMSWindowsScreenEventHandler { public: diff --git a/server/CPrimaryClient.h b/server/CPrimaryClient.h index a94da39e..468133d0 100644 --- a/server/CPrimaryClient.h +++ b/server/CPrimaryClient.h @@ -10,29 +10,60 @@ class CPrimaryScreen; class IPrimaryScreenReceiver; class IServer; +//! Primary screen as pseudo-client +/*! +The primary screen does not have a client associated with it. This +class provides a pseudo-client to allow the primary screen to be +treated as if it was on a client. +*/ class CPrimaryClient : public IScreenReceiver, public IClient { public: + /*! + \c name is the name of the server. + */ CPrimaryClient(IServer*, IPrimaryScreenReceiver*, const CString& name); ~CPrimaryClient(); - // manipulators + //! @name manipulators + //@{ - // cause run() to return + //! Exit event loop + /*! + Force run() to return. This call can return before + run() does (i.e. asynchronously). This may only be + called between a successful open() and close(). + */ void stop(); - // called by server when the configuration changes + //! Update configuration + /*! + Handles reconfiguration of jump zones. + */ void reconfigure(UInt32 activeSides); - // accessors + //@} + //! @name accessors + //@{ - // return the contents of the given clipboard. + //! Get clipboard + /*! + Save the marshalled contents of the clipboard indicated by \c id. + */ void getClipboard(ClipboardID, CString&) const; - // returns true iff the user is locked to the primary screen + //! Get toggle key state + /*! + Returns the primary screen's current toggle modifier key state. + */ + KeyModifierMask getToggleMask() const; + + //! Get screen lock state + /*! + Returns true if the user is locked to the screen. + */ bool isLockedToScreen() const; - // returns the state of the toggle keys on the primary screen - KeyModifierMask getToggleMask() const; + //@} // IScreenReceiver overrides virtual void onError(); diff --git a/server/CPrimaryScreen.h b/server/CPrimaryScreen.h index 7fab4eba..1bde5f92 100644 --- a/server/CPrimaryScreen.h +++ b/server/CPrimaryScreen.h @@ -9,140 +9,291 @@ class IClipboard; class IScreen; class IScreenReceiver; -// platform independent base class for primary screen implementations. -// each platform will derive a class from CPrimaryScreen to handle -// platform dependent operations. +//! Generic server-side screen +/*! +This is a platform independent base class for primary screen +implementations. A primary screen is a server-side screen. +Each platform will derive a class from CPrimaryScreen to handle +platform dependent operations. +*/ class CPrimaryScreen { public: CPrimaryScreen(IScreenReceiver*); virtual ~CPrimaryScreen(); - // manipulators + //! @name manipulators + //@{ - // enter the screen's message loop. this returns when it detects - // the application should terminate or when stop() is called. - // run() may only be called between open() and close(). - void run(); - - // cause run() to return - void stop(); - - // initializes the screen and starts reporting events + //! Open screen + /*! + Opens the screen. This includes initializing the screen, opening + the screen saver, synchronizing keyboard state, and causing events + to be reported to an IPrimaryScreenReceiver (set through another + interface). Calls close() before returning (rethrowing) if it + fails for any reason. + */ void open(); - // close the screen + //! Run event loop + /*! + Run the screen's event loop. This returns when it detects + the application should terminate or when stop() is called. + run() may only be called between open() and close(). + */ + void run(); + + //! Exit event loop + /*! + Force run() to return. This call can return before + run() does (i.e. asynchronously). + */ + void stop(); + + //! Close screen + /*! + Closes the screen. This close the screen saver and the screen. + */ void close(); - // called when the user navigates to the primary screen. - // forScreensaver == true means that we're entering the primary - // screen because the screensaver has activated. + //! Enter screen + /*! + Called when the user navigates to the primary screen. Warps + the cursor to the absolute coordinates \c x,y and unhides + it. If \c forScreensaver is true then we're entering because + the screen saver started and the cursor is not warped. + */ void enter(SInt32 x, SInt32 y, bool forScreensaver); - // called when the user navigates off the primary screen. returns - // true iff successful. + //! Leave screen + /*! + Called when the user navigates off the primary screen. Returns + true iff successful. + */ bool leave(); - // called when the configuration has changed. activeSides is a - // bitmask of EDirectionMask indicating which sides of the - // primary screen are linked to clients. + //! Update configuration + /*! + This is called when the configuration has changed. \c activeSides + is a bitmask of EDirectionMask indicating which sides of the + primary screen are linked to clients. Override to handle the + possible change in jump zones. + */ virtual void reconfigure(UInt32 activeSides) = 0; - // warp the cursor to the given absolute coordinates. also - // discard input events up to and including the warp before - // returning. + //! Warp cursor + /*! + Warp the cursor to the absolute coordinates \c x,y. Also + discard input events up to and including the warp before + returning. + */ virtual void warpCursor(SInt32 x, SInt32 y) = 0; - // set the screen's clipboard contents. this is usually called - // soon after an enter(). + //! Set clipboard + /*! + Sets the system's clipboard contents. This is usually called + soon after an enter(). + */ void setClipboard(ClipboardID, const IClipboard*); - // synergy should own the clipboard + //! Grab clipboard + /*! + Grabs (i.e. take ownership of) the system clipboard. + */ void grabClipboard(ClipboardID); - // accessors + //@} + //! @name accessors + //@{ - // returns true iff the screen is active (i.e. the user has left - // the screen) + //! Test if active + /*! + Returns true iff the screen is active (i.e. the user has left + the screen). Note this is the reverse of a secdonary screen. + */ bool isActive() const; - // return the contents of the given clipboard + //! Get clipboard + /*! + Saves the contents of the system clipboard indicated by \c id. + */ void getClipboard(ClipboardID, IClipboard*) const; - // returns the size of the zone on the edges of the screen that - // causes the cursor to jump to another screen. + //! Get jump zone size + /*! + Return the jump zone size, the size of the regions on the edges of + the screen that cause the cursor to jump to another screen. + */ virtual SInt32 getJumpZoneSize() const = 0; - // get the primary screen's current toggle modifier key state. - // the returned mask should have the corresponding bit set for - // each toggle key that is active. + //! Get toggle key state + /*! + Return the primary screen's current toggle modifier key state. + The returned mask should have the corresponding bit set for + each toggle key that is active. For example, if caps lock is + on then the returned mask should have \c KeyModifierCapsLock set. + */ virtual KeyModifierMask getToggleMask() const = 0; - // return true if any key or button is being pressed or if there's - // any other reason that the user should not be allowed to switch - // screens. + //! Get screen lock state + /*! + Return true if any key or button is being pressed or if there's + any other reason that the user should not be allowed to switch + screens. Active toggle keys (including the scroll lock key) + should not be counted as reasons to lock to the screen. + */ virtual bool isLockedToScreen() const = 0; - // get the platform dependent screen object + //! Get screen + /*! + Return the platform dependent screen. + */ virtual IScreen* getScreen() const = 0; + //@} + protected: - // template method hooks. these are called on entry/exit to the - // named method. onEnterScreensaver() is called by enter() iff - // forScreensaver is true. onPostLeave() is passed the result of - // showWindow(). override to do platform specific operations. - // defaults do nothing. + //! Pre-run() hook + /*! + Called on entry to run(). Override to perform platform specific + operations. Default does nothing. May throw. + */ virtual void onPreRun(); + + //! Post-run() hook + /*! + Called on exit from run(). Override to perform platform specific + operations. Default does nothing. May \b not throw. + */ virtual void onPostRun(); + + //! Pre-open() hook + /*! + Called on entry to open(). Override to perform platform specific + operations. Default does nothing. May throw. + */ virtual void onPreOpen(); + + //! Post-open() hook + /*! + Called on exit from open() iff the open was successful. Default + does nothing. May throw. + */ virtual void onPostOpen(); + + //! Pre-close() hook + /*! + Called on entry to close(). Override to perform platform specific + operations. Default does nothing. May \b not throw. + */ virtual void onPreClose(); + + //! Post-close() hook + /*! + Called on exit from close(). Override to perform platform specific + operations. Default does nothing. May \b not throw. + */ virtual void onPostClose(); + + //! Pre-enter() hook + /*! + Called from enter() after the cursor has been warped or, if + \c forScreensaver is true, onEnterScreensaver() was called. Override + to perform platform specific operations. Default does nothing. May + \b not throw. + */ virtual void onPreEnter(); + + //! Post-enter() hook + /*! + Called on exit from enter(). Override to perform platform specific + operations. Default does nothing. May \b not throw. + */ virtual void onPostEnter(); + + //! Pre-enter() for screen saver hook + /*! + Called on entry to enter() if the \c forScreensaver passed to it was + true. Override to perform platform specific operations. Default + does nothing. May \b not throw. + */ virtual void onEnterScreensaver(); + + //! Pre-leave() hook + /*! + Called on entry to leave() after desktop synchronization. Override + to perform platform specific operations. Default does nothing. May + \b not throw. + */ virtual void onPreLeave(); + + //! Post-leave() hook + /*! + Called on exit from leave(). \c success is the value returned by + showWindow(). Override to perform platform specific operations. + Default does nothing. May \b not throw. + */ virtual void onPostLeave(bool success); - // create/destroy the window. this window is generally used to - // receive events and, when the user navigates to another screen, - // to capture keyboard and mouse input. + //! Create window + /*! + Called to create the window. This window is generally used to + receive events, hide the cursor, and to capture keyboard and mouse + input. + */ virtual void createWindow() = 0; + + //! Destroy window + /*! + Called to destroy the window created by createWindow(). + */ virtual void destroyWindow() = 0; - // called when the user navigates off the primary screen. hide the - // cursor and grab exclusive access to the input devices. returns - // true iff successful. every call to showWindow() has a matching - // call to hideWindow() which preceeds it. return true iff - // successful (in particular, iff the input devices were grabbed). - // - // after a successful showWindow(), user input events and - // screensaver activation/deactivation should be reported to an - // IPrimaryScreenReceiver until hideWindow() is called. report - // mouse motion to IPrimaryScreenReceiver::onMouseMoveSecondary(). - // user input should not be delivered to any application except - // synergy. + //! Show window + /*! + Called when the user navigates off the primary screen. Hide the + cursor and grab exclusive access to the input devices. Every call + to showWindow() has a matching call to hideWindow() which preceeds + it. Return true iff successful (in particular, iff the input + devices were grabbed). + + After a successful showWindow(), user input events and + screensaver activation/deactivation should be reported to an + IPrimaryScreenReceiver (set through another interface) until + hideWindow() is called. Report mouse motion to its + onMouseMoveSecondary(). User input should not be delivered to + any application except this one. + */ virtual bool showWindow() = 0; - // called when the user navigates back to the primary screen. show - // the cursor and ungab the input devices. - // - // after hideWindow(), user input events should be delivered normally. - // mouse motion over (at least) the jump zones must be reported to - // an IPrimaryScreenReceiver::onMouseMovePrimary(). + //! Hide window + /*! + Called when the user navigates back to the primary screen. Show + the cursor and ungrab the input devices. + + After hideWindow(), user input events should be delivered normally + to other applications. Mouse motion over (at least) the jump zones + must be reported to an IPrimaryScreenReceiver's onMouseMovePrimary(). + */ virtual void hideWindow() = 0; - // prepare the cursor to report relative motion. when the user has - // navigated to another screen, synergy requires the cursor motion - // deltas, not the absolute coordinates. typically this is done by - // warping the cursor to the center of the primary screen and then - // every time it moves compute the motion and warp back to the - // center (but without reporting that warp as motion). this is - // only called after a successful showWindow(). + //! Warp cursor for relative motion + /*! + Prepare the cursor to report relative motion. When the user has + navigated to another screen, synergy requires the cursor motion + deltas, not the absolute coordinates. Typically this is done by + warping the cursor to the center of the primary screen and then + every time it moves compute the motion and warp back to the + center (but without reporting that warp as motion). This is + only called after a successful showWindow(). + */ virtual void warpCursorToCenter() = 0; - // check the current keyboard state. normally a screen will save - // the keyboard state in this method and use this shadow state - // when handling user input and in methods like isLockedToScreen(). + //! Synchronize key state + /*! + Check the current keyboard state. Normally a screen will save + the keyboard state in this method and use this shadow state + when handling user input and in methods like isLockedToScreen(). + */ virtual void updateKeys() = 0; private: diff --git a/server/CServer.h b/server/CServer.h index 0a34c9a6..a40823fd 100644 --- a/server/CServer.h +++ b/server/CServer.h @@ -20,39 +20,77 @@ class IServerProtocol; class ISocketFactory; class ISecurityFactory; +//! Synergy server +/*! +This class implements the top-level server algorithms for synergy. +*/ class CServer : public IServer, public IPrimaryScreenReceiver { public: + /*! + The server will look itself up in the configuration using \c serverName + as its name. + */ CServer(const CString& serverName); ~CServer(); - // manipulators + //! @name manipulators + //@{ - // open the server's screen + //! Open server + /*! + Open the server and return true iff successful. + */ bool open(); - // start the server. does not return until quit() is called. - // this must be preceeded by a successful call to open(). + //! Server main loop + /*! + Run server's event loop and return when quit() is called. + This must be called between a successful open() and close(). + + (cancellation point) + */ void run(); - // tell server to exit gracefully. this may only be called - // after a successful open(). + //! Exit event loop + /*! + Force run() to return. This call can return before + run() does (i.e. asynchronously). This may only be + called between a successful open() and close(). + */ void quit(); - // close the server's screen + //! Close server + /*! + Close the server. + */ void close(); - // update screen map. returns true iff the new configuration was - // accepted. + //! Set configuration + /*! + Change the server's configuration. Returns true iff the new + configuration was accepted (it must include the server's name). + This will disconnect any clients no longer in the configuration. + */ bool setConfig(const CConfig&); - // accessors + //@} + //! @name accessors + //@{ - // get the current screen map + //! Get configuration + /*! + Returns the current configuration. + */ void getConfig(CConfig*) const; - // get the primary screen's name + //! Get name + /*! + Returns the server's name passed to the c'tor + */ CString getPrimaryScreenName() const; + //@} + // IServer overrides virtual void onError(); virtual void onInfoChanged(const CString&, const CClientInfo&); @@ -71,6 +109,10 @@ public: virtual void onMouseWheel(SInt32 delta); protected: + //! Handle special keys + /*! + Handles keys with special meaning. + */ bool onCommandKey(KeyID, KeyModifierMask, bool down); private: diff --git a/server/CXWindowsPrimaryScreen.h b/server/CXWindowsPrimaryScreen.h index ad625ff7..08e244fd 100644 --- a/server/CXWindowsPrimaryScreen.h +++ b/server/CXWindowsPrimaryScreen.h @@ -14,6 +14,7 @@ class CXWindowsScreen; class IScreenReceiver; class IPrimaryScreenReceiver; +//! X11 primary screen implementation class CXWindowsPrimaryScreen : public CPrimaryScreen, public IScreenEventHandler { public: diff --git a/synergy/IClient.h b/synergy/IClient.h index a58f2859..c93c021c 100644 --- a/synergy/IClient.h +++ b/synergy/IClient.h @@ -23,10 +23,11 @@ public: */ virtual bool open() = 0; - //! Run client + //! Client main loop /*! - Service the client. This method is typically called in a separate - thread and is exited by cancelling the thread. + Run client's event loop. This method is typically called in a + separate thread and is exited by cancelling the thread. This + must be called between a successful open() and close(). (cancellation point) */ @@ -62,9 +63,10 @@ public: /*! Update the client's clipboard. This implies that the client's clipboard is now up to date. If the client's clipboard was - already known to be up to date then this may do nothing. + already known to be up to date then this may do nothing. \c data + has marshalled clipboard data. */ - virtual void setClipboard(ClipboardID, const CString&) = 0; + virtual void setClipboard(ClipboardID, const CString& data) = 0; //! Grab clipboard /*! @@ -152,7 +154,7 @@ public: //! Get screen shape /*! Return the position of the upper-left corner of the screen in \c x and - \c y and the size of the screen in \c w (width) and \c h (height). + \c y and the size of the screen in \c width and \c height. */ virtual void getShape(SInt32& x, SInt32& y, SInt32& width, SInt32& height) const = 0; diff --git a/synergy/IScreen.h b/synergy/IScreen.h index 7cb8b8d1..b60f56d6 100644 --- a/synergy/IScreen.h +++ b/synergy/IScreen.h @@ -33,7 +33,8 @@ public: //! Exit event loop /*! Force mainLoop() to return. This call can return before - mailLoop() does (i.e. asynchronously). + mainLoop() does (i.e. asynchronously). This may only be + called between a successful open() and close(). */ virtual void exitMainLoop() = 0; diff --git a/synergy/IScreenReceiver.h b/synergy/IScreenReceiver.h index 1cd2a79e..7ce2f7b3 100644 --- a/synergy/IScreenReceiver.h +++ b/synergy/IScreenReceiver.h @@ -41,7 +41,8 @@ public: //! Notify of new clipboard data /*! Called when the data on the clipboard has changed because some - other program has changed it. + other program has changed it. \c data will have marshalled + clipboard data. */ virtual void onClipboardChanged(ClipboardID, const CString& data) = 0; diff --git a/synergy/IServer.h b/synergy/IServer.h index 7dd819eb..b59b7af5 100644 --- a/synergy/IServer.h +++ b/synergy/IServer.h @@ -49,7 +49,8 @@ public: //! Notify of new clipboard data /*! Called when the data on the clipboard has changed because some - other program has changed it. + other program has changed it. \c data has the marshalled clipboard + data. */ virtual void onClipboardChanged(ClipboardID, UInt32 seqNum, const CString& data) = 0;