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 <username> <memory_location> <length>
   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/<userid>

2: Obtain the mail delivery path for a specified user
   Command line:
      -d <username> <memory_location> <length>
   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/<userid>

3: Obtain the name of the user at the current workstation
   Command line:
      -u <memory_location> <length>
   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  = <path>

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.