![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to clearinghouse.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 clearinghouse.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_LookupAddr,
5: CH_GetFirstCH,
6: CH_GetOtherCH,
7: CH_Enumerate,
8: CH_EnumerateAliases
9: \- Clearinghouse support routines.
10: .SH SYNOPSIS
11: .nf
12: .B "#include <courier/CH.h>"
13: .B "#include <courier/Clearinghouse2.h>
14: .PP
15: .B "Clearinghouse2_ObjectName CH_StringToName(str, defaults)"
16: .B " char *str;"
17: .B " Clearinghouse2_ObjectName *defaults;"
18: .PP
19: .B "CourierConnection * CH_GetFirstCH()"
20: .PP
21: .B "CourierConnection * CH_GetOtherCH(conn, hint)"
22: .B " CourierConnection *conn;"
23: .B " Clearinghouse2_ObjectName hint;"
24: .PP
25: .B "struct xn_addr * CH_LookupAddr(pattern,property)"
26: .B " Clearinghouse2_ObjectNamePattern pattern;"
27: .B " Clearinghouse2_Property property;"
28: .PP
29: .B "int CH_Enumerate(pattern, property, eachName)"
30: .B " Clearinghouse2_ObjectNamePattern pattern;"
31: .B " Clearinghouse2_Property property;"
32: .B " int (*eachName)();"
33: .PP
34: .B "CH_EnumerateAliases(pattern,eachName)"
35: .B " Clearinghouse2_ObjectNamePattern pattern;"
36: .B " int (*eachName)();"
37: .B "int eachName(name)"
38: .B " Clearinghouse2_ObjectName name;"
39: .f
40: .PP
41: Link with
42: .BR "-lcourier" .
43: .SH DESCRIPTION
44: .PP
45: Given a string in standard format (e.g. ``jqj:Computer Science:cornell-univ''),
46: .I CH_StringToName
47: returns an ObjectName containing broken out fields for object, domain, and
48: organization. If the string is incomplete, e.g. ``jqj'' or
49: ``::cornell-univ'', the unspecified values are filled in from
50: .IR defaults .
51: .I Defaults
52: may be NULL, in which case 0-length strings are used as defaults.
53: .PP
54: Given a Clearinghouse three part name (possibly containing wild cards)
55: and the property number on which a NetworkAddress is expected to occur,
56: .I CH_LookupAddr
57: returns a pointer to an xn_addr structure associated with that name.
58: Note that the xn_addr structure is statically allocated!
59: If
60: .I property
61: is given as 0, then the addressList property (actually 4) is used;
62: this is the typical property for storing Clearinghouse addresses of
63: objects. Returns 0 if any error occurs, if the name given is not
64: registered, or if it does not have the specified property.
65: If a name has several network addresses (e.g. a gateway machine), only
66: the first or primary address is returned; to obtain all addresses use
67: the remote procedure
68: .IR Clearinghouse2_RetrieveAddresses .
69: Users who require greater control than is provided by
70: .I CH_LookupAddress
71: should call
72: .I Clearinghouse2_RetrieveItem
73: directly.
74: .PP
75: The routine
76: .I CH_GetFirstCH
77: returns an XNS Courier connection to a nearby clearinghouse, useful
78: for Clearinghouse remote procedure calls. Since the Clearinghouse is
79: distributed, that instance of the CH may not contain the data desired;
80: in such cases, a remote CH procedure call will return the error
81: ``WrongServer'' with a hint as to the correct server, and the user
82: may retry the operation after connecting (using
83: .IR CH_GetOtherCH )
84: to the clearinghouse specified by the hint.
85: .nf
86: conn = CH_GetFirstCH();
87: DURING
88: objectname = Clearinghouse2_LookupObject(name, agent);
89: HANDLER {
90: if (Exception.Code == Clearinghouse2_WrongServer) {
91: hint = CourierErrArgs(Clearinghouse2_WrongServerArgs, hint);
92: ch2conn = CH_GetOtherCH(conn, hint);
93: CourierClose(conn);
94: objectname = Clearinghouse2_LookupObject(name, agent);
95: }
96: else exit(1);
97: END_HANDLER
98: }
99: .f
100: .PP
101: .I CH_Enumerate
102: and
103: .I CH_EnumerateAliases
104: each accept a pointer to a user-supplied function
105: .I eachProc
106: which is called once for each name in the local Clearinghouse
107: satisfying the
108: .I pattern
109: (which may contain wildcards in its local object part only) supplied.
110: .I CH_Enumerate
111: enumerates over all distinguished objects (i.e. no aliases) matching
112: the specified pattern and having the specified
113: .IR property .
114: If no specific property is desired, 0 should be used to obtain all
115: names.
116: .I CH_EnumerateAliases
117: is similar, except that
118: .I eachProc
119: is called once for each alias matching the specified pattern.
120: .SH FILES
121: /usr/lib/local/libcourier.a -lcourier library.
122: .SH SEE ALSO
123: clearinghouse(3N)
124: .br
125: ``XNS Courier Under Unix''.
126: .br
127: ``Clearinghouse Protocol,'' XSIS 078404 (April 1984).
128: .SH DIAGNOSTICS
129: .SH BUGS
130: Probably lots of them.
131: .SH AUTHOR
132: J.Q. Johnson
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.