Client guidelines

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

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:

• server not found
• connect failed
• ordering connection up
• ordering connection down
• connection terminated
• connection reset by peer
• network timeout
• fatal network error

• cannot open 'file'
• cannot open 'file' for writing
• saving config failed
• config saved
• invalid keyword in rc file line 4
• keyword requires an argument in rcfile line 2
• keyword not allowed argument in rcfile line 1

• need to specify a password
• need to specify a username
• need to specify a port
• need to specify a server

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.

Connecting

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
CONNECT\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".

Disconnecting

Print "ordering connection down".

Send the command:

DISCONNECT\n

If you wish to close the socket connection, send

QUIT\n

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

Protocol

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.