旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 � � � 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 ~8@home.otago.ac.nz (~p) will cause the from field of messages from user willy to read willy@home.otago.ac.nz (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: ~8@myhost.domain 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