THE GRAPEVINE INTERFACE
Appendix:  The Cedar Grapevine Interfaces
    This appendix contains those interfaces of the Cedar Grapevine client interface which were referred to earlier in this document.


<<GrapevineUser - public DEFS for basic types>>
<<GVBasics.mesa>>
<<Andrew Birrell  June 24, 1983 5:25 pm>>

    DIRECTORY
        Rope USING [ROPE];

    GVBasics: CEDAR DEFINITIONS =

    BEGIN

<<Note that incompatible changes to these definitions may require the cooperation of all mail servers and their clients, and the 
flushing of the mail server filestores.>>

<<The following types are basic to the transport mechanism.  "Connect", "Password" and "Remark" don't really occur in message 
bodies, but this is the most stable defs file for them. They are used by public clients of the transport mechanism.>>


    GVString: TYPE = Rope.ROPE;

    maxGVStringLength: CARDINAL = 64;
    <<Most strings occurring inside Grapevine are restricted in length.>>


    RName:  TYPE = GVString;
    <<An R-Name (Recipient-name) is the basic name within the transport mechanism.  It is of the form SN.Reg ( Simple-Name . Registry 
    ).  The representation is as a ROPE of up to maxRNameLength characters.  In message bodies, R-Names occupy an integral number 
    of words.>>

    maxRNameLength: CARDINAL = maxGVStringLength;


    Connect: TYPE = GVString;
    <<"Connect" is the representation of a connect-site for an individual (typically a server).  It is a string which is either an NLS 
    name or a PUP address.>>

    maxConnectLength: CARDINAL = maxGVStringLength;


    Remark:  TYPE = GVString;
    <<"Remark" is the representation of a remark associated with a group, or of a TOC entry in a mailbox.  It is a human readable 
    string.>>

    maxRemarkLength: CARDINAL = maxGVStringLength;


    Password: TYPE = ARRAY[0..3] OF CARDINAL;
    <<"Password" is the representation of an individual's encryption key.  It is intended to be used with the DES encryption algorithm. 
     Note that this is not the same as DESFace.Key (today), not even if you use LOOPHOLE.>>

    MakeKey: PROC[Rope.ROPE] RETURNS[ Password ];




<<The following definitions are concerned with the layout of "message bodies".  A message body is the internal representation of a 
message within and between mail servers.  It is also sent to the client when he retrieves his mail.  A message body contains a 
number of "items".  Items are used to represent such things as postmark, recipients, sender, as well as the message text (if any), 
or other content of the message such as audio or capabilities.  Some items are mandatory and always occur precisely once, others 
may occur any number of times (including zero).  Each Item has a header, followed by the number of bytes of data specified by the 
header, followed by an extra byte if its length is odd.  Thus items always start at a word boundary.  A complete message body 
consists of the mandatory items followed by the optional ones.>>


    Timestamp: TYPE = MACHINE DEPENDENT RECORD[
    <<Used as UID's for messages and for database updates>>
        net:  [0..256), -- the PUP net number --
        host: [0..256), -- the PUP host number --
        time: PackedTime];

    PackedTime: TYPE = LONG CARDINAL;
    <<The number of seconds since midnight, January 1, 1901 GMT>>

    oldestTime: Timestamp = [net:0, host:0, time:0];

    RopeFromTimestamp: PROC[Timestamp] RETURNS[Rope.ROPE];
    <<Returns "3#14@123456789", for example.>>


<<Layout of items>>

    ItemHeader: TYPE = MACHINE DEPENDENT RECORD[
        type: ItemType,
        length: ItemLength ];
    <<Each item consists of an ItemHeader followed by a variable length array, containing the number of bytes specified by the length.  
    The item is followed by an extra byte if its length is odd.>>

    Item: TYPE = REF ItemHeader;

    ItemLength: TYPE = INT;
    <<Number of data bytes in the item, excluding header>>

    ItemType: TYPE = MACHINE DEPENDENT {
    <<Mandatory items:>>
        PostMark(10B),
        <<the item contains a timestamp giving the originating host and approximate time at which the message was given to the transport 
        mechanism.>>
        Sender(20B),
        <<the item contains precisely one R-Name, being that of the sender of this message>>
        ReturnTo(30B),
        <<the item contains precisely one R-Name, being that of the client to whom non-delivery of the message should be notified>>
        Recipients(40B),
        <<the item contains a sequence of R-Names, being the intended recipients of this message, as provided by the sender>>
    <<Items used solely by clients:>>
        Text(1010B),
        <<the item contains a sequence of characters forming a textual message>>
        Capability(1020B),
        <<the item contains a capability>>
        Audio(1030B),
        <<the item is an audio message>>
    <<Items used in registration server internal mail:>>
        updateItem(2000B),
        <<the item contains a registration server entry>>
        reMail(2100B),
        <<the item is internal mail to a mail server, containing precisely one R-Name, indicating that the corresponding mailbox should be 
        re-mailed>>
    <<Mandatory last item:>>
        LastItem(LAST[CARDINAL])
        <<the item contains no data, and always occurs as the last item in a message body>>
        };

    END.
