Client guidelines

[ introduction | project page | mailing list | downloads | changelog | documentation | developers | license ]

screenshot of gcdial (13k)

More development info.

Example client description

30 Sep 2000: This is no longer an accurate description of gcdial. Take these as very loose guidelines.

All messages should be printed in the box at the bottom of the display. These messages could be:

The input focus should be in the password text entry box and when enter is pressed, the 'Connect' button should be run.

When the client is first run, all the text entry boxes should be empty, except port. This should have the default value of 5540.

If 'Save config' is clicked, the contents of the text boxes should be saved. You can either save the password by default or only save it if a 'Save password with config' checkbox is on.

When the 'Connect' button is clicked, check that all the text boxes are filled in (if not, print appropriate error). If we are already connected, act like 'Disconnect' and then 'Connect' were clicked.


Print "ordering connection up".

Connect to the given server on the specified port.

You should receive a message starting with 'Hello' containing version and possibly other information. This will finish with a newline.

At any time, if you receive a message starting with # you should print it, but put -> at the front. (e.g. ->#Connecting). If you receive a message that does not start with # other than 'OKAY\n' you should print the message then abort (It will be an error message. This way I can change the error messages without breaking clients).

Having received the hello message, you should send the following commands:

USER username\n
PASS password\n

After each line you send the server should send you 'OKAY\n' (or you might receive a message starting with #, in which case you should print that message and wait around for the OKAY).

If you want to spruce the interface up a bit, consider having a coloured light depending on the state. Show black when we're disconnected. When you receive "#Connecting\n" change the colour to yellow, "#Connected\n" to green, "#Connect failed\n" to red. You will receive other messages beginning with # that you should print without parsing, these are the only messages guaranteed not to change.

While connected, you should send 'ALIVE\n' to the server every 30 seconds. (The server will drop the client if an alive is not received within one minute). The server will reply with "OKAY\n".


Print "ordering connection down".

Send the command:


If you wish to close the socket connection, send


and the server will terminate the connection. You can print "socket connection terminated" in this case.


The given commands are all you need for a basic client, but if you want more flexibility, see the "Client commands" section in the HTML documentation.

Tim Sutherland (
Last modified: Mon Jul 09 15:56:01 NZST 2001