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