![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to clearinghouse.n CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / xns / doc|
Return to clearinghouse.n CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / xns / doc |
1.1 root 1: .TH CLEARINGHOUSESUPPORT 3X Cornell
2: .SH NAME
3: CH_StringToName,
4: CH_LookupAddr,
5: CH_GetFirstCH,
6: CH_GetOtherCH,
7: CH_Enumerate,
8: CH_EnumerateAliases
9: \- Clearinghouse support routines.
10: .SH SYNOPSIS
11: .PP
12: .nf
13: .B "#include <sys/types.h> /* used by ns.h */"
14: .B "#include <netns/ns.h> /* for sockaddr_ns */"
15: .B "#include <xnscourier/Clearinghouse2.h>"
16: .B "#include <xnscourier/CH.h>"
17: .PP
18: .B "Clearinghouse2_ObjectName CH_StringToName(string, defaults)"
19: .B " char *string;"
20: .B " Clearinghouse2_ObjectName *defaults;"
21: .PP
22: .B "struct xn_addr * CH_LookupAddr(pattern, property)"
23: .B " Clearinghouse2_ObjectName pattern;"
24: .B " Clearinghouse2_Property property;"
25: .PP
26: .B "CourierConnection * CH_GetFirstCH( )"
27: .PP
28: .B "CourierConnection * CH_GetOtherCH(conn, hint)"
29: .B " CourierConnection *conn;"
30: .B " Clearinghouse2_ObjectName hint;"
31: .PP
32: .B "int CH_Enumerate(pattern, property, eachName)"
33: .B " Clearinghouse2_ObjectName pattern;"
34: .B " Clearinghouse2_Property property;"
35: .B " int (*eachName)();"
36: .PP
37: .B "CH_EnumerateAliases(pattern, eachName)"
38: .B " Clearinghouse2_ObjectNamePattern pattern;"
39: .B " int (*eachName)();"
40: .B "int eachName(name)"
41: .B " Clearinghouse2_ObjectName name;"
42: .fi
43: .PP
44: Link with
45: .IR "-lcourier" .
46: .SH DESCRIPTION
47: .PP
48: These functions provide a convenient interface to the XNS Clearinghouse
49: built on Courier remote procedure calls. They all require the Maryland
50: XNS kernel.
51: .PP
52: Given a string in standard format (e.g.
53: ``jqj:Computer\ Science:cornell-univ''),
54: .I CH_StringToName
55: translates a string in standard format, e.g.
56: ``jqj:computer science:cornell-univ'' into a Clearinghouse ObjectName struct.
57: The storage for the resulting 3 fields is dynamically allocated via malloc().
58: If the argument string is incomplete, e.g. ``jqj'' or
59: ``::cornell-univ'', the unspecified values are filled in from
60: .IR defaults .
61: .I Defaults
62: may be NULL, in which case 0-length strings are used as defaults.
63: .PP
64: Given a Clearinghouse three part name (possibly containing wild cards
65: in the local object part)
66: designating an addressable resouce on the net,
67: and the property number on which a NetworkAddressList is expected to occur,
68: .I CH_LookupAddr
69: returns a pointer to an xn_addr structure associated with that name.
70: Note that the xn_addr structure is statically allocated!
71: If
72: .I property
73: is given as 0, then the ``addressList'' property (actually 4) is used;
74: this is the property typically used for storing Clearinghouse addresses of
75: objects. Returns 0 if any error occurs, if the name given is not
76: registered, or if the name does not have the specified property.
77: If a name has several network addresses (e.g. a gateway machine), only
78: the first or primary address is returned; to obtain all addresses use
79: the remote procedure
80: .IR Clearinghouse2_RetrieveAddresses .
81: Users who require greater control than is provided by
82: .I CH_LookupAddress
83: should call
84: .I Clearinghouse2_RetrieveItem
85: directly. Example:
86: .PP
87: .nf
88: struct xn_addr * pvaxaddr;
89: static struct Clearinghouse2_ObjectName pvaxname =
90: {"cornell-univ", "computer science", "pvax"};
91: pvaxaddr = CH_LookupAddr(pvaxname, 0);
92: .fi
93: .PP
94: The routine
95: .I CH_GetFirstCH
96: returns an XNS Courier connection to a nearby clearinghouse, useful
97: for Clearinghouse remote procedure calls. Since the Clearinghouse is
98: distributed, that instance of the CH may not contain the data desired;
99: in such cases, a remote CH procedure call will return the error
100: ``WrongServer'' with a hint as to the correct server, and the user
101: may retry the operation after connecting (using
102: .IR CH_GetOtherCH )
103: to the clearinghouse specified by the hint. For example:
104: .PP
105: .nf
106: conn = CH_GetFirstCH();
107: DURING objectname = Clearinghouse2_LookupObject(name, agent);
108: HANDLER {
109: if (Exception.Code == Clearinghouse2_WrongServer) {
110: hint = CourierErrArgs(Clearinghouse2_WrongServerArgs, hint);
111: ch2conn = CH_GetOtherCH(conn, hint);
112: CourierClose(conn);
113: objectname = Clearinghouse2_LookupObject(name, agent);
114: } else exit(1);
115: } END_HANDLER
116: .fi
117: .PP
118: .I CH_Enumerate
119: and
120: .I CH_EnumerateAliases
121: each accept a pointer to a user-supplied function
122: .IR eachProc .
123: This function is called once for each name in the local Clearinghouse
124: satisfying the
125: .I pattern
126: (which may contain wildcards in its local object part only) supplied;
127: .I eachProc
128: is called with a single argument, the name of the current object.
129: .I CH_Enumerate
130: enumerates over all distinguished objects (i.e. no aliases) matching
131: the specified pattern and having the specified
132: .IR property .
133: To enumerate everything in a domain which
134: has a given property, use ``*'' in the object portion
135: of the pattern. To enumerate all names in a domain which match a
136: given pattern, use the property value 0. Other useful property values
137: are specified in
138: .IR <courier/CHEntries.h> .
139: .PP
140: .I CH_EnumerateAliases
141: is similar to
142: .I CH_Enumerate ,
143: except that
144: .I eachProc
145: is called once for each alias in the clearinghouse
146: matching the specified pattern.
147: .SH NOTES
148: .PP
149: A CourierConnection is an anonymous data structure used by the
150: runtimes. Users should not dereference pointers to CourierConnection
151: themselves.
152: .PP
153: Some useful definitions equivalent to those in the include file
154: .I "<courier/Clearinghouse2.h>"
155: include:
156: .PP
157: .nf
158: typedef struct {
159: char *organization;
160: char *domain;
161: char *object;
162: } Clearinghouse2_ObjectName;
163: .PP
164: typedef unsigned long Clearinghouse2_Property;
165: .fi
166: .SH FILES
167: /usr/local/lib/libcourier.a -lcourier library.
168: .br
169: /usr/new/lib/xnscourier/clearinghouse.addresses local clearinghouse address.
170: .SH SEE ALSO
171: clearinghouse(3X)
172: .br
173: ``XNS Courier Under Unix''.
174: .br
175: ``Clearinghouse Protocol,'' XSIS 078404 (April 1984).
176: .SH DIAGNOSTICS
177: .SH BUGS
178: Probably lots of them. This is an \(*d -test version of Courier support
179: routines and is guaranteed to have bugs. Please report them to
180: .BR jqj@cornell .
181: .PP
182: In particular, since Packet Exchange is not yet working in the kernel,
183: .I CH_GetFirstCH
184: looks up the local clearinghouse address in a file rather than doing
185: an expanding ring broadcast. This will be fixed soon.
186: .PP
187: .I CH_LookupAddr
188: returns a pointer to a static data structure. The other routines use
189: .I malloc()
190: to dynamically allocate their data (you may use the routine
191: .I clear_Clearinghouse2_ObjectName
192: to free the strings allocated by
193: .IR CH_StringToName ).
194: .SH AUTHOR
195: J.Q. Johnson
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.