Return to clearinghousesupport.3 CVS log

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

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

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

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