-- GrapevineUser (Cedar) - public DEFS for client sending mail --

-- GVSend.mesa

-- Andrew Birrell August 27, 1982 3:41 pm

DIRECTORY
Rope USING[ ROPE ],
SendDefs USING[ StartSendInfo, ExpandInfo ],
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];

Close: PROCEDURE[ handle: Handle ];
-- Release resources associated with the Handle, particularly a
-- BSP connection. The Handle may not be used subsequently.


-- 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, until calling "Close". "Close" happens
-- implicitly sometime after the last reference to the Handle goes
-- away.

SendFailed: ERROR [ 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 this
-- re-try mechanism has been invoked.

StartSendInfo: TYPE = SendDefs.StartSendInfo;
-- { 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: LONG INTEGER ];
-- 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 = SendDefs.ExpandInfo ;

ExpandFailed: ERROR;

Expand: UNSAFE 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.