From: rhys@cs.uq.oz.au (Rhys Weatherley)
Newsgroups: comp.bbs.waffle
Subject: Discussion piece: Helldiver Send Protocol (long)
Keywords: helldiver waffle mail news
Date: 20 Jul 92 11:32:38 GMT
Reply-To: rhys@cs.uq.oz.au

Hi all!

Here's a little change of pace for comp.bbs.waffle.  During my development of
the Helldiver off-line newsreader for Waffle 1.64 and Windows (don't ask, it's
not quite ready yet :-) , I needed a way to call up RMAIL and RNEWS to send
mail and news.  Well, one thing lead to another and I ended up with the
"Helldiver Send Protocol".  Basically it is a more-or-less generic interface
to the Waffle mail and news transmission facilities: you set up a temporary
control file and the message, execute HSEND.EXE, and it does all the rest.

Since this program could be useful to writers of other mail and news utilities
for Waffle, notably mailers, other newsreaders, and mail archive servers, I'm
posting the protocol specification here for comments from the general Waffle
community.

I'd appreciate any comments, especially from writers of mail/news tools, and
also Tom Dell - might this make a good interface for Waffle-related mail and
news tools in general?

If anyone wants to play with HSEND.EXE itself, e-mail me and I'll send it
to you.  A version of Helldiver Send will be distributed with the Helldiver
newsreader when it is available.

Cheers,

Rhys.

------------------------------------------------------------------------------

			Helldiver Send Mail/News Interface

				   Version 1.02

		      Copyright (C) 1991-1992 Rhys Weatherley

1. INTRODUCTION.

This document describes how to use the Helldiver Send program HSEND.EXE to
send mail and news under Waffle.  The Helldiver Newsreader executes this DOS
program as its final mailing and posting stage.  In effect, Helldiver Send
provides an abstract interface for sending mail and news that is independent
of any particluar news/mail system.  It is intended that other similar programs
will be written in the future by myself or others for other UUCP systems.
Normally the user of a mailer or newsreader would not need to use HSEND.EXE
directly - the mailer or newsreader would invoke HSEND.EXE itself.

Currently Helldiver Send supports Waffle 1.64.  It is possible that it will
also work with version 1.65, but I don't have a 1.65 beta to try it against.
Any comments on this front are welcome.

Because this program could prove useful to other people's projects, HSEND.EXE
may be distributed free of charge with your own programs as long as either
this documentation file is included verbatim, or the following copyright and
warranty message pertaining to Helldiver Send is included in your own
documentation:

-------------------------------------------------------------------------------
Helldiver Send, Copyright (C) 1991-1992 Rhys Weatherley, rhys@cs.uq.oz.au

Permission to use, copy, and distribute this material for any purpose
and without fee is hereby granted, provided that the above copyright notice
and this permission notice appear in all copies, and that the name of Rhys
Weatherley not be used in advertising or publicity pertaining to this material
without specific, prior written permission.  RHYS WEATHERLEY MAKES NO
REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY OF THIS MATERIAL FOR ANY
PURPOSE.  IT IS PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
-------------------------------------------------------------------------------

Please contact me via e-mail at rhys@cs.uq.oz.au if you have any further
queries about Helldiver Send, or would like the latest version.

Other people are welcome to write Helldiver Send clones conforming to this
specification for Waffle, or for other mail/news packages.  Please contact me
if you wish to extend this specification in any way so everyone's programs can
keep the same interface.  To be conformant to this specification, both the
command-line and control file formats described below must be adhered to.

2. COMMAND-LINE USAGE.

Helldiver Send has the following two command-line usage alternatives:

	hsend (filename|-) command
	hsend control-file

In the first case, the filename specified in the first argument (standard
input if "-") is fed to the command specified by the remaining arguments as
standard input.  Usually the command has one of the forms:

	rmail addresss ...
	rnews

This usage requires that the message be fully formatted already, complete
with From:, Message-Id: lines, etc.  It is not recommended that new programs
calling Helldiver Send use this option.  It is provided exclusively for
backwards-compatibilty with an earlier version of Helldiver Send that had a
limited audience.  The current version runs Waffle's RMAIL.EXE or RNEWS.EXE
programs which must be on the PATH.  Conformant implementations may interpret
"rmail" and "rnews" (in either case) as invoking the local mail and news
transmission facilities, whatever they may be.

