Preliminary bump to 1.2.7.

[fwd] / addr.h

/* -*-c-*-
 *
 * $Id: addr.h,v 1.3 2003/11/25 14:08:23 mdw Exp $
 *
 * Generic interface to network address handlers
 *
 * (c) 1999 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of the `fw' port forwarder.
 *
 * `fw' is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * `fw' is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with `fw'; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: addr.h,v $
 * Revision 1.3  2003/11/25 14:08:23  mdw
 * Debianization.  Socket target options.  Internet binding.
 *
 * Revision 1.2  1999/07/27 18:30:53  mdw
 * Various minor portability fixes.
 *
 * Revision 1.1  1999/07/26 23:34:26  mdw
 * Socket address type management.
 *
 */

#ifndef ADDR_H
#define ADDR_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <sys/types.h>
#include <sys/socket.h>

#include <mLib/dstr.h>
#include <mLib/conn.h>

#ifndef REFFD_H
#  include "reffd.h"
#endif

#ifndef ENDPT_H
#  include "endpt.h"
#endif

#ifndef SCAN_H
#  include "scan.h"
#endif

/*----- Data structures ---------------------------------------------------*/
    
/* --- A generic socket address --- *
 *
 * Not all systems understand @sa_len@ fields.  (In particular, Linux
 * doesn't.)  Some fairly ugly hacking is then performed on particular
 * address types.
 */

typedef struct addr {
  struct addr_ops *ops;
  size_t sz;
} addr;

#define ADDRSZ(sz) (sizeof(addr) + (sz))

/* --- Address configuration --- *
 *
 * An address family will want to extend this.
 */

typedef struct addr_opts {
  unsigned f;
} addr_opts;

#define ADDRF_NOLOG 1u

/* --- Address types --- *
 *
 * For things like Internet addresses, source and destinations look
 * different.
 */

enum {
  ADDR_SRC,
  ADDR_DEST,
  ADDR_GLOBAL
};

/* --- Description of an address type handler --- */

typedef struct addr_ops {
  const char *name;                     /* Protocol's internal name */

  /* --- @read@ --- *
   *
   * Arguments: @scanner *sc@ = pointer to scanner to read from
   *            @unsigned type@ = type of address to be read
   *
   * Returns:   A filled-in socket address.
   *
   * Use:       Parses a textual representation of a socket address.
   */

  addr *(*read)(scanner */*sc*/, unsigned /*type*/);

  /* --- @destroy@ --- *
   *
   * Arguments: @addr *a@ = pointer to an address block
   *
   * Returns:   ---
   *
   * Use:       Disposes of an address block in some suitable fashion.
   */

  void (*destroy)(addr */*a*/);

  /* --- @print@ --- *
   *
   * Arguments: @addr *a@ = pointer to socket address to read
   *            @unsigned type@ = type of address to be written
   *            @dstr *d@ = string on which to write the description
   *
   * Returns:   ---
   *
   * Use:       Writes a textual representation of a socket address to
   *            a string.
   */

  void (*print)(addr */*a*/, unsigned /*type*/, dstr */*d*/);

  /* --- @initsrcopts@ --- *
   *
   * Arguments: ---
   *
   * Returns:   A pointer to a protocol-specific data block for a listener
   *
   * Use:       Creates a data block for a listener.  This is attached to the
   *            listener data structure.  Options can then be requested, and
   *            are added to the block when necessary.
   */

  addr_opts *(*initsrcopts)(void);

  /* --- @option@ --- *
   *
   * Arguments: @scanner *sc@ = pointer to a scanner to read from
   *            @unsigned type@ = kind of option this is
   *            @addr_opts *ao@ = data block to modify (from @init@), or null
   *
   * Returns:   Nonzero to claim the option.
   *
   * Use:       Parses a source option, either global or listener-specific.
   */

  int (*option)(scanner */*sc*/, addr_opts */*ao*/, unsigned /*type*/);

  /* --- @freesrcopts@ --- *
   *
   * Arguments: @addr_opts *ao@ = data block to remove
   *
   * Returns:   ---
   *
   * Use:       Throws away all the configuration data for an address type.
   */

  void (*freesrcopts)(addr_opts */*ao*/);

  /* --- @bind@ --- *
   *
   * Arguments: @addr *a@ = the address to bind to
   *            @addr_opts *ao@ = the address options
   *
   * Returns:   File descriptor of bound socket if OK, or @-1@ on error.
   *
   * Use:       Binds a listening socket.  The tedious stuff with @listen@
   *            isn't necessary.
   */

  int (*bind)(addr */*a*/, addr_opts */*ao*/);

  /* --- @unbind@ --- *
   *
   * Arguments: @addr *a@ = pointer to an address
   *
   * Returns:   ---
   *
   * Use:       Unbinds an address.  This is used when tidying up.  The main
   *            purpose is to let the Unix-domain handler remove its socket
   *            node from the filesystem.
   */

  void (*unbind)(addr */*a*/);

  /* --- @accept@ --- *
   *
   * Arguments: @int fd@ = listening file descriptor
   *            @addr_opts *ao@ = data block to get configuration from
   *            @const char *desc@ = description of the listener
   *
   * Returns:   Pointer to a reference counted file descriptor.
   *
   * Use:       Accepts, verifies and logs an incoming connection.
   */

  reffd *(*accept)(int /*fd*/, addr_opts */*ao*/, const char */*desc*/);

  /* --- @inittargopts@ --- *
   *
   * Arguments: ---
   *
   * Returns:   A pointer to a protocol-specific data block for a connecter
   *
   * Use:       Creates a data block for a target.  This is attached to the
   *            target data structure.  Options can then be requested, and
   *            are added to the block when necessary.
   */

  addr_opts *(*inittargopts)(void);

  /* --- @freetargopts@ --- *
   *
   * Arguments: @addr_opts *ao@ = data block to remove
   *
   * Returns:   ---
   *
   * Use:       Throws away all the configuration data for an address type.
   */

  void (*freetargopts)(addr_opts */*ao*/);

  /* --- @connect@ --- *
   *
   * Arguments: @addr *a@ = destination address
   *            @addr_opts *ao@ = target address options
   *            @conn *c@ = connection structure
   *            @endpt *e@ = endpoint structure
   *
   * Returns:   Zero if OK, @-1@ on some error.
   *
   * Use:       Requests that a connection be made, or at least set in
   *            motion.  An address may do one of these things:
   *
   *              * Return @-1@.
   *
   *              * Call @starget_connected@ with @-1@ or a connected file
   *                descriptor and the pointer @e@.
   *
   *              * Call @conn_init@ or @conn_fd@, giving @starget_connected@
   *                and @e@ as the function to call.
   */

  int (*connect)(addr */*a*/, addr_opts */*ao*/, conn */*c*/, endpt */*e*/);

} addr_ops;
  
/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif