.TH CLEARINGHOUSESUPPORT 3 Cornell .\" $Header: clearinghousesupport.n,v 1.2 86/12/15 11:26:07 jqj Exp $ .SH NAME CH_StringToName, CH_NameDefault, CH_LookupAddr, CH_LookupAddrDN, CH_GetFirstCH, CH_GetOtherCH, CH_Enumerate, CH_EnumerateAliases \- Clearinghouse support routines. .SH SYNOPSIS .PP .nf .B "#include <sys/types.h> /* used by ns.h */" .B "#include <netns/ns.h> /* for ns_addr */" .B "#include <xnscourier/Clearinghouse2.h>" .B "#include <xnscourier/CH.h>" .PP .B "Clearinghouse2_ObjectName CH_StringToName(string, defaults)" .B " char *string;" .B " Clearinghouse2_ObjectName *defaults;" .PP .B "CH_NameDefault(defaults)" .B " Clearinghouse2_ObjectName *defaults;" .PP .B "struct ns_addr * CH_LookupAddr(pattern, property)" .B " Clearinghouse2_ObjectName pattern;" .B " Clearinghouse2_Property property;" .PP .B "struct ns_addr * CH_LookupAddrDN(pattern, property, name, namelen)" .B " Clearinghouse2_ObjectName pattern;" .B " Clearinghouse2_Property property;" .B " char name[namelen];" .B " int namelen;" .PP .B "CourierConnection * CH_GetFirstCH()" .PP .B "CourierConnection * CH_GetOtherCH(conn, hint)" .B " CourierConnection *conn;" .B " Clearinghouse2_ObjectName hint;" .PP .B "int CH_Enumerate(pattern, property, eachName)" .B " Clearinghouse2_ObjectName pattern;" .B " Clearinghouse2_Property property;" .B " int (*eachName)();" .PP .B "CH_EnumerateAliases(pattern,eachName)" .B " Clearinghouse2_ObjectNamePattern pattern;" .B " int (*eachName)();" .B "int eachName(name)" .B " Clearinghouse2_ObjectName name;" .fi .PP Link with .IR "-lcourier" . .SH DESCRIPTION .PP Given a string in standard format (e.g. ``jqj:Computer\ Science:cornell-univ''), .I CH_StringToName returns an ObjectName containing broken out fields for object, domain, and organization. If the string is incomplete, e.g. ``jqj'' or ``::cornell-univ'', the unspecified values are filled in from .IR defaults . .I Defaults may be NULL, in which case 0-length strings are used as defaults. .PP .I CH_NameDefault sets its argument to default domain and organization based on data from the file .IR /usr/new/lib/xnscourier/CH.default . The strings pointed to by the argument are statically allocated. .PP Given a Clearinghouse three part name (possibly containing wild cards in the local object part) and the property number on which a NetworkAddressList is expected to occur, .I CH_LookupAddr returns a pointer to an ns_addr structure associated with that name. Note that the ns_addr structure is statically allocated! If .I property is given as 0, then the addressList property (actually 4) is used; this is the property typically used for storing Clearinghouse addresses of objects. Returns 0 if any error occurs, if the name given is not registered, or if the name does not have the specified property. If a name has several network addresses (e.g. a gateway machine), only the first or primary address is returned; to obtain all addresses use the remote procedure .IR Clearinghouse2_RetrieveAddresses . .PP The routine .I CH_LookupAddrDN is identical with .IR CH_LookupAddr , except that it accepts additional parameters of .IR namestring , a caller-allocated buffer of length .IR namelen , which on return is set to the distinguished name of the object found. Users who require greater control than is provided by .I CH_LookupAddress should call .I Clearinghouse2_RetrieveItem directly. .PP The routine .I CH_GetFirstCH returns an XNS Courier connection to a nearby clearinghouse, useful for Clearinghouse remote procedure calls. Since the Clearinghouse is distributed, that instance of the CH may not contain the data desired; in such cases, a remote CH procedure call will return the error ``WrongServer'' with a hint as to the correct server, and the user may retry the operation after connecting (using .IR CH_GetOtherCH ) to the clearinghouse specified by the hint. For example: .PP .nf CH_NameDefault(&default); name = CH_StringToName(argv[1], &default); conn = CH_GetFirstCH(); for (tries = 5; tries > 0; tries--) { DURING { objectname = Clearinghouse2_LookupObject(conn, NULL, name, agent); tries = -1; /* done. Note break is illegal inside DURING */ } HANDLER { if (Exception.Code == Clearinghouse2_WrongServer) { hint = CourierErrArgs(Clearinghouse2_WrongServerArgs, hint); ch2conn = CH_GetOtherCH(conn, hint); CourierClose(conn); conn = ch2conn; } else exit(1); } END_HANDLER } .fi .PP .I CH_Enumerate and .I CH_EnumerateAliases each accept a pointer to a user-supplied function .IR eachProc . This function is called once for each name in the local Clearinghouse satisfying the .I pattern (which may contain wildcards in its local object part only) supplied; .I eachProc is called with a single argument, the name of the current object. .I CH_Enumerate enumerates over all distinguished objects (i.e. no aliases) matching the specified pattern and having the specified .IR property . If no specific property is desired, 0 should be used to obtain all names. .I CH_EnumerateAliases is similar, except that .I eachProc is called once for each alias matching the specified pattern. .SH NOTES .PP A CourierConnection is an anonymous data structure used by the runtimes. Users should not dereference pointers to CourierConnection themselves. .PP Some useful definitions equivalent to those in the include file .I "<courier/Clearinghouse2.h>" include: .PP .nf typedef struct { char *organization; char *domain; char *object; } Clearinghouse2_ObjectName; typedef unsigned long Clearinghouse2_Property; .fi .SH FILES .nf /usr/local/lib/libcourier.a -lcourier library. /usr/new/lib/xnscourier/CH.addrs local clearinghouse address. /usr/new/lib/xnscourier/CH.default defaults for clearinghouse names. .fi .SH SEE ALSO xnscourier(3) .br ``XNS Courier Under Unix.'' .br ``Clearinghouse Protocol,'' XSIS 078404 (April 1984). .SH DIAGNOSTICS .SH BUGS Probably lots of them. .PP In particular, since Packet Exchange is not yet working in the kernel, .I CH_GetFirstCH looks up the local clearinghouse address in a file rather than doing an expanding ring broadcast. This will be fixed soon. .SH AUTHOR J.Q. Johnson