The second usage above is the recommended usage for all callers of Helldiver
Send and conformant clones.  The single argument specifies a control file
containing commands telling Helldiver Send how to transmit a mail or news
message.  The next section describes the legal commands.  An extensive,
albeit atypical, example control file follows:

	File: f:\waffle\temp\msgaaba.tmp
	From: rhys
	From-name: Rhys Weatherley
	Newsgroups: news.groups,news.admin
	Mod-newsgroup: comp.archives mod@machine.domain.edu
	Mod-newsgroup: comp.risks mod@risks.domain.edu
	Local-newsgroup: 0.admin d:\news\local\0\admin
	Local-newsgroup: 0.talk d:\news\local\0\talk
	Followup-To: news.groups,news.admin
	Followup-To-local: 0.talk
	To: peter
	Cc: paul
	Cc: mary
	Bcc: rhys
	X-Mailer: Helldiver 1.04 (Waffle 1.64)
	Append: f:\waffle\user\rhys\outbox
	Sig: f:\waffle\user\rhys\sig
	Lines: 40
	Ref-groups: news.groups,news.admin,comp.archives,comp.risks
	Distribution: aus
	Dead-letters: f:\waffle\user\rhys\dead
	Software: Waffle 1.64
	Approved-for: john@nowhere.com (John Citizen)
	Expires: 76757576
	Control: cancel <.....>
	Ignore: Newsgroup
	Ignore: Crossposted-To
	Ignore: Follow
	Tempdir: f:\waffle\temp
	Delete: no
	Delete-control: no
	Subject: PROGRAM.ZIP - a little useless program (Part 02/05)
	Reply-To: rhys@cs.uq.oz.au

3. CONTROL FILE COMMANDS.

This section describes the commands that may be specified in a control file.
The ordering of command lines is not important.  More than one message can
be specified in the same control file by separating the relevant sections with
a line containing a single "-" character.  Unknown commands are ignored.

The meaning of each section is as follows: if there is a "To:", "Cc:" or "Bcc:"
line, then a mail message is sent.  If there is a "Newsgroups" line, then a
news message is posted.  If there is a "Local-newsgroup" line is specified,
then a message is posted to a local newsgroup.  If there is a "Mod-newsgroup"
line, then a mail message is sent for a moderated newsgroup.  Each of the
above may be mixed to send more than one message at once.  Helldiver Send
avoids sending messages with a mixture of normal, local and moderated groups.
In particular, a message posted to a normal newsgroup must not contain any
local or moderated newsgroup names, and a message posted to a moderated
newsgroup must not contain any other newsgroup names, including other
moderated groups.

If an RFC-822 or RFC-1036 compliant header line is specified below, then it
should be removed from the original message file before copying the message
file to the final message.  The input message file specified by the "File:"
command must consist of zero or more header lines, followed by a blank line
and the body of the message.  If a header is implicitly specified by one of
the commands below, it doesn't need to be included in the original message,
though it can be: it will just be ignored.

Append:
	If present, this command specifies a file to append the initial message
	(specified by "File:") to.  This is useful if a user has requested that
	all their messages be saved in a file before transmission.

Approved-for:
	If present, this command tells Helldiver Send to use the argument as
	the "From:" line for the final message, and to use the "From:" command
	as the user-id for the user approving the message, and the "Sender:"
	name.  The "Approved:" line always has the form "user@host" where
	"host" is derived externally to Helldiver Send (in the case of Waffle,
	it is specified in the STATIC file).  This is a security measure to
	ensure that e-mail names of user's on a different site may not be
	inserted into the "Approved:" line.  Helldiver Send automatically
	removes any "Approved:" lines in the original message file to prevent
	bypassing this security feature.

Bcc:
	Specify the e-mail address of a blind carbon-copy recipient of a
	mail message.  Only one recipient may be specified on the line,
	but more than one "Bcc:" line may be given.

Cc:
	Specify the e-mail address of a carbon-copy recipient of a mail
	message.  Only one recipient may be specified on the line, but
	more than one "Cc:" line may be given.

Control:
	The text of the "Control:" line in the final message.  Note that
	supporting this command can be a big USENET security risk.  It is
	recommended that friendly front-end user interfaces not use this
	command, except maybe for the cancellation of a user's articles.
	Conformant Helldiver Send clones may wish to inhibit this command
	or restrict the control messages that can be generated using it.
	Ultimately it is not possible to stop a system administrator
	generating bogus control messages by directly talking to RNEWS,
	but other users should be restricted from its use.

Dead-letters:
	The name of a file to append messages to that could not be delivered
	for any reason.  The Helldiver Newsreader uses the file "DEAD" in the
	user's home directory for this purpose.  If this command is not
	present, dead letters are merely discarded.

Delete:
	If present, it indicates if the message file specified by "File:"
	should NOT be deleted after message delivery.  The default is to
	delete the file.  The argument should be "no" in lower case for
	upwards compatibility with future Helldiver Send versions.  Currently
	the argument is ignored, and file is deleted if this command is
	not present.

