Copied Types
ROPE: TYPE ~ Rope.ROPE;
The following three types are equivalent; the difference lies in what we consider to be legitimate values ...
Name: TYPE ~ XNSCHName.Name; -- valid name (or alias) of object
Pattern: TYPE ~ Name; -- may contain wildcards
Element: TYPE ~ Name; -- element of a group, needn't name an object
PropertyID: TYPE ~ CHOps.Property;
notUsable: PropertyID ~ CHOps.nullProperty;
unspecified: PropertyID ~ CHOps.all;
Properties: TYPE ~ CHOps.Properties;
Types
Conversation: TYPE ~ REF ConversationObject;
ConversationObject: TYPE;
NameStreamProc:
TYPE ~
PROC [Element];
A callback proc for handling a sequence of names.
ElementStreamProc:
TYPE ~
PROC [Element];
A callback proc for handling a sequence of group elements.
EnumeratorProc:
TYPE ~
PROC [ElementStreamProc];
A callback that supplies a sequence of group elements by repeatedly calling the ElementStreamProc.
Constants that should be in CHEntries0.cr / CHEntriesP0V0
alias: CARD32 ~ 1;
aliases: CARD32 ~ 2;
Authentication
A conversation contains credentials that identify the user to the Clearinghouse service. See also XNSAuth.
InitiateConversation:
PROC [identity: XNSAuth.Identity ¬
NIL, server:
XNS.Address ¬
XNS.unknownAddress]
RETURNS [Conversation];
Initiate a conversation with the Clearinghouse service using the given identity.
A NIL identity is okay for simple lookups.
If server is not specified, the conversation is with the generic Clearinghouse service, and the package takes care of server location and WrongServer error processing. If a server is specified, calls using this conversation will go to that address, and WrongServer errors will be passed back to the client.
There should never be more than one outstanding call on any conversation.
No ERRORs.
TerminateConversation:
PROC [c: Conversation];
Terminate the conversation. Dropping it on the floor is safe, but expensive.
Operations on Objects
Add:
PROC [c: Conversation, name: Name];
! Error
Delete:
PROC [c: Conversation, name: Name];
! Error
Lookup:
PROC [c: Conversation, pattern: Pattern]
RETURNS [distingName: Name];
! Error
AddAlias:
PROC [c: Conversation, name, alias: Name]
RETURNS [distingName: Name];
! Error
DeleteAlias:
PROC [c: Conversation, alias: Name]
RETURNS [distingName: Name];
! Error
ListAliases:
PROC [c: Conversation, pattern: Pattern, eachAlias: NameStreamProc]
RETURNS [distingName: Name];
! Error
Operations on Properties
GetProperties:
PROC [c: Conversation, pattern: Pattern]
RETURNS [distingName: Name, properties: Properties];
! Error
DeleteProperty:
PROC [c: Conversation, name: Name, pID: PropertyID]
RETURNS [distingName: Name];
! Error
AddItemProperty:
PROC [c: Conversation, name: Name, pID: PropertyID, item: Item]
RETURNS [distingName: Name];
! Error
ChangeItemProperty:
PROC [c: Conversation, name: Name, pID: PropertyID, item: Item]
RETURNS [distingName: Name];
! Error
LookupItemProperty:
PROC [c: Conversation, pattern: Pattern, pID: PropertyID]
RETURNS [distingName: Name, item: Item];
! Error
LookupAddress:
PROC [c: Conversation, pattern: Pattern]
RETURNS [distingName: Name, address: XNS.Address];
! Error
LookupRopeProperty:
PROC [c: Conversation, pattern: Pattern, pID: PropertyID]
RETURNS [distingName: Name, ropeProperty:
ROPE];
! Error
LookupNameProperty:
PROC [c: Conversation, pattern: Pattern, pID: PropertyID]
RETURNS [distingName: Name, nameProperty: Name];
! Error
AddGroupProperty:
PROC [c: Conversation, name: Name, pID: PropertyID,
enumerator: EnumeratorProc ¬
NIL]
RETURNS [distingName: Name];
! Error
AddMember:
PROC [c: Conversation, name: Name, pID: PropertyID, member: Element]
RETURNS [distingName: Name];
! Error
AddSelf:
PROC [c: Conversation, name: Name, pID: PropertyID]
RETURNS [distingName: Name];
! Error
DeleteMember:
PROC [c: Conversation, name: Name, pID: PropertyID, member: Element]
RETURNS [distingName: Name];
! Error
DeleteSelf:
PROC [c: Conversation, name: Name, pID: PropertyID]
RETURNS [distingName: Name];
! Error
ListMembers:
PROC [c: Conversation, pattern: Pattern, pID: PropertyID, eachMember: ElementStreamProc]
RETURNS [distingName: Name];
! Error
IsMember:
PROC [c: Conversation, pattern: Pattern, pID: PropertyID, member: Element]
RETURNS [distingName: Name, isMember:
BOOL];
! Error
IsMemberClosure:
PROC [c: Conversation, pattern: Pattern, pID: PropertyID, member: Element, pID2: PropertyID ¬ unspecified]
RETURNS [distingName: Name, isMember:
BOOL];
! Error
Enumeration Operations
Enumerate:
PROC [c: Conversation, pattern: Pattern, pID: PropertyID,
eachObject: NameStreamProc];
! Error
EnumerateAliases:
PROC [c: Conversation, pattern: Pattern, eachName: NameStreamProc];
! Error
EnumerateOrganizations:
PROC [c: Conversation, pattern: Pattern,
eachOrganization: ElementStreamProc];
! Error
The domain and object fields of the Elements passed to eachOrganization are indeterminate and should be ignored.
EnumerateDomains:
PROC [c: Conversation, pattern: Pattern,
eachDomain: ElementStreamProc];
! Error
The object fields of the Elements passed to eachDomain are indeterminate and should be ignored.
Common Lookups (generic conversations only)
LookupAddressFromRope:
PROC [rope:
ROPE]
RETURNS [distingName: Name, address:
XNS.Address];
No ERRORs — returns [[NIL,NIL,NIL], unknownAddress] on failure.
LookupAddressFromRopeClosure:
PROC [rope: Rope.
ROPE]
RETURNS [distingName: XNSCHName.Name, address:
XNS.Address, didClosure:
BOOL];
Like LookupAddressFromRope, but if the initial lookup fails try getting the "associatedWorkstation" property and iterate.
No ERRORs — returns [[NIL,NIL,NIL], unknownAddress, ?] on failure.
Utilities
AddressesFromItem: PROC [item: Item] RETURNS [addresses: LIST OF XNS.Address];
ItemFromAddresses: PROC [addresses: LIST OF XNS.Address] RETURNS [item: Item];
RopeFromItem: PROC [item: Item] RETURNS [rope: ROPE];
ItemFromRope: PROC [rope: ROPE] RETURNS [item: Item];
ElementFromItem: PROC [item: Item] RETURNS [element: Element];
ItemFromElement: PROC [element: Element] RETURNS [item: Item];
BestAddressInList: PUBLIC PROC [list: LIST OF XNS.Address]
RETURNS [bestAddress: XNS.Address];
Errors
WrongServerError:
VAR
ERROR [hint: Name];
← CHOps.WrongServer.
Raised only for a call directed to a specific CH Server.
Error:
ERROR [code: ErrorCode, which: Which];
code is defined below.
which is significant for naming problems or propertyID errors when more than one argument might be the cause of the error.
Asterisk (*) ==> error only occurs on call directed to a specific CH Server.
ErrorCode:
TYPE ~ {
Operational problems
notAllowed,
allDown,
wasUpNowDown,
protocolError,
cantConnectToServer, -- (*)
communicationFailure, -- (*)
serverTooBusy, -- (*)
serviceNotExported, -- (*)
Naming problems
illegalPropertyID,
illegalOrganizationName,
illegalDomainName,
illegalObjectName,
noSuchOrganization,
noSuchDomain,
noSuchObject,
PropertyID errors
propertyIDNotFound,
wrongPropertyType,
Update problems
noChange,
outOfDate,
overflowOfName,
overflowOfDataBase,
Authentication problems
credentialsInvalid,
credentialsTooWeak,
Specific/Generic mixup
inappropriateConversation,
};
Which: TYPE ~ { first, second };