Return to clearinghouse.n CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / xns / doc

Annotation of 43BSD/contrib/xns/doc/clearinghouse.n, revision 1.1

1.1     ! root        1: .TH CLEARINGHOUSESUPPORT 3X 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: .PP
        !            12: .nf
        !            13: .B "#include <sys/types.h>             /* used by ns.h */"
        !            14: .B "#include <netns/ns.h>              /* for sockaddr_ns */"
        !            15: .B "#include <xnscourier/Clearinghouse2.h>"
        !            16: .B "#include <xnscourier/CH.h>"
        !            17: .PP
        !            18: .B "Clearinghouse2_ObjectName CH_StringToName(string, defaults)"
        !            19: .B "   char *string;"
        !            20: .B "   Clearinghouse2_ObjectName *defaults;"
        !            21: .PP
        !            22: .B "struct xn_addr * CH_LookupAddr(pattern, property)"
        !            23: .B "   Clearinghouse2_ObjectName pattern;"
        !            24: .B "   Clearinghouse2_Property property;"
        !            25: .PP
        !            26: .B "CourierConnection * CH_GetFirstCH( )"
        !            27: .PP
        !            28: .B "CourierConnection * CH_GetOtherCH(conn, hint)"
        !            29: .B "   CourierConnection *conn;"
        !            30: .B "   Clearinghouse2_ObjectName hint;"
        !            31: .PP
        !            32: .B "int CH_Enumerate(pattern, property, eachName)"
        !            33: .B "   Clearinghouse2_ObjectName pattern;"
        !            34: .B "   Clearinghouse2_Property property;"
        !            35: .B "   int (*eachName)();"
        !            36: .PP
        !            37: .B "CH_EnumerateAliases(pattern, eachName)"
        !            38: .B "   Clearinghouse2_ObjectNamePattern pattern;"
        !            39: .B "   int (*eachName)();"
        !            40: .B "int eachName(name)"
        !            41: .B "   Clearinghouse2_ObjectName name;"
        !            42: .fi
        !            43: .PP
        !            44: Link with
        !            45: .IR "-lcourier" .
        !            46: .SH DESCRIPTION
        !            47: .PP
        !            48: These functions provide a convenient interface to the XNS Clearinghouse
        !            49: built on Courier remote procedure calls.  They all require the Maryland
        !            50: XNS kernel.
        !            51: .PP
        !            52: Given a string in standard format (e.g. 
        !            53: ``jqj:Computer\ Science:cornell-univ''),
        !            54: .I CH_StringToName
        !            55: translates a string in standard format, e.g.
        !            56: ``jqj:computer science:cornell-univ'' into a Clearinghouse ObjectName struct.
        !            57: The storage for the resulting 3 fields is dynamically allocated via malloc().
        !            58: If the argument string is incomplete, e.g. ``jqj'' or 
        !            59: ``::cornell-univ'', the unspecified values are filled in from
        !            60: .IR defaults .
        !            61: .I Defaults
        !            62: may be NULL, in which case 0-length strings are used as defaults.
        !            63: .PP
        !            64: Given a Clearinghouse three part name (possibly containing wild cards
        !            65: in the local object part)
        !            66: designating an addressable resouce on the net,
        !            67: and the property number on which a NetworkAddressList is expected to occur,
        !            68: .I CH_LookupAddr
        !            69: returns a pointer to an xn_addr structure associated with that name.
        !            70: Note that the xn_addr structure is statically allocated!
        !            71: If
        !            72: .I property
        !            73: is given as 0, then the ``addressList'' property (actually 4) is used;
        !            74: this is the property typically used for storing Clearinghouse addresses of
        !            75: objects.  Returns 0 if any error occurs, if the name given is not
        !            76: registered, or if the name does not have the specified property.
        !            77: If a name has several network addresses (e.g. a gateway machine), only
        !            78: the first or primary address is returned; to obtain all addresses use
        !            79: the remote procedure
        !            80: .IR Clearinghouse2_RetrieveAddresses .
        !            81: Users who require greater control than is provided by
        !            82: .I CH_LookupAddress
        !            83: should call
        !            84: .I Clearinghouse2_RetrieveItem
        !            85: directly.  Example:
        !            86: .PP
        !            87: .nf
        !            88: struct xn_addr * pvaxaddr;
        !            89: static struct Clearinghouse2_ObjectName pvaxname =
        !            90:         {"cornell-univ", "computer science", "pvax"};
        !            91: pvaxaddr = CH_LookupAddr(pvaxname, 0);
        !            92: .fi
        !            93: .PP
        !            94: The routine
        !            95: .I CH_GetFirstCH
        !            96: returns an XNS Courier connection to a nearby clearinghouse, useful
        !            97: for Clearinghouse remote procedure calls.  Since the Clearinghouse is
        !            98: distributed, that instance of the CH may not contain the data desired;
        !            99: in such cases, a remote CH procedure call will return the error
        !           100: ``WrongServer'' with a hint as to the correct server, and the user
        !           101: may retry the operation after connecting (using 
        !           102: .IR CH_GetOtherCH )
        !           103: to the clearinghouse specified by the hint.  For example:
        !           104: .PP
        !           105: .nf
        !           106: conn = CH_GetFirstCH();
        !           107: DURING objectname = Clearinghouse2_LookupObject(name, agent);
        !           108: HANDLER {
        !           109:     if (Exception.Code == Clearinghouse2_WrongServer) {
        !           110:        hint = CourierErrArgs(Clearinghouse2_WrongServerArgs, hint);
        !           111:        ch2conn = CH_GetOtherCH(conn, hint);
        !           112:        CourierClose(conn);
        !           113:        objectname = Clearinghouse2_LookupObject(name, agent);
        !           114:     } else exit(1);
        !           115: } END_HANDLER
        !           116: .fi
        !           117: .PP
        !           118: .I CH_Enumerate
        !           119: and
        !           120: .I CH_EnumerateAliases
        !           121: each accept a pointer to a user-supplied function 
        !           122: .IR eachProc .
        !           123: This function is called once for each name in the local Clearinghouse
        !           124: satisfying the 
        !           125: .I pattern
        !           126: (which may contain wildcards in its local object part only) supplied;
        !           127: .I eachProc
        !           128: is called with a single argument, the name of the current object.
        !           129: .I CH_Enumerate
        !           130: enumerates over all distinguished objects (i.e. no aliases) matching
        !           131: the specified pattern and having the specified
        !           132: .IR property .
        !           133: To enumerate everything in a domain which
        !           134: has a given property, use ``*'' in the object portion
        !           135: of the pattern.  To enumerate all names in a domain which match a
        !           136: given pattern, use the property value 0.  Other useful property values
        !           137: are specified in
        !           138: .IR <courier/CHEntries.h> .
        !           139: .PP
        !           140: .I CH_EnumerateAliases
        !           141: is similar to
        !           142: .I CH_Enumerate ,
        !           143: except that
        !           144: .I eachProc
        !           145: is called once for each alias in the clearinghouse
        !           146: matching the specified pattern.
        !           147: .SH NOTES
        !           148: .PP
        !           149: A CourierConnection is an anonymous data structure used by the
        !           150: runtimes.  Users should not dereference pointers to CourierConnection
        !           151: themselves.
        !           152: .PP
        !           153: Some useful definitions equivalent to those in the include file
        !           154: .I "<courier/Clearinghouse2.h>"
        !           155: include:
        !           156: .PP
        !           157: .nf
        !           158: typedef struct {
        !           159:        char *organization;
        !           160:        char *domain;
        !           161:        char *object;
        !           162: } Clearinghouse2_ObjectName;
        !           163: .PP
        !           164: typedef unsigned long Clearinghouse2_Property;
        !           165: .fi
        !           166: .SH FILES
        !           167: /usr/local/lib/libcourier.a            -lcourier library.
        !           168: .br
        !           169: /usr/new/lib/xnscourier/clearinghouse.addresses        local clearinghouse address.
        !           170: .SH SEE ALSO
        !           171: clearinghouse(3X)
        !           172: .br
        !           173: ``XNS Courier Under Unix''.
        !           174: .br
        !           175: ``Clearinghouse Protocol,'' XSIS 078404 (April 1984).
        !           176: .SH DIAGNOSTICS
        !           177: .SH BUGS
        !           178: Probably lots of them.  This is an \(*d -test version of Courier support
        !           179: routines and is guaranteed to have bugs.  Please report them to 
        !           180: .BR jqj@cornell .
        !           181: .PP
        !           182: In particular, since Packet Exchange is not yet working in the kernel,
        !           183: .I CH_GetFirstCH
        !           184: looks up the local clearinghouse address in a file rather than doing
        !           185: an expanding ring broadcast.  This will be fixed soon.
        !           186: .PP
        !           187: .I CH_LookupAddr
        !           188: returns a pointer to a static data structure.  The other routines use
        !           189: .I malloc()
        !           190: to dynamically allocate their data (you may use the routine
        !           191: .I clear_Clearinghouse2_ObjectName
        !           192: to free the strings allocated by
        !           193: .IR CH_StringToName ).
        !           194: .SH AUTHOR
        !           195: J.Q. Johnson

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.