Home | History | Annotate | Line # | Download | only in global 
      1 /*	$NetBSD: map_search.h,v 1.2 2020/03/18 19:05:16 christos Exp $	*/
      2 
      3 /*++
      4 /* NAME
      5 /*      map_search 3h
      6 /* SUMMARY
      7 /*      lookup table search list support
      8 /* SYNOPSIS
      9 /*      #include <map_search.h>
     10 /* DESCRIPTION
     11 /* .nf
     12 
     13  /*
     14   * Utility library.
     15   */
     16 #include <name_code.h>
     17 
     18  /*
     19   * External interface.
     20   *
     21   * The map_search module maintains one lookup table with MAP_SEARCH results,
     22   * indexed by the unparsed form of a map specification. The conversion from
     23   * unparsed form to MAP_SEARCH result is controlled by a NAME_CODE mapping,
     24   * Since one lookup table can support only one mapping per unparsed name,
     25   * every MAP_SEARCH result in the lookup table must be built using the same
     26   * NAME_CODE table.
     27   *
     28   * Alternative 1: no lookup table. Allow the user to specify the NAME_CODE
     29   * mapping in the map_search_create() request (in addition to the unparsed
     30   * form), and let the MAP_SEARCH user store each MAP_SEARCH pointer. But
     31   * that would clumsify code that wants to use MAP_SEARCH functionality.
     32   *
     33   * Alternative 2: one lookup table per NAME_CODE mapping. Change
     34   * map_search_init() to return a pointer to {HTABLE *, NAME_CODE *}, and
     35   * require that the MAP_SEARCH user pass that pointer to other
     36   * map_search_xxx() calls (in addition to the unparsed forms). That would be
     37   * about as clumsy as Alternative 1.
     38   *
     39   * Alternative 3: one lookup table, distinct lookup keys per NAME_CODE table
     40   * and map_spec. The caller specifies both the map_spec and the NAME_CODE
     41   * mapping when it calls map_seach_create() and map_search_find(). The
     42   * implementation securely prepends the name_code argument to the map_spec
     43   * argument and uses the result as the table lookup key.
     44   *
     45   * Alternative 1 is not suitable for the smtpd_mumble_restrictions parser,
     46   * which instantiates MAP_SEARCH instances without knowing which specific
     47   * access feature is involved. It uses a NAME_CODE mapping that contains the
     48   * superset of what all smtpd_mumble_restrictions features need. The
     49   * downside is delayed error notification.
     50   */
     51 typedef struct {
     52     char   *map_type_name;		/* "type:name", owned */
     53     char   *search_order;		/* null or owned */
     54 } MAP_SEARCH;
     55 
     56 extern void map_search_init(const NAME_CODE *);
     57 extern const MAP_SEARCH *map_search_create(const char *);
     58 extern const MAP_SEARCH *map_search_lookup(const char *);
     59 
     60 #define MAP_SEARCH_ATTR_NAME_SEARCH	"search_order"
     61 
     62 #define MAP_SEARCH_CODE_UNKNOWN		127
     63 
     64 /* LICENSE
     65 /* .ad
     66 /* .fi
     67 /*      The Secure Mailer license must be distributed with this software.
     68 /* AUTHOR(S)
     69 /*      Wietse Venema
     70 /*      Google, Inc.
     71 /*      111 8th Avenue
     72 /*      New York, NY 10011, USA
     73 /*--*/
     74