The lichat-tcp-client Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The lichat-tcp-client Reference Manual

This is the lichat-tcp-client Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:05:18 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

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:

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


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 lichat-tcp-client

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

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

License

Artistic

Description

A simple TCP client implementation for lichat

Version

1.0.0

Dependencies
Source

lichat-tcp-client.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 lichat-tcp-client.asd

Location

lichat-tcp-client.asd

Systems

lichat-tcp-client (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 lichat-tcp-client/package.lisp

Parent

lichat-tcp-client (system)

Location

package.lisp

Packages

lichat-tcp-client


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 lichat-tcp-client/client.lisp

Dependency

package.lisp (file)

Parent

lichat-tcp-client (system)

Location

client.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 lichat-tcp-client/documentation.lisp

Dependency

client.lisp (file)

Parent

lichat-tcp-client (system)

Location

documentation.lisp


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 lichat-tcp-client

Source

package.lisp (file)

Nickname

org.shirakumo.lichat.tcp-client

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Compiler macros

Compiler Macro: s CLIENT TYPE &rest ARGS
Package

lichat-tcp-client

Source

client.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Functions

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

Generic Function: password OBJECT

Accessor to the password of the client, if any.

See CLIENT
See LICHAT-PROTOCOL:PASSWORD

Package

lichat-tcp-client

Writer

(setf password) (generic function)

Methods
Method: password (CLIENT client)

automatically generated reader method

Source

client.lisp (file)

Generic Function: (setf password) NEW-VALUE OBJECT
Package

lichat-tcp-client

Reader

password (generic function)

Methods
Method: (setf password) NEW-VALUE (CLIENT client)

automatically generated writer method

Source

client.lisp (file)

Generic Function: port OBJECT

Accessor to the TCP port the client is connecting over.

See CLIENT

Package

lichat-tcp-client

Writer

(setf port) (generic function)

Methods
Method: port (CLIENT client)

automatically generated reader method

Source

client.lisp (file)

Generic Function: (setf port) NEW-VALUE OBJECT
Package

lichat-tcp-client

Reader

port (generic function)

Methods
Method: (setf port) NEW-VALUE (CLIENT client)

automatically generated writer method

Source

client.lisp (file)

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 disconnect) (CLIENT client)
Source

client.lisp (file)

Method: process (UPDATE ping) (CLIENT client)
Source

client.lisp (file)

Method: process OBJECT (CLIENT client)
Source

client.lisp (file)

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 (file)

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 wire-object) (CLIENT client)
Source

client.lisp (file)

Generic Function: socket OBJECT

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

See CLIENT

Package

lichat-tcp-client

Writer

(setf socket) (generic function)

Methods
Method: socket (CLIENT client)

automatically generated reader method

Source

client.lisp (file)

Generic Function: (setf socket) NEW-VALUE OBJECT
Package

lichat-tcp-client

Reader

socket (generic function)

Methods
Method: (setf socket) NEW-VALUE (CLIENT client)

automatically generated writer method

Source

client.lisp (file)

Generic Function: thread OBJECT

Accessor to the background processing thread of the client.

See CLIENT

Package

lichat-tcp-client

Writer

(setf thread) (generic function)

Methods
Method: thread (CLIENT client)

automatically generated reader method

Source

client.lisp (file)

Generic Function: (setf thread) NEW-VALUE OBJECT
Package

lichat-tcp-client

Reader

thread (generic function)

Methods
Method: (setf thread) NEW-VALUE (CLIENT client)

automatically generated writer method

Source

client.lisp (file)

Generic Function: username OBJECT

Accessor to the username of the client.

See CLIENT
See LICHAT-PROTOCOL:USERNAME

Package

lichat-tcp-client

Writer

(setf username) (generic function)

Methods
Method: username (CLIENT client)

automatically generated reader method

Source

client.lisp (file)

Generic Function: (setf username) NEW-VALUE OBJECT
Package

lichat-tcp-client

Reader

username (generic function)

Methods
Method: (setf username) NEW-VALUE (CLIENT client)

automatically generated writer method

Source

client.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: username
Initargs

:username

Readers

username (generic function)

Writers

(setf username) (generic function)

Slot: password
Initargs

:password

Readers

password (generic function)

Writers

(setf password) (generic function)

Slot: hostname
Initargs

:hostname

Readers

hostname (generic function)

Writers

(setf hostname) (generic function)

Slot: port
Initargs

:port

Readers

port (generic function)

Writers

(setf port) (generic function)

Slot: socket
Initargs

:socket

Readers

socket (generic function)

Writers

(setf socket) (generic function)

Slot: thread
Initargs

:thread

Readers

thread (generic function)

Writers

(setf thread) (generic function)