<<>>
<<GrapevineUser:  Client access to the R-Server database>>
<<GVNames.mesa>>
<<Andrew Birrell  September 22, 1983 10:25 am>>
    <<>>
    DIRECTORY
        GVBasics USING[ Connect, GVString, oldestTime, Password, MakeKey, Remark, RName, Timestamp ],
        Rope USING[ ROPE ];

    GVNames: CEDAR DEFINITIONS
        IMPORTS GVBasics =

    BEGIN

    Outcome: TYPE = { -- possible outcomes of RS operations --
        noChange, -- updates and timestamped enquiries --
        group, individual, notFound, -- any --
        protocolError, wrongServer, allDown, -- any --
        badPwd, -- authentication and updates --
        outOfDate, notAllowed -- updates --
        };

    NameType: TYPE = Outcome[noChange..badPwd]; -- outcomes for enquiries --

    RListHandle: TYPE = LIST OF GVBasics.RName;



    ExpandInfo: TYPE = RECORD[ SELECT type: NameType[noChange..allDown] FROM
        noChange => NULL,
        group => [ members: RListHandle,
            stamp: GVBasics.Timestamp,
            count: INT ],
        individual => [ sites: RListHandle,
            stamp: GVBasics.Timestamp,
            count: INT ],
        notFound => NULL,
        protocolError => NULL,
        wrongServer => NULL,
        allDown => NULL,
        ENDCASE ];

    Expand: PROC[name: GVBasics.RName, oldStamp: GVBasics.Timestamp _ GVBasics.oldestTime, reporter: ReporterProc _ NIL] RETURNS[ 
    ExpandInfo ];
    <<"Expand" returns mailbox site names for individuals, membership list for groups. If the old stamp is still current, returns 
    "noChange".  Will not return "noChange" if the old stamp is defaulted.>>



    MemberInfo: TYPE = RECORD[ SELECT type: NameType[noChange..allDown] FROM
        noChange => NULL,
        group => [ members: RListHandle,
            stamp: GVBasics.Timestamp,
            count: INT ],
        individual => NULL,
        notFound => NULL,
        protocolError => NULL,
        wrongServer => NULL,
        allDown => NULL,
        ENDCASE ];

    GetMembers: PROC[name: GVBasics.RName, oldStamp: GVBasics.Timestamp _ GVBasics.oldestTime] RETURNS[ MemberInfo ] = INLINE
        { RETURN[ GetList[name, oldStamp, members] ] };
    <<"GetMembers" returns the membership list for a group. If the old stamp is still current, returns "noChange".  Will not return 
    "noChange" if the old stamp is defaulted.>>

    GetOwners: PROC[name: GVBasics.RName, oldStamp: GVBasics.Timestamp _ GVBasics.oldestTime] RETURNS[ MemberInfo ] = INLINE
        { RETURN[ GetList[name, oldStamp, owners] ] };

    GetFriends: PROC[name: GVBasics.RName, oldStamp: GVBasics.Timestamp _ GVBasics.oldestTime] RETURNS[ MemberInfo ] = INLINE
        { RETURN[ GetList[name, oldStamp, friends] ] };

    GetList: PROC[name: GVBasics.RName, oldStamp: GVBasics.Timestamp, list: ListType, reporter: ReporterProc _ NIL] RETURNS[MemberInfo];



    StampInfo: TYPE = NameType[noChange..allDown];

    CheckStamp: PROC[name: GVBasics.RName, oldStamp: GVBasics.Timestamp _ GVBasics.oldestTime, reporter: ReporterProc _ NIL] RETURNS[ 
    StampInfo ];
    <<"CheckStamp" performs basic name validation, also telling the caller the name type. If the old stamp is still current, returns 
    "noChange".  Will not return "noChange" if the old stamp is defaulted.>>



    ConnectInfo: TYPE = NameType[group..allDown];

    GetConnect: PROC[name: GVBasics.RName, reporter: ReporterProc _ NIL] RETURNS[ info: ConnectInfo, connect: GVBasics.Connect ];
    <<"GetConnect" returns the connect-site for an individual.  The connect-site is either an NLS name or a net-address.>>



    RemarkInfo: TYPE = NameType[group..allDown];

    GetRemark: PROC[name: GVBasics.RName, reporter: ReporterProc _ NIL] RETURNS[ info: RemarkInfo, remark: GVBasics.Remark ];
    <<"GetRemark" returns the remark for a group.  The remark is a human readable string..>>



    GetEntryInfo: TYPE = RECORD[
        name: GVBasics.RName,
        stamp: GVBasics.Timestamp,
        body: SELECT type: * FROM
            group => [
                remark: GVBasics.Remark,
                remarkStamp: GVBasics.Timestamp,
                members: GetEntryList,
                owners: GetEntryList,
                friends: GetEntryList],
            individual => [
                password: GVBasics.Password,
                passwordStamp: GVBasics.Timestamp,
                connect: GVBasics.Connect,
                connectStamp: GVBasics.Timestamp,
                forward: GetEntryList,
                sites: GetEntryList],
            notFound => NULL,
            dead => NULL,
        ENDCASE ];

    GetEntryList: TYPE = RECORD[
        current: RListHandle,
        currentStamps: LIST OF GVBasics.Timestamp,
        deleted: RListHandle,
        deletedStamps: LIST OF GVBasics.Timestamp];

    GetEntry: PRIVATE PROC[name: GVBasics.RName, reporter: ReporterProc _ NIL] RETURNS[rc: NameType[group..allDown], info: REF 
    GetEntryInfo];
