plugins.pod update

* hook_help 
 * isa_plugin() example
 * some white space at EOL removed


git-svn-id: https://svn.perl.org/qpsmtpd/trunk@829 958fd67b-6ff1-0310-b445-bb7760255be9

docs/plugins.pod

@@ -156,6 +156,9 @@ C<init()> subroutine.
     $self->SUPER::hook_rcpt($transaction, $recipient);
   }
 
+See also chapter C<Changing return values> and 
+F<contrib/vetinari/rcpt_ok_maxrelay> in SVN.
+
 =head2 Config files
 
 Most of the existing plugins fetch their configuration data from files in the
@@ -1092,6 +1095,32 @@ is called. It's probably best not to try acessing it.
 
 Example plugin is F<tls>.
 
+=head2 hook_help
+
+This hook triggers if a client sends the B<HELP> command, allowed return
+codes are:
+
+=over 4
+
+=item DONE
+
+Plugin gave the answer.
+
+=item DENY
+
+Will result in a syntax error, probably not what you want, better use
+  $self->qp->respond(502, "Not implemented.");
+  return DONE;
+
+=back
+
+Anything else will be send as help answer.
+
+Arguments are
+   my ($self, $transaction, @args) = @_;
+
+with C<@args> being the arguments from the client's command.
+
 =head2 hook_vrfy
 
 If the client sents the B<VRFY> command, this hook is called. Default is to 
@@ -1167,7 +1196,7 @@ B<FIXME>
 
 =pod
 
-...documentation will follow later
+See F<README.authentication> in the qpsmtpd base dir.
 
 =head1 Writing your own plugins
 
@@ -1440,6 +1469,52 @@ like the following plugin and load it before your default queue plugin.
     return(DECLINED);
   }
 
+
+=head2 Changing return values
+
+This is an example how to use the C<isa_plugin> method.
+
+The B<rcpt_ok_maxrelay> plugin wraps the B<rcpt_ok> plugin. The B<rcpt_ok>
+plugin checks the F<rcpthosts> and F<morercpthosts> config files for
+domains, which we accept mail for. If not found it tells the
+client that relaying is not allowed. Clients which are marked as
+C<relay clients> are excluded from this rule. This plugin counts the
+number of unsuccessfull relaying attempts and drops the connection if
+too many were made.
+
+The optional parameter I<MAX_RELAY_ATTEMPTS> configures this plugin to drop
+the connection after I<MAX_RELAY_ATTEMPTS> unsuccessful relaying attempts.
+Set to C<0> to disable, default is C<5>.
+
+Note: Do not load both (B<rcpt_ok> and B<rcpt_ok_maxrelay>). This plugin
+should be configured to run I<last>, like B<rcpt_ok>.
+
+ use Qpsmtpd::DSN;
+ 
+ sub init {
+   my ($self, $qp, @args) = @_;
+   die "too many arguments"
+     if @args > 1;
+   $self->{_count_relay_max} = defined $args[0] ? $args[0] : 5;
+   $self->isa_plugin("rcpt_ok");
+ }
+
+ sub hook_rcpt {
+   my ($self, $transaction, $recipient) = @_;
+   my ($rc, @msg) = $self->SUPER::hook_rcpt($transaction, $recipient);
+ 
+   return ($rc, @msg)
+      unless (($rc == DENY) and $self->{_count_relay_max});
+
+   my $count = 
+     ($self->qp->connection->notes('count_relay_attempts') || 0) + 1;
+   $self->qp->connection->notes('count_relay_attempts', $count);
+
+   return ($rc, @msg) unless ($count > $self->{_count_relay_max});
+   return Qpsmtpd::DSN->relaying_denied(DENY_DISCONNECT, 
+           "Too many relaying attempts"); 
+ }
+
 =head2 TBC... :-)
 
 =cut