Pegasus Mail Electronic Mail System,
Copyright (c) 1990-94 David Harris, all rights reserved

Pegasus Mail - Local Delivery System Interface Services


Starting with version 3.2 for DOS and 1.2 for Windows, Pegasus Mail
provides a programmatic mechanism for setting the following internal
system information required for local delivery at runtime:

A: The name of the user at the current workstation
B: The path to a specified user's new mail directory
C: The delivery path for outgoing mail to a specified user

A mechanism is also provided which allows Pegasus Mail's local user list
to be substituted with any programmatic service appropriate to a site.

For the path lookup functions (B and C), two methods are provided - the
first simply involves the use of simple static paths which Pegasus Mail
will use in preference to its default paths. The strings specifying these
paths may use the same substitution values as any User-Defined Gateway
substitution string (for instance, "C:\MAIL\~8"). The more complex
approach involves the provision of working code, either as a program or
as a Windows DLL.


Rationale

Why is this interface necessary? The simplest answer is because it
allows Pegasus Mail to operate transparently on systems about which it
may have no inherent internal understanding. By default, Pegasus Mail has
intrinsic support only for Novell NetWare 3.x and earlier - all other
systems are classed as "standalone". So, if you are a LAN Manager user,
for example, Pegasus Mail will not be able to take advantage of any
special services offered by that environment without some help. The
external interface mechanism defined here allows you to "hook in" to the
internal routines Pegasus Mail uses to identify users and paths with a
minimal amount of coding, potentially providing a similar level of
system integration to that Pegasus Mail enjoys natively with NetWare.

NetWare users may also want to use this interface if their system
requirements mean that the defaults Pegasus Mail uses are unacceptable
for some reason: as an example, if you have a small SYS: volume, you may
prefer Pegasus Mail to write new mail onto a volume other than SYS:.
Using this interface, all that is required to make this change (for
example to the USERS volume) is to add a PMSYSTEM.INI file which looks
like this:

[Pegasus Mail for DOS]
Static new mail directory path = USERS:MAIL/~B
Static outgoing delivery path = USERS:MAIL/~B

The mechanisms which have to be provided to implement these interfaces
necessarily vary for each version of Pegasus Mail: for the DOS version, a
program or programs should be provided, while the Windows version expects
a DLL with certain well-defined entry points. The exact values each
version of Pegasus Mail should use are defined in an INI file called
PMSYSTEM.INI, which must be located in the same directory as the .EXE
file it serves. PMSYSTEM.INI is described below.


Pegasus Mail for DOS

To provide interface services for Pegasus Mail for DOS, you must supply
a program or programs which accept certain fixed command-line parameters.
Pegasus Mail will invoke the program with a command-line switch which
indicates the service required, so a single program can perform multiple
duties if this is required. The program is passed the address of a memory
location inside Pegasus Mail into which the requested information must be
written, and an integer representing the maximum number of characters
which can be written into that location. The requirement that the program
write directly into Pegasus Mail's data segment necessitates considerable
care on the part of the programmer, and also implicitly requires the use
of a large memory model, since the location will be passed as a decimal
representation of a far pointer.

Pegasus Mail expects to find full pathnames to the program(s) it should
run in a section entitled "[Pegasus Mail for DOS]" in PMSYSTEM.INI. The
name of the entry associated with each command in this section is shown
in the descriptions below:

The following service calls are defined:

1: Obtain the specified user's new mail directory
Command line:
-n
Notes:
Pegasus Mail will run this program when it needs to know the
location of a specific user's new mail box. The new mail box
is where Pegasus Mail expects to find the user's PMAIL.INI
preferences file and where it should scan to find the user's
new mail.
PMSYSTEM.INI section entry:
"Query program for new mail directory"
Default:
On standalone systems - depends on configuration.
On NetWare systems - SYS:MAIL/

2: Obtain the mail delivery path for a specified user
Command line:
-d
Notes:
Pegasus Mail will issue this command when it needs to know where
a file should be written for delivery to the specified user. It
is legitimate for the program to return the same path for all or
any subset of users (in the case where a smart system is being
used to process mail for all users). The current user must have
at least file create rights ([C] under NetWare) in this location.
Messages are always written into this location in RFC-822 format.
PMSYSTEM.INI section entry:
"Query program for delivery path"
Default:
On standalone systems - depends on configuration.
On NetWare systems - SYS:MAIL/

3: Obtain the name of the user at the current workstation
Command line:
-u
Notes:
This command is issued before any other processing inside the
program, and is usually only issued at initialization time. It
should return the username of the user at the current station.
(Note, this does NOT necessarily mean an address - a simple
username is expected).
PMSYSTEM.INI section entry:
"Query program for user name"
Default:
On standalone systems - value of PMUSER environment variable,
or the value entered by the user in response to a prompt.
On NetWare systems - the value returned by the NetWare API.

Example:

You have two programs, LMUSER.EXE and LMPATH.EXE, which provide the
services Pegasus Mail needs. You would copy them into a specific
location (say for example R:\MAIL\EXE) and write your PMSYSTEM.INI so
that it looks like this:

[Pegasus Mail for DOS]
Query program for new mail directory = R:\MAIL\EXE\LMPATH.EXE
Query program for delivery path = R:\MAIL\EXE\LMPATH.EXE
Query program for user name = R:\MAIL\EXE\LMUSER.EXE

If you are working in an environment where it is acceptable to do
so, you may prefer to use '/' characters in paths instead of '\'s.


Pegasus Mail for Windows

Pegasus Mail for windows supports the same static paths as the DOS
version, using the same heading names. The programmatic interface
services for Pegasus Mail for Windows must be provided in the form of a
DLL. PMSYSTEM.INI will have a section entitled "[Pegasus Mail for
Windows]", which will contain an entry specifying the name of the DLL to
load, in the following format:

[Pegasus Mail for Windows]
External interface routines DLL =

The DLL should export the following routines by name:

int FAR PASCAL pmif_username (LPSTR username, long FAR *id, int maxlength);
int FAR PASCAL pmif_newmail_directory (const LPSTR username, LPSTR path,
int maxlength);
int FAR PASCAL pmif_delivery_path (const LPSTR username, LPSTR path,
int maxlength);

Each function should return 0 on success or 1 on failure. Other numeric
return values are reserved for future use (to allow more elaborate
error reporting).

These routines should operate as follows:

pmif_username:
Should return the name of the user at the current workstation
in the string pointed to by "username". Optionally, the routine
may fill out the "id" parameter with a unique identifier for
this user; this equates to the user's Bindery Object ID under
NetWare, and if set to 1 tells Pegasus Mail that the user is
the system supervisor.

pmif_newmail_directory:
Should return the fully-qualified path to the new mailbox for the
user specified. The path can be in DOS, NetWare or UNC format, but
be aware that some versions of the NetWare shell do not handle
fully-qualified NetWare paths (of the form SERVER/VOL:PATH/PATH)
properly.

pmif_delivery_path:
Should return the fully-qualified path to the directory where
Pegasus Mail should write the file containing a message addressed
to the specified user. It is legal for the DLL to return the same
path for more than one, or all users.

The following notes apply to all these routines: at most "maxlength"
bytes can be written into the target string, including the terminating
nul; strings are expected to be standard C-style strings (nul-terminated,
no leading length byte). Where a path is expected, Pegasus Mail can
accept any valid DOS, Windows or NetWare format, but we recommend the use
of UNC paths (in the general form \\SERVER\VOLUME\PATH...) in network
environments and DOS paths in the standalone environment.

The DLL you provide is loaded at runtime and is not released until
Pegasus Mail terminates.