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

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