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

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