<<"GetEntry" is mainly for use by Maintain.  It returns the entire contents of a database entry.  Consult a wizard before using 
GetEntry>>



    AuthenticateInfo: TYPE = NameType[group..badPwd];

    Authenticate: PROC[name: GVBasics.RName, password: Rope.ROPE]
        RETURNS[ AuthenticateInfo ] = INLINE
        { RETURN[ AuthenticateKey[name, GVBasics.MakeKey[password]] ] };
    <<"Authenticate" checks a user name and password.>>

    AuthenticateKey: PROC[name: GVBasics.RName, key: GVBasics.Password, reporter: ReporterProc _ NIL]
        RETURNS[ AuthenticateInfo ];



<<Access control primitives>>

    Membership: TYPE = { yes, no, notGroup, allDown };

    IsMemberDirect: PROC[name: GVBasics.RName, member: GVBasics.RName] RETURNS[ Membership ] = INLINE
        { RETURN[IsInList[name, member, direct, self, members]] };

    IsOwnerDirect: PROC[name: GVBasics.RName, owner: GVBasics.RName] RETURNS[ Membership ] = INLINE
        { RETURN[IsInList[name, owner, direct, self, owners]] };

    IsFriendDirect: PROC[name: GVBasics.RName, friend: GVBasics.RName] RETURNS[ Membership ] = INLINE
        { RETURN[IsInList[name, friend, direct, self, friends]] };

    IsMemberClosure: PROC[name: GVBasics.RName, member: GVBasics.RName] RETURNS[ Membership ] = INLINE
        { RETURN[IsInList[name, member, closure, self, members]] };

    IsOwnerClosure: PROC[name: GVBasics.RName, owner: GVBasics.RName] RETURNS[ Membership ] = INLINE
        { RETURN[IsInList[name, owner, closure, self, owners]] };

    IsFriendClosure:PROC[name: GVBasics.RName, friend: GVBasics.RName] RETURNS[ Membership ] = INLINE
        { RETURN[IsInList[name, friend, closure, self, friends]] };

    IsMemberUpArrow:PROC[name: GVBasics.RName, member: GVBasics.RName] RETURNS[ Membership ] = INLINE
        { RETURN[IsInList[name, member, upArrow, self, members]] };

    IsOwnerUpArrow: PROC[name: GVBasics.RName, owner: GVBasics.RName] RETURNS[ Membership ] = INLINE
        { RETURN[IsInList[name, owner, upArrow, self, owners]] };

    IsFriendUpArrow:PROC[name: GVBasics.RName, friend: GVBasics.RName] RETURNS[ Membership ] = INLINE
        { RETURN[IsInList[name, friend, upArrow, self, friends]] };

    MembershipLevel: TYPE = MACHINE DEPENDENT { direct(0), closure(1), upArrow(2) };
    MembershipGrade: TYPE = MACHINE DEPENDENT { self(0), registry(1) };
    ListType: TYPE = MACHINE DEPENDENT { members(0), owners(1), friends(2) };

    IsInList: PROC[name: GVBasics.RName, member: GVBasics.RName, level: MembershipLevel, grade: MembershipGrade, acl: ListType, 
    reporter: ReporterProc _ NIL]
        RETURNS[Membership];




