src/sockets/base-sockets.lisp

   1 ;;;; -*- Mode: Lisp; indent-tabs-mode: nil -*-
   2 ;;;
   3 ;;; --- Base socket classes.
   4 ;;;
   5
   6 (in-package :iolib.sockets)
   7
   8 ;;;; Sockets
   9
  10 (defclass socket (dual-channel-fd-mixin)
  11   ((address-family :initarg :address-family :accessor socket-address-family)
  12    (protocol :initarg :protocol :accessor socket-protocol)
  13    (bound    :initform nil      :reader   socket-bound-p :type boolean))
  14   (:documentation "Base class for sockets."))
  15 (unset-method-docstring #'socket-address-family () '(socket))
  16 (set-function-docstring 'socket-address-family "Return the address family of a socket.")
  17 (unset-method-docstring #'socket-protocol () '(socket))
  18 (set-function-docstring 'socket-protocol "Return the protocol of a socket.")
  19
  20 (defgeneric make-socket (&key address-family type connect ipv6 external-format
  21                               &allow-other-keys)
  22   (:documentation "Create an instance of a subclass of SOCKET. ADDRESS-FAMILY, TYPE, CONNECT and IPV6
  23 are used to specify the kind of socket to create.
  24
  25 * ADDRESS-FAMILY - :INTERNET or :LOCAL (or :FILE as synonim)
  26 * TYPE - :STREAM or :DATAGRAM
  27 * CONNECT - :ACTIVE or :PASSIVE
  28 * IPV6 - if NIL, create an IPv4 socket, otherwise an IPv6 socket.
  29
  30 To initialize the socket, the following keyword arguments can be used depending on ADDRESS-FAMILY, TYPE and CONNECT:
  31 * :local-host - a hostname designator or NIL. If non-null the socket will be bound to this address
  32 * :local-port - a port designator or NIL. If LOCAL-HOST is non-null, bind the socket to this port. If NIL, choose a random port
  33 * :remote-host - a hostname designator or NIL. If non-null the socket will be connected to this address
  34 * :remote-port - a port designator. If REMOTE-HOST is non-null, connect the socket to this port
  35 * :local-filename - a string or NIL. If non-null the socket will be bound to this file
  36 * :remote-filename - a string or NIL. If non-null the socket will be connected to this file
  37 * :backlog - a positive integer or NIL. Specifies the length of the incomming connection queue and can't be larger than +MAX-BACKLOG-SIZE+. If NIL, default is *DEFAULT-BACKLOG-SIZE*
  38 * :reuse-address: a boolean(default T). set option SO_REUSEADDR if LOCAL-HOST is non-null
  39 * :keepalive - a boolean. set option SO_KEEPALIVE
  40 * :nodelay - a boolean. set option SO_NODELAY
  41 * :interface - a string. set option SO_BINDTODEVICE to this interface
  42 * :input-buffer-size - a positive integer. Create the stream input buffer of this size
  43 * :output-buffer-size - a positive integer. Create the stream output buffer of this size
  44
  45 Glossary:
  46 * hostname designator: an instance of INET-ADDRESS or any object accepted by LOOKUP-HOST. IPV6 is passed to LOOKUP-HOST as is
  47 * port designator: any object accepted by LOOKUP-SERVICE
  48
  49 :address-family :INTERNET :type :STREAM :connect :ACTIVE
  50 * Valid keyword args: :LOCAL-HOST, :LOCAL-PORT, :REMOTE-HOST, :REMOTE-PORT, :REUSE-ADDRESS, :KEEPALIVE, :NODELAY, :INPUT-BUFFER-SIZE and :OUTPUT-BUFFER-SIZE
  51
  52 :address-family :INTERNET :type :STREAM :connect :PASSIVE
  53 * Valid keyword args: :LOCAL-HOST, :LOCAL-PORT, :BACKLOG, :REUSE-ADDRESS, :INTERFACE and :NODELAY
  54
  55 :address-family :INTERNET :type :STREAM :connect :ACTIVE
  56 * Valid keyword args: :LOCAL-FILENAME, :REMOTE-FILENAME, :INPUT-BUFFER-SIZE and :OUTPUT-BUFFER-SIZE
  57
  58 :address-family :INTERNET :type :STREAM :connect :PASSIVE
  59 * Valid keyword args: :LOCAL-FILENAME, :REMOTE-FILENAME, :BACKLOG and :REUSE-ADDRESS
  60
  61 :address-family :INTERNET :type :DATAGRAM
  62 * Valid keyword args: :LOCAL-HOST, :LOCAL-PORT, :REMOTE-HOST, :REMOTE-PORT, :REUSE-ADDRESS, :INTERFACE and :BROADCAST
  63
  64 :address-family :LOCAL :type :DATAGRAM
  65 * Valid keyword args: :LOCAL-FILENAME and :REMOTE-FILENAME"))
  66
  67 (defgeneric make-socket-from-fd (fd &key connect external-format
  68                                     input-buffer-size output-buffer-size)
  69   (:documentation "Create a socket instance of the appropriate subclass of SOCKET using FD.
  70 The connection type of the socket must be specified - :ACTIVE or :PASSIVE.
  71 The address family and type of the socket are automatically discovered using OS functions. Buffer sizes
  72 for the new socket can also be specified using INPUT-BUFFER-SIZE and OUTPUT-BUFFER-SIZE."))
  73
  74 (defgeneric make-socket-pair (&key type protocol external-format
  75                                    input-buffer-size output-buffer-size)
  76   (:documentation "Create a pair of sockets connected to each other.
  77 The socket type must be either :STREAM or :DATAGRAM. Currently OSes can only create :LOCAL sockets this way.
  78 Buffer sizes for the new sockets can also be specified using INPUT-BUFFER-SIZE and OUTPUT-BUFFER-SIZE."))
  79
  80 (defgeneric socket-os-fd (socket)
  81   (:documentation "Returns the OS file descriptor of SOCKET."))
  82
  83 (defgeneric socket-type (socket)
  84   (:documentation "Returns the socket type of SOCKET - :STREAM or :DATAGRAM."))
  85
  86 (defgeneric socket-open-p (socket)
  87   (:documentation "Returns a boolean indicating whether or not the file descriptor of SOCKET is open."))
  88
  89 (defgeneric local-name (socket)
  90   (:documentation "For INTERNET sockets, returns two values: the local host and the local port.
  91 For LOCAL sockets, returns the local filename."))
  92
  93 (defgeneric local-host (socket)
  94   (:documentation "Returns the local host of SOCKET.
  95 Works only on INTERNET sockets."))
  96
  97 (defgeneric local-port (socket)
  98   (:documentation "Returns the local port of SOCKET - an (UNSIGNED-BYTE 16).
  99 Works only on INTERNET sockets."))
 100
 101 (defgeneric local-filename (socket)
 102   (:documentation "Returns the local filename of SOCKET.
 103 Works only on LOCAL sockets."))
 104
 105 (defgeneric remote-name (socket)
 106   (:documentation "For INTERNET sockets, returns two values: the remote host and the remote port.
 107 For REMOTE sockets, returns the remote filename."))
 108
 109 (defgeneric remote-host (socket)
 110   (:documentation "Returns the remote host of SOCKET.
 111 Works only on INTERNET sockets."))
 112
 113 (defgeneric remote-port (socket)
 114   (:documentation "Returns the remote port of SOCKET - an (UNSIGNED-BYTE 16).
 115 Works only on INTERNET sockets."))
 116
 117 (defgeneric remote-filename (socket)
 118   (:documentation "Returns the remote filename of SOCKET.
 119 Works only on LOCAL sockets."))
 120
 121 (defgeneric socket-option (socket option-name)
 122   (:documentation "Returns the value(s) of OS option OPTION-NAME on SOCKET.
 123 For a complete list of supported options see src/sockets/socket-options.lisp."))
 124
 125 (defclass stream-socket (socket) ()
 126   (:default-initargs :type :stream)
 127   (:documentation "Mixin for sockets of type SOCK_STREAM."))
 128
 129 (defclass datagram-socket (socket) ()
 130   (:default-initargs :type :datagram)
 131   (:documentation "Mixin for sockets of type SOCK_DGRAM."))
 132
 133 (defclass raw-socket (socket) ()
 134   (:default-initargs :type :raw)
 135   (:documentation "Mixin for sockets of type SOCK_RAW."))
 136
 137 (defgeneric disconnect (socket)
 138   (:documentation "Disassociates SOCKET from any remote address.
 139 Works only on DATAGRAM sockets."))
 140
 141 (define-symbol-macro +default-inet-address-family+
 142   (if *ipv6* :ipv6 :ipv4))
 143
 144 (defclass internet-socket (socket) ()
 145   (:default-initargs :address-family +default-inet-address-family+)
 146   (:documentation "Mixin for sockets of domain AF_INET or AF_INET6."))
 147
 148 (defclass local-socket (socket) ()
 149   (:default-initargs :address-family :local)
 150   (:documentation "Mixin for sockets of domain AF_LOCAL."))
 151
 152 (defgeneric send-file-descriptor (socket file-descriptor)
 153   (:documentation "Send FILE-DESCRIPTOR through SOCKET.
 154 The receiving process must use RECEIVE-FILE-DESCRIPTOR to receive the
 155 file descriptor in order for it to be valid in the receiving process."))
 156
 157 (defgeneric receive-file-descriptor (socket)
 158   (:documentation "Receive a file descriptor as ancillary data through SOCKET."))
 159
 160 (defun socket-read-fn (fd buffer nbytes)
 161   (debug-only
 162     (assert buffer)
 163     (assert fd))
 164   (%recvfrom fd buffer nbytes 0 (null-pointer) (null-pointer)))
 165
 166 (defun socket-write-fn (fd buffer nbytes)
 167   (debug-only
 168     (assert buffer)
 169     (assert fd))
 170   (%sendto fd buffer nbytes 0 (null-pointer) 0))
 171
 172 (defclass active-socket (socket dual-channel-gray-stream) ()
 173   (:default-initargs :read-fn #'socket-read-fn
 174                      :write-fn #'socket-write-fn)
 175   (:documentation "Mixin class for active(client) sockets."))
 176
 177 (defgeneric connect (socket address &key &allow-other-keys)
 178   (:documentation "Connects SOCKET to ADDRESS. For INTERNET sockets you can specify
 179 the port to connect to using keyword argument PORT. The default value of PORT is 0,
 180 which usually means letting the OS choose a random port to connect to.
 181 WAIT specifies how long to wait for a connection: NIL means \"return immediately\", a non-negative real
 182 specifies a timeout in seconds and T means \"wait forever\"."))
 183
 184 (defgeneric socket-connected-p (socket)
 185   (:documentation "Returns a boolean specifying whether or not SOCKET is connected."))
 186
 187 (defgeneric shutdown (socket &key read write)
 188   (:documentation "Shut down all or part of a connection. If READ it non-NIL, further receptions are
 189 disallowed; if WRITE is non-NIL, further transmissions are disallowed. CLOSE must still be called on
 190 SOCKET in order to release OS resources."))
 191
 192 (defgeneric receive-from (socket &rest args &key &allow-other-keys)
 193   (:documentation "Receives data from SOCKET. If BUFFER is specified
 194 START and END are used as bounding index. In that case BUFFER must be
 195 an array and its ARRAY-ELEMENT-TYPE be either (UNSIGNED-BYTE 8) or T.
 196 If BUFFER is not specified an (UNSIGNED-BYTE 8) buffer of size SIZE
 197 will be allocated.
 198
 199 Some flags can also be passed to recvfrom(2):
 200 * :OUT-OF-BAND for receiving out-of-band data - only for STREAM sockets
 201 * :PEEK for keeping the returned data in the kernel buffers
 202 * :WAIT-ALL for waiting until the entire buffer can be filled
 203 * :DONT-WAIT for making only the current call non-blocking
 204
 205 The first two values returned are the buffer and the number of elements that have been copied into the buffer.
 206 For INTERNET DATAGRAM sockets, two additional values are returned: the host and port of the remote peer
 207 from which the data was received.
 208 For LOCAL DATAGRAM sockets, one additional values is returned: the filename of the remote peer
 209 from which the data was received."))
 210
 211 (defgeneric send-to (socket buffer &rest args &key &allow-other-keys)
 212   (:documentation "Send the contents of BUFFER to SOCKET.
 213 BUFFER must be a vector that can be coerced to a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*)).
 214 START and END are used a bounding index on BUFFER.
 215 For disconnected datagram sockets, REMOTE-HOST and REMOTE-PORT or REMOTE-FILENAME are used
 216 as destination for the data.
 217
 218 Some flags can also be passed to sendto(2):
 219 * :OUT-OF-BAND for receiving out-of-band data - only for stream sockets
 220 * :DONT-WAIT for making only the current call non-blocking
 221 * :DONT-ROUTE for sending only to hosts on directly connected networks, not using gateways
 222 * :CONFIRM for signalling progress on the link layer - only available on Linux and only with DATAGRAM sockets
 223 * :MORE for telling the kernel that there is more data to send - only available on Linux
 224
 225 Returns the number of bytes sent."))
 226
 227 (defclass passive-socket (socket)
 228   ((listening :initform nil :reader socket-listening-p :type boolean)
 229    (external-format :initarg :external-format :reader external-format-of)
 230    (active-class :initarg :active-class :reader active-class
 231                  :type symbol :allocation :class))
 232   (:default-initargs :external-format :default)
 233   (:documentation "Mixin class for PASSIVE(server) sockets."))
 234
 235 (defgeneric bind-address (socket address &key &allow-other-keys)
 236   (:documentation "Sets the local address of SOCKET to ADDRESS(and PORT for INTERNET sockets).
 237 REUSE-ADDRESS sets the SO_REUSEADDR socket option on SOCKET."))
 238
 239 (defgeneric listen-on (socket &key &allow-other-keys)
 240   (:documentation "Start allowing incoming connections on SOCKET.
 241 BACKLOG specifies the maximum length of the queue of pending connections."))
 242
 243 (defgeneric accept-connection (passive-socket &key &allow-other-keys)
 244   (:documentation "Extracts the first connection from the queue of pending connections on SOCKET.
 245 WAIT specifies how long to wait for a connection: NIL means \"return immediately\", a non-negative real
 246 specifies a timeout in seconds and T means \"wait forever\".
 247 EXTERNAL-FORMAT optionally specifies the external format of the new socket - the default being
 248 that of SOCKET. Buffer sizes for the new socket can also be specified using INPUT-BUFFER-SIZE
 249 and OUTPUT-BUFFER-SIZE.
 250 If a connection is received, returns two or three values: the newly created socket, the remote peer
 251 address and the remote port if applicable."))
 252
 253 (defclass socket-stream-internet-active
 254     (active-socket stream-socket internet-socket) ()
 255   (:documentation "Class representing active sockets of type SOCK_STREAM and domain AF_INET or AF_INET6."))
 256
 257 (defclass socket-stream-internet-passive
 258     (passive-socket stream-socket internet-socket) ()
 259   (:default-initargs :active-class 'socket-stream-internet-active)
 260   (:documentation "Class representing passive sockets of type SOCK_STREAM and domain AF_INET or AF_INET6."))
 261
 262 (defclass socket-stream-local-active
 263     (active-socket stream-socket local-socket) ()
 264   (:documentation "Class representing active sockets of type SOCK_STREAM and domain AF_LOCAL."))
 265
 266 (defclass socket-stream-local-passive
 267     (passive-socket stream-socket local-socket) ()
 268   (:default-initargs :active-class 'socket-stream-local-active)
 269   (:documentation "Class representing passive sockets of type SOCK_STREAM and domain AF_LOCAL."))
 270
 271 (defclass socket-datagram-internet
 272     (datagram-socket internet-socket) ()
 273   (:documentation "Class representing active sockets of type SOCK_DGRAM and domain AF_INET or AF_INET6."))
 274
 275 (defclass socket-datagram-local
 276     (datagram-socket local-socket) ()
 277   (:documentation "Class representing active sockets of type SOCK_DGRAM and domain AF_LOCAL."))
 278
 279 (defclass socket-raw-internet
 280     (internet-socket raw-socket) ()
 281   (:default-initargs :type :raw)
 282   (:documentation "Class representing active sockets of type SOCK_RAW and domain AF_LOCAL."))