From b5a8ae11acc2135a74c823fcae378ddf421b53bc Mon Sep 17 00:00:00 2001 From: crs Date: Mon, 29 Jul 2002 16:07:26 +0000 Subject: [PATCH] Added doxygen comments for all relevant headers in synergy. --- synergy/CClipboard.h | 52 +++++++--- synergy/CInputPacketStream.h | 8 +- synergy/COutputPacketStream.h | 9 +- synergy/CProtocolUtil.h | 58 +++++++---- synergy/CTCPSocketFactory.h | 5 +- synergy/ClipboardTypes.h | 8 +- synergy/IClient.h | 161 +++++++++++++++++++++++++------ synergy/IClipboard.h | 110 ++++++++++++++------- synergy/IPrimaryScreenReceiver.h | 33 ++++++- synergy/IScreen.h | 123 +++++++++++++++++------ synergy/IScreenEventHandler.h | 50 +++++++--- synergy/IScreenReceiver.h | 38 ++++++-- synergy/IScreenSaver.h | 47 +++++++-- synergy/IServer.h | 49 +++++++--- synergy/ISocketFactory.h | 16 ++- synergy/KeyTypes.h | 25 +++-- synergy/MouseTypes.h | 9 +- synergy/ProtocolTypes.h | 31 +++++- synergy/Version.h | 6 +- synergy/XScreen.h | 6 +- synergy/XSynergy.h | 48 ++++++--- 21 files changed, 659 insertions(+), 233 deletions(-) diff --git a/synergy/CClipboard.h b/synergy/CClipboard.h index fea2b1d2..d7bfc9f0 100644 --- a/synergy/CClipboard.h +++ b/synergy/CClipboard.h @@ -1,35 +1,59 @@ #ifndef CCLIPBOARD_H #define CCLIPBOARD_H -// -// CClipboard -- stores clipboard data in a memory buffer -// - #include "IClipboard.h" +//! Memory buffer clipboard +/*! +This class implements a clipboard that stores data in memory. +*/ class CClipboard : public IClipboard { public: CClipboard(); virtual ~CClipboard(); - // manipulators + //! @name manipulators + //@{ - // unmarshall clipboard data - void unmarshall(const CString& data, Time); + //! Unmarshall clipboard data + /*! + Extract marshalled clipboard data and store it in this clipboard. + Sets the clipboard time to \c time. + */ + void unmarshall(const CString& data, Time time); - // accessors + //@} + //! @name accessors + //@{ - // marshall clipboard data + //! Marshall clipboard data + /*! + Merge this clipboard's data into a single buffer that can be later + unmarshalled to restore the clipboard and return the buffer. + */ CString marshall() const; - // transfer all the data in one clipboard to another. the - // clipboards can be of any concrete clipboard type (and - // they don't have to be the same type). this also sets - // the timestamp to time, if provided, or the time in src. - // returns true iff the copy succeeded. + //! Copy clipboard + /*! + Transfers all the data in one clipboard to another. The + clipboards can be of any concrete clipboard type (and + they don't have to be the same type). This also sets + the destination clipboard's timestamp to source clipboard's + timestamp. Returns true iff the copy succeeded. + */ static bool copy(IClipboard* dst, const IClipboard* src); + + //! Copy clipboard + /*! + Transfers all the data in one clipboard to another. The + clipboards can be of any concrete clipboard type (and they + don't have to be the same type). This also sets the + timestamp to \c time. Returns true iff the copy succeeded. + */ static bool copy(IClipboard* dst, const IClipboard* src, Time); + //@} + // IClipboard overrides virtual bool empty(); virtual void add(EFormat, const CString& data); diff --git a/synergy/CInputPacketStream.h b/synergy/CInputPacketStream.h index c8b123d1..5e4762f9 100644 --- a/synergy/CInputPacketStream.h +++ b/synergy/CInputPacketStream.h @@ -5,15 +5,15 @@ #include "CBufferedInputStream.h" #include "CMutex.h" +//! Packetizing input stream filter +/*! +Filters an input stream to extract packet by packet. +*/ class CInputPacketStream : public CInputStreamFilter { public: CInputPacketStream(IInputStream*, bool adoptStream = true); ~CInputPacketStream(); - // manipulators - - // accessors - // IInputStream overrides virtual void close(); virtual UInt32 read(void*, UInt32 maxCount, double timeout); diff --git a/synergy/COutputPacketStream.h b/synergy/COutputPacketStream.h index 07ee40a5..dda632c4 100644 --- a/synergy/COutputPacketStream.h +++ b/synergy/COutputPacketStream.h @@ -3,15 +3,16 @@ #include "COutputStreamFilter.h" +//! Packetizing output stream filter +/*! +Filters an output stream to create packets that include message +boundaries. Each write() is considered a single packet. +*/ class COutputPacketStream : public COutputStreamFilter { public: COutputPacketStream(IOutputStream*, bool adoptStream = true); ~COutputPacketStream(); - // manipulators - - // accessors - // IOutputStream overrides virtual void close(); virtual UInt32 write(const void*, UInt32 count); diff --git a/synergy/CProtocolUtil.h b/synergy/CProtocolUtil.h index 9c633b81..e277a757 100644 --- a/synergy/CProtocolUtil.h +++ b/synergy/CProtocolUtil.h @@ -8,32 +8,43 @@ class IInputStream; class IOutputStream; +//! Synergy protocol utilities +/*! +This class provides various functions for implementing the synergy +protocol. +*/ class CProtocolUtil { public: - // write formatted binary data to a stream. fmt consists of - // regular characters and format specifiers. format specifiers - // begin with %. all characters not part of a format specifier - // are regular and are transmitted unchanged. - // - // format specifiers are: - // %% -- writes % - // %1i -- converts integer argument to 1 byte integer - // %2i -- converts integer argument to 2 byte integer in NBO - // %4i -- converts integer argument to 4 byte integer in NBO - // %s -- converts CString* to stream of bytes - // %S -- converts integer N and const UInt8* to stream of N bytes + //! Write formatted data + /*! + Write formatted binary data to a stream. \c fmt consists of + regular characters and format specifiers. Format specifiers + begin with \%. All characters not part of a format specifier + are regular and are transmitted unchanged. + + Format specifiers are: + - \%\% -- literal `\%' + - \%1i -- converts integer argument to 1 byte integer + - \%2i -- converts integer argument to 2 byte integer in NBO + - \%4i -- converts integer argument to 4 byte integer in NBO + - \%s -- converts CString* to stream of bytes + - \%S -- converts integer N and const UInt8* to stream of N bytes + */ static void writef(IOutputStream*, const char* fmt, ...); - // read formatted binary data from a buffer. this performs the - // reverse operation of writef(). - // - // format specifiers are: - // %% -- read (and discard) a % - // %1i -- reads a 1 byte integer; argument is a SInt32* or UInt32* - // %2i -- reads an NBO 2 byte integer; arg is SInt32* or UInt32* - // %4i -- reads an NBO 4 byte integer; arg is SInt32* or UInt32* - // %s -- reads bytes; argument must be a CString*, *not* a char* + //! Read formatted data + /*! + Read formatted binary data from a buffer. This performs the + reverse operation of writef(). + + Format specifiers are: + - \%\% -- read (and discard) a literal `\%' + - \%1i -- reads a 1 byte integer; argument is a SInt32* or UInt32* + - \%2i -- reads an NBO 2 byte integer; arg is SInt32* or UInt32* + - \%4i -- reads an NBO 4 byte integer; arg is SInt32* or UInt32* + - \%s -- reads bytes; argument must be a CString*, \b not a char* + */ static void readf(IInputStream*, const char* fmt, ...); @@ -44,6 +55,11 @@ private: static void read(IInputStream*, void*, UInt32); }; +//! Mismatched read exception +/*! +Thrown by CProtocolUtil::readf() when the data being read does not +match the format. +*/ class XIOReadMismatch : public XIO { public: // XBase overrides diff --git a/synergy/CTCPSocketFactory.h b/synergy/CTCPSocketFactory.h index 2b900bb2..766c2170 100644 --- a/synergy/CTCPSocketFactory.h +++ b/synergy/CTCPSocketFactory.h @@ -3,15 +3,12 @@ #include "ISocketFactory.h" +//! Socket factory for TCP sockets class CTCPSocketFactory : public ISocketFactory { public: CTCPSocketFactory(); virtual ~CTCPSocketFactory(); - // manipulators - - // accessors - // ISocketFactory overrides virtual IDataSocket* create() const; virtual IListenSocket* createListen() const; diff --git a/synergy/ClipboardTypes.h b/synergy/ClipboardTypes.h index 63c44c91..478627bf 100644 --- a/synergy/ClipboardTypes.h +++ b/synergy/ClipboardTypes.h @@ -3,9 +3,14 @@ #include "BasicTypes.h" -// type to hold a clipboard identifier +//! Clipboard ID +/*! +Type to hold a clipboard identifier. +*/ typedef UInt8 ClipboardID; +//! @name Clipboard identifiers +//@{ // clipboard identifiers. kClipboardClipboard is what is normally // considered the clipboard (e.g. the cut/copy/paste menu items // affect it). kClipboardSelection is the selection on those @@ -17,5 +22,6 @@ static const ClipboardID kClipboardSelection = 1; // the number of clipboards (i.e. one greater than the last clipboard id) static const ClipboardID kClipboardEnd = 2; +//@} #endif diff --git a/synergy/IClient.h b/synergy/IClient.h index bf570772..a58f2859 100644 --- a/synergy/IClient.h +++ b/synergy/IClient.h @@ -7,74 +7,171 @@ #include "MouseTypes.h" #include "CString.h" -// the client interface. this provides all the methods necessary for -// the server to communicate with a client. +//! Client interface +/*! +This interface defines the methods necessary for the server to +communicate with a client. +*/ class IClient : public IInterface { public: - // manipulators + //! @name manipulators + //@{ - // open client. return true iff successful. + //! Open client + /*! + Open the client and return true iff successful. + */ virtual bool open() = 0; - // service client + //! Run client + /*! + Service the client. This method is typically called in a separate + thread and is exited by cancelling the thread. + + (cancellation point) + */ virtual void run() = 0; - // close client + //! Close client + /*! + Close the client. + */ virtual void close() = 0; - // enter the screen. the cursor should be warped to xAbs,yAbs. - // the client should record seqNum for future reporting of - // clipboard changes. mask is the expected toggle button state. - // forScreensaver is true if the screen is being entered because - // the screen saver is starting. + //! Enter screen + /*! + Enter the screen. The cursor should be warped to \c xAbs,yAbs. + The client should record seqNum for future reporting of + clipboard changes. \c mask is the expected toggle button state + and the client should update its state to match. \c forScreensaver + is true iff the screen is being entered because the screen saver is + starting. + */ virtual void enter(SInt32 xAbs, SInt32 yAbs, UInt32 seqNum, KeyModifierMask mask, bool forScreensaver) = 0; - // leave the screen. returns false if the user may not leave the - // client's screen. + //! Leave screen + /*! + Leave the screen. Return false iff the user may not leave the + client's screen (because, for example, a button is down). + */ virtual bool leave() = 0; - // 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 can do nothing. + //! Set clipboard + /*! + 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. + */ virtual void setClipboard(ClipboardID, const CString&) = 0; - // grab the client's clipboard. since this is called when another - // client takes ownership of the clipboard it implies that the - // client's clipboard is dirty. + //! Grab clipboard + /*! + Grab (i.e. take ownership of) the client's clipboard. Since this + is called when another client takes ownership of the clipboard it + implies that the client's clipboard is out of date. + */ virtual void grabClipboard(ClipboardID) = 0; - // called to set the client's clipboard as dirty or clean + //! Mark clipboard dirty + /*! + Mark the client's clipboard as dirty (out of date) or clean (up to + date). + */ virtual void setClipboardDirty(ClipboardID, bool dirty) = 0; - // handle input events - virtual void keyDown(KeyID, KeyModifierMask) = 0; - virtual void keyRepeat(KeyID, KeyModifierMask, SInt32 count) = 0; - virtual void keyUp(KeyID, KeyModifierMask) = 0; - virtual void mouseDown(ButtonID) = 0; - virtual void mouseUp(ButtonID) = 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; + + //! 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; + + //! Notify of screen saver change virtual void screensaver(bool activate) = 0; - // accessors + //@} + //! @name accessors + //@{ - // get the client's identifier + //! Get client name + /*! + Return the client's name. + */ virtual CString getName() const = 0; - // get the size of jump zone + //! Get jump zone size + /*! + Called to get the jump zone size. + */ virtual SInt32 getJumpZoneSize() const = 0; - // get the screen's shape + //! 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). + */ virtual void getShape(SInt32& x, SInt32& y, SInt32& width, SInt32& height) const = 0; - // get the mouse position + //! Get cursor position + /*! + Return the current position of the cursor in \c x and \c y. + */ virtual void getCursorPos(SInt32& x, SInt32& y) const = 0; - // get the center pixel + //! Get cursor center position + /*! + Return the cursor center position which is where we park the + cursor to compute cursor motion deltas and should be far from + the edges of the screen, typically the center. + */ virtual void getCursorCenter(SInt32& x, SInt32& y) const = 0; + + //@} }; #endif diff --git a/synergy/IClipboard.h b/synergy/IClipboard.h index cd56d9e2..9ad913eb 100644 --- a/synergy/IClipboard.h +++ b/synergy/IClipboard.h @@ -5,61 +5,99 @@ #include "CString.h" #include "BasicTypes.h" +//! Clipboard interface +/*! +This interface defines the methods common to all clipboards. +*/ class IClipboard : public IInterface { public: - // timestamp type. timestamps are in milliseconds from some - // arbitrary starting time. timestamps will wrap around to 0 - // after about 49 3/4 days. + //! Timestamp type + /*! + Timestamp type. Timestamps are in milliseconds from some + arbitrary starting time. Timestamps will wrap around to 0 + after about 49 3/4 days. + */ typedef UInt32 Time; - // known clipboard formats. kNumFormats must be last and - // formats must be sequential starting from zero. clipboard - // data set via add() and retrieved via get() is in one of - // these formats. platform dependent clipboard subclasses - // can and should present any suitable formats derivable - // from these formats (e.g. UTF-16 encoded unicode). - // - // kText: UTF-8 encoded unicode (ISO-10646), newline is LF. - enum EFormat { kText, kNumFormats }; + //! Clipboard formats + /*! + The list of known clipboard formats. kNumFormats must be last and + formats must be sequential starting from zero. Clipboard data set + via add() and retrieved via get() must be in one of these formats. + Platform dependent clipboard subclasses can and should present any + suitable formats derivable from these formats. + */ + enum EFormat { + kText, //!< Text format, UTF-8, newline is LF + kNumFormats //!< The number of clipboard formats + }; - // manipulators + //! @name manipulators + //@{ - // take ownership of the clipboard and clear all data from it. - // must be called between an open() and close(). if returns - // false then the clipboard ownership could not be taken; the - // clipboard should not be emptied in this case. + //! Empty clipboard + /*! + Take ownership of the clipboard and clear all data from it. + This must be called between a successful open() and close(). + Return false if the clipboard ownership could not be taken; + the clipboard should not be emptied in this case. + */ virtual bool empty() = 0; - // add data in the given format to the clipboard. data is - // passed as a string but the contents are generally not - // interpreted. may only be called after a successful empty(). + //! Add data + /*! + Add data in the given format to the clipboard. May only be + called after a successful empty(). + */ virtual void add(EFormat, const CString& data) = 0; - // accessors + //@} + //! @name accessors + //@{ - // open the clipboard. return true iff the clipboard could - // be opened. if open() returns true then it must be followed - // by a close() at some later time; if it returns false then - // close() must not be called. - virtual bool open(Time) const = 0; + //! Open clipboard + /*! + Open the clipboard. Return true iff the clipboard could be + opened. If open() returns true then the client must call + close() at some later time; if it returns false then close() + must not be called. \c time should be the current time or + a time in the past when the open should effectively have taken + place. + */ + virtual bool open(Time time) const = 0; - // close the clipboard. close() must match a preceding open(). - // this signals that the clipboard has been filled with all the - // necessary data. it does not mean the clipboard ownership - // should be released. + //! Close clipboard + /*! + Close the clipboard. close() must match a preceding successful + open(). This signals that the clipboard has been filled with + all the necessary data or all data has been read. It does not + mean the clipboard ownership should be released (if it was + taken). + */ virtual void close() const = 0; - // returns the timestamp passed to the last successful open(). + //! Get time + /*! + Return the timestamp passed to the last successful open(). + */ virtual Time getTime() const = 0; - // returns true iff the clipboard contains data in the given - // format. must be called between an open() and close(). + //! Check for data + /*! + Return true iff the clipboard contains data in the given + format. Must be called between a successful open() and close(). + */ virtual bool has(EFormat) const = 0; - // returns data in the given format. rturns the empty string - // if there is no data in that format. must be called between - // an open() and close(). + //! Get data + /*! + Return the data in the given format. Returns the empty string + if there is no data in that format. Must be called between + a successful open() and close(). + */ virtual CString get(EFormat) const = 0; + + //@} }; #endif diff --git a/synergy/IPrimaryScreenReceiver.h b/synergy/IPrimaryScreenReceiver.h index f347786e..1d34dfc3 100644 --- a/synergy/IPrimaryScreenReceiver.h +++ b/synergy/IPrimaryScreenReceiver.h @@ -5,24 +5,47 @@ #include "KeyTypes.h" #include "MouseTypes.h" -// the interface for receiving notification of events on the primary -// screen. the server implements this interface to handle user input. -// platform dependent primary screen implementation will need to take -// an IPrimaryScreenReceiver* and notify it of events. +//! Primary screen event receiver interface +/*! +The interface for receiving notification of events on the primary +screen. The server implements this interface to handle user input. +Platform dependent primary screen implementation will need to take +an IPrimaryScreenReceiver* and notify it of events. +*/ class IPrimaryScreenReceiver : public IInterface { public: - // called when the screensaver is activated or deactivated + //! Notify of screen saver change + /*! + Called when the screensaver is activated or deactivated. + */ virtual void onScreensaver(bool activated) = 0; // call to notify of events. onMouseMovePrimary() returns // true iff the mouse enters a jump zone and jumps. + //! Notify of key press virtual void onKeyDown(KeyID, KeyModifierMask) = 0; + //! Notify of key release virtual void onKeyUp(KeyID, KeyModifierMask) = 0; + //! Notify of key repeat virtual void onKeyRepeat(KeyID, KeyModifierMask, SInt32 count) = 0; + //! Notify of mouse button press virtual void onMouseDown(ButtonID) = 0; + //! Notify of mouse button release virtual void onMouseUp(ButtonID) = 0; + //! Notify of mouse motion + /*! + Called when the mouse has moved while on the primary screen. \c x + and \c y are the absolute screen position of the mouse. Return + true iff the mouse enters a jump zone and jumps. + */ virtual bool onMouseMovePrimary(SInt32 x, SInt32 y) = 0; + //! Notify of mouse motion + /*! + Called when the mouse has moved while on the secondary screen. + \c dx and \c dy are the relative motion from the last position. + */ virtual void onMouseMoveSecondary(SInt32 dx, SInt32 dy) = 0; + //! Notify of mouse wheen motion virtual void onMouseWheel(SInt32 delta) = 0; }; diff --git a/synergy/IScreen.h b/synergy/IScreen.h index 08c337ab..7cb8b8d1 100644 --- a/synergy/IScreen.h +++ b/synergy/IScreen.h @@ -6,65 +6,128 @@ class IClipboard; -// the interface for platform dependent screen implementations. each -// platform will derive a type from IScreen for interaction with the -// platform's screen that's common to primary and secondary screens. +//! Screen interface +/*! +This interface defines the methods common to all platform dependent +screen implementations that are use by both primary and secondary +screens. +*/ class IScreen : public IInterface { public: - // manipulators + //! @name manipulators + //@{ - // open the screen + //! Open screen + /*! + Called to open and initialize the screen. + */ virtual void open() = 0; - // runs an event loop and returns when exitMainLoop() is called. - // must be called between open() and close(). + //! Run event loop + /*! + Run the event loop and return when exitMainLoop() is called. + This must be called between a successful open() and close(). + */ virtual void mainLoop() = 0; - // force mainLoop() to return + //! Exit event loop + /*! + Force mainLoop() to return. This call can return before + mailLoop() does (i.e. asynchronously). + */ virtual void exitMainLoop() = 0; - // close the screen + //! Close screen + /*! + Called to close the screen. close() should quietly ignore calls + that don't have a matching successful call to open(). + */ virtual void close() = 0; - // set the contents of the clipboard - virtual bool setClipboard(ClipboardID, const IClipboard*) = 0; + //! Set clipboard + /*! + Set the contents of the system clipboard indicated by \c id. + */ + virtual bool setClipboard(ClipboardID id, const IClipboard*) = 0; - // check clipboard ownership and notify IScreenReceiver (set through - // some other interface) if any changed + //! Check clipboard owner + /*! + Check ownership of all clipboards and notify an IScreenReceiver (set + through some other interface) if any changed. This is used as a + backup in case the system doesn't reliably report clipboard ownership + changes. + */ virtual void checkClipboards() = 0; - // open/close the screen saver. if notify is true then this object - // will call IScreenEventHandler's onScreenSaver() when the screensaver - // activates or deactivates until close. if notify is false then - // the screen saver is disabled on open and restored on close. + //! Open screen saver + /*! + Open the screen saver. If \c notify is true then this object must + call an IScreenEventHandler's (set through some other interface) + onScreenSaver() when the screensaver activates or deactivates until + it's closed. If \c notify is false then the screen saver is + disabled on open and restored on close. + */ virtual void openScreensaver(bool notify) = 0; + + //! Close screen saver + /*! + // Close the screen saver. Stop reporting screen saver activation + and deactivation and, if the screen saver was disabled by + openScreensaver(), enable the screen saver. + */ virtual void closeScreensaver() = 0; - // activate or deactivate the screen saver + //! Activate/deactivate screen saver + /*! + Forcibly activate the screen saver if \c activate is true otherwise + forcibly deactivate it. + */ virtual void screensaver(bool activate) = 0; - // ensure that this thread attached with the visible desktop. this is - // mainly intended for windows which has an artificial distinction - // between desktops and a thread cannot interact with the visible - // desktop unless the thread is attached to that desktop. + //! Attach to desktop + /*! + Called to ensure that this thread is attached to the visible desktop. + This is mainly intended for microsoft windows which has an artificial + distinction between desktops where a thread cannot interact with the + visible desktop unless the thread is attached to that desktop. Since + it doesn't report when the visible desktop changes we must poll. + */ virtual void syncDesktop() = 0; - // accessors + //@} + //! @name accessors + //@{ - // get the contents of the clipboard - virtual bool getClipboard(ClipboardID, IClipboard*) const = 0; + //! Get clipboard + /*! + Save the contents of the clipboard indicated by \c id and return + true iff successful. + */ + virtual bool getClipboard(ClipboardID id, IClipboard*) const = 0; - // get the shape 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 w (width) and \c h (height). + */ virtual void getShape(SInt32& x, SInt32& y, SInt32& w, SInt32& h) const = 0; - // get the current cursor coordinates + //! Get cursor position + /*! + Return the current position of the cursor in \c x and \c y. + */ virtual void getCursorPos(SInt32& x, SInt32& y) const = 0; - // get the cursor center position. this is where we park the - // cursor to compute cursor motion deltas and should be far from - // the edges of the screen, typically the center. + //! Get cursor center position + /*! + Return the cursor center position which is where we park the + cursor to compute cursor motion deltas and should be far from + the edges of the screen, typically the center. + */ virtual void getCursorCenter(SInt32& x, SInt32& y) const = 0; + + //@} }; #endif diff --git a/synergy/IScreenEventHandler.h b/synergy/IScreenEventHandler.h index 4c6cd14e..196fbed9 100644 --- a/synergy/IScreenEventHandler.h +++ b/synergy/IScreenEventHandler.h @@ -8,32 +8,52 @@ class CEvent; class IScreen; -// the interface through which IScreen sends notification of events. -// each platform will derive two types from IScreenEventHandler, one -// for handling events on the primary screen and one for the -// secondary screen. the header file with the IScreen subclass for -// each platform should define the CEvent type, which depends on the -// type of native events for that platform. +//! Screen event handler interface +/*! +This is the interface through which IScreen sends notification of events. +Each platform will derive two types from IScreenEventHandler, one +for handling events on the primary screen and one for the +secondary screen. The header file with the IScreen subclass for +each platform should define the CEvent type, which depends on the +type of native events for that platform. +*/ class IScreenEventHandler : public IInterface { public: - // manipulators + //! @name manipulators + //@{ - // called when the screensaver is activated or deactivated + //! Notify of screen saver change + /*! + Called when the screensaver is activated or deactivated. + */ virtual void onScreensaver(bool activated) = 0; - // called for each event before event translation and dispatch. return - // true to skip translation and dispatch. subclasses should call the - // superclass's version first and return true if it returns true. + //! Event filtering + /*! + Called for each event before event translation and dispatch. Return + true to skip translation and dispatch. Subclasses should call the + superclass's version first and return true if it returns true. + */ virtual bool onPreDispatch(const CEvent* event) = 0; - // called by mainLoop(). iff the event was handled return true and - // store the result, if any, in m_result, which defaults to zero. + //! Event handling + /*! + Called to handle an event. Iff the event was handled return true and + store the result, if any, in event->m_result, which defaults to zero. + */ virtual bool onEvent(CEvent* event) = 0; - // accessors + //@} + //! @name accessors + //@{ - // called to get the jump zone size + //! Get jump zone size + /*! + Called to get the jump zone size. + */ virtual SInt32 getJumpZoneSize() const = 0; + + //@} }; #endif diff --git a/synergy/IScreenReceiver.h b/synergy/IScreenReceiver.h index da2d40c9..1cd2a79e 100644 --- a/synergy/IScreenReceiver.h +++ b/synergy/IScreenReceiver.h @@ -6,23 +6,43 @@ #include "ProtocolTypes.h" #include "CString.h" -// the interface for types that receive screen resize and clipboard -// notifications (indirectly) from the system. +//! Screen event receiver interface +/*! +This interface defines the methods common to most types that receive +events for changes to a screen. Note that the methods in this +interface are similar to the methods in IServer but have different +parameters. This interface is suitable for client-side types. +*/ class IScreenReceiver : public IInterface { public: - // called if the screen is unexpectedly closing. this implies that - // the screen is no longer usable and that the program should - // close the screen and possibly terminate. + //! Notify of error + /*! + Called when the screen is unexpectedly closing. This implies that + the screen is no longer usable and that the program should close + the screen and probably terminate. + */ virtual void onError() = 0; - // notify of client info change + //! Notify of client screen change + /*! + Called when the client's info has changed. For example, when the + screen resolution has changed. + */ virtual void onInfoChanged(const CClientInfo&) = 0; - // notify of clipboard grab. returns true if the grab was honored, - // false otherwise. + //! Notify of clipboad grab + /*! + Called when the clipboard was grabbed by another program and, + therefore, we no longer own it. Returns true if the grab was + honored, false otherwise. + */ virtual bool onGrabClipboard(ClipboardID) = 0; - // notify of new clipboard data + //! Notify of new clipboard data + /*! + Called when the data on the clipboard has changed because some + other program has changed it. + */ virtual void onClipboardChanged(ClipboardID, const CString& data) = 0; }; diff --git a/synergy/IScreenSaver.h b/synergy/IScreenSaver.h index d1bccf45..e0662011 100644 --- a/synergy/IScreenSaver.h +++ b/synergy/IScreenSaver.h @@ -3,28 +3,57 @@ #include "IInterface.h" +//! Screen saver interface +/*! +This interface defines the methods common to all screen savers. +*/ class IScreenSaver : public IInterface { public: // note -- the c'tor/d'tor must *not* enable/disable the screen saver - // manipulators + //! @name manipulators + //@{ - // enable/disable the screen saver. enable() should restore the - // screen saver settings to what they were when disable() was - // previously called. if disable() wasn't previously called then - // it should keep the current settings or use reasonable defaults. + //! Enable screen saver + /*! + Enable the screen saver, restoring the screen saver settings to + what they were when disable() was previously called. If disable() + wasn't previously called then it should keep the current settings + or use reasonable defaults. + */ virtual void enable() = 0; + + //! Disable screen saver + /*! + Disable the screen saver, saving the old settings for the next + call to enable(). + */ virtual void disable() = 0; - // activate/deactivate (i.e. show/hide) the screen saver. - // deactivate() also resets the screen saver timer. + //! Activate screen saver + /*! + Activate (i.e. show) the screen saver. + */ virtual void activate() = 0; + + //! Deactivate screen saver + /*! + Deactivate (i.e. hide) the screen saver, reseting the screen saver + timer. + */ virtual void deactivate() = 0; - // accessors + //@} + //! @name accessors + //@{ - // returns true iff the screen saver is active + //! Test if screen saver on + /*! + Returns true iff the screen saver is currently active (showing). + */ virtual bool isActive() const = 0; + + //@} }; #endif diff --git a/synergy/IServer.h b/synergy/IServer.h index ee3798d6..7dd819eb 100644 --- a/synergy/IServer.h +++ b/synergy/IServer.h @@ -7,33 +7,54 @@ class CClientInfo; -// the server interface. this provides all the methods necessary for -// clients to communicate with the server. note that the methods -// in this interface are similar to the methods in IScreenReceiver but -// include extra parameters. this interface is suitable for server-side -// client proxies. client-side objects should use the IScreenReceiver -// interface since the extra parameters are meaningless on the client-side. +//! Server interface +/*! +This interface defines the methods necessary for clients to +communicate with the server. Note that the methods in this +interface are similar to the methods in IScreenReceiver but +include extra parameters. This interface is suitable for +server-side client proxies. Client-side objects should use +the IScreenReceiver interface since the extra parameters are +meaningless on the client-side. +*/ class IServer : public IInterface { public: - // manipulators + //! @name manipulators + //@{ - // called if the screen is unexpectedly closing. this implies that - // the screen is no longer usable and that the program should - // close the screen and possibly terminate. + //! Notify of error + /*! + Called when the screen is unexpectedly closing. This implies that + the screen is no longer usable and that the program should close + the screen and probably terminate. + */ virtual void onError() = 0; - // notify of client info change + //! Notify of client screen change + /*! + Called when the client's info has changed. + */ virtual void onInfoChanged(const CString& clientName, const CClientInfo&) = 0; - // notify of clipboard grab. returns true if the grab was honored, - // false otherwise. + //! Notify of clipboad grab + /*! + Called when the clipboard was grabbed by another program and, + therefore, we no longer own it. Returns true if the grab was + honored, false otherwise. + */ virtual bool onGrabClipboard(const CString& clientName, ClipboardID, UInt32 seqNum) = 0; - // notify of new clipboard data + //! Notify of new clipboard data + /*! + Called when the data on the clipboard has changed because some + other program has changed it. + */ virtual void onClipboardChanged(ClipboardID, UInt32 seqNum, const CString& data) = 0; + + //@} }; #endif diff --git a/synergy/ISocketFactory.h b/synergy/ISocketFactory.h index 7b7ff8cd..cb719a5e 100644 --- a/synergy/ISocketFactory.h +++ b/synergy/ISocketFactory.h @@ -6,15 +6,23 @@ class IDataSocket; class IListenSocket; +//! Socket factory +/*! +This interface defines the methods common to all factories used to +create sockets. +*/ class ISocketFactory : public IInterface { public: - // manipulators + //! @name accessors + //@{ - // accessors - - // create sockets + //! Create data socket virtual IDataSocket* create() const = 0; + + //! Create listen socket virtual IListenSocket* createListen() const = 0; + + //@} }; #endif diff --git a/synergy/KeyTypes.h b/synergy/KeyTypes.h index 37e54184..0623961a 100644 --- a/synergy/KeyTypes.h +++ b/synergy/KeyTypes.h @@ -3,15 +3,22 @@ #include "BasicTypes.h" -// type to hold a key identifier. the encoding is UTF-32, using -// U+E000 through U+EFFF for the various control keys (e.g. arrow -// keys, function keys, modifier keys, etc). +//! Key ID +/*! +Type to hold a key identifier. The encoding is UTF-32, using +U+E000 through U+EFFF for the various control keys (e.g. arrow +keys, function keys, modifier keys, etc). +*/ typedef UInt32 KeyID; -// type to hold bitmask of key modifiers (e.g. shift keys) +//! Modifier key ID +/*! +Type to hold a bitmask of key modifiers (e.g. shift keys). +*/ typedef UInt32 KeyModifierMask; -// modifier key bitmasks +//! @name Modifier key identifiers +//@{ static const KeyModifierMask KeyModifierShift = 0x0001; static const KeyModifierMask KeyModifierControl = 0x0002; static const KeyModifierMask KeyModifierAlt = 0x0004; @@ -19,11 +26,12 @@ static const KeyModifierMask KeyModifierMeta = 0x0008; static const KeyModifierMask KeyModifierCapsLock = 0x1000; static const KeyModifierMask KeyModifierNumLock = 0x2000; static const KeyModifierMask KeyModifierScrollLock = 0x4000; +//@} -// -// key codes. all codes except kKeyNone are equal to the corresponding +//! @name Key identifiers +//@{ +// all identifiers except kKeyNone are equal to the corresponding // X11 keysym - 0x1000. -// // no key static const KeyID kKeyNone = 0x0000; @@ -163,5 +171,6 @@ static const KeyID kKeyHyper_R = 0xEFEE; /* Right hyper */ // more function and modifier keys static const KeyID kKeyLeftTab = 0xEE20; +//@} #endif diff --git a/synergy/MouseTypes.h b/synergy/MouseTypes.h index ad5f0c7a..8b6719de 100644 --- a/synergy/MouseTypes.h +++ b/synergy/MouseTypes.h @@ -3,13 +3,18 @@ #include "BasicTypes.h" -// type to hold mouse button identifier +//! Mouse button ID +/*! +Type to hold a mouse button identifier. +*/ typedef UInt8 ButtonID; -// mouse button identifiers +//! @name Mouse button identifiers +//@{ static const ButtonID kButtonNone = 0; static const ButtonID kButtonLeft = 1; static const ButtonID kButtonMiddle = 2; static const ButtonID kButtonRight = 3; +//@} #endif diff --git a/synergy/ProtocolTypes.h b/synergy/ProtocolTypes.h index c4d48ae4..3e14cd13 100644 --- a/synergy/ProtocolTypes.h +++ b/synergy/ProtocolTypes.h @@ -3,11 +3,11 @@ #include "BasicTypes.h" -// version number +// protocol version number static const SInt16 kProtocolMajorVersion = 0; static const SInt16 kProtocolMinorVersion = 7; -// contact port number +// default contact port number static const UInt16 kDefaultPort = 24800; // time between heartbeats (in seconds) @@ -181,16 +181,37 @@ static const char kMsgEBad[] = "EBAD"; // structures // +//! Screen information +/*! +This class contains information about a screen. +*/ class CClientInfo { public: - // the coordinates of the screen + //! Screen position + /*! + The position of the upper-left corner of the screen. This is + typically 0,0. + */ SInt32 m_x, m_y; + + //! Screen size + /*! + The size of the screen in pixels. + */ SInt32 m_w, m_h; - // the size of the jump zone + //! Jump zone size + /*! + This is the size of the jump zone. The cursor jumps to the adjacent + screen when it comes within this many pixels of the edge of the screen. + */ SInt32 m_zoneSize; - // mouse position + //! Mouse position + /*! + The position of the cursor. This is not kept up-to-date so it's + only meaningful when receiving an update. + */ SInt32 m_mx, m_my; }; diff --git a/synergy/Version.h b/synergy/Version.h index 5b8ae1c7..128f500c 100644 --- a/synergy/Version.h +++ b/synergy/Version.h @@ -3,10 +3,12 @@ #include "BasicTypes.h" +// important strings static const char* kCopyright = "Copyright (C) 2002 Chris Schoeneman"; -static const char* kContact = "Chris Schoeneman crs23@bigfoot.com"; +static const char* kContact = "Chris Schoeneman, crs23@bigfoot.com"; +static const char* kWebsite = ""; -// build version. follows linux kernel style: minor number even implies +// build version. follows linux kernel style: an even minor number implies // a release version, odd implies development version. static const SInt16 kMajorVersion = 0; static const SInt16 kMinorVersion = 9; diff --git a/synergy/XScreen.h b/synergy/XScreen.h index 23ea45e5..2b71402a 100644 --- a/synergy/XScreen.h +++ b/synergy/XScreen.h @@ -3,9 +3,13 @@ #include "XBase.h" +//! Generic screen exception class XScreen : public XBase { }; -// screen cannot be opened +//! Cannot open screen exception +/*! +Thrown when a screen cannot be opened or initialized. +*/ class XScreenOpenFailure : public XScreen { protected: virtual CString getWhat() const throw(); diff --git a/synergy/XSynergy.h b/synergy/XSynergy.h index dda1d106..86ce98ee 100644 --- a/synergy/XSynergy.h +++ b/synergy/XSynergy.h @@ -3,26 +3,36 @@ #include "XBase.h" +//! Generic synergy exception class XSynergy : public XBase { }; -// client is misbehaving +//! Client error exception +/*! +Thrown when the client fails to follow the protocol. +*/ class XBadClient : public XSynergy { protected: virtual CString getWhat() const throw(); }; -// client has incompatible version +//! Incompatible client exception +/*! +Thrown when a client attempting to connect has an incompatible version. +*/ class XIncompatibleClient : public XSynergy { public: XIncompatibleClient(int major, int minor); - // manipulators - - // accessors + //! @name accessors + //@{ + //! Get client's major version number int getMajor() const throw(); + //! Get client's minor version number int getMinor() const throw(); + //@} + protected: virtual CString getWhat() const throw(); @@ -31,18 +41,24 @@ private: int m_minor; }; -// client has duplicate name (i.e. client with name is already connected) +//! Client already connected exception +/*! +Thrown when a client attempting to connect is using the same name as +a client that is already connected. +*/ class XDuplicateClient : public XSynergy { public: XDuplicateClient(const CString& name); - // manipulators - - // accessors + //! @name accessors + //@{ + //! Get client's name virtual const CString& getName() const throw(); + //@} + protected: virtual CString getWhat() const throw(); @@ -50,18 +66,24 @@ private: CString m_name; }; -// client has unknown name (i.e. name is not in server's screen map) +//! Client not in map +/*! +Thrown when a client attempting to connect is using a name that is +unknown to the server. +*/ class XUnknownClient : public XSynergy { public: XUnknownClient(const CString& name); - // manipulators - - // accessors + //! @name accessors + //@{ + //! Get the client's name virtual const CString& getName() const throw(); + //@} + protected: virtual CString getWhat() const throw();