Using the Internet/21003.iso/email/PEGASUS/WINPM222.ZIP/WINPMAIL.ZIP/UDG/UDG.TXT

Text File | 1995-04-27 | 20KB | 435 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 Pegasus Mail use it.
The intention is that you will provide the mechanism for moving the
messages and  attachments from place to place, while Pegasus Mail 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 Pegasus Mail 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 Pegasus Mail 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 Pegasus Mail 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!). Pegasus Mail 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 Pegasus Mail with Waffle, a
popular BBS and UUCP program.


How Pegasus Mail uses a UDG
--------------------

You have to provide Pegasus Mail with a set of instructions which it uses
to interface to your gateway. You do this using Pegasus Mail'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 Pegasus Mail 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 Pegasus Mail was run
   ~h       The current user's home mailbox location
   ~w       The current user's new mail location
   ~r       Sender's reply address (reply-to or from, in that order)
   ~~       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 Pegasus Mail stores in c:\temp\119944.tmp. When Pegasus Mail
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
Pegasus Mail'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 Pegasus
Mail 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 Pegasus Mail 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 Pegasus Mail
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
Pegasus Mail 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 Pegasus Mail
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,
Pegasus Mail 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
Pegasus Mail 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 Pegasus Mail
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.
** NOTE - Address validation routines will not work correctly when used
with Pegasus Mail for MS-Windows.

*Reply address format:  This field allows you control how Pegasus Mail
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 willy to read
   [e-mail] (Willy Murgatroyd).

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, Pegasus Mail
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:  Pegasus Mail 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 Pegasus
   Mail. 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 Pegasus Mail 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 Pegasus Mail v3.0
   expects to see messages in glue header format.

UUencode attachments:  If 'Y', then Pegasus Mail 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.

   (Pegasus Mail currently ONLY supports uuencoded attachments).

Burst messages?  If 'Y', then Pegasus Mail 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', Pegasus Mail 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.

Gateway processes BCC?  If 'Y', then Pegasus Mail will generate only a
single file for any message it sends, even if that message contains BCC
addressees. In this case, it is up to the gateway to ensure that the BCC
field is properly handled. If 'N', then Pegasus Mail will generate two
files when a message contains BCC addressees - the first with no BCC line
and addressed to everyone except the BCC addressees, the second with a BCC
line and addressed only to the BCC addressees.

Strip gateway name?  If 'Y', then Pegasus Mail will remove the gateway
name and trailing '/' character from addresses passed to the gateway.

Force all mail through:  If you set this field to 'Y', then Pegasus Mail
will pass all mail irrespective of addressing to the gateway for
processing. This effectively disables Pegasus Mail'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. Pegasus Mail 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 can process BCC headers on its own and you only want a
single message generated containing all the fields, make sure the
"Gateway processes BCC?" field in your gateway definition is set to 'Y'.


Altering the Main menu - Pegasus Mail 3.0 and later
--------------------------------------------

Under Pegasus Mail 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 Pegasus Mail 3.0 distribution - please examine it for further
details.


Altering the Main menu - Pegasus Mail 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 Pegasus Mail will look for the file when the
command returns: if the file exists and is longer than 0 bytes,
Pegasus Mail 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 Pegasus Mail should save its screen
before invoking the command, and restore it when the command
returns. If N, then Pegasus Mail assumes that the command either does
no screen output, or that it does it non-destructively.

*   Line 5: Enter the command Pegasus Mail 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 - Pegasus Mail 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.

Pegasus Mail 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 Pegasus Mail 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, Pegasus Mail 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 Pegasus Mail 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