lichat tcp client

1.0.0

A simple TCP client implementation for lichat

Table of Contents

About Lichat-TCP-Client

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.

Mini Client

You can also try a minimal sample client by calling mini-client. The client is meant to illustrate simple use of the library, so make sure to check out its source file, mini.lisp.

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.

System Information

Version: 1.0.0

Dependencies:

Author: Yukari Hafner

License: zlib

Homepage: https://Shirakumo.github.io/lichat-tcp-client/

Bug Tracker: https://github.com/Shirakumo/lichat-tcp-client/issues

Sources: https://github.com/Shirakumo/lichat-tcp-client.git

Definition Index

LICHAT-TCP-CLIENT

ORG.SHIRAKUMO.LICHAT.TCP-CLIENT

No documentation provided.

EXTERNAL SPECIAL-VARIABLE

DEFAULT-PORT

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

EXTERNAL CLASS

CLIENT

Class to represent a Lichat client.

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

EXTERNAL CLASS
MINI-CLIENT
Source
No documentation provided.
EXTERNAL FUNCTION
MINI-CLIENT
- &KEY
- USERNAME
- PASSWORD
- HOSTNAME
- PORT
- &REST
Source
No documentation provided.

EXTERNAL FUNCTION

S

CLIENT
TYPE
&REST
ARGS
&REST

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

EXTERNAL FUNCTION
S-DATA
- CLIENT
- CHANNEL
- FILE
- &REST
Source
No documentation provided.

EXTERNAL GENERIC-FUNCTION

CALL-WITH-RESPONSE

FUNCTION
CLIENT
INIT
&REST

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

EXTERNAL GENERIC-FUNCTION

CLOSE-CONNECTION

CLIENT
&REST

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

EXTERNAL GENERIC-FUNCTION
CONNECTION-OPEN-P
- CLIENT
- &REST
No documentation provided.

EXTERNAL GENERIC-FUNCTION

HANDLE-CONNECTION

CLIENT
&REST

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

EXTERNAL GENERIC-FUNCTION

HANDLE-FATAL-ERROR

CLIENT
&REST

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

EXTERNAL GENERIC-FUNCTION

HOSTNAME

OBJECT
&REST

Accessor to the TCP hostname the client is connecting to.

See CLIENT

EXTERNAL GENERIC-FUNCTION
(SETF HOSTNAME)
- NEW-VALUE
- OBJECT
- &REST
No documentation provided.

EXTERNAL GENERIC-FUNCTION

OPEN-CONNECTION

CLIENT
&REST

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

EXTERNAL GENERIC-FUNCTION

PASSWORD

OBJECT
&REST

Accessor to the password of the client, if any.

See CLIENT
See LICHAT-PROTOCOL:PASSWORD

EXTERNAL GENERIC-FUNCTION
(SETF PASSWORD)
- NEW-VALUE
- OBJECT
- &REST
No documentation provided.

EXTERNAL GENERIC-FUNCTION

PORT

OBJECT
&REST

Accessor to the TCP port the client is connecting over.

See CLIENT

EXTERNAL GENERIC-FUNCTION
(SETF PORT)
- NEW-VALUE
- OBJECT
- &REST
No documentation provided.

EXTERNAL GENERIC-FUNCTION

PROCESS

OBJECT
CLIENT
&REST

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

EXTERNAL GENERIC-FUNCTION

READ-MESSAGE

CLIENT
&REST

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

EXTERNAL GENERIC-FUNCTION

SEND

OBJECT
CLIENT
&REST

Send an update over the client connection to the server.

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

EXTERNAL GENERIC-FUNCTION

SOCKET

OBJECT
&REST

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

See CLIENT

EXTERNAL GENERIC-FUNCTION
(SETF SOCKET)
- NEW-VALUE
- OBJECT
- &REST
No documentation provided.

EXTERNAL GENERIC-FUNCTION

THREAD

OBJECT
&REST

Accessor to the background processing thread of the client.

See CLIENT

EXTERNAL GENERIC-FUNCTION
(SETF THREAD)
- NEW-VALUE
- OBJECT
- &REST
No documentation provided.
EXTERNAL GENERIC-FUNCTION
URL
- CLIENT
- &REST
No documentation provided.

EXTERNAL GENERIC-FUNCTION

USERNAME

OBJECT
&REST

Accessor to the username of the client.

See CLIENT
See LICHAT-PROTOCOL:USERNAME

EXTERNAL GENERIC-FUNCTION
(SETF USERNAME)
- NEW-VALUE
- OBJECT
- &REST
No documentation provided.

EXTERNAL MACRO

WITH-RESPONSE

MESSAGE
CLIENT
&REST

INIT
&BODY
BODY
&REST

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

See CALL-WITH-RESPONSE