NAME

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

SYNOPSIS

         use Net::SIP::Packet;
         use Net::SIP::Request;
         use Net::SIP::Response;
         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 | HASH )
           This  is  the default constructor. Depending on the number of arguments branches into new_from_string
           or new_from_parts or just creates the object directly from the given HASH.

       new_from_string ( STRING )
           Interprets STRING as a SIP request or response and creates  Net::SIP::Request  or  Net::SIP::Response
           object  accordingly (these classes must have been loaded already).  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.  Note that the Request or Response class need to be loaded already.

           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.

       _new_request | _new_response
           These  work  like  "new"  but  assign  the  new  object  to  the subclasses "Net::SIP::Request" resp.
           "Net::SIP:.Response". They are not intended to be used directly but only  for  redefining  for  using
           different subclasses when subclassing "Net::SIP::Packet".

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 which 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( [ SDP ] )
           Returns body as Net::SIP::SDP object if there is a body and the content-type is 'application/sdp'  or
           empty. Will also find 'application/sdp' inside a 'multipart/mixed' body.

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

           If  the  optional  SDP  argument  is given, it is expected to be a Net::SIP::SDP object. This will be
           converted into a string and will replace an existing body (also inside multipart/mixed,  leaving  the
           rest untouched) or set a new body if none existed before.

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

perl v5.36.0                                       2023-09-29                              Net::SIP::Packet(3pm)