The lichat-tcp-client Reference Manual

This is the lichat-tcp-client Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:53:50 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 lichat-tcp-client

A simple TCP client implementation for lichat

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

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

Source Control

(GIT https://github.com/Shirakumo/lichat-tcp-client.git)

Bug Tracker

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

License

zlib

Version

1.0.0

Dependencies
  • lichat-protocol (system).
  • usocket (system).
  • bordeaux-threads (system).
  • documentation-utils (system).
  • verbose (system).
  • cl-base64 (system).
  • trivial-mimes (system).
Source

lichat-tcp-client.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 lichat-tcp-client/lichat-tcp-client.asd

Source

lichat-tcp-client.asd.

Parent Component

lichat-tcp-client (system).

ASDF Systems

lichat-tcp-client.


3.1.2 lichat-tcp-client/package.lisp

Source

lichat-tcp-client.asd.

Parent Component

lichat-tcp-client (system).

Packages

lichat-tcp-client.


3.1.3 lichat-tcp-client/client.lisp

Dependency

package.lisp (file).

Source

lichat-tcp-client.asd.

Parent Component

lichat-tcp-client (system).

Public Interface
Internals

3.1.4 lichat-tcp-client/mini.lisp

Dependency

client.lisp (file).

Source

lichat-tcp-client.asd.

Parent Component

lichat-tcp-client (system).

Public Interface
Internals

3.1.5 lichat-tcp-client/documentation.lisp

Dependency

mini.lisp (file).

Source

lichat-tcp-client.asd.

Parent Component

lichat-tcp-client (system).


4 Packages

Packages are listed by definition order.


4.1 lichat-tcp-client

Source

package.lisp.

Nickname

org.shirakumo.lichat.tcp-client

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *default-port*

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

Package

lichat-tcp-client.

Source

client.lisp.


5.1.2 Macros

Macro: with-response ((message client) init &body body)

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

See CALL-WITH-RESPONSE

Package

lichat-tcp-client.

Source

client.lisp.


5.1.3 Compiler macros

Compiler Macro: s (client type &rest args)
Package

lichat-tcp-client.

Source

client.lisp.


5.1.4 Ordinary functions

Function: mini-client (&key username password hostname port)
Package

lichat-tcp-client.

Source

mini.lisp.

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

Package

lichat-tcp-client.

Source

client.lisp.

Function: s-data (client channel file)
Package

lichat-tcp-client.

Source

client.lisp.


5.1.5 Generic functions

Generic Function: 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

Package

lichat-tcp-client.

Methods
Method: call-with-response (function client init)
Source

client.lisp.

Generic Function: 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

Package

lichat-tcp-client.

Methods
Method: close-connection ((client client))
Source

client.lisp.

Generic Function: connection-open-p (client)
Package

lichat-tcp-client.

Methods
Method: connection-open-p ((client client))
Source

client.lisp.

Generic Function: 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

Package

lichat-tcp-client.

Methods
Method: handle-connection ((client client))
Source

client.lisp.

Generic Function: 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

Package

lichat-tcp-client.

Methods
Method: handle-fatal-error ((client client))
Source

client.lisp.

Generic Reader: hostname (object)

Accessor to the TCP hostname the client is connecting to.

See CLIENT

Package

lichat-tcp-client.

Methods
Reader Method: hostname ((client client))

automatically generated reader method

Source

client.lisp.

Target Slot

hostname.

Generic Writer: (setf hostname) (object)
Package

lichat-tcp-client.

Methods
Writer Method: (setf hostname) ((client client))

automatically generated writer method

Source

client.lisp.

Target Slot

hostname.

Generic Function: 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

Package

lichat-tcp-client.

Methods
Method: open-connection ((client client))
Source

client.lisp.

Generic Reader: password (object)

Accessor to the password of the client, if any.

See CLIENT
See LICHAT-PROTOCOL:PASSWORD

Package

lichat-tcp-client.

Methods
Reader Method: password ((client client))

automatically generated reader method

Source

client.lisp.

Target Slot

password.

Generic Writer: (setf password) (object)
Package

lichat-tcp-client.

Methods
Writer Method: (setf password) ((client client))

automatically generated writer method

Source

client.lisp.

Target Slot

password.

Generic Reader: port (object)

Accessor to the TCP port the client is connecting over.

See CLIENT

Package

lichat-tcp-client.

Methods
Reader Method: port ((client client))

automatically generated reader method

Source

client.lisp.

Target Slot

port.

Generic Writer: (setf port) (object)
Package

lichat-tcp-client.

Methods
Writer Method: (setf port) ((client client))

automatically generated writer method

Source

client.lisp.

Target Slot

port.

Generic Function: 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

Package

lichat-tcp-client.

Methods
Method: process ((update join) (client mini-client))
Source

mini.lisp.

Method: process ((update message) (client mini-client))
Source

mini.lisp.

Method: process ((update text-update) (client mini-client))
Source

mini.lisp.

Method: process ((update channel-update) (client mini-client))
Source

mini.lisp.

Method: process (update (client mini-client))
Source

mini.lisp.

Method: process ((update disconnect) (client client))
Source

client.lisp.

Method: process ((update connect) (client client))
Source

client.lisp.

Method: process ((update ping) (client client))
Source

client.lisp.

Method: process (object (client client))
Source

client.lisp.

Generic Function: 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

Package

lichat-tcp-client.

Methods
Method: read-message ((client client))
Source

client.lisp.

Generic Function: send (object client)

Send an update over the client connection to the server.

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

Package

lichat-tcp-client.

Methods
Method: send ((object object) (client client))
Source

client.lisp.

Generic Reader: socket (object)

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

See CLIENT

Package

lichat-tcp-client.

Methods
Reader Method: socket ((client client))

automatically generated reader method

Source

client.lisp.

Target Slot

socket.

Generic Writer: (setf socket) (object)
Package

lichat-tcp-client.

Methods
Writer Method: (setf socket) ((client client))

automatically generated writer method

Source

client.lisp.

Target Slot

socket.

Generic Reader: thread (object)

Accessor to the background processing thread of the client.

See CLIENT

Package

lichat-tcp-client.

Methods
Reader Method: thread ((client client))

automatically generated reader method

Source

client.lisp.

Target Slot

thread.

Generic Writer: (setf thread) (object)
Package

lichat-tcp-client.

Methods
Writer Method: (setf thread) ((client client))

automatically generated writer method

Source

client.lisp.

Target Slot

thread.

Generic Reader: username (object)

Accessor to the username of the client.

See CLIENT
See LICHAT-PROTOCOL:USERNAME

Package

lichat-tcp-client.

Methods
Reader Method: username ((client client))

automatically generated reader method

Source

client.lisp.

Target Slot

username.

Generic Writer: (setf username) (object)
Package

lichat-tcp-client.

Methods
Writer Method: (setf username) ((client client))

automatically generated writer method

Source

client.lisp.

Target Slot

username.


5.1.6 Classes

Class: client

Class to represent a Lichat client.

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

Package

lichat-tcp-client.

Source

client.lisp.

Direct subclasses

mini-client.

Direct methods
Direct Default Initargs
InitargValue
:username(machine-instance)
:passwordnil
:hostnamelocalhost
:port*default-port*
:socketnil
:threadnil
Direct slots
Slot: username
Initargs

:username

Readers

username.

Writers

(setf username).

Slot: password
Initargs

:password

Readers

password.

Writers

(setf password).

Slot: hostname
Initargs

:hostname

Readers

hostname.

Writers

(setf hostname).

Slot: port
Initargs

:port

Readers

port.

Writers

(setf port).

Slot: socket
Initargs

:socket

Readers

socket.

Writers

(setf socket).

Slot: thread
Initargs

:thread

Readers

thread.

Writers

(setf thread).

Class: mini-client
Package

lichat-tcp-client.

Source

mini.lisp.

Direct superclasses

client.

Direct methods
Direct slots
Slot: current-channel
Readers

current-channel.

Writers

(setf current-channel).


5.2 Internals


5.2.1 Macros

Macro: with-eresponse ((message client) init &body body)

Shorthand like WITH-RESPONSE that signals an error if the matching update is not of type LICHAT-PROTOCOL:UPDATE or of type LICHAT-PROTOCOL:FAILURE.

See WITH-RESPONSE
See LICHAT-PROTOCOL:FAILURE
See LICHAT-PROTOCOL:UPDATE

Package

lichat-tcp-client.

Source

client.lisp.


5.2.2 Ordinary functions

Function: format-mini-line (update format &rest args)
Package

lichat-tcp-client.

Source

mini.lisp.


5.2.3 Generic functions

Generic Reader: current-channel (object)
Package

lichat-tcp-client.

Methods
Reader Method: current-channel ((mini-client mini-client))

automatically generated reader method

Source

mini.lisp.

Target Slot

current-channel.

Generic Writer: (setf current-channel) (object)
Package

lichat-tcp-client.

Methods
Writer Method: (setf current-channel) ((mini-client mini-client))

automatically generated writer method

Source

mini.lisp.

Target Slot

current-channel.

Generic Function: handle-command (client cmd args)
Package

lichat-tcp-client.

Methods
Method: handle-command ((client mini-client) (cmd (eql :leave)) args)
Source

mini.lisp.

Method: handle-command ((client mini-client) (cmd (eql :join)) args)
Source

mini.lisp.

Method: handle-command ((client mini-client) (cmd (eql :quit)) args)
Source

mini.lisp.

Method: handle-command ((client mini-client) cmd args)
Source

mini.lisp.

Generic Function: handle-input (client line)
Package

lichat-tcp-client.

Methods
Method: handle-input ((client mini-client) (line string))
Source

mini.lisp.

Generic Function: socket-stream (client)

Returns the stream of the socket of the client, if such is available.

See CLIENT

Package

lichat-tcp-client.

Methods
Method: socket-stream ((client client))
Source

client.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   F   G   H   M   O   P   R   S   T   U   W  
Index Entry  Section

(
(setf current-channel): Private generic functions
(setf current-channel): Private generic functions
(setf hostname): Public generic functions
(setf hostname): Public generic functions
(setf password): Public generic functions
(setf password): Public generic functions
(setf port): Public generic functions
(setf port): Public generic functions
(setf socket): Public generic functions
(setf socket): Public generic functions
(setf thread): Public generic functions
(setf thread): Public generic functions
(setf username): Public generic functions
(setf username): Public generic functions

C
call-with-response: Public generic functions
call-with-response: Public generic functions
close-connection: Public generic functions
close-connection: Public generic functions
Compiler Macro, s: Public compiler macros
connection-open-p: Public generic functions
connection-open-p: Public generic functions
current-channel: Private generic functions
current-channel: Private generic functions

F
format-mini-line: Private ordinary functions
Function, format-mini-line: Private ordinary functions
Function, mini-client: Public ordinary functions
Function, s: Public ordinary functions
Function, s-data: Public ordinary functions

G
Generic Function, (setf current-channel): Private generic functions
Generic Function, (setf hostname): Public generic functions
Generic Function, (setf password): Public generic functions
Generic Function, (setf port): Public generic functions
Generic Function, (setf socket): Public generic functions
Generic Function, (setf thread): Public generic functions
Generic Function, (setf username): Public generic functions
Generic Function, call-with-response: Public generic functions
Generic Function, close-connection: Public generic functions
Generic Function, connection-open-p: Public generic functions
Generic Function, current-channel: Private generic functions
Generic Function, handle-command: Private generic functions
Generic Function, handle-connection: Public generic functions
Generic Function, handle-fatal-error: Public generic functions
Generic Function, handle-input: Private generic functions
Generic Function, hostname: Public generic functions
Generic Function, open-connection: Public generic functions
Generic Function, password: Public generic functions
Generic Function, port: Public generic functions
Generic Function, process: Public generic functions
Generic Function, read-message: Public generic functions
Generic Function, send: Public generic functions
Generic Function, socket: Public generic functions
Generic Function, socket-stream: Private generic functions
Generic Function, thread: Public generic functions
Generic Function, username: Public generic functions

H
handle-command: Private generic functions
handle-command: Private generic functions
handle-command: Private generic functions
handle-command: Private generic functions
handle-command: Private generic functions
handle-connection: Public generic functions
handle-connection: Public generic functions
handle-fatal-error: Public generic functions
handle-fatal-error: Public generic functions
handle-input: Private generic functions
handle-input: Private generic functions
hostname: Public generic functions
hostname: Public generic functions

M
Macro, with-eresponse: Private macros
Macro, with-response: Public macros
Method, (setf current-channel): Private generic functions
Method, (setf hostname): Public generic functions
Method, (setf password): Public generic functions
Method, (setf port): Public generic functions
Method, (setf socket): Public generic functions
Method, (setf thread): Public generic functions
Method, (setf username): Public generic functions
Method, call-with-response: Public generic functions
Method, close-connection: Public generic functions
Method, connection-open-p: Public generic functions
Method, current-channel: Private generic functions
Method, handle-command: Private generic functions
Method, handle-command: Private generic functions
Method, handle-command: Private generic functions
Method, handle-command: Private generic functions
Method, handle-connection: Public generic functions
Method, handle-fatal-error: Public generic functions
Method, handle-input: Private generic functions
Method, hostname: Public generic functions
Method, open-connection: Public generic functions
Method, password: Public generic functions
Method, port: Public generic functions
Method, process: Public generic functions
Method, process: Public generic functions
Method, process: Public generic functions
Method, process: Public generic functions
Method, process: Public generic functions
Method, process: Public generic functions
Method, process: Public generic functions
Method, process: Public generic functions
Method, process: Public generic functions
Method, read-message: Public generic functions
Method, send: Public generic functions
Method, socket: Public generic functions
Method, socket-stream: Private generic functions
Method, thread: Public generic functions
Method, username: Public generic functions
mini-client: Public ordinary functions

O
open-connection: Public generic functions
open-connection: Public generic functions

P
password: Public generic functions
password: Public generic functions
port: Public generic functions
port: Public generic functions
process: Public generic functions
process: Public generic functions
process: Public generic functions
process: Public generic functions
process: Public generic functions
process: Public generic functions
process: Public generic functions
process: Public generic functions
process: Public generic functions
process: Public generic functions

R
read-message: Public generic functions
read-message: Public generic functions

S
s: Public compiler macros
s: Public ordinary functions
s-data: Public ordinary functions
send: Public generic functions
send: Public generic functions
socket: Public generic functions
socket: Public generic functions
socket-stream: Private generic functions
socket-stream: Private generic functions

T
thread: Public generic functions
thread: Public generic functions

U
username: Public generic functions
username: Public generic functions

W
with-eresponse: Private macros
with-response: Public macros