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 this
re-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.