[Cyan]<Cedar6.1>GrapevineUser>GVRetrieve.mesa!1

GVRetrieve.mesa (Cedar) - public DEFS for retrieval of messages

Andrew Birrell September 1, 1982 10:08 am

DIRECTORY

GVBasics USING[ ItemHeader, RName, Timestamp ],

IO USING[ STREAM ],

Rope USING[ ROPE ];

GVRetrieve: CEDAR DEFINITIONS = BEGIN OPEN IO, 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[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.