src/sockets/base-sockets.lisp

   1 ;;;; -*- Mode: Lisp; Syntax: ANSI-Common-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-single-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 «iolib.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 (defgeneric disconnect (socket)
 134   (:documentation "Disassociates SOCKET from any remote address.
 135 Works only on DATAGRAM sockets."))
 136
 137 (define-symbol-macro +default-inet-address-family+
 138   (if *ipv6* :ipv6 :ipv4))
 139
 140 (defclass internet-socket (socket) ()
 141   (:default-initargs :address-family +default-inet-address-family+)
 142   (:documentation "Mixin for sockets of domain AF_INET or AF_INET6."))
 143
 144 (defclass local-socket (socket) ()
 145   (:default-initargs :address-family :local)
 146   (:documentation "Mixin for sockets of domain AF_LOCAL."))
 147
 148 (defgeneric send-file-descriptor (socket file-descriptor)
 149   (:documentation "Send FILE-DESCRIPTOR through SOCKET.
 150 The receiving process must use RECEIVE-FILE-DESCRIPTOR to receive the
 151 file descriptor in order for it to be valid in the receiving process."))
 152
 153 (defgeneric receive-file-descriptor (socket)
 154   (:documentation "Receive a file descriptor as ancillary data through SOCKET."))
 155
 156 (defun socket-read-fn (fd buffer nbytes)
 157   (debug-only
 158     (assert buffer)
 159     (assert fd))
 160   (%recvfrom fd buffer nbytes 0 (null-pointer) (null-pointer)))
 161
 162 (defun socket-write-fn (fd buffer nbytes)
 163   (debug-only
 164     (assert buffer)
 165     (assert fd))
 166   (%sendto fd buffer nbytes 0 (null-pointer) 0))
 167
 168 (defclass active-socket (socket dual-channel-gray-stream) ()
 169   (:default-initargs :read-fn #'socket-read-fn
 170                      :write-fn #'socket-write-fn)
 171   (:documentation "Mixin class for active(client) sockets."))
 172
 173 (defgeneric connect (socket address &key &allow-other-keys)
 174   (:documentation "Connects SOCKET to ADDRESS. For INTERNET sockets you can specify
 175 the port to connect to using keyword argument PORT. The default value of PORT is 0,
 176 which usually means letting the OS choose a random port to connect to.
 177 WAIT specifies how long to wait for a connection: NIL means \"return immediately\", a non-negative real
 178 specifies a timeout in seconds and T means \"wait forever\"."))
 179
 180 (defgeneric socket-connected-p (socket)
 181   (:documentation "Returns a boolean specifying whether or not SOCKET is connected."))
 182
 183 (defgeneric shutdown (socket &key read write)
 184   (:documentation "Shut down all or part of a connection. If READ it non-NIL, further receptions are
 185 disallowed; if WRITE is non-NIL, further transmissions are disallowed. CLOSE must still be called on
 186 SOCKET in order to release OS resources."))
 187
 188 (defgeneric receive-from (socket &rest args &key &allow-other-keys)
 189   (:documentation "Receives data from SOCKET. If BUFFER is specified
 190 START and END are used as bounding index. In that case BUFFER must be
 191 an array and its ARRAY-ELEMENT-TYPE be either (UNSIGNED-BYTE 8) or T.
 192 If BUFFER is not specified an (UNSIGNED-BYTE 8) buffer of size SIZE
 193 will be allocated.
 194
 195 Some flags can also be passed to recvfrom(2):
 196 * :OUT-OF-BAND for receiving out-of-band data - only for STREAM sockets
 197 * :PEEK for keeping the returned data in the kernel buffers
 198 * :WAIT-ALL for waiting until the entire buffer can be filled
 199 * :DONT-WAIT for making only the current call non-blocking
 200
 201 The first two values returned are the buffer and the number of elements that have been copied into the buffer.
 202 For INTERNET DATAGRAM sockets, two additional values are returned: the host and port of the remote peer
 203 from which the data was received.
 204 For LOCAL DATAGRAM sockets, one additional values is returned: the filename of the remote peer
 205 from which the data was received."))
 206
 207 (defgeneric send-to (socket buffer &rest args &key &allow-other-keys)
 208   (:documentation "Send the contents of BUFFER to SOCKET.
 209 BUFFER must be a vector that can be coerced to a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*)).
 210 START and END are used a bounding index on BUFFER.
 211 For disconnected datagram sockets, REMOTE-HOST and REMOTE-PORT or REMOTE-FILENAME are used
 212 as destination for the data.
 213
 214 Some flags can also be passed to sendto(2):
 215 * :OUT-OF-BAND for receiving out-of-band data - only for stream sockets
 216 * :DONT-WAIT for making only the current call non-blocking
 217 * :DONT-ROUTE for sending only to hosts on directly connected networks, not using gateways
 218 * :CONFIRM for signalling progress on the link layer - only available on Linux and only with DATAGRAM sockets
 219 * :MORE for telling the kernel that there is more data to send - only available on Linux
 220
 221 Returns the number of bytes sent."))
 222
 223 (defclass passive-socket (socket)
 224   ((listening :initform nil :reader socket-listening-p :type boolean)
 225    (external-format :initarg :external-format :reader external-format-of)
 226    (active-class :initarg :active-class :reader active-class
 227                  :type symbol :allocation :class))
 228   (:default-initargs :external-format :default)
 229   (:documentation "Mixin class for PASSIVE(server) sockets."))
 230
 231 (defgeneric bind-address (socket address &key &allow-other-keys)
 232   (:documentation "Sets the local address of SOCKET to ADDRESS(and PORT for INTERNET sockets).
 233 REUSE-ADDRESS sets the SO_REUSEADDR socket option on SOCKET."))
 234
 235 (defgeneric listen-on (socket &key &allow-other-keys)
 236   (:documentation "Start allowing incoming connections on SOCKET.
 237 BACKLOG specifies the maximum length of the queue of pending connections."))
 238
 239 (defgeneric accept-connection (passive-socket &key &allow-other-keys)
 240   (:documentation "Extracts the first connection from the queue of pending connections on SOCKET.
 241 WAIT specifies how long to wait for a connection: NIL means \"return immediately\", a non-negative real
 242 specifies a timeout in seconds and T means \"wait forever\".
 243 EXTERNAL-FORMAT optionally specifies the external format of the new socket - the default being
 244 that of SOCKET. Buffer sizes for the new socket can also be specified using INPUT-BUFFER-SIZE
 245 and OUTPUT-BUFFER-SIZE.
 246 If a connection is received, returns two values: the newly created socket and the remote host address."))
 247
 248 (defclass socket-stream-internet-active
 249     (active-socket stream-socket internet-socket) ()
 250   (:documentation "Class representing active sockets of type SOCK_STREAM and domain AF_INET or AF_INET6."))
 251
 252 (defclass socket-stream-internet-passive
 253     (passive-socket stream-socket internet-socket) ()
 254   (:default-initargs :active-class 'socket-stream-internet-active)
 255   (:documentation "Class representing passive sockets of type SOCK_STREAM and domain AF_INET or AF_INET6."))
 256
 257 (defclass socket-stream-local-active
 258     (active-socket stream-socket local-socket) ()
 259   (:documentation "Class representing active sockets of type SOCK_STREAM and domain AF_LOCAL."))
 260
 261 (defclass socket-stream-local-passive
 262     (passive-socket stream-socket local-socket) ()
 263   (:default-initargs :active-class 'socket-stream-local-active)
 264   (:documentation "Class representing passive sockets of type SOCK_STREAM and domain AF_LOCAL."))
 265
 266 (defclass socket-datagram-internet-active
 267     (active-socket datagram-socket internet-socket) ()
 268   (:documentation "Class representing active sockets of type SOCK_DGRAM and domain AF_INET or AF_INET6."))
 269
 270 (defclass socket-datagram-local-active
 271     (active-socket datagram-socket local-socket) ()
 272   (:documentation "Class representing active sockets of type SOCK_DGRAM and domain AF_LOCAL."))