-- GrapevineUser (Cedar) - public DEFS for retrieval of messages

-- GVRetrieve.mesa

-- Andrew Birrell September 1, 1982 10:08 am

DIRECTORY
RetrieveDefs USING[ MBXState, FailureReason, ServerState, ServerType ],
GVBasics USING[ ItemHeader, RName, Timestamp ],
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 Object;
-- 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). --

Object: 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 = RetrieveDefs.MBXState ;
-->>> { 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
-- on 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", use the Access Procs to read the mail in
-- the mailbox.

-- 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 "NextBlock" to access the data of the item. Each call of
-- "NextBlock" within an item will fill its buffer if the data exists; the
-- end of the item is indicated by "nextBlock" returning 0.

-- 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 an item, you may call "NextItem" to skip the
-- remainder of the item; 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 = RetrieveDefs.ServerType;
-->>> { MTP, GV };

ServerState: TYPE = RetrieveDefs.ServerState ;
-->>> { unknown, empty, notEmpty }
-- "unknown" means the server didn't reply to mail check packets;
-- in this case, for efficiency, you should NOT call "NextMessage".

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 = RetrieveDefs.FailureReason;
-->>> { communicationFailure, server or network down --
-->>>  noSuchServer,   server name incorrect --
-->>>  connectionRejected,  server full, mbx busy, etc --
-->>>  badCredentials,   name/pwd rejected --
-->>>  unknownFailure  protocol violation
-->>>         likely to be permanent
-->>>  };

Failed: ERROR[why: FailureReason];
-- 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];

-- "NextBlock" may be called to read the item piece by piece.
NextBlock: PROC[handle: Handle, maxlength: INT] RETURNS[block: ROPE];
  
-- "ReadItem" returns the entire (remainder of the) item. --
ReadItem: PROC[handle: Handle] RETURNS[item: ROPE] = INLINE
{ RETURN[ NextBlock[handle, LAST[INT]] ] };

-- "GetBlock", "GetChar", "CharsAvail" are intended for building an IO.STREAM for the item --
GetBlock: PROC[handle: Handle, block: REF TEXT, startIndex: NAT, stopIndexPlusOne: NAT]
RETURNS[nBytesRead: NAT];
GetChar: PROC[handle: Handle] RETURNS[CHAR];
CharsAvail: PROC[handle: Handle] RETURNS[BOOL];
EndOf: PROC[handle: Handle] RETURNS[BOOL] = INLINE { RETURN[NOT CharsAvail[handle]] };

-- "Accept" flushes the current inbox. --
Accept: PROC[handle: Handle];



-- "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.