4.3BSD/usr/contrib/xns/doc/clearinghouse.n

.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 <sys/types.h>		/* used by ns.h */"
.B "#include <netns/ns.h>		/* for sockaddr_ns */"
.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 "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 <courier/CHEntries.h> .
.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 "<courier/Clearinghouse2.h>"
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