Current Shareware 1994 January/SHAR194.ISO/email/pm301.zip/UDG.ZIP/UDG.TXT

Text File | 1993-08-30 | 19KB | 427 lines

┌────────────────────────────────────────────────────────────┐
│                                                            │
│    Pegasus Mail v3.0 user-defined gateway reference.       │
│    This document is part of the Pegasus Mail manual set    │
│    and is provided as a courtesy to users of Pegasus       │
│    Mail.                                                   │
│                                                            │
│    Copyright 1992-93, David Harris, All Rights Reserved.   │
│                                                            │
└────────────────────────────────────────────────────────────┘


User-defined gateways
---------------------

Pegasus Mail version 2.25 and later incorporate a feature which
allows you to implement your own mail transport and have PMail
use it. The intention is that you will provide the mechanism
for moving the messages and  attachments from place to place,
while PMail does the preparation, formatting and filing for you.

Here are some possible gateways you could develop:

*    An implementation of uucp for dial-in Internet mail

*    A standalone gateway which communicates with a machine attached
to your LAN, allowing you access to all your LAN mail features
from a remote machine (such a gateway is currently under development
as part of the PMail system).

*    A custom system which takes LAN mail and transfers it via some
file transfer protocol to a mainframe.

*    A gateway to a facsimile server.

The possibilities are limited only by your imagination.


The gateway process.
-------------------

While PMail offers considerable flexibility in the way it can
interact with your gateway, be aware that creating a gateway
will almost certainly involve a small amount of programming -
typically, you will need to write the program which PMail runs
to deliver and receive mail. You can do this programming in any
language which produces a program which could be run from DOS:
Pegasus Mail is written in C, but you could easily write your
gateway process in Pascal, Modula-II or even in Basic (God forbid!).
PMail invokes your gateway process when sending mail, or to check
for new mail. In most cases, your gateway process must not write
to the screen.

Note: you can use MS-DOS batch files as gateway processes.

What the gateway process does, and how you should do it is not
covered in this manual - this is your part of the project, and
you'll have to design it to your own specification. As a help,
however, the last section of this document describes how we interfaced
PMail with Waffle, a popular BBS and UUCP program.


How PMail uses a UDG
--------------------

You have to provide PMail with a set of instructions which it
uses to interface to your gateway. You do this using PMail's
PCONFIG program, choosing "create a User-defined gateway". The
gateway definition screen is essentially a form - you merely
have to fill in the appropriate details for your gateway.


Command substitution
--------------------

Most of the entries in this screen which accept strings allow
you to use special command substitution characters in the strings:
these are like "escape sequences" which will cause PMail to perform
some substitution at run-time. Command substitutions always begin
with a tilde (~) character, and are always two characters long.
The following command substitutions are recognised:

   This sequence...   Is replaced with this value

   ~c       The full path to the file containing the message
   ~t       The address to which to send this message
            (note: this is not necessarily the To: field)
   ~s       The message's subject field
   ~f       The full form of the message's "from" field
   ~n       The sender's user name in its simplest form
   ~b       The sender's bindery id, as a long hex integer
   ~8       The first 8 chars in the sender's username
   ~y       The time and date in RFC-822 format
   ~d       A random integer, expressed as 4 hex digits
   ~q       Y if this message is a BCC, N otherwise
   ~%name%  The value of the environment variable %name%.
   ~p       The user's personal name preference
   ~x       The name.ext ONLY of the container file (no path)
   ~a       The directory from which PMail was run (or base directory)
   ~h       The current user's home mailbox location
   ~~       A single tilde character.

Example: Assume that you have defined the gateway output command

   mygate ~c ~8 sys:mail/~b

And a user called DAVID, whose bindery ID is 4000001 sends a
message which PMail stores in c:\temp\119944.tmp. When PMail
invokes your gateway, the command line will be as follows:

      mygate c:\temp\119944.tmp DAVID sys:mail/4000001

In the following description of the Gateway Definition screen,
fields marked with an * will support command substitution. Command
substitution is also possible in the "Home mailbox" and "New
mailbox" fields of PMail's standalone configuration screen.


Gateway definition fields
-------------------------

Gateway name:  This is the name by which users will know this
gateway. It should follow legal NetWare naming rules, and cannot
contain spaces.

Users will access the gateway using NetWare usercode syntax so,
say you call your gateway HONG_KONG, and a user wants to mail
to someone called J_JONES at the gateway, they would enter the
address as HONG_KONG/J_JONES.

*New mail path:  This is either a full path to a location where
PMail is to find new mail, or else the name of a program to run
when checking for new mail. You can use command substitution
in this string to construct complex paths.  note that PMail will
assume that ALL mail matching the search mask is for the current
user - it will not parse messages to determine the recipient.
If your transport places new mail in the mail directory each
user has in SYS:MAIL, using a .CNM file extension, then you do
not need to enter anything in this field. Note that if you have
a gateway which writes messages into the user's NetWare directory
in SYS:MAIL using an extension other than .CNM, you can enter
a search path here using this command substitution: SYS:MAIL/~b
(See the section on command substitutions for more on this).

