net.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 :net.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 socket-os-fd (socket)
  21   (:documentation "Returns the OS file descriptor of `SOCKET'."))
  22
  23 (defgeneric socket-type (socket)
  24   (:documentation "Returns the socket type of `SOCKET' - one of :STREAM or :DATAGRAM."))
  25
  26 (defgeneric socket-open-p (socket)
  27   (:documentation "Returns a boolean indicating whether or not the file descriptor of `SOCKET' is open."))
  28
  29 (defgeneric local-name (socket)
  30   (:documentation "For INTERNET sockets, returns two values: the local host and the local port.
  31 For LOCAL sockets, returns the local filename."))
  32
  33 (defgeneric local-host (socket)
  34   (:documentation "Returns the local host of `SOCKET'.
  35 Works only on INTERNET sockets."))
  36
  37 (defgeneric local-port (socket)
  38   (:documentation "Returns the local port of `SOCKET' - an (unsigned-byte 16).
  39 Works only on INTERNET sockets."))
  40
  41 (defgeneric local-filename (socket)
  42   (:documentation "Returns the local filename of `SOCKET'.
  43 Works only on LOCAL sockets."))
  44
  45 (defgeneric remote-name (socket)
  46   (:documentation "For INTERNET sockets, returns two values: the remote host and the remote port.
  47 For REMOTE sockets, returns the remote filename."))
  48
  49 (defgeneric remote-host (socket)
  50   (:documentation "Returns the remote host of `SOCKET'.
  51 Works only on INTERNET sockets."))
  52
  53 (defgeneric remote-port (socket)
  54   (:documentation "Returns the remote port of `SOCKET' - an (unsigned-byte 16).
  55 Works only on INTERNET sockets."))
  56
  57 (defgeneric remote-filename (socket)
  58   (:documentation "Returns the remote filename of `SOCKET'.
  59 Works only on LOCAL sockets."))
  60
  61 (defgeneric socket-option (socket option-name)
  62   (:documentation "Returns the value(s) of OS options on `SOCKET'.
  63 For a complete list of supported options see net.sockets/socket-options.lisp ."))
  64
  65 (defclass stream-socket (socket) ()
  66   (:default-initargs :type :stream)
  67   (:documentation "Mixin for sockets of type SOCK_STREAM."))
  68
  69 (defclass datagram-socket (socket) ()
  70   (:default-initargs :type :datagram)
  71   (:documentation "Mixin for sockets of type SOCK_DGRAM."))
  72
  73 (defgeneric disconnect (socket)
  74   (:documentation "Disassociates `SOCKET' from any remote address.
  75 Works only on DATAGRAM sockets."))
  76
  77 (define-symbol-macro +default-inet-address-family+
  78     (if *ipv6* :ipv6 :ipv4))
  79
  80 (defclass internet-socket (socket) ()
  81   (:default-initargs :address-family +default-inet-address-family+)
  82   (:documentation "Mixin for sockets of domain AF_INET or AF_INET6."))
  83
  84 (defclass local-socket (socket) ()
  85   (:default-initargs :address-family :local)
  86   (:documentation "Mixin for sockets of domain AF_LOCAL."))
  87
  88 (defgeneric send-file-descriptor (socket file-descriptor)
  89   (:documentation "Send `FILE-DESCRIPTOR' through `SOCKET'.
  90 The receiving process must use RECEIVE-FILE-DESCRIPTOR to receive the
  91 file descriptor in order for it to be valid in the receiving process."))
  92
  93 (defgeneric receive-file-descriptor (socket)
  94   (:documentation "Receive a file descriptor as ancillary data through `SOCKET'."))
  95
  96 (defun socket-read-fn (fd buffer nbytes)
  97   (%recvfrom fd buffer nbytes 0 (null-pointer) (null-pointer)))
  98
  99 (defun socket-write-fn (fd buffer nbytes)
 100   (%sendto fd buffer nbytes 0 (null-pointer) 0))
 101
 102 (defclass active-socket (socket dual-channel-gray-stream) ()
 103   (:default-initargs :read-fn 'socket-read-fn
 104                      :write-fn 'socket-write-fn)
 105   (:documentation "Mixin class for active(client) sockets."))
 106
 107 (defgeneric connect (socket address &key &allow-other-keys)
 108   (:documentation "Connects `SOCKET' to `ADDRESS'. For INTERNET sockets you can specify
 109 the port to connect to using keyword argument `PORT'. The default value of `PORT' is 0,
 110 which usually means letting the OS choose a random port to connect to.
 111 For `INTERNET' sockets, if `WAIT' is true and a connection cannot be established within
 112 `TIMEOUT' seconds signal `IOMUX:POLL-TIMEOUT', but it works only with non-blocking sockets."))
 113
 114 (defgeneric socket-connected-p (socket)
 115   (:documentation "Returns a boolean specifying whether or not `SOCKET' is connected."))
 116
 117 (defgeneric shutdown (socket &key read write)
 118   (:documentation "Shut down all or part of a connection. If `READ' it non-NIL, further receptions are
 119 disallowed; if `WRITE' is non-NIL, further transmissions are disallowed. CLOSE must still be called on
 120 `SOCKET' in order to release OS resources."))
 121
 122 (defgeneric receive-from (socket &rest args &key &allow-other-keys)
 123   (:documentation "Receives data from `SOCKET'. If `BUFFER' is specified
 124 `START' and `END' are used as bounding index. In that case `BUFFER' must be
 125 an array and its ARRAY-ELEMENT-TYPE be either (UNSIGNED-BYTE 8) or T.
 126 If `BUFFER' is not specified an (UNSIGNED-BYTE 8) buffer of size `SIZE'
 127 will be allocated.
 128
 129 Some flags can also be passed to recvfrom(2):
 130 * `OUT-OF-BAND' for receiving out-of-band data - only for stream sockets
 131 * `PEEK' for keeping the returned data in the kernel buffers
 132 * `WAIT-ALL' for waiting until the entire buffer can be filled
 133 * `DONT-WAIT' for making only the current call non-blocking
 134
 135 The first two values returned are the buffer and the number of elements that have been copied into the buffer.
 136 For INTERNET DATAGRAM sockets, two additional values are returned: the host and port of the remote peer
 137 from which the data was received.
 138 For LOCAL DATAGRAM sockets, one additional values is returned: the filename of the remote peer
 139 from which the data was received."))
 140
 141 (defgeneric send-to (socket buffer &rest args &key &allow-other-keys)
 142   (:documentation "Send the contents of `BUFFER' to `SOCKET'.
 143 `BUFFER' must be either a vector that can be coerced to a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) *).
 144 `START' and `END' are used a bounding index on `BUFFER'.
 145 For disconnected datagram sockets, `REMOTE-HOST' and `REMOTE-PORT' or `REMOTE-FILENAME' are used
 146 as destination for the data.
 147
 148 Some flags can also be passed to sendto(2):
 149 * `OUT-OF-BAND' for receiving out-of-band data - only for stream sockets
 150 * `DONT-WAIT' for making only the current call non-blocking
 151 * `DONT-ROUTE' for sending only to hosts on directly connected networks, not using gateways
 152 * `CONFIRM' for signalling progress on the link layer - only available on Linux and only with DATAGRAM sockets
 153 * `MORE' for telling the kernel that there is more data to send - only available on Linux
 154
 155 Returns the number of bytes sent."))
 156
 157 (defclass passive-socket (socket)
 158   ((listening :initform nil :reader socket-listening-p :type boolean)
 159    (external-format :initarg :external-format :reader external-format-of)
 160    (active-class :initarg :active-class :reader active-class
 161                  :type symbol :allocation :class))
 162   (:default-initargs :external-format :default)
 163   (:documentation "Mixin class for passive(server) sockets."))
 164
 165 (defgeneric bind-address (socket address &key &allow-other-keys)
 166   (:documentation "Sets the local address of `SOCKET' to `ADDRESS'(and `PORT' for INTERNET sockets).
 167 `REUSE-ADDRESS' sets the SO_REUSEADDR socket option on `SOCKET'."))
 168
 169 (defgeneric listen-on (socket &key &allow-other-keys)
 170   (:documentation "Start allowing incoming connections on `SOCKET'.
 171 `BACKLOG' specifies the maximum length of the queue of pending connections."))
 172
 173 (defgeneric accept-connection (passive-socket &key &allow-other-keys)
 174   (:documentation "Returns one connection from the queue of pending connections on `SOCKET'.
 175 If `WAIT' is true, waits until a connection is received or `TIMEOUT' expires in which case returns NIL.
 176 If `WAIT' is false and there are no pending connections return NIL.
 177 `EXTERNAL-FORMAT' optionally specifies the external format of the new socket - the default being
 178 that of `SOCKET'. Buffer sizes for the new socket can also be specified using `INPUT-BUFFER-SIZE'
 179 and `OUTPUT-BUFFER-SIZE'."))
 180
 181 (defclass socket-stream-internet-active
 182     (active-socket stream-socket internet-socket) ()
 183   (:documentation "Class representing active sockets of type SOCK_STREAM and domain AF_INET or AF_INET6."))
 184
 185 (defclass socket-stream-internet-passive
 186     (passive-socket stream-socket internet-socket) ()
 187   (:default-initargs :active-class 'socket-stream-internet-active)
 188   (:documentation "Class representing passive sockets of type SOCK_STREAM and domain AF_INET or AF_INET6."))
 189
 190 (defclass socket-stream-local-active
 191     (active-socket stream-socket local-socket) ()
 192   (:documentation "Class representing active sockets of type SOCK_STREAM and domain AF_LOCAL."))
 193
 194 (defclass socket-stream-local-passive
 195     (passive-socket stream-socket local-socket) ()
 196   (:default-initargs :active-class 'socket-stream-local-active)
 197   (:documentation "Class representing passive sockets of type SOCK_STREAM and domain AF_LOCAL."))
 198
 199 (defclass socket-datagram-internet-active
 200     (active-socket datagram-socket internet-socket) ()
 201   (:documentation "Class representing active sockets of type SOCK_DGRAM and domain AF_INET or AF_INET6."))
 202
 203 (defclass socket-datagram-local-active
 204     (active-socket datagram-socket local-socket) ()
 205   (:documentation "Class representing active sockets of type SOCK_DGRAM and domain AF_LOCAL."))