CHANNELS(7)

NAME
MMDF Transmission Channels

SYNOPSIS
From deliver:
execl (path, name,
		msgfd, addressfd, responsefd,
		msg_txname, msg_sender,
		(domsg) ? "y" : "n", 0)
	char *path,
		*name,
	 	*msg_txname,
		*msg_sender;
	int  msgfd,
		addressfd,
		responsefd;

DESCRIPTION

Channel programs view themselves as relatively independent. Their goal in life is to perform the task of "channel fitting," sending mail from one channel (module) to another, possibly also sending mail in the reverse direction. Most channel programs just send mail from deliver to an outbound channel. Interaction with deliver is co-routined, so that it looks, to the channel program, like any other mail port. phone and slave are the only two programs that currently send in both directions. Each program's pattern for doing the fitting entails accessing the same types of modules, using similar types of interactions. A channel module has an I/O package, which is called by higher-level read-mail and write-mail packages. They are called by the the "fitting" module. Hence, a process which transfers mail in both directions between two channels "xx" and "yy" will have the basic modules relationships:

    	xx_rdmail	xx2yy_send	yy_wtmail

    xx_io						yy_io

    	xx_wtmail	yy2xx_send	yy_rdmail

As mentioned above, channel programs commonly send only from the local machine's deliver program, through module (qu_), out to a destination channel. Such channel programs will have the basic structure:
    qu_io	qu_rdmail	qu2yy_send	yy_wtmail	yy_io

  CHANNEL INVOCATION

When a channel program is invoked by deliver, the argument list is as shown in the Synopsis. The msgfd is a read-only file descriptor on the message text. The addressfd is a read-only pipe for getting destination addresses from deliver. The responsefd is for sending dispositions back to deliver. The last two arguments are the "name" of the message (almost never useful) and the return address, if given, of the message sender. This last is often used by channels during submission of the message to the next site. The argument list is hidden from channel programs, by mapping it into the qu_* calls.

  INTERACTION MODES

The I/O, read-mail and write-mail modules for channels have standard, but not identical, calls. In particular, a given module might not have certain calls. Also, some calls have mutually exclusive return options. In addition, the permissible sequencing of calls may be different. For example, the write-mail call that sends an address can send either of two positive responses: Address ok, or Message ok. The former means that only the address was sent and that the message text must be sent separately, when the address list is completed. The latter means that a copy of the entire message was sent. A channel that can return one of the two values MAY NOT EVER return the other. It is the responsibility of the xx2yy_send module to check for correct return values. The reason for the differences is that different channels may have VERY different protocol characteristics. For example, the local channel expects completed delivery of the entire message for each addressee. Alternatively, the telephone and SMTP packages expect the address list for a message to be sent before the (one) copy of the message text. For the currently implemented channels, the Local delivery channel expects text-writing calls after each address call. Most other channels expect addresses to be specified before text is sent. The independent local submission and pickup modules are list oriented, although submission can accept text-per-address, somewhat awkwardly. The deliver module (qu_) will handle either mode.

  CHANNEL PROCESSING PHASES

A channel module might go through several phases:

1.  Channel initialization

2.  Mode initialization (sending or receiving)

3.  Message initialization

4.  Address transmission

5.  Text transmission

6.  Optional iteration to step 3

7.  Mode termination

8.  Optional iteration to step 2

9.  Channel termination.

In many cases, particularly initializations, the module's calls for a phase are no-ops. However, they are included for completeness and to permit easy modification. To callers, message initialization only requires passing a mode string (usually containing an "m" to indicate that the mail is for a mailbox, rather than a terminal) and a return address string. Address passing entails iteratively passing a host/local address combination and retrieving a mmdf.h reply value for the address. The host portion may not be passed to the destination channel, as in the case of the local channel since there is no question for which host the address is intended. (This does not preclude the local address portion from containing additional host references, if the one receiving the address is a relay.) Text transfer is essentially a stream file transfer, effected by repeated calls to pass successive chunks of the message.

  INSTRUCTION SETS

The following are the calls from which a channel draws its instructions. No single module uses the entire set.

