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