1/*
2
3Copyright 1995, 1998  The Open Group
4
5Permission to use, copy, modify, distribute, and sell this software and its
6documentation for any purpose is hereby granted without fee, provided that
7the above copyright notice appear in all copies and that both that
8copyright notice and this permission notice appear in supporting
9documentation.
10
11The above copyright notice and this permission notice shall be
12included in all copies or substantial portions of the Software.
13
14THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
18OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20OTHER DEALINGS IN THE SOFTWARE.
21
22Except as contained in this notice, the name of The Open Group shall
23not be used in advertising or otherwise to promote the sale, use or
24other dealings in this Software without prior written authorization
25from The Open Group.
26
27*/
28
29/*
30	  A Set Abstract Data Type (ADT) for the RECORD Extension
31			   David P. Wiggins
32			       7/25/95
33
34    The RECORD extension server code needs to maintain sets of numbers
35    that designate protocol message types.  In most cases the interval of
36    numbers starts at 0 and does not exceed 255, but in a few cases (minor
37    opcodes of extension requests) the maximum is 65535.  This disparity
38    suggests that a single set representation may not be suitable for all
39    sets, especially given that server memory is precious.  We introduce a
40    set ADT to hide implementation differences so that multiple
41    simultaneous set representations can exist.  A single interface is
42    presented to the set user regardless of the implementation in use for
43    a particular set.
44
45    The existing RECORD SI appears to require only four set operations:
46    create (given a list of members), destroy, see if a particular number
47    is a member of the set, and iterate over the members of a set.  Though
48    many more set operations are imaginable, to keep the code space down,
49    we won't provide any more operations than are needed.
50
51    The following types and functions/macros define the ADT.
52*/
53
54/* an interval of set members */
55typedef struct {
56    CARD16 first;
57    CARD16 last;
58} RecordSetInterval;
59
60typedef struct _RecordSetRec *RecordSetPtr; /* primary set type */
61
62typedef void *RecordSetIteratePtr;
63
64/* table of function pointers for set operations.
65   set users should never declare a variable of this type.
66*/
67typedef struct {
68    void (*DestroySet)(
69    RecordSetPtr pSet
70);
71    unsigned long (*IsMemberOfSet)(
72    RecordSetPtr pSet,
73    int possible_member
74);
75    RecordSetIteratePtr (*IterateSet)(
76    RecordSetPtr pSet,
77    RecordSetIteratePtr pIter,
78    RecordSetInterval *interval
79);
80} RecordSetOperations;
81
82/* "base class" for sets.
83   set users should never declare a variable of this type.
84 */
85typedef struct _RecordSetRec {
86    RecordSetOperations *ops;
87} RecordSetRec;
88
89RecordSetPtr RecordCreateSet(
90    RecordSetInterval *intervals,
91    int nintervals,
92    void *pMem,
93    int memsize
94);
95/*
96    RecordCreateSet creates and returns a new set having members specified
97    by intervals and nintervals.  nintervals is the number of RecordSetInterval
98    structures pointed to by intervals.  The elements belonging to the new
99    set are determined as follows.  For each RecordSetInterval structure, the
100    elements between first and last inclusive are members of the new set.
101    If a RecordSetInterval's first field is greater than its last field, the
102    results are undefined.  It is valid to create an empty set (nintervals ==
103    0).  If RecordCreateSet returns NULL, the set could not be created due
104    to resource constraints.
105*/
106
107int RecordSetMemoryRequirements(
108    RecordSetInterval * /*pIntervals*/,
109    int /*nintervals*/,
110    int * /*alignment*/
111);
112
113#define RecordDestroySet(_pSet) \
114	/* void */ (*_pSet->ops->DestroySet)(/* RecordSetPtr */ _pSet)
115/*
116    RecordDestroySet frees all resources used by _pSet.  _pSet should not be
117    used after it is destroyed.
118*/
119
120#define RecordIsMemberOfSet(_pSet, _m) \
121  /* unsigned long */ (*_pSet->ops->IsMemberOfSet)(/* RecordSetPtr */ _pSet, \
122						   /* int */ _m)
123/*
124    RecordIsMemberOfSet returns a non-zero value if _m is a member of
125    _pSet, else it returns zero.
126*/
127
128#define RecordIterateSet(_pSet, _pIter, _interval) \
129 /* RecordSetIteratePtr */ (*_pSet->ops->IterateSet)(/* RecordSetPtr */ _pSet,\
130	/* RecordSetIteratePtr */ _pIter, /* RecordSetInterval */ _interval)
131/*
132    RecordIterateSet returns successive intervals of members of _pSet.  If
133    _pIter is NULL, the first interval of set members is copied into _interval.
134    The return value should be passed as _pIter in the next call to
135    RecordIterateSet to obtain the next interval.  When the return value is
136    NULL, there were no more intervals in the set, and nothing is copied into
137    the _interval parameter.  Intervals appear in increasing numerical order
138    with no overlap between intervals.  As such, the list of intervals produced
139    by RecordIterateSet may not match the list of intervals that were passed
140    in RecordCreateSet.  Typical usage:
141
142	pIter = NULL;
143	while (pIter = RecordIterateSet(pSet, pIter, &interval))
144	{
145	    process interval;
146	}
147*/
148