Direct Default Initargs
InitargValue
:username(machine-instance)
:passwordnil
:hostname"localhost"
:portlichat-tcp-client:*default-port*
:threadnil

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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 (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Generic functions

Generic Function: hostname OBJECT

Accessor to the TCP hostname the client is connecting to.

See CLIENT

Package

lichat-tcp-client

Writer

(setf hostname) (generic function)

Methods
Method: hostname (CLIENT client)

automatically generated reader method

Source

client.lisp (file)

Generic Function: (setf hostname) NEW-VALUE OBJECT
Package

lichat-tcp-client

Reader

hostname (generic function)

Methods
Method: (setf hostname) NEW-VALUE (CLIENT client)

automatically generated writer method

Source

client.lisp (file)

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 (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L  
Index Entry  Section

F
File, Lisp, lichat-tcp-client.asd: The lichat-tcp-client<dot>asd file
File, Lisp, lichat-tcp-client/client.lisp: The lichat-tcp-client/client<dot>lisp file
File, Lisp, lichat-tcp-client/documentation.lisp: The lichat-tcp-client/documentation<dot>lisp file
File, Lisp, lichat-tcp-client/package.lisp: The lichat-tcp-client/package<dot>lisp file

L
lichat-tcp-client.asd: The lichat-tcp-client<dot>asd file
lichat-tcp-client/client.lisp: The lichat-tcp-client/client<dot>lisp file
lichat-tcp-client/documentation.lisp: The lichat-tcp-client/documentation<dot>lisp file
lichat-tcp-client/package.lisp: The lichat-tcp-client/package<dot>lisp file
Lisp File, lichat-tcp-client.asd: The lichat-tcp-client<dot>asd file
Lisp File, lichat-tcp-client/client.lisp: The lichat-tcp-client/client<dot>lisp file
Lisp File, lichat-tcp-client/documentation.lisp: The lichat-tcp-client/documentation<dot>lisp file
Lisp File, lichat-tcp-client/package.lisp: The lichat-tcp-client/package<dot>lisp file

Jump to:   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

(
(setf hostname): Internal generic functions
(setf hostname): Internal generic functions
(setf password): Exported generic functions
(setf password): Exported generic functions
(setf port): Exported generic functions
(setf port): Exported generic functions
(setf socket): Exported generic functions
(setf socket): Exported generic functions
(setf thread): Exported generic functions
(setf thread): Exported generic functions
(setf username): Exported generic functions
(setf username): Exported generic functions

C
call-with-response: Exported generic functions
call-with-response: Exported generic functions
close-connection: Exported generic functions
close-connection: Exported generic functions
Compiler Macro, s: Exported compiler macros

F
Function, s: Exported functions

G
Generic Function, (setf hostname): Internal generic functions
Generic Function, (setf password): Exported generic functions
Generic Function, (setf port): Exported generic functions
Generic Function, (setf socket): Exported generic functions
Generic Function, (setf thread): Exported generic functions
Generic Function, (setf username): Exported generic functions
Generic Function, call-with-response: Exported generic functions
Generic Function, close-connection: Exported generic functions
Generic Function, handle-connection: Exported generic functions
Generic Function, handle-fatal-error: Exported generic functions
Generic Function, hostname: Internal generic functions
Generic Function, open-connection: Exported generic functions
Generic Function, password: Exported generic functions
Generic Function, port: Exported generic functions
Generic Function, process: Exported generic functions
Generic Function, read-message: Exported generic functions
Generic Function, send: Exported generic functions
Generic Function, socket: Exported generic functions
Generic Function, socket-stream: Internal generic functions
Generic Function, thread: Exported generic functions
Generic Function, username: Exported generic functions

H
handle-connection: Exported generic functions
handle-connection: Exported generic functions
handle-fatal-error: Exported generic functions
handle-fatal-error: Exported generic functions
hostname: Internal generic functions
hostname: Internal generic functions

M
Macro, with-eresponse: Internal macros
Macro, with-response: Exported macros
Method, (setf hostname): Internal generic functions
Method, (setf password): Exported generic functions
Method, (setf port): Exported generic functions
Method, (setf socket): Exported generic functions
Method, (setf thread): Exported generic functions
Method, (setf username): Exported generic functions
Method, call-with-response: Exported generic functions
Method, close-connection: Exported generic functions
Method, handle-connection: Exported generic functions
Method, handle-fatal-error: Exported generic functions
Method, hostname: Internal generic functions
Method, open-connection: Exported generic functions
Method, password: Exported generic functions
Method, port: Exported generic functions
Method, process: Exported generic functions
Method, process: Exported generic functions
Method, process: Exported generic functions
Method, read-message: Exported generic functions
Method, send: Exported generic functions
Method, socket: Exported generic functions
Method, socket-stream: Internal generic functions
Method, thread: Exported generic functions
Method, username: Exported generic functions

O
open-connection: Exported generic functions
open-connection: Exported generic functions

P
password: Exported generic functions
password: Exported generic functions
port: Exported generic functions
port: Exported generic functions
process: Exported generic functions
process: Exported generic functions
process: Exported generic functions
process: Exported generic functions

R
read-message: Exported generic functions
read-message: Exported generic functions

S
s: Exported compiler macros
s: Exported functions
send: Exported generic functions
send: Exported generic functions
socket: Exported generic functions
socket: Exported generic functions
socket-stream: Internal generic functions
socket-stream: Internal generic functions

T
thread: Exported generic functions
thread: Exported generic functions

U
username: Exported generic functions
username: Exported generic functions

W
with-eresponse: Internal macros
with-response: Exported macros

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

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
H   P   S   T   U  
Index Entry  Section

*
*default-port*: Exported special variables

H
hostname: Exported classes

P
password: Exported classes
port: Exported classes

S
Slot, hostname: Exported classes
Slot, password: Exported classes
Slot, port: Exported classes
Slot, socket: Exported classes
Slot, thread: Exported classes
Slot, username: Exported classes
socket: Exported classes
Special Variable, *default-port*: Exported special variables

T
thread: Exported classes

U
username: Exported classes

Jump to:   *  
H   P   S   T   U  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   L   P   S  
Index Entry  Section

C
Class, client: Exported classes
client: Exported classes

L
lichat-tcp-client: The lichat-tcp-client system
lichat-tcp-client: The lichat-tcp-client package

P
Package, lichat-tcp-client: The lichat-tcp-client package

S
System, lichat-tcp-client: The lichat-tcp-client system

Jump to:   C   L   P   S