<<Updates>>


<<Creation and Deletion>>

    CreateIndividual: PROC[user: GVBasics.RName, password: GVBasics.Password, individual: GVBasics.RName, newPwd: GVBasics.Password ] 
    RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, CreateIndividual, individual, NIL, newPwd] ] };

    DeleteIndividual: PROC[user: GVBasics.RName, password: GVBasics.Password, individual: GVBasics.RName] RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, DeleteIndividual, individual] ] };

    CreateGroup: PROC[user: GVBasics.RName, password: GVBasics.Password, group: GVBasics.RName] RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, CreateGroup, group] ] };

    DeleteGroup: PROC[user: GVBasics.RName, password: GVBasics.Password, group: GVBasics.RName] RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, DeleteGroup, group] ] };  




<<Updates to single-valued components>>

    SetPassword: PROC[user: GVBasics.RName, password: GVBasics.Password, individual: GVBasics.RName, newPwd: GVBasics.Password] 
    RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, ChangePassword, individual, NIL, newPwd] ] };

    SetConnect: PROC[user: GVBasics.RName, password: GVBasics.Password, individual: GVBasics.RName, connect: GVBasics.Connect] 
    RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, ChangeConnect, individual, connect] ] };

    SetRemark: PROC[user: GVBasics.RName, password: GVBasics.Password, group: GVBasics.RName, remark: GVBasics.Remark] RETURNS[Outcome] 
    = INLINE
        { RETURN[ Update[user, password, ChangeRemark, group, remark] ] };




<<Adding to list-valued components>>

    AddMailbox: PROC[user: GVBasics.RName, password: GVBasics.Password, individual: GVBasics.RName, site: GVBasics.RName] 
    RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, AddMailBox, individual, site] ] };

    AddForward: PROC[user: GVBasics.RName, password: GVBasics.Password, individual: GVBasics.RName, dest: GVBasics.RName] 
    RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, AddForward, individual, dest] ] };

    AddMember: PROC[user: GVBasics.RName, password: GVBasics.Password, group: GVBasics.RName, member: GVBasics.RName] RETURNS[Outcome] 
    = INLINE
        { RETURN[ Update[user, password, AddMember, group, member] ] };

    AddOwner: PROC[user: GVBasics.RName, password: GVBasics.Password, group: GVBasics.RName, owner: GVBasics.RName] RETURNS[Outcome] = 
    INLINE
        { RETURN[ Update[user, password, AddOwner, group, owner] ] };

    AddFriend: PROC[user: GVBasics.RName, password: GVBasics.Password, group: GVBasics.RName, friend: GVBasics.RName] RETURNS[Outcome] 
    = INLINE
        { RETURN[ Update[user, password, AddFriend, group, friend] ] };




