chiark - git - mdw - fwd/blob - addr.h

   1 /* -*-c-*-
   2  *
   3  * $Id: addr.h,v 1.4 2003/11/29 20:36:07 mdw Exp $
   4  *
   5  * Generic interface to network address handlers
   6  *
   7  * (c) 1999 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of the `fw' port forwarder.
  13  *
  14  * `fw' is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * `fw' is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with `fw'; if not, write to the Free Software Foundation,
  26  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 /*----- Revision history --------------------------------------------------*
  30  *
  31  * $Log: addr.h,v $
  32  * Revision 1.4  2003/11/29 20:36:07  mdw
  33  * Privileged outgoing connections.
  34  *
  35  * Revision 1.3  2003/11/25 14:08:23  mdw
  36  * Debianization.  Socket target options.  Internet binding.
  37  *
  38  * Revision 1.2  1999/07/27 18:30:53  mdw
  39  * Various minor portability fixes.
  40  *
  41  * Revision 1.1  1999/07/26 23:34:26  mdw
  42  * Socket address type management.
  43  *
  44  */
  45
  46 #ifndef ADDR_H
  47 #define ADDR_H
  48
  49 #ifdef __cplusplus
  50   extern "C" {
  51 #endif
  52
  53 /*----- Header files ------------------------------------------------------*/
  54
  55 #include <sys/types.h>
  56 #include <sys/socket.h>
  57
  58 #include <mLib/dstr.h>
  59 #include <mLib/conn.h>
  60
  61 #ifndef REFFD_H
  62 #  include "reffd.h"
  63 #endif
  64
  65 #ifndef ENDPT_H
  66 #  include "endpt.h"
  67 #endif
  68
  69 #ifndef SCAN_H
  70 #  include "scan.h"
  71 #endif
  72
  73 /*----- Data structures ---------------------------------------------------*/
  74
  75 /* --- A generic socket address --- *
  76  *
  77  * Not all systems understand @sa_len@ fields.  (In particular, Linux
  78  * doesn't.)  Some fairly ugly hacking is then performed on particular
  79  * address types.
  80  */
  81
  82 typedef struct addr {
  83   struct addr_ops *ops;
  84   size_t sz;
  85 } addr;
  86
  87 #define ADDRSZ(sz) (sizeof(addr) + (sz))
  88
  89 /* --- Address configuration --- *
  90  *
  91  * An address family will want to extend this.
  92  */
  93
  94 typedef struct addr_opts {
  95   unsigned f;
  96 } addr_opts;
  97
  98 #define ADDRF_NOLOG 1u
  99
 100 /* --- Address types --- *
 101  *
 102  * For things like Internet addresses, source and destinations look
 103  * different.
 104  */
 105
 106 enum {
 107   ADDR_SRC,
 108   ADDR_DEST,
 109   ADDR_GLOBAL
 110 };
 111
 112 /* --- Description of an address type handler --- */
 113
 114 typedef struct addr_ops {
 115   const char *name;                     /* Protocol's internal name */
 116
 117   /* --- @read@ --- *
 118    *
 119    * Arguments: @scanner *sc@ = pointer to scanner to read from
 120    *            @unsigned type@ = type of address to be read
 121    *
 122    * Returns:   A filled-in socket address.
 123    *
 124    * Use:       Parses a textual representation of a socket address.
 125    */
 126
 127   addr *(*read)(scanner */*sc*/, unsigned /*type*/);
 128
 129   /* --- @destroy@ --- *
 130    *
 131    * Arguments: @addr *a@ = pointer to an address block
 132    *
 133    * Returns:   ---
 134    *
 135    * Use:       Disposes of an address block in some suitable fashion.
 136    */
 137
 138   void (*destroy)(addr */*a*/);
 139
 140   /* --- @print@ --- *
 141    *
 142    * Arguments: @addr *a@ = pointer to socket address to read
 143    *            @unsigned type@ = type of address to be written
 144    *            @dstr *d@ = string on which to write the description
 145    *
 146    * Returns:   ---
 147    *
 148    * Use:       Writes a textual representation of a socket address to
 149    *            a string.
 150    */
 151
 152   void (*print)(addr */*a*/, unsigned /*type*/, dstr */*d*/);
 153
 154   /* --- @initsrcopts@ --- *
 155    *
 156    * Arguments: ---
 157    *
 158    * Returns:   A pointer to a protocol-specific data block for a listener
 159    *
 160    * Use:       Creates a data block for a listener.  This is attached to the
 161    *            listener data structure.  Options can then be requested, and
 162    *            are added to the block when necessary.
 163    */
 164
 165   addr_opts *(*initsrcopts)(void);
 166
 167   /* --- @option@ --- *
 168    *
 169    * Arguments: @scanner *sc@ = pointer to a scanner to read from
 170    *            @unsigned type@ = kind of option this is
 171    *            @addr_opts *ao@ = data block to modify (from @init@), or null
 172    *
 173    * Returns:   Nonzero to claim the option.
 174    *
 175    * Use:       Parses a source option, either global or listener-specific.
 176    */
 177
 178   int (*option)(scanner */*sc*/, addr_opts */*ao*/, unsigned /*type*/);
 179
 180   /* --- @confirm@ --- *
 181    *
 182    * Arguments: @addr *a@ = pointer to an address structure
 183    *            @unsigned type@ = kind of address this is
 184    *            @addr_opts *ao@ = address options
 185    *
 186    * Returns:   ---
 187    *
 188    * Use:       Called during initialization when an address is fully
 189    *            configured.
 190    */
 191
 192   void (*confirm)(addr */*a*/, unsigned /*type*/, addr_opts */*ao*/);
 193
 194   /* --- @freesrcopts@ --- *
 195    *
 196    * Arguments: @addr_opts *ao@ = data block to remove
 197    *
 198    * Returns:   ---
 199    *
 200    * Use:       Throws away all the configuration data for an address type.
 201    */
 202
 203   void (*freesrcopts)(addr_opts */*ao*/);
 204
 205   /* --- @bind@ --- *
 206    *
 207    * Arguments: @addr *a@ = the address to bind to
 208    *            @addr_opts *ao@ = the address options
 209    *
 210    * Returns:   File descriptor of bound socket if OK, or @-1@ on error.
 211    *
 212    * Use:       Binds a listening socket.  The tedious stuff with @listen@
 213    *            isn't necessary.
 214    */
 215
 216   int (*bind)(addr */*a*/, addr_opts */*ao*/);
 217
 218   /* --- @unbind@ --- *
 219    *
 220    * Arguments: @addr *a@ = pointer to an address
 221    *
 222    * Returns:   ---
 223    *
 224    * Use:       Unbinds an address.  This is used when tidying up.  The main
 225    *            purpose is to let the Unix-domain handler remove its socket
 226    *            node from the filesystem.
 227    */
 228
 229   void (*unbind)(addr */*a*/);
 230
 231   /* --- @accept@ --- *
 232    *
 233    * Arguments: @int fd@ = listening file descriptor
 234    *            @addr_opts *ao@ = data block to get configuration from
 235    *            @const char *desc@ = description of the listener
 236    *
 237    * Returns:   Pointer to a reference counted file descriptor.
 238    *
 239    * Use:       Accepts, verifies and logs an incoming connection.
 240    */
 241
 242   reffd *(*accept)(int /*fd*/, addr_opts */*ao*/, const char */*desc*/);
 243
 244   /* --- @inittargopts@ --- *
 245    *
 246    * Arguments: ---
 247    *
 248    * Returns:   A pointer to a protocol-specific data block for a connecter
 249    *
 250    * Use:       Creates a data block for a target.  This is attached to the
 251    *            target data structure.  Options can then be requested, and
 252    *            are added to the block when necessary.
 253    */
 254
 255   addr_opts *(*inittargopts)(void);
 256
 257   /* --- @freetargopts@ --- *
 258    *
 259    * Arguments: @addr_opts *ao@ = data block to remove
 260    *
 261    * Returns:   ---
 262    *
 263    * Use:       Throws away all the configuration data for an address type.
 264    */
 265
 266   void (*freetargopts)(addr_opts */*ao*/);
 267
 268   /* --- @connect@ --- *
 269    *
 270    * Arguments: @addr *a@ = destination address
 271    *            @addr_opts *ao@ = target address options
 272    *            @conn *c@ = connection structure
 273    *            @endpt *e@ = endpoint structure
 274    *
 275    * Returns:   Zero if OK, @-1@ on some error.
 276    *
 277    * Use:       Requests that a connection be made, or at least set in
 278    *            motion.  An address may do one of these things:
 279    *
 280    *              * Return @-1@.
 281    *
 282    *              * Call @starget_connected@ with @-1@ or a connected file
 283    *                descriptor and the pointer @e@.
 284    *
 285    *              * Call @conn_init@ or @conn_fd@, giving @starget_connected@
 286    *                and @e@ as the function to call.
 287    */
 288
 289   int (*connect)(addr */*a*/, addr_opts */*ao*/, conn */*c*/, endpt */*e*/);
 290
 291 } addr_ops;
 292
 293 /*----- That's all, folks -------------------------------------------------*/
 294
 295 #ifdef __cplusplus
 296   }
 297 #endif
 298
 299 #endif