=head1 NAME

Net::SIP::ReceiveChain - handle incoming packet by multiple receivers

=head1 SYNOPSIS

  # create proxy which works as a registrar too, but
  # all register requests should be authorized

  my $registrar = Net::SIP::Registrar->new...
  my $auth = Net::SIP::Authorize->new ....
  my $reg_chain = Net::SIP::ReceiveChain->new(
	[ $auth,$registrar ],
	methods => [ 'REGISTER' ],
  );

  my $proxy = Net::SIP::StatelessProxy->new...
  my $chain = Net::SIP::ReceiveChain->new(
	[ $registrar,$proxy ]
  );

=head1 DESCRIPTION

This package is used to handle incoming packets by multiple receivers,
e.g. make sure that requests for L<Net::SIP::Registrar> will be
authorized by L<Net::SIP::Authorize>.

Objects in the chain might be L<Net::SIP::Registrar>, L<Net::SIP::StatelessProxy>,
L<Net::SIP::Authorize>, L<Net::SIP::ReceiveChain> itself and
every other object which handles C<receive> like described below.

=head1 CONSTRUCTOR

=over 4

=item new ( OBJECTS, %ARGS )

This creates a new registar object, OBJECTS is a reference to an array of
objects implementing the C<receive> method.

%ARGS can have the following keys:

=over 8

=item filter

A callback which gets called during C<receive> with all arguments of
the method. If it returns TRUE the packet will be handled by the
chain, otherwise not.

=item methods

If B<filter> is not given but B<methods> is it will set B<filter>
to a callback which accepts only the methods specified in the
array reference given to B<methods>.

=back

=back

=head1 METHODS

=over 4

=item receive ( PACKET,LEG,FROM )

PACKET is the incoming packet,
LEG is the L<Net::SIP::Leg> where the packet arrived and FROM
is the C<< "ip:port" >> of the sender. Responses will be send
back to the sender through the same leg.

Called from the managing L<Net::SIP::Dispatcher> object if a new
packet arrives.

Returns TRUE if the packet was fully handled by one of the objects
in the chain, else FALSE:

=over 8

=item *

If a filter was given checks the packet against the filter and
returns FALSE if the filter does return FALSE.

=item *

Otherwise it will call C<receive> on all objects in the
chain until one of these returns TRUE. In this case it
will return TRUE.

=item *

If no object in the chain handled the packet it will return FALSE.

=back

=back