<<Removing from list-valued components>>

    RemoveMailbox: PROC[user: GVBasics.RName, password: GVBasics.Password, individual: GVBasics.RName, site: GVBasics.RName] 
    RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, DeleteMailBox, individual, site] ] };

    RemoveForward: PROC[user: GVBasics.RName, password: GVBasics.Password, individual: GVBasics.RName, dest: GVBasics.RName] 
    RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, DeleteForward, individual, dest] ] };

    RemoveMember: PROC[user: GVBasics.RName, password: GVBasics.Password, group: GVBasics.RName, member: GVBasics.RName] 
    RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, DeleteMember, group, member] ] };

    RemoveOwner: PROC[user: GVBasics.RName, password: GVBasics.Password, group: GVBasics.RName, owner: GVBasics.RName] RETURNS[Outcome] 
    = INLINE
        { RETURN[ Update[user, password, DeleteOwner, group, owner] ] };

    RemoveFriend: PROC[user: GVBasics.RName, password: GVBasics.Password, group: GVBasics.RName, friend: GVBasics.RName] 
    RETURNS[Outcome] = INLINE
        { RETURN[ Update[user, password, DeleteFriend, group, friend] ] };


    Update: PROC[
        user: GVBasics.RName,
        password:  GVBasics.Password,
        op: RSOperation,
        target: GVBasics.RName,
        value: GVBasics.GVString _ NIL,
        newPwd: GVBasics.Password _ NULL,
        list: RListHandle _ NIL,
        reporter: ReporterProc _ NIL]
        RETURNS[Outcome];

    RSOperation: TYPE = MACHINE DEPENDENT {
        NoOp(0),
    <<Enquiries (also 60..69)>>
        Expand(1),
        ReadMembers(2),
        ReadOwners(3),
        ReadFriends(4),
        ReadEntry(5),
        CheckStamp(6),
        ReadConnect(7),
        ReadRemark(8),
        Authenticate(9),
    <<Updates>>
        CreateRegistry(10), -- not implemented
        DeleteRegistry(11), -- not implemented
        CreateIndividual(12),
        DeleteIndividual(13),
        CreateGroup(14),
        DeleteGroup(15),
        ChangePassword(16),
        ChangeConnect(17),
        ChangeRemark(18),
        AddMember(19),
        AddMailBox(20),
        AddForward(21),
        AddOwner(22),
        AddFriend(23),
        DeleteMember(24),
        DeleteMailBox(25),
        DeleteForward(26),
        DeleteOwner(27),
        DeleteFriend(28),
        AddSelf(29),
        DeleteSelf(30),
        AddListOfMembers(31),
        NewName(32),
        IdentifyCaller(33),--internal to GVNamesImpl
        IsMemberDirect(40), -- archaic
        IsOwnerDirect(41), -- archaic
        IsFriendDirect(42), -- archaic
        IsMemberClosure(43), -- archaic
        IsOwnerClosure(44), -- archaic
        IsFriendClosure(45), -- archaic
        IsInList(46),
    <<60..69 reserved for more enquiries>>
        ReadMailboxes(60), -- not implemented
        (255)
        };



    ReporterProc: TYPE = PROC[Rope.ROPE];
    <<"ReporterProc" is primarily to allow Maintain to report progress to its user.  Consult a wizard before using this facility.>>



    SetServerInfo: TYPE = { badName, allDown, noRoute, ok };

    SetServer: PROC[Rope.ROPE] RETURNS[ SetServerInfo ];
    <<"SetServer" provides a server hint, primarily used by Maintain.  Consult a wizard before using this facility.>>

    END.
<<>>
<<GrapevineUser (Cedar) - Location of servers>>
<<GVLocate.mesa>>
<<Andrew Birrell  May 13, 1983 1:29 pm>>

    DIRECTORY
        GVBasics USING[ RName ],
        PupDefs USING[ PupAddress ];

    GVLocate: CEDAR DEFINITIONS =

    BEGIN

    FoundState: TYPE = { allDown, notFound, found };

    FoundServerInfo: TYPE = RECORD[
        SELECT t: FoundState FROM
            allDown => NULL,
            notFound => NULL,
            found => [where: PupDefs.PupAddress],
        ENDCASE ];

    FindNearestServer: PROC[list: GVBasics.RName, accept: PROC[PupDefs.PupAddress]RETURNS[BOOLEAN] ] RETURNS[ FoundServerInfo ];

    FindLocalServer: PROC[listl: GVBasics.RName ] RETURNS[ FoundState, GVBasics.RName ];

    FindRegServer: PROC[ who: GVBasics.RName, accept: PROC[PupDefs.PupAddress]RETURNS[BOOLEAN] ] RETURNS[ FoundServerInfo ];

    AcceptFirst: PROC[PupDefs.PupAddress]RETURNS[BOOLEAN];
    <<returns TRUE>>

    END.
<<>>
<<GrapevineUser (Cedar) - public DEFS for retrieval of messages>>
<<GVRetrieve.mesa>>
<<Andrew Birrell  September 1, 1982 10:08 am>>

    DIRECTORY
        GVBasics USING[ ItemHeader, RName, Timestamp ],
        IO USING[ STREAM ],
        Rope USING[ ROPE ];

    GVRetrieve: CEDAR DEFINITIONS =

    BEGIN

    ROPE: TYPE = Rope.ROPE;