Session handling (in xx_io):
    *	xx_init	Get ready to handle mail
    *	xx_end	End this session
    *	xx_synch	Re-join sub-machines
    *	xx_sbinit	Caller will be submitting mail
    *	xx_sbend	Done submitting mail
    *	xx_pkinit	Caller wishes to receive mail
     	xx_pkkill	Caller wishes to stop receiving

Receiving mail (in xx_rmail):
    *	xx_rinit	Caller wishes to receive a message
     	xx_rkill	Terminate current message
     	xx_rainit	Caller ready to receive addresses
    *	xx_radr	Get an address
    *	xx_rtinit	Caller ready to receive text
    *	xx_rtxt	Get some message text
     	xx_rtcpy	Give me a handle to text copy

Sending mail (in xx_wtmail):
    *	xx_winit	Caller ready to send a message
     	xx_wkill	Terminate current message
    *	xx_wainit	Get ready for addresses
    *	xx_wadr	Here is an address
    *	xx_waend	Done sending set of addresses
    *	xx_wtinit	Get ready for message text
    *	xx_wtxt	Here is some message text
    *	xx_wtend	End of message text

Basic I/O (in    xx_io):
    *	xx_wrply	Here is a reply
    *	xx_rrply	Get a reply
    *	xx_wrec	Here is a record/packet
    *	xx_wstm	Here is part of a stream of text
    *	xx_rrec	Get a record
    *	xx_rsinit	Prepare to read stream
    *	xx_rstm	Get part of a stream of text

Notes:

    The asterisks indicate which calls currently are used by at least one channel.

A common calling sequence will comprise:
    xx_init	/* init for sending	*/
    xx_winit	/* init first message	*/
    xx_wadr	/* send first address	 */
    xx_rrply	/* address acceptable?	*/
    xx_wadr	/* second address...	*/
    xx_rrply
      ...
    xx_waend	/* no more addresses	*/
    xx_wtinit	/* message text next	*/
    xx_wtxt	/* send a chunk of it	*/
    xx_wtxt	/* another...	*/
      ...
    xx_wtend	/* no more message	*/
    xx_rrply	/* text accepted ok?*/
    xx_winit	/* next message...	*/
      ...
    xx_sbend	/* no more sending	*/
    xx_end	/* done with channel	*/

Note that the only direct user calls to the xx_io part of the module are for initialization. No record or stream calls are made directly.

  EXISTING MODULES

The following shows what channel programs and modules exist and what their names are.
    CHANNEL PROGRAMS
    Name	Program	Description
    -------	--------	------------------
    SMTP	smtp	Internet RFC821 SMTP outbound
    SMTP	smtpsrvr	Internet RFC821 SMTP inbound
    Local	local	Local machine send
    Phone	phone	PhoneNet dial-out (send & pickup)
    P.O. Box	pobox	Release held mail (currently to PhoneNet slave)
    UUCP	uucp	UUCP outbound (calls uux)
    UUCP	rmail	UUCP inbound
    List	list	Re-submit mailing list mail with header rewriting
    Ean (in)	ean2mmdf	EAN X.400 mail system to MMDF
    Ean (out)	ean	MMDF to EAN X.400 mail system
    Delay	delay	Delay channel (to resubmit due to NS failure)
    Prog	sendprog	Generalized program interface (outbound)
    Prog	recvprog	Generalized program interface (inbound)
    MAIL MODULES
    Channel	Basic	Receiving	Sending
    -------	----------	---------	-----------
    Deliver	qu_io	qu_rdmail
    MMDF	mm_io	mm_rdmail	mm_wtmail
    Local	lo_io	lo_rdmail	 lo_wtmail
    SMTP	sm_io		sm_wtmail
    Phone	ph_io	ph_rdmail	ph_wtmail
    	ph_iouser
    	ph_ioslave
    P.O.Box	po_io		po_wtmail

Notes:

    phone dials out to the site containing ph_slave and invokes it. Ph_io is combined with ph_iouser or ph_ioslave to make a full I/O set. mm_wtmail calls submit. mm_rdmail calls deliver (by default) in pickup mode. The default pickup program may be changed by altering the variable pathpkup[] in conf.c. The mm module is the user software interface to MMDF, for mail submission and POBox delivery (pickup). Lo_wtmail effects actual mailbox-stuffing. It does not have an associated lo_io because it was not needed.