map_search.h revision 1.1 
1/*	$NetBSD: map_search.h,v 1.1 2020/03/18 18:59:34 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  */
51typedef struct {
52    char   *map_type_name;		/* "type:name", owned */
53    char   *search_order;		/* null or owned */
54} MAP_SEARCH;
55
56extern void map_search_init(const NAME_CODE *);
57extern const MAP_SEARCH *map_search_create(const char *);
58extern 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