<<No procedures in this interface other than the message accessing procs ever raise a SIGNAL or ERROR.>>


    Handle: TYPE = REF HandleObject;
    <<This interface is intended to be able to be used by multiple clients.  They are distinguished by a "handle", created by "Create" 
    and destroyed by the garbage collector.  "Close" should be called when you're finished with the handle as a hint to release 
    resources (particularly any BSP connection). -->>

    HandleObject: TYPE;


    Create: PROC[pollingInterval: CARDINAL, reportChanges: PROCEDURE[MBXState] _ NIL] RETURNS[Handle];
    <<Must be called before any other entries in this interface.  Can be called many times.  "pollingInterval" is the interval in 
    seconds to wait between successive inbox checks and "reportChanges" (if provided) is called  whenever the state of the user's 
    authentication or mailboxes changes;  "reportChanges" will not be called if the state changes to "unknown" or "userOK".>>


    Close: PROC[Handle];
    <<Releases resources used by this handle.  Further use of this handle is illegal.>>




<<AUTHENTICATION AND MAILBOX POLLING>>


    NewUser: PROC[ handle: Handle, user: GVBasics.RName, password: ROPE];
    <<Provides new user name and password, and starts authentication and mailbox checking.>>


    MBXState: TYPE = { unknown, badName, badPwd, cantAuth, userOK, allDown, someEmpty, allEmpty, notEmpty };
    <<Records current state of the user's mailboxes. Initially "unknown".  Set to "badName", "badPwd", "cantAuth" or "userOK" after  
    authentication check.  Set to "allDown", "someEmpty", "allEmpty", or  "notEmpty" after mail polling is complete.  "someEmpty" 
    means not all  servers replied and none had mail; "allEmpty" means all replied and  none had mail; "notEmpty" means at least 
    one has mail; "allDown"  means none replied.>>

    MailboxState: PROC[ handle: Handle] RETURNS[ state: MBXState];
    <<Returns the current mailbox state.  Will not return "unknown" or "userOK" (These change to "cantAuth" or "allDown" after suitable 
    timeouts if necessary.)>>


    WaitForMail: PROC[ handle: Handle ];
    <<returns only when there is likely to be mail for the user>>
    <<Possible ERRORS: none>>





<<ACCESS TO MAILBOXES>>


<<The intended use is as follows.>>

<<The user has a number of mailboxes, each of which is on an MTP server or xon a Grapevine server.  To access all of a client's 
mail, call "NextServer" repeatedly until it returns noMore=TRUE.  For each successful call of "NextServer", if the ServerState is 
"notEmpty" use the mailbox access procedures to read the mail in the mailbox (otherwise there is no point in using the mailbox 
access procedures, since the mailbox is either empty or inaccessible).>>

<<To read the mail in the mailbox, call "NextMessage" until it returns msgExists=FALSE.  The first call of "NextMessage" for each 
server will attempt to create a stream to the server (signalling if it fails).  While accessing a mailbox, "Failed" may be 
signalled at any time if the communication system fails (because of network or server error).  If "Failed" is signalled, no further 
operations on this mailbox are allowed>>

<<NOTE: If the user has a mailbox on an MTP server, calling "NextMessage" for that mailbox will raise 
"Failed[communicationFailure]".>>

<<If "NextMessage" returns deleted=TRUE it indicates that the message is really just a placeholder and has been removed from the 
mailbox; you should not attempt to access the message.  Returning archived=TRUE indicates that the message has been spilled to some 
file server, and accessing it is likely to be much slower.  For each message that exists and is not deleted, the message may be 
manipulated by the other procedures provided.>>

<<"ReadTOC" may be used to read any TOC entry for the message (giving length=0 if there is no TOC entry), then "StartMessage" may 
be called to read the guaranteed properties of the message; these are not available for MTP servers; these may not be called after 
you have called "NextItem" for this message.>>

<<"NextItem" may be called to access in sequence the items which are the contents of the message body.  Note that the ItemHeader 
contains the item type and length in bytes.  The first item will be the guaranteed recipient list.  The message body is followed by 
an item of type "LastItem".  Within an item, use an IO.STREAM may be used to access the data of the item.  EndOf[] will be true at 
the end of the item.  Calling NextItem closes any IO.STREAM on a current item (even if the entrie item has not been read yet) and 
moves on to the next item.>>

