external/ibm-public/postfix/dist/src/global/scache.h

   1 /*      $NetBSD$        */
   2
   3 #ifndef _SCACHE_H_INCLUDED_
   4 #define _SCACHE_H_INCLUDED_
   5
   6 /*++
   7 /* NAME
   8 /*      scache 3h
   9 /* SUMMARY
  10 /*      generic session cache API
  11 /* SYNOPSIS
  12 /*      #include <scache.h>
  13 /* DESCRIPTION
  14 /* .nf
  15
  16  /*
  17   * Utility library.
  18   */
  19 #include <vstring.h>
  20
  21 typedef struct SCACHE SCACHE;
  22 typedef struct SCACHE_SIZE SCACHE_SIZE;
  23
  24  /*
  25   * In order to cache a session, we specify:
  26   *
  27   * - TTL for this session.
  28   *
  29   * - File descriptor.
  30   *
  31   * - Transport name and physical endpoint. The transport name must be included,
  32   * because fall-back destinations can be transport-dependent, and routing
  33   * for a given destination may be context dependent.
  34   *
  35   * In the case of SMTP, the physical endpoint is the numerical IP address and
  36   * TCP port.
  37   *
  38   * - Application-specific endpoint properties.
  39   *
  40   * In the case of SMTP, the properties specify the ESMTP features advertised by
  41   * the server.
  42   *
  43   * Note: with message delivery transports that have only one endpoint per
  44   * logical destination, the above is the only information that needs to be
  45   * maintained in a connection cache.
  46   */
  47 typedef void (*SCACHE_SAVE_ENDP_FN) (SCACHE *, int, const char *, const char *, int);
  48 typedef int (*SCACHE_FIND_ENDP_FN) (SCACHE *, const char *, VSTRING *);
  49
  50  /*
  51   * The following information is stored in order to make a binding from
  52   * logical destination to physical destination. One logical destination can
  53   * have multiple physical destinations (and one physical destination can
  54   * have multiple sessions).
  55   *
  56   * - TTL for this binding.
  57   *
  58   * - Transport name and logical destination.
  59   *
  60   * In the case of SMTP: the next-hop (NOT: fall-back) destination domain and
  61   * destination network port. It is not useful to create a link for an
  62   * address literal (but it is not harmful either: it just wastes a few
  63   * bits). This information specifies the destination domain in [] if no MX
  64   * lookup is done.
  65   *
  66   * - Application-specific properties.
  67   *
  68   * In case the of SMTP, the properties specify a) whether a physical endpoint
  69   * is best mx host with respect to a logical or fall-back destination (this
  70   * information is needed by the loop detection code in smtp_proto.c).
  71   *
  72   * - Transport name and physical endpoint (see above).
  73   *
  74   * Note 1: there is no need to store the binding's MX preference or equivalent
  75   * with respect to the logical destination; a client should store only the
  76   * first successful session for a given delivery request (otherwise the
  77   * client would keep talking to a less preferred server after the cached
  78   * connection for a more preferred server expires). After a failed delivery,
  79   * the client should not attempt to cache follow-up sessions with less
  80   * preferred endpoints under the same logical destination.
  81   *
  82   * Note 2: logical to physical bindings exist independently from cached
  83   * sessions. The two types of information have independent TTLs; creation
  84   * and destruction proceed independently. Thus, a logical to physical
  85   * binding can refer to an endpoint for which all cached connections are
  86   * occupied or expired.
  87   */
  88 typedef void (*SCACHE_SAVE_DEST_FN) (SCACHE *, int, const char *, const char *, const char *);
  89 typedef int (*SCACHE_FIND_DEST_FN) (SCACHE *, const char *, VSTRING *, VSTRING *);
  90
  91  /*
  92   * Session cache statistics. These are the actual numbers at a specific
  93   * point in time.
  94   */
  95 struct SCACHE_SIZE {
  96     int     dest_count;                 /* Nr of destination names */
  97     int     endp_count;                 /* Nr of endpoint adresses */
  98     int     sess_count;                 /* Nr of cached sessions */
  99 };
 100
 101  /*
 102   * Generic session cache object. Actual session cache objects are derived
 103   * types with some additional, cache dependent, private information.
 104   */
 105 struct SCACHE {
 106     SCACHE_SAVE_ENDP_FN save_endp;
 107     SCACHE_FIND_ENDP_FN find_endp;
 108     SCACHE_SAVE_DEST_FN save_dest;
 109     SCACHE_FIND_DEST_FN find_dest;
 110     void    (*size) (struct SCACHE *, SCACHE_SIZE *);
 111     void    (*free) (struct SCACHE *);
 112 };
 113
 114 extern SCACHE *scache_single_create(void);
 115 extern SCACHE *scache_clnt_create(const char *, int, int, int);
 116 extern SCACHE *scache_multi_create(void);
 117
 118 #define scache_save_endp(scache, ttl, endp_label, endp_prop, fd) \
 119     (scache)->save_endp((scache), (ttl), (endp_label), (endp_prop), (fd))
 120 #define scache_find_endp(scache, endp_label, endp_prop) \
 121     (scache)->find_endp((scache), (endp_label), (endp_prop))
 122 #define scache_save_dest(scache, ttl, dest_label, dest_prop, endp_label) \
 123     (scache)->save_dest((scache), (ttl), (dest_label), (dest_prop), (endp_label))
 124 #define scache_find_dest(scache, dest_label, dest_prop, endp_prop) \
 125     (scache)->find_dest((scache), (dest_label), (dest_prop), (endp_prop))
 126 #define scache_size(scache, stats) (scache)->size((scache), (stats))
 127 #define scache_free(scache) (scache)->free(scache)
 128
 129  /*
 130   * Cache types.
 131   */
 132 #define SCACHE_TYPE_SINGLE      1       /* single-instance cache */
 133 #define SCACHE_TYPE_CLIENT      2       /* session cache client */
 134 #define SCACHE_TYPE_MULTI       3       /* multi-instance cache */
 135
 136  /*
 137   * Client-server protocol.
 138   */
 139 #define SCACHE_REQ_FIND_ENDP    "find_endp"
 140 #define SCACHE_REQ_SAVE_ENDP    "save_endp"
 141 #define SCACHE_REQ_FIND_DEST    "find_dest"
 142 #define SCACHE_REQ_SAVE_DEST    "save_dest"
 143
 144  /*
 145   * Session cache server status codes.
 146   */
 147 #define SCACHE_STAT_OK          0       /* request completed successfully */
 148 #define SCACHE_STAT_BAD         1       /* malformed request */
 149 #define SCACHE_STAT_FAIL        2       /* request completed unsuccessfully */
 150
 151 /* LICENSE
 152 /* .ad
 153 /* .fi
 154 /*      The Secure Mailer license must be distributed with this software.
 155 /* AUTHOR(S)
 156 /*      Wietse Venema
 157 /*      IBM T.J. Watson Research
 158 /*      P.O. Box 704
 159 /*      Yorktown Heights, NY 10598, USA
 160 /*--*/
 161
 162 #endif