NAME

       Net::SIP::Leg - Wrapper around Socket for sending and receiving SIP packets

SYNOPSIS

         my $leg = Net::SIP::Leg->new( addr => '192.168.0.2' );
         $leg->deliver( $packet, '192.168.0.5:5060' );

DESCRIPTION

       A Leg wraps the socket which is used to send and receive packets.  It provides ways to
       strip Via header from incoming packets, to add Via header to outgoing packets and to add
       Record-Route header while forwarding.

       It's usually not used directly, but from Net::SIP::Dispatcher.

CONSTRUCTOR

       new ( %ARGS )
           The constructor creates a new object based on the hash %ARGS.  The following keys are
           used from %ARGS:

           sock    The socket as IO::Socket::INET object. "addr", "port" and "proto" will be
                   determined from this object and not from %ARGS.

           addr    The local address of the socket. If this is given but no port it will extract
                   port from addr, if it's in the format "host:port".

           port    The port of the socket. Defaults to 5060.

           proto   The connection protocol, e.g. 'tcp' or 'udp'. Defaults to 'udp'.

           contact Optional contact information which will be added as Record-route header to
                   outgoing requests and used within Contact header for 200 Responses to INVITE.
                   If not given it will be created based on "addr", "port" and "proto".

           If no socket is given with "sock" it will be created based on "addr", "port" and
           "proto". If this fails the constructur will "die()".

           The constructor will creeate a uniq branch tag for this leg.

METHODS

       forward_incoming ( PACKET )
           Modifies the Net::SIP::Packet PACKET in-place for forwarding, e.g strips top Via
           header in responses, adds received parameter to top Via header in requests, handles
           the difference between forwarding of requests to strict or loose routes and inserts
           Record-Route header in requests.

       forward_outgoing ( PACKET, LEG_IN )
           Similar to forward_incoming, but will be called on the outgoing leg. LEG_IN is the
           Net::SIP::Leg, where the packet came in (and where forward_incoming was called). Will
           add Record-Route header and remove itself from Route.

       deliver ( PACKET, ADDR, [ CALLBACK ] )
           Delivers Net::SIP::Packet PACKET through the leg $self to ADDR, which is "ip:port".
           Usually this method will be call from within Net::SIP::Dispatcher.

           If the packet was received by the other end (which is only possible to say if a
           reliable protocol, e.g. 'tcp' was used) it will call CALLBACK if provided. See
           invoke_callback in Net::SIP::Util for the format of callbacks. If the packet could not
           be delivered CALLBACK will be invoked with the appropriate errno ($!).

           While delivering requests it adds a Via header.

       receive
           Reads a packet from the socket and returns the Net::SIP::Packet PACKET and the senders
           ADDR as "ip:port". If reading failed will return "()".

       check_via ( PACKET )
           Returns TRUE if the top Via header in the Net::SIP::Packet PACKET contains the
           branch-tag from $self, otherwise FALSE. Used to check if the response came in through
           the same leg the response was send.

       add_via ( PACKET )
           Adds itself to PACKET as Via header.

       can_deliver_to ( ADDR|%SPEC )
           Returns TRUE if the leg can deliver address specified by ADDR or %SPEC.  ADDR is a
           hostname which can be prefixed by the protocol ( e.g. "udp:host" ) and postfixed by
           the port ( "host:port", "tcp:host:port",... ).

           If the caller has 'proto','addr' and 'port' already as separate items it can call the
           method with %SPEC instead.

           Right now it has now way to check if the leg can deliver to a specific host because it
           has no access to the routing information of the underlying OS, so that only proto will
           be checked.

       fd  Returns socket of leg. In some special environments (like tests) there might be legs,
           which don't have a socket associated. In this case you need to call receive from
           Net::SIP::Dispatcher yourself, because it cannot be called automatically once it
           receives data on the socket.

       dump
           Returns string containing information about the leg.  Used for debugging.