NAME
    FML::Process::Kernel - provide fml core functions

SYNOPSIS
        use FML::Process::Kernel;
        $curproc = new FML::Process::Kernel;
        $curproc->prepare($args);

           ... snip ...

DESCRIPTION
    This modules is the base class of fml processes. It provides basic core
    functions. See FML::Process::Flow on where and how each function is used
    in the process flow.

METHODS
  new($args)
    1. import variables such as $ml_home_dir via "libexec/loader"

    2. determine $fml_version for further library loading

    3. initialize current process struct $curproc such as

        $curproc->{ main_cf }
        $curproc->config()
        $curproc->pcb()

    For example, this "main_cf" provides the pointer to /etc/fml/main.cf
    parameters.

    4. load and evaluate configuration files e.g.
    "/var/spool/ml/elena/config.cf" for "elena" mailing list.

    5. initialize signal handlders

  prepare($args)
    preparation before the main part starts.

    It parses the message injected from STDIN to set up a set of the header
    and the body object.

  lock( [$channel] )
    lock the specified channel. lock a giant lock if the channel is not
    specified.

  unlock( [$channel] )
    unlock the specified channel. unlock a giant lock if the channel is not
    specified.

  is_event_timeout( $channel )
  event_get_timeout( $channel )
  event_set_timeout( $channel, $time )
  credential_verify_sender($args)
    validate the mail sender (From: in the header not SMTP SENEDER). If
    valid, it sets the adddress within $curproc->credential() object as a
    side effect.

  simple_loop_check($args)
    loop checks the following rules of $config->{
    incoming_mail_header_loop_check_rules }. The autual check is done by
    header->"$rule()" for a "rule". See "FML::Header" object for more
    details.

  ml_variables_resolve( $args )
    determine ml specific variables $ml_name $ml_domain $ml_home_prefix
    $ml_home_dir by command line arguments or CGI environment variables with
    considering virtual domains.

        Example: "| /usr/local/libexec/fml/distribute elena@fml.org"
                 makefml COMMAND elena@fml.org ...
           or in the old style
                 "| /usr/local/libexec/fml/fml.pl /var/spool/ml/elena"

  config_cf_files_load($files)
    read several configuration @$files. The variable evaluation (expansion)
    is done on demand when $config->get() of FETCH() method is called.

  incoming_message_parse()
    "preapre()" method calls this to parse the message to a set of header
    and body. $curproc->{'incoming_message'} holds the parsed message which
    consists of a set of

       $curproc->{'incoming_message'}->{ header }

    and

       $curproc->{'incoming_message'}->{ body }.

    The "header" is "FML::Header" object. The "body" is "Mail::Message"
    object.

CREDENTIAL
  is_premit_post()
    permit posting. The restriction rules follows the order of
    "article_post_restrictions".

  stop_this_process($reason)
    Set "we should refuse this processing now" flag. We should stop this
    process as soon as possible.

  do_nothing($reason)
    same as stop_this_process($reason). dedicated to fml 4.0's $DO_NOTHING
    variable.

  is_refused()
    We should stop this process as soon as possible due to something invalid
    conditions by such as filtering.

LOG MESSAGE HANDLING
  log_message_init()
    initialize log message queue.

  log_enable
  log_disable
  log_message($msg, $msg_args)
    ? log(STR) log_message(STR, { level => "ok" }) logwarn(STR)
    log_message(STR, { level => "warning" }) logerror(STR) log_message(STR,
    { level => "error" })

  log($msg, $msg_args)
  logwarn($msg, $msg_args)
  logerror($msg, $msg_args)
REPLY MESSAGES
  reply_message($msg)
    "reply_message($msg)" holds message $msg sent back to the mail sender.

    To send a plain text,

        $curproc->reply_message( "message" );

    but to attach an image file, please use in the following way:

        $curproc->reply_message( {
            type        => "image/gif",
            path        => "aaa00123.gif",
            filename    => "logo.gif",
            disposition => "attachment",
        });

    If you attach a plain text with the charset = iso-2022-jp,

        $curproc->reply_message( {
            type        => "text/plain; charset=iso-2022-jp",
            path        => "/etc/fml/main.cf",
            filename    => "main.cf",
            disposition => "main.cf example",
        });

   CAUTION
    makefml/fml not support message handling not yet. If given, makefml/fml
    ignores message output.

  reply_message_nl($class, $default_msg, $args)
    This is a wrapper for "reply_message()" with natural language support.
    The message in natural language corresponding with $class is sent. If
    translation fails, $default_msg, English by default, is used.

    We need parameters in some cases. They are stored in $args if needed.

            $curproc->reply_message_nl('error.not_member',
                                       "you are not a ML member.",
                                       $args);

    This $args is passed through to reply_message().

  reply_message_delete
    delete message queue matched by the specified condition.

  reply_message_inform($args)
    inform the error messages to the sender or maintainer.
    "reply_message_inform($args)" checks existence of message(s) of the
    following category.

       category          description
       ----------------------------------
       reply_message     message sent back to the mail sender
       system_message    message sent to this list maintainer

    Prepare the message and queue it in by "Mail::Delivery::Queue".

  queue_in($category, $optargs)
  queue_flush()
    flush all queue.

    "TODO:" flush $queue, that is, send mail specified by $queue.

  reply_message_prepare_template($pf_args)
    expand $xxx variables in template (e.g. $help_file). return file name
    string, which is a new template converted by this routine.

    For example, it expands

            welcome to $ml_name ML

    to welcome to elena ML

    "Caution:" We need to convert charset of the specified file in some
    language. For example, Japanese message is ISO-2022-JP but programs love
    euc-jp since it is easy to use euc-jp.

ERROR HANDLING
MISCELLANEOUS METHODS
EXIT AS SPECIAL CODE
  exit_as_tempfail()
    exit as EX_TEMPFAIL.

CODING STYLE
    See "http://www.fml.org/software/FNF/" on fml coding style guide.

AUTHOR
    Ken'ichi Fukamachi

COPYRIGHT
    Copyright (C) 2001,2002,2003,2004,2005,2006,2008 Ken'ichi Fukamachi

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

HISTORY
    FML::Process::Kernel first appeared in fml8 mailing list driver package.
    See "http://www.fml.org/" for more details.

