Table of Contents
-----------------
1. Overview
2. Introduction
3. Multiple servers and/or accounts
4. Automatic game state checking
5. Manual game state checking
6. Menubar icon animation
7. Is my password safe with dgsmonX?


Overview
--------
This document contains a detailed description of the features of dgsmonX.

- The first section "Introduction" provides a short overview of dgsmonX' user
  interface and the first configuration steps you must perform before dgsmonX
  becomes useful
- The following sections go into more detail on certain configuration and usage
  aspects of dgsmonX
- The last section talks about how safe your password is with dgsmonX


Introduction
------------
dgsmonX monitors the games you have joined on one or more Dragon Go Servers
(DGS) and alerts you when it is your turn to move in any of these games.
Naturally you do not want to be bothered when it is *not* your turn - which will
probably be most of the time that dgsmonX is running. dgsmonX therefore tries to
be as unobtrusive as possible, staying in the background while it has nothing
to report, and coming to the fore only when it needs to notify you.

To achieve its goal of being inconspicuous, dgsmonX has been designed as a
faceless application. This means that when it is launched, it will not appear in
the Dock as normal applications do when they are started, nor does it display
an application window while it is running. All this with the purpose not to
clutter your desktop or take away screen estate from other, more important
applications that you are working with. The only clue you have that dgsmonX is
running is when you see its icon appear somewhere on the right-hand side of the
system menubar.

[Note: The current version of dgsmonX does not yet have an icon, it therefore
displays the name "dgsmonX" in the system menubar.]

The system menubar icon serves two purposes:

1. When dgsmonX detects that it is your turn to move in any of the games that it
   is monitoring, it animates the menubar icon in a more or less annoying
   fashion so as to catch your attention.

2. When you click the menubar icon, a menu pops up which gives you access to
   dgsmonX's functions. These will be discussed in detail in the next sections.
   For now it is enough to say that the menu contains an item that you can use
   to configure dgsmonX, and one item that you can use to quit dgsmonX.

Before dgsmonX can do anything for you, you must tell it which Dragon Go Server
it should monitor for you, and what the login details are that it should use.
Because dgsmonX is supposed to watch *your* games, the login details are, by
necessity, *your* user name and password. You may wish to first read the section
"Is my password safe with dgsmonX?" before you entrust dgsmonX with your login
details.

The following list guides you through the initial configuration, step-by-step:
- Launch the application.
- Click the dgsmonX menubar icon to pop up the application's main menu.
- Select the "Preferences..." menu item to display the Preferences window.
- Select the "Servers" tab.
- Click the "+" button to add a new Dragon Go Server.
- Configure the server as follows:
  - Correct the default server's name and/or URL if they do not match your
    desired server name and/or URL. New servers always point to the canonical
    installation http://www.dragongoserver.net/.
  - Enter your user ID and password.
  - Click the "Test" button to check if the details you entered work correctly.
    After a moment, a message box will pop up to tell you whether dgsmonX
    succeeded in connecting to the server. [Note: This feature is not yet
    implemented in the current version of dgsmonX, at the moment the "Test"
    button is therefore always disabled.]
  - When you are satisfied that the server configuration works, check the
    "Monitor this server" button. This activates periodic checking for this
    server.
- Click the "Close" button to hide the Preferences window.

From now on, the Dragon Go Server that you have just configured is being
monitored by dgsmonX. As described above, when it is your turn dgsmonX will
animate the menubar icon to catch your attention.

Should you no longer need the services of dgsmonX, select "Quit" from the
applications's main menu in order to terminate the application.


