NAME

       Net::SIP::Packet - handling of SIP packets

SYNOPSIS

         use Net::SIP::Packet;
         my $pkt = eval { Net::SIP::Packet->new( $sip_string ) }
           or die "invalid SIP packet";
         $pkt->get_header( 'call-id' ) || die "no call-id";
         $pkt->set_header( via => \@via );
         print $pkt->as_string;

DESCRIPTION

       This module implements the parsing, manipulation and creation of SIP packets according to
       RFC3261.

       NET::SIP::Packet's objects can be created by parsing a string containing the SIP packet or
       by constructing it from parts, e.g. header keys and values, body, method+URI (requests) or
       code+text (responses).

       All parts can be manipulated and finally the string representation of the manipulated
       packet can be (re)created.

       For dealing with requests and responses directly usually the subclasses Net::SIP::Request
       or Net::SIP::Response will be used instead.

EXAMPLES

         # create packet from string
         my $invite = Net::SIP::Packet->new(  <<'EOS' );
         INVITE sip:you@example.com SIP/2.0
         From: <sip:me@example.com>
         To: <sip:you@example.com>
         ...
         EOS

         # show and manipulate some header
         print "callid=".$invite->get_header( 'call-id' )."\n";
         print "route=".join( ",", $invite->get_header( 'route' ))."\n";
         $invite->set_header( 'via' => [ $via1,$via2,.. ] );

         # get resulting string representation
         print $invite->as_string;

         # create packet from parts
         my $resp = Net::SIP::Packet->new(
               200, 'Ok',
               { to => '<sip:you@example.com>', from => '<sip:me@example.com>',.. }
               Net::SIP::SDP->new(...)
         );

         # and get the packet as string
         print $resp->as_string;

CONSTRUCTOR

       new ( STRING | @PARTS )
           This is the default constructor. Depending on the number of arguments branches into
           new_from_string or new_from_parts.

       new_from_string ( STRING )
           Interprets STRING as a SIP request or response and creates Net::SIP::Request or
           Net::SIP::Response object accordingly.  Will die() if it cannot parse the string as a
           SIP packet.

       new_from_parts ( CODE|METHOD, TEXT|URI, \%HEADER|\@HEADER, [ BODY ] )
           If CODE|METHOD is numeric a Net::SIP::Response object will be created with the
           response code CODE and the text TEXT.  Otherwise a Net::SIP::Request object will be
           created with the method METHOD and the uri URI.

           Header data can be given as a hash %HEADER or array @HEADER reference.  In case of a
           hash the key is the SIP field name and the value as either a string or a \@list of
           strings. The fields on the resulting SIP packet will be sorted by name of the fields
           and fields with multiple values will be created as seperat lines.

           If the header is given as an array the elements of the array are "[ key => value ]"
           pairs where the keys are the field names and the values are strings or \@list of
           strings. Each pair will result in a single line in the SIP header.  If the value was a
           list reference the values in the list will be concatened by ','.  The order of the
           fields in the resulting SIP packet will be the same as in the array.

           The BODY is optional and can be given either as a string or as an reference to an
           object which has a method as_string, like Net::SIP::SDP. If the BODY is an object
           which has a method content_type it will set the "content-type" header of the SIP
           object based on the result of "BODY->content_type" unless a "content-type" header was
           explicitly given.

METHODS

       is_request
           Returns TRUE if the SIP packet is a request, otherwise FALSE.

       is_response
           Returns TRUE if the SIP packet is a response, otherwise FALSE.

       tid Returns a transaction ID created from the sequence number in the "CSeq" header and the
           "Call-Id" header.  All packets with the same tid belong to the same transaction.

       cseq
           Returns "CSeq" header. Short for "$self->get_header( 'cseq' )".

       callid
           Returns "Call-Id" header. Short for "$self->get_header( 'call-id' )".

       get_header ( [ NAME ] )
           If NAME is given it returns the SIP header for NAME. If no header exists returns ().
           If there is only one value for the header returns this value. In case of multiple
           values it returns a @list of all values, but if "wantarray" says, that the caller
           expects only a single value it will "croak()".

           If no NAME is given it will return a reference to a hash wich contains all fields and
           has the format described in new_from_parts.

       add_header ( NAME, VAL )
           Adds the header at the end of the SIP header.  VAL can be a string or a reference to a
           list of strings.

       insert_header ( NAME, VAL )
           Like add_header, but the lines will be added on top of the header.

       del_header ( NAME )
           Delete all lines from header where the field name is NAME.

       set_header ( NAME, VAL )
           Replaces an existing header, like del_header followed by add_header.

       set_body ( VAL )
           Sets body to VAL, which can be string or object. The handling for body objects see
           new_from_parts.

       as_string
           Returns string representation of SIP packet.

       dump ( [ LEVEL ] )
           Returns dump of packet as string for debugging. The higher LEVEL is the more details
           one gets. At the moment a LEVEL of 0 gets a one-line summary and the rest the result
           from as_string.

       as_parts
           Returns Array with CODE|METHOD, TEXT|URI, \@HEADER and BODY like used in
           new_from_parts.

       sdp_body
           Returns body as Net::SIP::SDP object if there is a body and the content-type is
           'application/sdp' or empty.

           If body contains invalid SDP it raises an exception (e.g. die()).

   UNDOCUMENTED METHODS
       get_header_hashval ( [ NAME ] )
       scan_header ( @ARG )
       clone