Delete-control:
	Similar to "Delete:", but indicates if the control file should be
	deleted after delivering all messages.  This command must occur in
	the first section if there is more than one separated by "-" lines.
	It is recommended that callers of Helldiver Send not specify "Delete"
	or "Delete-control" but arrange for temporary files to be used for
	both the message and control files.  Thus, a single call on Helldiver
	Send can stand-alone, with the calling program not needing to do
	any clean-up afterwards.  This is important in environments like
	Microsoft Windows where it is difficult to detect when a child process
	(like running Helldiver Send to send a message) has terminated and
	clean up the temporary files in the parent: all clean-ups are done
	in Helldiver Send itself.

Distribution:
	A comma-separated list of USENET distributions to place into the
	final message's "Distribution:" line.

Expires:
	An expiry date in Unix datetime format (i.e. the number of seconds
	since 1 Jan 1970).

File:
	Specifies the name of the file containing the message.  The header is
	separated from the body by a single blank line.  The header may
	contain some header fields that are automatically generated by other
	control file commands, which are ignored when the final message is
	generated.

Followup-To:
	Specifies a comma-separated list of newsgroups to enter into the
	final message's "Followup-To:" line.

Followup-To-local:
	Specifies a comma-separated list of local newsgroups to enter into
	the "Followup-To:" line (in addition to any "Followup-To" groups) for
	messages posted to local newsgroups.

From:
	Specify the user-id of the user the message is from.  If the
	"Approved-for:" line is also present, this specifies the user-id of
	the user approving the message and "Approved-for:" gives the text
	of the final message's "From:" line.

From-name:
	Real name of the user to be inserted into the "From:" line of the
	final message.  The final "From:" line will have the form
	"user@host (real name)" or "real name <user@host>" depending on
	the implementation.  Helldiver Send uses the first form.

Ignore:
	The name of a header field to ignore when generating the final
	message.  i.e. if the header field appears in the original message
	file, then that line will be removed.

Lines:
	Number of lines in the body of the message.  If this command is not
	present, then no "Lines:" header is inserted into the final message.
	Note the comments for the "Sig:" command when using this command.

Local-newsgroup:
	Name of a local newsgroup and the corresponding spool directory.  It
	is assumed that the article is to be stored into the directory as a
	numbered file, and no other processing is required.  On some systems,
	"Newsgroups:" could be used instead of "Local-newsgroup:".  This
	is possible under Waffle, but since RNEWS.EXE is executed, then the
	FEEDS file must be edited to stop local newsgroups being fed to other
	sites.  Note that no checking is done to see if local newsgroups in
	Waffle have overflowed the "/keep" setting.

Mailer-ident:
	A short string of characters that can be inserted into the final
	message's "Message-Id:" field if the program desires to.  The default
	string is an empty string.  For example, the Helldiver Newsreader
	sets this command to "hxyyh" where "x.yy" is the current newsreader
	version, so that Message-Id's have the form "<ABCDEFhxyyh@host>".
	Use of this command can help isolate software versions that generate
	invalid news and mail messages by inspecting the Message-Id.  It is
	not necessary that all conformant implementations use this command.

Mod-newsgroup:
	Name of a moderated newsgroup and the e-mail address to send the
	posting to.

Newsgroups:
	A comma-separated list of newsgroups to post the message to.

Ref-groups:
	If present, then the text of this line is output as the "Newsgroups:"
	line in any mail messages.  It is intended to be used for replies to
	news postings so that the newsgroups appear in the final reply.

Reply-To:
	A fully qualified e-mail address to be inserted into the "Reply-To:"
	line of the final message.

Sig:
	If present, specifies the name of a file to be appended to the final
	message as the user's signature.  Note that if the "Lines:" option
	is also present, then the lines of the signature may not be included
	in the final count, so it is usually better to append the signature
	in the originating program if a "Lines:" header is desired.

Software:
	The name of the software to use for mailing or posting the final
	messages.  At present, Helldiver Send recognises "Waffle 1.64" in
	this command as indicating that Waffle 1.64 should be used for sending
	mail and news.  Contact rhys@cs.uq.oz.au for details on other
	identifiers, and for registering your own identifiers.  If "Software:"
	is not recognised, then the program can either ignore or continue to
	process the message - this behaviour is not defined by this
	specification.

Subject:
	If present, then it indicates a new subject to be used to replace the
	subject in the original message.  This is convenient for indicating
	the part number for multi-part messages by overriding the user's
	entered subject for each of the parts.

Tempdir:
	This command is mandatory and specifies a directory that temporary
	files can be created in.

To:
	Specify the e-mail address of a recipient of a mail message.  Only
	one recipient may be specified on the line, but more than one "To:"
	line may be given.

X-Mailer:

	An optional comment line.  The contents of this line are copied into
	an "X-Mailer:" line in the final message.  Usually this is the name
	and version of the program calling Helldiver Send.

Please contact the author at rhys@cs.uq.oz.au if you have any further queries.

------------------------------------------------------------------------------
--
Rhys Weatherley, University of Queensland, Australia.
rhys@cs.uq.oz.au  "I'm a FAQ nut - what's your problem?"