Lichat-Tcp-Client

About Lichat-TCP-Server

This is a simple, threaded, TCP-based client for the Lichat protocol.

How To

Create a new client instance and pass it whatever settings you would like.

(defvar *client* (make-instance 'lichat-tcp-client:client))

Notable initargs of potential interest are:

:username The name the client goes by on the network. Defaults to (machine-instance).
:password The password of the user profile, if any. Defaults to NIL.
:hostname The hostname to which the TCP socket should connect. The default is localhost.
:port The port the TCP socket should connect to. The default is 1111.

Once a client exists, it can be started to attempt a connection to the server.

(lichat-tcp-client:open-connection *client*)

The client logs information via Verbose. If you set the REPL level to :trace you should see a bunch of status messages being printed every now and again.

Once you're done with the client, you can shut it down again.

(lichat-tcp-client:close-connection *client*)

Naturally this client doesn't really do much on its own. You can send updates to the server with s:

(lichat-tcp-client:s *client* 'create :channel "test")
(lichat-tcp-client:s *client* 'message :channel "test" :text "Hey.")

If you would like to respond to updates that the server sends back, you can define a method on process to do so.

(defmethod lichat-tcp-client:process ((update lichat-protocol:join) (client lichat-tcp-client:client))
  (lichat-tcp-client:s client 'message
                       :channel (lichat-protocol:channel update)
                       :text "What's up everyone?"))

See the Lichat protocol for more information on the available updates, their arguments, and their behaviour.

Also See

lichat-protocol The Lichat protocol specification.
lichat-serverlib An agnostic implementation of the server-side protocol.
lichat-tcp-server A basic, threaded, TCP-based implementation of a Lichat server.
LionChat A Qt GUI client for a TCP server.

Copyright

lichat-tcp-client is licensed under the Artistic license. © Nicolas Hafner <shinmera@tymoon.eu> . This library can be obtained on https://github.com/Shirakumo/lichat-tcp-client.

Package Index

LICHAT-TCP-CLIENT (ORG.SHIRAKUMO.LICHAT.TCP-CLIENT)

special

`DEFAULT-PORT`

The default TCP port on which to connect. Should be 1111.

class

`CLIENT`

Class to represent a Lichat client.

See USERNAME
See PASSWORD
See HOSTNAME
See PORT
See SOCKET
See THREAD

accessor (

`PASSWORD`

OBJECT)

Accessor to the password of the client, if any.

See CLIENT
See LICHAT-PROTOCOL:PASSWORD

accessor (

`PORT`

OBJECT)

Accessor to the TCP port the client is connecting over.

See CLIENT

accessor (

`SOCKET`

OBJECT)

Accessor to the USOCKET:SOCKET instance that connects to the server.

See CLIENT

accessor (

`THREAD`

OBJECT)

Accessor to the background processing thread of the client.

See CLIENT

accessor (

`USERNAME`

OBJECT)

Accessor to the username of the client.

See CLIENT
See LICHAT-PROTOCOL:USERNAME

function (

`S`

CLIENT TYPE &REST ARGS)

Shorthand to construct an update to the server.

TYPE is coerced to a symbol from the LICHAT-PROTOCOL package.
It is then used together with the initargs to create an update
instance. A :FROM initarg using the client's USERNAME is
automatically added.

See SEND

generic (

`CALL-WITH-RESPONSE`

FUNCTION CLIENT INIT)

Calls the function once a suitable response update has appeared on the client's stream.

A suitable response is either an UPDATE with the same ID
as the update returned by INIT, or an UPDATE-FAILURE with
the same UPDATE-ID as the ID of the updated returned by
INIT. If another message is found that does not match, it
is simply ignored.

See READ-MESSAGE
See LICHAT-PROTOCOL:UPDATE-FAILURE
See LICHAT-PROTOCOL:UPDATE
See LICHAT-PROTOCOL:ID
See LICHAT-PROTOCOL:UPDATE-ID

generic (

`CLOSE-CONNECTION`

CLIENT)

Closes the connection to the server.

Attempts to be graceful by first sending a 
LICHAT-PROTOCOL:DISCONNECT update to the server, if it can.

See LICHAT-PROTOCOL:DISCONNECT

generic (

`HANDLE-CONNECTION`

CLIENT)

Handles the incoming updates from the server.

This repeatedly (while the stream is open) calls READ-MESSAGE
and then passes that message on to PROCESS. If a connection
stability error occurs during this (timout, shutdown, reset, etc)
then HANDLE-FATAL-ERROR is called.

A restart called CLOSE-CONNECTION is active during this, which
allows you to gracefully exit and close the connection.

See PROCESS
See HANDLE-FATAL-ERROR

generic (

`HANDLE-FATAL-ERROR`

CLIENT)

This function is used to handle a fatal, aborting connection error.

You can use this to either simply close and exit, or to try
and reestablish a new connection.

See HANDLE-CONNECTION

generic (

`OPEN-CONNECTION`

CLIENT)

Initiate the connection from the client to the connection.

Implements the proper connection procedure as mandated by the
protocol in §4.1. If the connection fails, for whatever reason,
an error is signalled. If the connection succeeds, a background
thread is started that calls HANDLE-CONNECTION.

See HANDLE-CONNECTION

generic (

`PROCESS`

OBJECT CLIENT)

This method is intended to be extended by user code and is called with any update received from the server.

Default methods exist for the following update types:
 * LICHAT-PROTOCOL:PING       -- Automatically replies to the server
                                 with a LICHAT-PROTOCOL:PONG update.
 * LICHAT-PROTOCOL:DISCONNECT -- Invoke the CLOSE-CONNECTION restart.
 * T                          -- Print the object via Verbose.

See HANDLE-CONNECTION
See LICHAT-PROTOCOL:PING
See LICHAT-PROTOCOL:DISCONNECT

generic (

`READ-MESSAGE`

CLIENT)

Reads wireables from the client's stream until one can be read successfully.

This is to say, it will repeatedly try to read a message,
ignoring all LICHAT-PROTOCOL:WIRE-CONDITIONs until one can
be read without such an error. The message is returned.

See LICHAT-PROTOCOL:WIREABLE
See LICHAT-PROTOCOL:FROM-WIRE
See SOCKET-STREAM

generic (

`SEND`

OBJECT CLIENT)

Send an update over the client connection to the server.

See LICHAT-PROTOCOL:TO-WIRE
See SOCKET-STREAM

macro (

`WITH-RESPONSE`

&REST ARGS)

Shorthand macro to await a response from the server that matches the update generated in the INIT form.

See CALL-WITH-RESPONSE