<<You may call "WriteTOC" to change or create a TOC entry for the message, or you may call "DeleteMessage" to remove this single 
message from the mailbox;  "ReadTOC", "StartMessage", "NextItem" or "NextBlock" may not be called after calling "WriteTOC" or 
"DeleteMessage" for this message.>>

<<At any time within a message, you may call "NextMessage" to skip the remainder of this message.>>

<<At any time within a mailbox, you may call "Accept".  This terminates reading the mailbox and deletes all messages from the 
mailbox.  Calling "accept" will not delete any messages which you haven't been given a chance to read.  No other operations on the 
mailbox are allowed after calling "accept".  If you call "NextServer" without having called "accept", the mailbox is closed (if 
necessary) without deleting the messages (except those which were deleted by calling "deleteMessage").>>

    ServerType: TYPE = { MTP, GV };

    ServerState: TYPE = { unknown, empty, notEmpty };
    <<"unknown" means the server didn't reply to mail check packets; in this case, for efficiency, you should NOT call "NextMessage".  
    There is no point in calling NextMessage if the ServerState is "empty".>>

    NextServer: PROC[ handle: Handle ] RETURNS[ noMore: BOOLEAN, state: ServerState, type: ServerType ];
    <<Returns information about the next server in the mailbox site list of the user, and that server becomes the "current server".  If 
    there is no such server, noMore=TRUE, in which case the next call to "NextServer" will start a new sequence of mail retrieval.  
    If the state is "unknown", attempting to access the mailbox is inadvisable, as the server is probably down.  If the state is 
    "empty", there may in fact be mail, as the state is only a hint obtained by polling. >>


    ServerName: PROC[ handle: Handle] RETURNS [serverName: GVBasics.RName];
    <<Provides the name of the current server.  For MTP registries, this will be equivalent to the registry name.>>


    FailureReason: TYPE = {
        communicationFailure, -- server or network down --
        noSuchServer, -- server name incorrect --
        connectionRejected, -- server full, mbx busy, etc --
        badCredentials, -- name/pwd rejected --
        unknownFailure -- protocol violation or unknown MTP error: likely to be permanent --
        }; 

    Failed: ERROR[why: FailureReason, text: ROPE];
    <<May be signalled by any of the procedures that handle messages.>>


    NextMessage: PROC[handle: Handle] RETURNS[msgExists, archived, deleted: BOOLEAN];

    StartMessage: PROC[handle: Handle ]  RETURNS[postmark: GVBasics.Timestamp, sender: GVBasics.RName, returnTo: GVBasics.RName];

    NextItem: PROC[handle: Handle] RETURNS[GVBasics.ItemHeader];
    <<Skips the remainder of any previous item, then delivers the header of the next item.>>

    GetItem: PROC[handle: Handle] RETURNS[IO.STREAM];
    <<Provides an IO stream for reading the current item.>>

    Accept: PROC[handle: Handle];
    <<Flush the mailbox entirely (and irrecoverably).>>



<<"ReadTOC", "WriteTOC" and "DeleteMessage" are useful mainly for Lily.>>

    ReadTOC: PROC[handle: Handle] RETURNS[ ROPE ];

    WriteTOC: PROC[handle: Handle, entry:ROPE ];

    DeleteMessage: PROC[handle: Handle] ;




    END.
<<>>
<<GrapevineUser (Cedar) - public DEFS for client sending mail>>
<<GVSend.mesa>>
<<Andrew Birrell  May 12, 1983 1:34 pm>>

    DIRECTORY
        Rope USING[ ROPE ],
        GVBasics USING[ ItemType, Password, RName ];

    GVSend: CEDAR DEFINITIONS =

    BEGIN

    ROPE: TYPE = Rope.ROPE;

<<These defs allow clients to inject messages into the mail system.  They are designed so that they can be used by multiple 
processes creating different messages;  the state of creation of a single message is represented by a "Handle".  The interface is 
also designed so that it may be implemented either by transmission over the network to a remote mail server, or by calls on a local 
mail server.>>

    Handle:  TYPE = REF Object;

    Object:  TYPE;

    Create:  PROCEDURE RETURNS[handle: Handle];

