-- Transport Mechanism - DEFS for client sending mail --

-- [Juniper]<DMS>MS>SendDefs.mesa

-- Andrew Birrell  23-Jan-81 11:00:14 --

DIRECTORY
BodyDefs	USING[ ItemType, Password, RName ];

SendDefs:	DEFINITIONS = BEGIN


-- 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[SIZE[POINTER]];

Create:		PROCEDURE RETURNS[handle: Handle];

Destroy:	PROCEDURE[ 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.


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 = { ok, badPwd, badSender, badReturnTo, allDown };

StartSend:	PROC[ handle:    Handle,
		      senderPwd: STRING,
		      sender:    BodyDefs.RName,
		      returnTo:  BodyDefs.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),
		      fromHost:  [0..256),
		      senderKey: BodyDefs.Password,
		      sender:    BodyDefs.RName,
		      returnTo:  BodyDefs.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: BodyDefs.RName ];
   -- Adds to the recipient list. --


CheckValidity:	PROC[ handle: Handle,
		      notify: PROCEDURE[CARDINAL,BodyDefs.RName] ]
		RETURNS[ ok: CARDINAL ];
   -- 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: BodyDefs.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: DESCRIPTOR FOR PACKED ARRAY OF CHARACTER ];
   -- 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 = { ok, notFound, individual, allDown};

ExpandFailed:	ERROR;

Expand:		PROC[name: BodyDefs.RName, work: PROC[BodyDefs.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.