Return to clearinghouse.3 CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / xns / morexnslib / ch

Annotation of 43BSD/contrib/xns/morexnslib/ch/clearinghouse.3, revision 1.1

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.