net.sockets/base-sockets.lisp

   1 ;;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; indent-tabs-mode: nil -*-
   2 ;;;
   3 ;;; base-sockets.lisp --- Base socket classes.
   4 ;;;
   5 ;;; Copyright (C) 2006-2008, Stelian Ionescu  <sionescu@common-lisp.net>
   6 ;;;
   7 ;;; This code is free software; you can redistribute it and/or
   8 ;;; modify it under the terms of the version 2.1 of
   9 ;;; the GNU Lesser General Public License as published by
  10 ;;; the Free Software Foundation, as clarified by the
  11 ;;; preamble found here:
  12 ;;;     http://opensource.franz.com/preamble.html
  13 ;;;
  14 ;;; This program is distributed in the hope that it will be useful,
  15 ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 ;;; GNU General Public License for more details.
  18 ;;;
  19 ;;; You should have received a copy of the GNU Lesser General
  20 ;;; Public License along with this library; if not, write to the
  21 ;;; Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  22 ;;; Boston, MA 02110-1301, USA
  23
  24 (in-package :net.sockets)
  25
  26 ;;;; Sockets
  27
  28 (defclass socket (dual-channel-single-fd-mixin)
  29   ((family   :initarg :family   :accessor socket-family)
  30    (protocol :initarg :protocol :accessor socket-protocol)
  31    (bound    :initform nil      :reader   socket-bound-p :type boolean)))
  32
  33 (defgeneric socket-os-fd (socket)
  34   (:documentation "Returns the OS file descriptor of `SOCKET'."))
  35
  36 (defgeneric socket-type (socket)
  37   (:documentation "Returns the socket type of `SOCKET' - one of :STREAM or :DATAGRAM."))
  38
  39 (defgeneric socket-open-p (socket)
  40   (:documentation "Returns a boolean indicating whether or not the file descriptor of `SOCKET' is open."))
  41
  42 (defgeneric local-name (socket)
  43   (:documentation "For INTERNET sockets, returns two values: the local host and the local port.
  44 For LOCAL sockets, returns the local filename."))
  45
  46 (defgeneric local-host (socket)
  47   (:documentation "Returns the local host of `SOCKET'.
  48 Works only on INTERNET sockets."))
  49
  50 (defgeneric local-port (socket)
  51   (:documentation "Returns the local port of `SOCKET' - an (unsigned-byte 16).
  52 Works only on INTERNET sockets."))
  53
  54 (defgeneric local-filename (socket)
  55   (:documentation "Returns the local filename of `SOCKET'.
  56 Works only on LOCAL sockets."))
  57
  58 (defgeneric remote-name (socket)
  59   (:documentation "For INTERNET sockets, returns two values: the remote host and the remote port.
  60 For REMOTE sockets, returns the remote filename."))
  61
  62 (defgeneric remote-host (socket)
  63   (:documentation "Returns the remote host of `SOCKET'.
  64 Works only on INTERNET sockets."))
  65
  66 (defgeneric remote-port (socket)
  67   (:documentation "Returns the remote port of `SOCKET' - an (unsigned-byte 16).
  68 Works only on INTERNET sockets."))
  69
  70 (defgeneric remote-filename (socket)
  71   (:documentation "Returns the remote filename of `SOCKET'.
  72 Works only on LOCAL sockets."))
  73
  74 (defgeneric socket-option (socket option-name)
  75   (:documentation "Returns the value(s) of OS options on `SOCKET'.
  76 For a complete list of supported options see net.sockets/socket-options.lisp ."))
  77
  78 (defclass stream-socket (socket) ()
  79   (:default-initargs :type :stream))
  80
  81 (defclass datagram-socket (socket) ()
  82   (:default-initargs :type :datagram))
  83
  84 (defgeneric disconnect (socket)
  85   (:documentation "Disassociates `SOCKET' from any remote address.
  86 Works only on DATAGRAM sockets."))
  87
  88 (define-symbol-macro +default-inet-family+
  89     (if *ipv6* :ipv6 :ipv4))
  90
  91 (defclass internet-socket (socket) ()
  92   (:default-initargs :family +default-inet-family+))
  93
  94 (defclass local-socket (socket) ()
  95   (:default-initargs :family :local))
  96
  97 (defgeneric send-file-descriptor (socket file-descriptor)
  98   (:documentation "Send `FILE-DESCRIPTOR' through `SOCKET'.
  99 The receiving process must use RECEIVE-FILE-DESCRIPTOR to receive the
 100 file descriptor in order for it to be valid in the receiving process."))
 101
 102 (defgeneric receive-file-descriptor (socket)
 103   (:documentation "Receive a file descriptor as ancillary data through `SOCKET'."))
 104
 105 (defun socket-read-fn (fd buffer nbytes)
 106   (%recvfrom fd buffer nbytes 0 (null-pointer) (null-pointer)))
 107
 108 (defun socket-write-fn (fd buffer nbytes)
 109   (%sendto fd buffer nbytes 0 (null-pointer) 0))
 110
 111 (defclass active-socket (socket dual-channel-gray-stream) ()
 112   (:default-initargs :read-fn 'socket-read-fn
 113                      :write-fn 'socket-write-fn))
 114
 115 (defgeneric connect (socket address &key &allow-other-keys)
 116   (:documentation "Connects `SOCKET' to `ADDRESS'. For INTERNET sockets you can specify
 117 the port to connect to using keyword argument `PORT'. The default value of `PORT' is 0,
 118 which usually means letting the OS choose a random port to connect to."))
 119
 120 (defgeneric socket-connected-p (socket)
 121   (:documentation "Returns a boolean specifying whether or not `SOCKET' is connected."))
 122
 123 (defgeneric shutdown (socket &key read write)
 124   (:documentation "Shut down all or part of a connection. If `READ' it non-NIL, further receptions are
 125 disallowed; if `WRITE' is non-NIL, further transmissions are disallowed. CLOSE must still be called on
 126 `SOCKET' in order to release OS resources."))
 127
 128 (defgeneric receive-from (socket &rest args &key &allow-other-keys)
 129   (:documentation "Receives data from `SOCKET'. If `BUFFER' is specified - which must be either a
 130 string or a (simple-array (unsigned-byte 8) *) - then `START' and `END' are used as bounding index,
 131 otherwise a buffer of size `SIZE' will be allocated.
 132
 133 Some flags can also be passed to recvfrom(2):
 134 * `OUT-OF-BAND' for receiving out-of-band data - only for stream sockets
 135 * `PEEK' for keeping the returned data in the kernel buffers
 136 * `WAIT-ALL' for waiting until the entire buffer can be filled
 137 * `DONT-WAIT' for making only the current call non-blocking
 138
 139 The first two values returned are the buffer and the number of elements that have been copied into the buffer.
 140 For INTERNET DATAGRAM sockets, two additional values are returned: the host and port of the remote peer
 141 from which the data was received.
 142 For LOCAL DATAGRAM sockets, one additional values is returned: the filename of the remote peer
 143 from which the data was received."))
 144
 145 (defgeneric send-to (socket buffer &rest args &key &allow-other-keys)
 146   (:documentation "Send the contents of `BUFFER' to `SOCKET'.
 147 `BUFFER' must be either a string or a vector that can be coerced to a (simple-array (unsigned-byte 8) *).
 148 `START' and `END' are used a bounding index on `BUFFER'.
 149 For disconnected datagram sockets, `REMOTE-HOST' and `REMOTE-PORT' or `REMOTE-FILENAME' are used
 150 as destination for the data.
 151
 152 Some flags can also be passed to sendto(2):
 153 * `OUT-OF-BAND' for receiving out-of-band data - only for stream sockets
 154 * `DONT-WAIT' for making only the current call non-blocking
 155 * `DONT-ROUTE' for sending only to hosts on directly connected networks, not using gateways
 156 * `CONFIRM' for signalling progress on the link layer - only available on Linux and only with DATAGRAM sockets
 157 * `MORE' for telling the kernel that there is more data to send - only available on Linux
 158
 159 Returns the number of bytes sent."))
 160
 161 (defclass passive-socket (socket)
 162   ((listening :initform nil :reader socket-listening-p :type boolean)
 163    (external-format :initarg :external-format :reader external-format-of)
 164    (active-class :initarg :active-class :reader active-class
 165                  :type symbol :allocation :class))
 166   (:default-initargs :external-format :default))
 167
 168 (defgeneric bind-address (socket address &key &allow-other-keys)
 169   (:documentation "Sets the local address of `SOCKET' to `ADDRESS'(and `PORT' for INTERNET sockets).
 170 `REUSE-ADDRESS' sets the SO_REUSEADDR socket option on `SOCKET'."))
 171
 172 (defgeneric listen-on (socket &key &allow-other-keys)
 173   (:documentation "Start allowing incoming connections on `SOCKET'.
 174 `BACKLOG' specifies the maximum length of the queue of pending connections."))
 175
 176 (defgeneric accept-connection (passive-socket &key &allow-other-keys)
 177   (:documentation "Returns one connection from the queue of pending connections on `SOCKET'.
 178 `EXTERNAL-FORMAT' optionally specifies the external format of the new socket - the default being
 179 that of `SOCKET'. Buffer sizes for the new socket can also be specified using `INPUT-BUFFER-SIZE'
 180 and `OUTPUT-BUFFER-SIZE'."))
 181
 182 (defclass socket-stream-internet-active
 183     (active-socket stream-socket internet-socket)
 184   ())
 185
 186 (defclass socket-stream-internet-passive
 187     (passive-socket stream-socket internet-socket)
 188   ()
 189   (:default-initargs :active-class 'socket-stream-internet-active))
 190
 191 (defclass socket-stream-local-active (active-socket stream-socket local-socket)
 192   ())
 193
 194 (defclass socket-stream-local-passive
 195     (passive-socket stream-socket local-socket)
 196   ()
 197   (:default-initargs :active-class 'socket-stream-local-active))
 198
 199 (defclass socket-datagram-local-active
 200     (active-socket datagram-socket local-socket)
 201   ())
 202
 203 (defclass socket-datagram-internet-active
 204     (active-socket datagram-socket internet-socket)
 205   ())