Multiple servers and/or accounts
--------------------------------
When you add new DGS entries in the Preferences window (you have seen in the
Introduction chapter how you can do this), they default to the URL of the
canonical Dragon Go Server installation on the Internet
(http://www.dragongoserver.net/). dgsmonX does not prevent you from changing
the URL, though. dgsmonX therefore is capable of monitoring *any* Dragon Go
Server installation reachable over the network. This might be useful, for
instance, if someone runs a local Dragon Go Server using the DGS software which
is freely available at SourceForge.net
(http://sourceforge.net/projects/dragongoserver/).

Since dgsmonX does not restrict how you configure DGS entries, you can also
have dgsmonX check multiple accounts on the same DGS installation.


Automatic game state checking
-----------------------------
dgsmonX performs automatic game state checks in regular intervals. The default
interval is 15 minutes. You can change the interval in the Preferences window
to anything you like, although you can never go below 1 second.

An automatic game state check always includes all configured Dragon Go Servers
for which you have enabled monitoring (a checkbox that you can set/unset in the
Preferences window). The first series of game state checks is performed as soon
as possible after the application is launched. The next series of checks is run
after the monitoring time interval has elapsed. Periodic checks continue until
the application terminates. If a series of checks is in progress at that time,
it is interrupted.

Checks are also interrupted when the Preferences window is about to be
displayed. In addition, no checks are triggered while the Preferences window is
displayed. These limitations exist mainly for technical reasons. To compensate,
a new series of checks is triggered immediately when the Preferences window is
closed and if one of the following is true:
- The monitoring interval since the last series of checks has elapsed
- The previous series of checks has been interrupted by displaying the
  Preferences window


Manual game state checking
--------------------------
All configured Dragon Go Servers are represented in the application's main menu
by a menu item. The menu item is greyed out if monitoring is disabled for the
item's DGS. Otherwise the menu item appears normal, and you can select it to
trigger an immediate manual game state check for the item's DGS. The special
menu item "Check all" triggers an immediate game state check for *all* Dragon
Go Servers.

Manual checks are cancelled in the same way as are automatic checks when the
Preferences window is about to be displayed. If manual checks were cancelled,
they are not re-run when the Preferences window is closed.


Menubar icon animation
----------------------
When dgsmonX detects that it is your turn to move in any of the games that it
is monitoring, it animates the menubar icon in a more or less annoying fashion
so as to catch your attention.

[Note: The current version of dgsmonX does not yet have an icon, it therefore
animates the application title in the menubar.]

The animation is very simple: The regular menubar icon is alternated with a
different icon that indicates that it is your turn. The default interval for
switching between icons is 3 seconds. You may change this in the Preferences
window to make it more or less annoying (i.e. make the animation faster or
slower).

To stop the animation, you must click on the application's menubar icon. This
indicates to dgsmonX that you have seen the notification. As a side effect, the
application's main menu will pop up.


Is my password safe with dgsmonX?
---------------------------------
The simple answer is: No.

The more detailed answer tells you which areas are problematic and what can (or
can't) be done to fix the problems.

* The password is stored in the Preferences file
  ~/Library/Preferences/ch.herzbube.dgsmonX, which is basically a text file in
  XML format. Currently the password is stored unprotected and in clear text
  inside this Preferences files. Whoever has read access to that file can
  therefore potentially see your password (the question is whether they are
  looking :-). There is not much that can be done to improve the situation,
  unless a feature is added to dgsmonX that forces the user to enter a master
  password (or some other secret) when dgsmonX is launched, and that can then
  be used to encrypt/decrypt the Preferences file. Such a feature will not be
  implemented soon, if at all, because it will decrease dgsmonX' usability.

* dgsmonX does not yet support the HTTPS protocol. This means that, for the
  moment, you have no choice but to configure Dragon Go Servers to use the HTTP
  protocol. HTTP is not a secure protocol, though: Whenever you log in to a
  DGS using the HTTP protocol, your password is transmitted over the network in
  clear text. Whoever has read access to the network traffic between the
  computer that runs dgsmonX, and the computer that runs the Dragon Go Server,
  can therefore potentially see your password. Again, the question is whether
  they are looking. The situation will improve slightly when dgsmonX becomes
  able to handle HTTPS, the secure variant of HTTP that encrypts all network
  traffic between the two computers talking to each other. The problem remains,
  though, if the computer that runs the Dragon Go Server does not support HTTPS.
  For instance, at the time of writing the canonical Dragon Go Server
  installation on the Internet (http://www.dragongoserver.net/) does *not*
  support HTTPS. As a final word, I would like to point out that the
  insecurity of HTTP is not a weakness of dgsmonX, but a weakness of the
  network protocol. For instance, whenever you log in to a Dragon Go Server
  using your web browser, your password is also transmitted over the network
  in clear text.

* Even if HTTPS is used, there might still be holes where your password is
  visible to a third party. One that comes to mind is the web server log file
  on the computer that runs the Dragon Go Server. Again, the same holes might
  be present when you are using a web browser instead of dgsmonX to log in.


Recommendation: Do not use a valuable password for your DGS account.
