.TH CLEARINGHOUSESUPPORT 3X Cornell .SH NAME CH_StringToName, CH_LookupAddr, CH_GetFirstCH, CH_GetOtherCH, CH_Enumerate, CH_EnumerateAliases \- Clearinghouse support routines. .SH SYNOPSIS .PP .nf .B "#include /* used by ns.h */" .B "#include /* for sockaddr_ns */" .B "#include " .B "#include " .PP .B "Clearinghouse2_ObjectName CH_StringToName(string, defaults)" .B " char *string;" .B " Clearinghouse2_ObjectName *defaults;" .PP .B "struct xn_addr * CH_LookupAddr(pattern, property)" .B " Clearinghouse2_ObjectName pattern;" .B " Clearinghouse2_Property property;" .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 These functions provide a convenient interface to the XNS Clearinghouse built on Courier remote procedure calls. They all require the Maryland XNS kernel. .PP Given a string in standard format (e.g. ``jqj:Computer\ Science:cornell-univ''), .I CH_StringToName translates a string in standard format, e.g. ``jqj:computer science:cornell-univ'' into a Clearinghouse ObjectName struct. The storage for the resulting 3 fields is dynamically allocated via malloc(). If the argument 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 Given a Clearinghouse three part name (possibly containing wild cards in the local object part) designating an addressable resouce on the net, and the property number on which a NetworkAddressList is expected to occur, .I CH_LookupAddr returns a pointer to an xn_addr structure associated with that name. Note that the xn_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 . Users who require greater control than is provided by .I CH_LookupAddress should call .I Clearinghouse2_RetrieveItem directly. Example: .PP .nf struct xn_addr * pvaxaddr; static struct Clearinghouse2_ObjectName pvaxname = {"cornell-univ", "computer science", "pvax"}; pvaxaddr = CH_LookupAddr(pvaxname, 0); .fi .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 conn = CH_GetFirstCH(); DURING objectname = Clearinghouse2_LookupObject(name, agent); HANDLER { if (Exception.Code == Clearinghouse2_WrongServer) { hint = CourierErrArgs(Clearinghouse2_WrongServerArgs, hint); ch2conn = CH_GetOtherCH(conn, hint); CourierClose(conn); objectname = Clearinghouse2_LookupObject(name, agent); } 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 . To enumerate everything in a domain which has a given property, use ``*'' in the object portion of the pattern. To enumerate all names in a domain which match a given pattern, use the property value 0. Other useful property values are specified in .IR . .PP .I CH_EnumerateAliases is similar to .I CH_Enumerate , except that .I eachProc is called once for each alias in the clearinghouse 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 "" include: .PP .nf typedef struct { char *organization; char *domain; char *object; } Clearinghouse2_ObjectName; .PP typedef unsigned long Clearinghouse2_Property; .fi .SH FILES /usr/local/lib/libcourier.a -lcourier library. .br /usr/new/lib/xnscourier/clearinghouse.addresses local clearinghouse address. .SH SEE ALSO clearinghouse(3X) .br ``XNS Courier Under Unix''. .br ``Clearinghouse Protocol,'' XSIS 078404 (April 1984). .SH DIAGNOSTICS .SH BUGS Probably lots of them. This is an \(*d -test version of Courier support routines and is guaranteed to have bugs. Please report them to .BR jqj@cornell . .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. .PP .I CH_LookupAddr returns a pointer to a static data structure. The other routines use .I malloc() to dynamically allocate their data (you may use the routine .I clear_Clearinghouse2_ObjectName to free the strings allocated by .IR CH_StringToName ). .SH AUTHOR J.Q. Johnson