Is ^ a program to run?  Enter 'Y' if "New mail path" is a program
 name rather than a directory name. Gateways which require a
program  to be run to retrieve new mail will not be polled periodically
- rather, the "check for New mail" option will remain permanently
on the main menu, and the program can only be run when that option
is selected.

*New mail search mask:  This is a DOS filename pattern which
PMail is to use when searching the New mail path for new mail.
New mail messages will be rewritten in the user's home mailbox
using the normal PMail naming convention prior to reading, but
they need not be in this format as written by the gateway.

*Outgoing mail path:  The name of the directory in which PMail
should create outgoing mail messages. Again, command substitution
(described above) can be used in this string for specialised
processing.

*Run for outgoing mail:  If you enter a program name in this
field,  PMail will run it every time it sends new mail to the
gateway. The program must leave  the screen in the condition
it found it (ie, if it writes to the screen, it must do so using
non-destructive windows). This field is the one which will normally
benefit the most from the use of command substitution (see above).
By embedding escape keys in this string, you can construct extremely
complex command lines. Usually, this field will refer to a "glue"
program you have written to interface with the gateway: the actual
invocation of the gateway is intended to be user-activated via
choices in the SENDER.PM file.

*Filename format:  This field allows you some control over the
filenames PMail will use when creating outgoing messages. The
~d command substitution (random integer value) is often very
useful in this field.

Run to validate address:  You can provide a program which PMail
will call to validate that an address is correct. If you do so,
enter it in this field. Unlike other command strings, command
substitution is not possible with this field  the only parameter
passed on the  command line is the address to validate. Your
program must not disturb the screen, and must return 0 if the
address is invalid, or non-zero if the address is OK.  If nothing
is entered in this field, no attempt will be made to validate
addresses.

*Reply address format:  This field allows you control how PMail
will construct the "From" address in outgoing messages. You can
use command substitution in this field.

   Example: entering ~[e-mail] (~p)
   will cause the from field of messages from user david to read
   [e-mail] (David Harris).

Accepts SMTP addresses:  If your gateway accepts messages using
standard internet address formats, set this flag to 'Y'. If Charon
is not installed on your system and a user enters a standard
internet address, PMail will examine all available gateways,
and will pass the message to the first with this flag set. This
allows users to send internet mail using normal addressing, rather
than having to send it specifically via a gateway using the SERVER/ADDRESS
format.

Simple message headers:  PMail can write messages with extra
preparsed address information at the beginning of the message in
either of two formats:

1: Simple message headers is the original form provided by PMail.
   It is not particularly effective and is only provided for
   backwards compatibility.

   The simple header information is line-based, using line number
   as a key. Gateways which read simple message headers must read
   until a totally blank line is encountered, then send the remainder
   of the message, which will be normally formatted. At present, two
   lines are defined in the simple headers, although others may
   be added in future:

    * Line 1: The recipient of this message (not the same as
      the To: field)
    * Line 2: Contains 'Y' if this message has attachments.

   Lines without values will contain a single space. Addresses are
   already parsed. Since the format is intended to be extensible,
   gateways which understand simple headers must ignore lines they
   are not written to use, and must read until the blank line.

2: 'Glue' headers are an extension of simple headers; they are
   essentially a variant of the format PMail uses for Charon and
   Mercury with a little more information. The first line of the
   message is the signature "$$ " followed by the "from" address
   of the sender. Each subsequent line lists all the addressees
   to which this message should be sent, with a single character
   code at the start of the line indicating whether the address
   is for someone in the "to" field (T), the CC field (C) or the
   BCC field (B). The code is followed by exactly one space then
   the address. The glue headers end with a blank line and are
   followed by the message in canonical RFC822 format. Gateways
   designed to work with glue headers MUST IGNORE a line which
   starts with an unrecognized code character: this allows the
   format to grow. The PMPOP POP3 gateway for PMail v3.0 expects
   to see messages in glue header format.

UUencode attachments:  If 'Y', then PMail will generate a separate
message for each attachment, and will uuencode the attachment
into the message. If 'N', a file with the same name as the message
but the extension '.ATT' will be written into the outgoing mail
directory, along with the attachments. The .ATT file will contain
the names of the attachments to the message, one per line.

   (PMail currently ONLY supports uuencoded attachments).

Burst messages?  If 'Y', then PMail will create one message for
every address sent to: it is up to your gateway process to use
the ~t command substitution to ensure that delivery is correct,
since you generally will not be able to tell from the message's
headers who a particular copy should be sent to. If 'N', PMail
assumes that your gateway can parse the message for address data,
and will write all the addresses into one message, using standard
RFC-822 folding and header rules. The exception to this is messages
with a BCC header: this will generate two envelopes, one with
the BCC field, the other without. Your process can determine
which is the BCC delivery using the ~q command substitution.

