
	customize fml by hooks

------------------------------------------------------------
1	HOOKS overview
2.1	Header Operation
2.2	%Envelope Operation
2.3	Read Files
2.4	Example

3	Hooks
3.1	$START_HOOK
3.2	$HEADER_ADD_HOOK
3.3	$DISTRIBUTE_START_HOOK
3.4	$SMTP_OPEN_HOOK
3.5	$DISTRIBUTE_CLOSE_HOOK (SMTP_CLOSE_HOOK)
3.6	$FML_EXIT_HOOK
3.7	$FML_EXIT_PROG
3.8	$MSEND_START_HOOK
3.9	$MSEND_HEADER_HOOK
3.10	$MSEND_OPT_HOOK
3.11	$REPORT_HEADER_CONFIG_HOOK
3.12	$COMMAND_HOOK (obsolete on to add new commands technique)
3.13	$MODE_BIFURCATE_HOOK
3.14	$COMMAND_FILTER_HOOK
3.15	$REJECT_COMMAND_FILTER_HOOK
3.16	$DISTRIBUTE_SUMMARY_HOOK
------------------------------------------------------------


1	HOOKS overview

HOOK is "execute a small perl program" within fml. 

2.1	Header Operation

GET_HEADER_FIELD_VALUE( header_field )

GET_ORIGINAL_HEADER_FIELD_VALUE( header_field )

SET_HEADER_FIELD_VALUE( header_field , value )

2.2	%Envelope Operation

GET_ENVELOPE_VALUE( hash_key )

SET_ENVELOPE_VALUE( hash_key, value )

ENVELOPE_APPEND( hash_key, value )

ENVELOPE_PREPEND( hash_key, value )

2.3	Read Files

GET_BUFFER_FROM_FILE( file )

	$s = &GET_BUFFER_FROM_FILE( "$DIR/xxx" );

2.4	Example

$START_HOOK = q#
	my ($s) = &GET_BUFFER_FROM_FILE("$DIR/info");
	&ENVELOPE_APPEND('Body', &STR2JIS($s));
#;

Please write message in $DIR/info (for example,
/var/spool/ml/elena/info ).

3	Hooks

Perl is an interpreter language. FML evaluates several hooks in a lot
of places. In this chapter we describe hooks. You can use complicated
control of FML and dynamic configuration changes by using hooks.

3.1	$START_HOOK

FML evaluates $START_HOOK, after header parsing and fundamental checks
but before main distribution and command functions

3.2	$HEADER_ADD_HOOK

Evaluated before header generation of distribution articles. $body
variable is used.

Example: add the field "X-Baycity-Weather: Mizumaki" (riddle:-).

    $HEADER_ADD_HOOK = q#
	$body .= "X-Baycity-Weather: Mizumaki\n";
    #;

is the same as

	&DEFINE_FIELD_FORCED("X-Baycity-Weather","Mizumaki");

Example 2: append the original Message-Id.

Message-ID: <19950518.01905.Elena.Lolobrigita@Baycity.asia>

$HEADER_ADD_HOOK = q#
   $body .= "Message-ID: ".
	sprintf("<%4d%02d%02d.%05d.%s>\n", 1900 + $year, $mon + 1, $mday, $ID, 
	"Elena.Lolobrigita@Baycity.asia");
#;

3.3	$DISTRIBUTE_START_HOOK

evaluated in the begging of &Distribute which is the main function of
distribution.

3.4	$SMTP_OPEN_HOOK

The variable name is historical, so ambiguous. Today this hook is
evaluated after $DISTRIBUTE_START_HOOK but before $HEADER_ADD_HOOK.
You can understand faster to see libdist.pl.

Example: Overwrite Reply-To: field of distribution mail. Today we
recommend to use $DEFINE_FIELD_FORCED.

$SMTP_OPEN_HOOK = q#
	$Envelope{'fh:reply-to:'} = $MAIL_LIST; 	
#;

Example 2: overwrite Precedence: to set "bulk".

$SMTP_OPEN_HOOK = q#
	$Envelope{'h:Precedence:'} = 'bulk';
#;

3.5	$DISTRIBUTE_CLOSE_HOOK (SMTP_CLOSE_HOOK)

$DISTRIBUTE_CLOSE_HOOK is evaluated in the last of &Distribute, which
is the main function of distribution. $SMTP_CLOSE_HOOK is an old
obsolete name, so both are same.

3.6	$FML_EXIT_HOOK

fml.pl evaluates this hook in the last. This evaluation is after
unlock! This hook is the last hook but $FML_EXIT_PROG is executed
after this since $FML_EXIT_PROG is to start a new process.

3.7	$FML_EXIT_PROG

In the last of fml.pl, FML starts $FML_EXIT_PROG as a new process by
exec(2) system call (precisely speaking via exec(3)).

3.8	$MSEND_START_HOOK

After msend.pl is initialized, msend.pl evaluates this hook in the
begging of the main function. See msend.pl internal.

3.9	$MSEND_HEADER_HOOK

In the header generation when sending digest mail creation time.

3.10	$MSEND_OPT_HOOK

msend.pl evaluates $MSEND_OPT_HOOK in the &MSendInit.

In default, digest delivery's subject is 

Subject: Matomete Send [PLAINTEXT(UNIX FROM)] (1/1) (Elena Lolobrigita ML)

To overwrite this, you can set the following ...

$MSEND_OPT_HOOK = q%
    $MSendOpt{'#uf'} = "#Overwritten... $MSendOpt{'#uf'}";
%;

		$MSEND_OPT_HOOK 

3.11	$REPORT_HEADER_CONFIG_HOOK

In SMTP library, this hook is evaluated just before the mail is passed
to &Smtp; This routine is used in a reply mail of command results.

3.12	$COMMAND_HOOK (obsolete on to add new commands technique)

3.13	$MODE_BIFURCATE_HOOK

Called in the first stage of &ModeBifurcate where fml.pl running mode
changes.

3.14	$COMMAND_FILTER_HOOK

3.15	$REJECT_COMMAND_FILTER_HOOK

3.16	$DISTRIBUTE_SUMMARY_HOOK

$DISTRIBUTE_SUMMARY_HOOK = q#
	&Append2(sprintf("%s [%d:%s] %s", 
			 $Now, $ID, substr($From_address, 0, 15), $s),
		 $SUMMARY_FILE);
#;

$s is the subject when this hook is evaluated.


		INDEX

$COMMAND_FILTER_HOOK                       ...   3.14 
$COMMAND_HOOK                              ...   3.12 
$DISTRIBUTE_CLOSE_HOOK                     ...   3.5 
$DISTRIBUTE_START_HOOK                     ...   3.3 
$DISTRIBUTE_SUMMARY_HOOK                   ...   3.16 
$FML_EXIT_HOOK                             ...   3.6 
$FML_EXIT_PROG                             ...   3.7 
$HEADER_ADD_HOOK                           ...   3.2 
$MODE_BIFURCATE_HOOK                       ...   3.13 
$MSEND_HEADER_HOOK                         ...   3.9 
$MSEND_OPT_HOOK                            ...   3.10 
$MSEND_START_HOOK                          ...   3.8 
$REJECT_COMMAND_FILTER_HOOK                ...   3.15 
$REPORT_HEADER_CONFIG_HOOK                 ...   3.11 
$SMTP_CLOSE_HOOK                           ...   3.5 
$SMTP_OPEN_HOOK                            ...   3.4 
$START_HOOK                                ...   3.1 
