contrib/sb-bsd-sockets/protocol.lisp

   1 (cl:in-package #:sb-bsd-sockets)
   2
   3 ;;; Addresses
   4
   5 (defgeneric make-sockaddr-for (socket &optional sockaddr &rest address)
   6   (:documentation
   7    "Return a Socket Address object suitable for use with SOCKET.
   8 When SOCKADDR is passed, it is used instead of a new object."))
   9
  10 (defgeneric free-sockaddr-for (socket sockaddr)
  11   (:documentation
  12    "Deallocate the socket address object SOCKADDR that was created for
  13 SOCKET."))
  14
  15 (defgeneric bits-of-sockaddr (socket sockaddr)
  16   (:documentation
  17    "Return as multiple values protocol-dependent bits of parameter
  18 SOCKADDR, e.g. the host/port if SOCKET is an inet socket."))
  19
  20 (defgeneric size-of-sockaddr (socket)
  21   (:documentation
  22    "Return the size in bytes of a sockaddr object for SOCKET."))
  23
  24 ;;; Sockets
  25
  26 (defgeneric socket-name (socket)
  27   (:documentation
  28    "Return the address (as vector of bytes) and port that SOCKET is
  29 bound to, as multiple values."))
  30
  31 (defgeneric socket-peername (socket)
  32   (:documentation
  33    "Return SOCKET's peer; depending on the address family this may
  34 return multiple values"))
  35
  36 (defgeneric socket-namestring (socket)
  37   (:method ((socket t))
  38     nil)
  39   (:documentation
  40    "Return a string representation of the address and port that SOCKET
  41 is bound to."))
  42
  43 (defgeneric socket-peerstring (socket)
  44   (:method ((socket t))
  45     nil)
  46   (:documentation
  47    "Return a string representation of the address and port of SOCKET's
  48 peer."))
  49
  50 (defgeneric socket-open-p (socket)
  51   (:documentation
  52    "Return true if SOCKET is open; otherwise, return false.")
  53   (:method ((socket t))
  54     (error 'type-error :datum socket :expected-type 'socket)))
  55
  56 (defgeneric socket-close (socket &key abort)
  57   (:documentation
  58    "Close SOCKET, unless it was already closed.
  59
  60 If SOCKET-MAKE-STREAM has been called, calls CLOSE using ABORT on that
  61 stream.  Otherwise closes the socket file descriptor using
  62 close(2)."))
  63
  64 (defgeneric socket-bind (socket &rest address)
  65   (:documentation
  66    "Bind SOCKET to ADDRESS, which may vary according to socket family.
  67 For the INET family, pass ADDRESS and PORT as two arguments; for FILE
  68 address family sockets, pass the filename string.  See also bind(2)"))
  69
  70 (defgeneric socket-accept (socket)
  71   (:documentation
  72    "Perform the accept(2) call, returning a newly-created connected
  73 socket and the peer address as multiple values"))
  74
  75 (defgeneric socket-connect (socket &rest address)
  76   (:documentation
  77    "Perform the connect(2) call to connect SOCKET to a remote PEER.
  78 No useful return value."))
  79
  80 (defgeneric socket-receive (socket buffer length
  81                             &key
  82                             oob peek waitall dontwait element-type)
  83   (:documentation
  84    "Read LENGTH octets from SOCKET into BUFFER (or a freshly-consed
  85 buffer if NIL), using recvfrom(2). If LENGTH is NIL, the length of
  86 BUFFER is used, so at least one of these two arguments must be
  87 non-NIL. If BUFFER is supplied, it had better be of an element type
  88 one octet wide. Returns the buffer, its length, and the address of the
  89 peer that sent it, as multiple values. On datagram sockets, sets
  90 MSG_TRUNC so that the actual packet length is returned even if the
  91 buffer was too small."))
  92
  93 (defgeneric socket-send (socket buffer length
  94                          &key
  95                          address
  96                          external-format
  97                          oob eor dontroute dontwait nosignal
  98                          #+linux confirm #+linux more)
  99   (:documentation
 100    "Send LENGTH octets from BUFFER into SOCKET, using sendto(2). If
 101 BUFFER is a string, it will converted to octets according to
 102 EXTERNAL-FORMAT. If LENGTH is NIL, the length of the octet buffer is
 103 used. The format of ADDRESS depends on the socket type (for example
 104 for INET domain sockets it would be a list of an IP address and a
 105 port). If no socket address is provided, send(2) will be called
 106 instead. Returns the number of octets written."))
 107
 108 (defgeneric socket-listen (socket backlog)
 109   (:documentation
 110    "Mark SOCKET as willing to accept incoming connections.  The
 111 integer BACKLOG defines the maximum length that the queue of pending
 112 connections may grow to before new connection attempts are refused.
 113 See also listen(2)"))
 114
 115 (defgeneric socket-shutdown (socket &key direction)
 116   (:documentation
 117    "Indicate that no communication in DIRECTION will be performed on
 118 SOCKET.
 119
 120 DIRECTION has to be one of :INPUT, :OUTPUT or :IO.
 121
 122 After a shutdown, no input and/or output of the indicated DIRECTION
 123 can be performed on SOCKET."))
 124
 125 (defgeneric socket-make-stream (socket &key input output
 126                                             element-type external-format
 127                                             buffering
 128                                             timeout)
 129   (:documentation
 130    "Find or create a STREAM that can be used for IO on SOCKET \(which
 131 must be connected\).  Specify whether the stream is for INPUT, OUTPUT,
 132 or both \(it is an error to specify neither\).
 133
 134 ELEMENT-TYPE and EXTERNAL-FORMAT are as per OPEN.
 135
 136 TIMEOUT specifies a read timeout for the stream."))
 137
 138 (defgeneric non-blocking-mode (socket)
 139   (:documentation
 140    "Is SOCKET in non-blocking mode?"))
 141
 142 (defgeneric (setf non-blocking-mode) (non-blocking-p socket)
 143   (:documentation
 144    "Put SOCKET in non-blocking mode - or not, according to
 145 NON-BLOCKING-P"))
 146
 147 ;;; Name service
 148
 149 (defgeneric host-ent-address (host-ent)
 150   (:documentation
 151    "Return some valid address for HOST-ENT."))