Force all mail through:  If you set this field to 'Y', then PMail
will pass all mail irrespective of addressing to the gateway for
processing. This effectively disables PMail's support for all other
transports in the system.


Gateways and BCC:
----------------

Messages with BCC (Blind Carbon Copy) recipients present special
problems to gateways, since the same message ends up being processed
twice - once with no BCC header, then again as a separate job
containing the BCC header. PMail can indicate to the gateway
process that a message needs BCC processing (using the ~q command
substitution), but it is up to the gateway process to ensure
that the BCC field is properly handled, and that the message
is correctly forwarded. If your gateway does not handle BCC as
a special case, we recommend that you do NOT use BCC fields.


Altering the Main menu - PMail 3.0 and later
--------------------------------------------

Under PMail 3.0 and later, options are added to the "Send Message"
and "Check New mail" menu items via a resource file called
PM-MENU.RSC. A heavily-commented sample for this file is provided
with the PMail 3.0 distribution - please examine it for further
details.


Altering the Main menu - PMail 2.35 and earlier
-----------------------------------------------

Pegasus Mail v2.35 and earlier allow you to add sub-choices to
two of the options on the main menu- "Check for New mail" and
"Send a mail message". The addition is done via a text file called
SENDER.PM, which must be stored in the same directory as PMAIL.EXE.
This file contains sets of 5 lines, each set defining one sub-choice.
Blank lines and lines beginning with a semi-colon (';') are treated
as comments and are ignored. The lines within each set have the
following meanings:

*    Line 1: Either N if this entry is to be added to the New Mail
submenu, or S if it is for the Send message submenu.

*    Line 2: The text to show in the submenu

*    Line 3: Pegasus Mail will create a temporary filename which
can be passed to the command you specify on the command line.
If this field is Y, then PMail will look for the file when the
command returns: if the file exists and is longer than 0 bytes,
PMail will parse it as a message and mail it normally. This allows
you to create alternative message entry screens. Note that if
you use this option, the file must contain a properly-formatted
RFC-822 message on return. Attachments cannot currently be specified
in this file.

*    Line 4: Enter Y on this line if PMail should save its screen
before invoking the command, and restore it when the command
returns. If N, then PMail assumes that the command either does
no screen output, or that it does it non-destructively.

*    Line 5: Enter the command PMail should invoke on this line.
All command substitutions (see above) are possible here. The
maximum length of an entry on this line is 80 characters, although
the command line may be up to 128 characters in length after
command substitution. To invoke the usual built-in function (ie,
either Check for New Mail or Send a Message), enter a single
colon (':') on this line. The command you enter here may be an
MS-DOS batch file or an executable image.


A Sample Implementation - PMail and Waffle.
-------------------------------------------

Waffle is a particularly good Bulletin-Board System which is
widely distributed as Shareware on the Internet and on numerous
public services. Among its features is a solid implementation
of uucico, the UNIX copy-in - copy-out routine used to make uucp
transfers. Remember that Waffle is a Shareware program: we urge
you to send in the shareware license for Waffle if you use any
part of it - the program is well worth it, and the author deserves
support.

PMail can be quite easily interfaced with Waffle, providing a
quite functional standalone mail facility via uucp. One small
"glue" program is required - the source for this is included
on the PMail distribution diskette as an example of how gateways
can be implemented. The glue program was written by Brendan Murray,
Systems Manager at the University of Otago. Brendan has kindly
made the source freely available and modifiable without charge
or restriction. Both the glue code and this example assume that
you have a properly-configured copy of Waffle on your system.

Essentially, PMail creates a temporary file, then passes it to
the glue program, using a number of command substitutions to
minimise the parsing the program has to do. The glue code then
parses Waffle's static configuration file and creates appropriate
mail files in the right place for uucico and uuxqt. Two options
are added to the main menu to allow the user to choose when to
invoke uucico to process outgoing mail, and receive incoming
mail.

A sample user-defined gateway definition for Waffle is as follows:

Gateway name:              WAFFLE
New mail path:             c:\mailbox\~8
Is ^ a program to run?:    N
New mail search mask:      ~8.*
Outgoing mail path:        c:\scratch\tmp
Run for outgoing mail:     c:\bin\filter ~n ~c ~t ~y
Filename format:           ~d~d.WOM
Run to validate address:
Reply address format:      ~[e-mail]
Accepts SMTP addresses?:   Y
Simple message headers?:   N
UUencode attachments?:     Y
Burst messages?:           Y
Strip GW name?:            Y
Check new mail every x seconds.


Brendan's filter program locates Waffle's configuration file
using the WAFFLE environment variable; it expects parameters
on the command-line in the following order:

   1:    The name of the user sending the message
   2:    The name of the message container file
   3:    The To: field of the message
   4:    The time and date as an RFC-822 string



The SENDER.PM file for PMail using Waffle is as follows:

S
Regular mail message
N
N
:

S
Send all outgoing mail
N
Y
uucico

N
Read new mail messages
N
N
:

N
Check host for new mail
N
Y
uucico