<<For any one Handle, the following calls must be made in the order:>>
<<StartSend,>>
<<AddRecipient, AddRecipient, AddRecipient, . . .>>
<<CheckValidity {iff "validate=TRUE" when "StartSend" was called},>>
<<StartItem, (AddToItem, AddToItem, . . .), StartItem, (...), . . .>>
<<Send>>
<<Abort may be called at any point to abandon the sequence.  A Handle may be re-used.  "Abort" happens implicitly if needed 
sometime after the last reference to the Handle goes away.>>

    SendFailed: ERROR [ why: Rope.ROPE, notDelivered: BOOLEAN ] ;
    <<"StartSend" raises no signals that may be caught by the client.  The ERROR "SendFailed" may be raised by any of AddRecipient, 
    CheckValidity, StartItem, AddToItem, or Send if some communication failure occurs.  If it is raised, the client should 
    generally catch it, go back to the start of the message, and re-call "StartSend".   "StartSend" will then attempt to find a 
    better mail server to talk to.  Only when "StartSend" returns "allDown" is it not possible to send the message.  The client may 
    want to inform the user if thisre-try mechanism has been invoked.>>

    StartSendInfo: TYPE = MACHINE DEPENDENT { ok, badPwd, badSender, badReturnTo, allDown };

    StartSend: PROC[ handle: Handle, senderPwd: ROPE, sender: GVBasics.RName, returnTo: GVBasics.RName _ NIL, validate: BOOLEAN ] 
    RETURNS[ StartSendInfo ];
    <<Starts a message.  If "returnTo" is NIL, the sender name is used as return-to name.  "validate" says whether recipient names 
    should be validated during the communication with the mail server.>>


    SendFromClient: PROC[ handle: Handle, fromNet: [0..256) _ 0, fromHost: [0..256) _ 0, senderKey: GVBasics.Password, sender: 
    GVBasics.RName, returnTo: GVBasics.RName, validate: BOOLEAN ] RETURNS[ StartSendInfo ];
    <<Note: this procedure is intended for use only by the remote server.  Starts a message.  "fromNet" and "fromHost" are ignored if 
    the mail server is remote.  "validate" says whether recipient names should be validated during the communication with the mail 
    server.>>


    AddRecipient: PROC[ handle: Handle, recipient: GVBasics.RName ];
    <<Adds to the recipient list.>>


    CheckValidity: PROC[ handle: Handle, notify: PROCEDURE[INT,GVBasics.RName] ] RETURNS[ ok: INT ];
    <<Must be called after all the recipients have been given, iff the "validate" argument to "StartSend" was TRUE.  Calls "notify" for 
    each bad recipient.  The arguments to "notify" are the recipient number (counting from 1) and name of an illegal recipient.  
    Returns the number of valid recipients.  If any recipients were invalid, delivery of the message is still allowed.>>


    StartItem: PROC[ handle: Handle, type: GVBasics.ItemType ];
    <<Start a message body item.  The type must not be "Postmark", "Sender", "ReturnTo", or "Recipients".>>


    StartText: PROC[ handle: Handle ] = INLINE{ StartItem[handle,Text] };


    AddToItem: PROC[ handle: Handle, buffer: ROPE ];
    <<Add the data to the current message body item.>>


    Send: PROC[ handle: Handle ];
    <<Commit to sending the message; returns only when the mail server has commited to delivering the message.>>


    Abort: PROC[ handle: Handle ];
    <<Abandon the message.  May be called at any time.>>

    ExpandInfo: TYPE = MACHINE DEPENDENT { ok, notFound, individual, allDown} ;

    ExpandFailed: ERROR[why: Rope.ROPE];

    Expand: PROC[name: GVBasics.RName, work: PROC[GVBasics.RName]] RETURNS[ ExpandInfo ];
    <<If the name will be interpreted by the mail server as a distribution list, enumerates the names which are direct members of that 
    list. This is intended for use only if the user wants to inspect the contents.  Note that the contents may change, or the name 
    may become invalid, before delivery of any message.  "Expand" works even if the list has to be read from an MTP server.  May 
    raise "ExpandFailed".  If ExpandFailed is raised, some communication error has occurred;  you should re-call Expand, which will 
    try another server.  Note that failure of Expand may be caused by failure of some remote server;  you may still be able to send 
    a message successfully. "notFound" means the name is invalid; "individual" means the name specifies an individual; "allDown" 
    means either all mail servers are inaccessible, or some other server (possibly MTP) needed for the expansion is inaccessible.>>

    END.