milter-manager-commit

[Kenji O. <ok...@cl...>]

Kenji Okimoto	2013-08-16 15:08:50 +0900 (Fri, 16 Aug 2013)

  New Revision: 6b303257f8b01b9e8bfb3ebd47698070f0fad54a
  https://github.com/milter-manager/milter-manager/commit/6b303257f8b01b9e8bfb3ebd47698070f0fad54a

  Message:
    Add English version of ruby-milter-tutorial (Callbacks)
    
    This is in progress.
    
    GitHub: see #17

  Modified files:
    doc/ruby-milter-tutorial.rd

  Modified: doc/ruby-milter-tutorial.rd (+133 -0)
===================================================================
--- doc/ruby-milter-tutorial.rd    2013-08-16 15:08:21 +0900 (a86b3cb)
+++ doc/ruby-milter-tutorial.rd    2013-08-16 15:08:50 +0900 (bca6bc8)
@@ -65,3 +65,136 @@ Milter written in Ruby is followings:
 Let's write the milter that can reject a mail includes specified
 regular expression.
 
+== Callbacks
+
+Milter callback methods are called for each event. Almost events have
+additional information. You can pass additional information via
+callback parameters or macro. This document describes callback
+parameters.
+
+This is the list of callback methods and parameters.
+
+: connect(host, address)
+
+   This method is called when SMTP client connects to SMTP server.
+
+   ((|host|)) is hostname of SMTP client.
+   ((|address|)) is IP Address of SMTP client.
+
+   For example, connetct from localhost.
+
+   : host
+       "localhost"
+   : address
+       This is a (({Milter::SocketAddress::IPv4})) object represents
+       (({inet:45875@[127.0.0.1]})).
+
+: helo(fqdn)
+
+   This method is called when SMTP client sends HELO or EHLO command.
+
+   ((|fqdn|)) is FQDN reported via HELO/EHLO.
+
+   For example, SMTP client sends "EHLO mail.example.com".
+
+   : fqdn
+      "mail.example.com"
+
+: envelope_from(from)
+
+   This method is called when SMTP client sends MAIL command.
+
+   ((|from|)) is sender mail address reported via MAIL command.
+
+   For exapme, SMTP client sends "MAIL FROM: <us...@ex...>"
+
+   : from
+      "<us...@ex...>"
+
+: envelope_recipient(to)
+
+   This method is called when SMTP client send RCPT command.
+   This method is called twice if SMTP client send RCPT command twice.
+
+   ((|to|)) is recipient mail address reported via RCPT command.
+
+   For example, SMTP client sends "RCPT TO: <us...@ex...>"
+
+   : to
+      "<us...@ex...>"
+
+: data
+
+   This method is called when SMTP client sends DATA command.
+
+: header(name, value)
+
+   This method is called N times. N is the number of headers included
+   in the mail.
+
+   ((|name|)) is header name.
+   ((|value|)) is header value.
+
+   For example, there is a header which is "Subject: Hello!"
+
+   : name
+      "Subject"
+
+   : value
+      "Hello!"
+
+: end_of_header
+
+   This method is called when milter has finished processing header of
+   the mail.
+
+: body(chunk)
+
+   This method is called when milter has received mail body.
+   This method is called only once if mail body is small enough.
+   This methos is called multiple times if mail body is large.
+
+   ((|chunk|)) is splitted body.
+
+   For examle, if the mail body includes "Hi!", this method is called only once.
+
+   : chunk
+      "Hi!"
+
+: end_of_message
+
+   This method is called when SMTP client sends "<CR><LF>.<CR><LF>"
+   that represents end of data.
+
+: abort(state)
+
+   This method is called when SMTP transaction is resetted.
+   In particular, after end_of_message and SMTP client sends RSET.
+
+   ((|state|)) is a object represents timing of calling abort.
+
+: unknown(command)
+
+   This method is called when SMTP client sends unknown command in
+   milter protocol.
+
+   ((|command|)) is command name.
+
+: reset
+
+   This method is called when initialize and finish mail transaction.
+
+   ((mail transaction|URL:http://tools.ietf.org/html/rfc5321#section-3.3>))
+   has finished at:
+
+     * Called (({abort})) callback.
+     * Call (({reject})) in milter.
+     * Call (({temporary_failure})) in milter.
+     * Call (({discard})) in milter.
+     * Call (({accept})) in milter.
+
+: finished
+
+   This method is called when completed milter protocol.
+   TODO: write about timing
+