Return to clearinghousesupport.n CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / new / xns / man

Annotation of 43BSDTahoe/new/xns/man/clearinghousesupport.n, revision 1.1

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

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