=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