Chip 1994 February

home *** CD-ROM | disk | FTP | other *** search

/ Chip 1994 February / CHIP0294.ISO / digital / best100 / buero / pmail / udg.txt < prev next >

Wrap

Text File | 1992-08-09 | 16.8 KB | 394 lines

┌────────────────────────────────────────────────────────────┐ │ │ │ Pegasus Mail v2.3 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. │ │ │ │ (c) 1992, 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 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 ~8@home.otago.ac.nz (~p) will cause the from field of messages from user david to read david@home.otago.ac.nz (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. This 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 will certainly be added: * 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. 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 2.2 (R4) and (R5) ONLY support 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 information, 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. Check new mail every X seconds: [Only applies to gateways where "New mail path" is not a program] specifies how often Pmail should check the New mail path for new mail. This value is a minimum length of time - Pmail may check less frequently than the value specified, but will never check more frequently. 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. SENDER.PM - Altering the Main menu ---------------------------------- Pegasus Mail v2.25 and later 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: ~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 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