.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::SIP::Packet 3pm"
.TH Net::SIP::Packet 3pm "2023-09-29" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::SIP::Packet \- handling of SIP packets
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\&  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( \*(Aqcall\-id\*(Aq ) || die "no call\-id";
\&  $pkt\->set_header( via => \e@via );
\&  print $pkt\->as_string;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements the parsing, manipulation and creation of \s-1SIP\s0
packets according to \s-1RFC3261.\s0
.PP
NET::SIP::Packet's objects can be created by parsing a string containing
the \s-1SIP\s0 packet or by constructing it from parts, e.g. header keys and
values, body, method+URI (requests) or code+text (responses).
.PP
All parts can be manipulated and finally the string representation of
the manipulated packet can be (re)created.
.PP
For dealing with requests and responses directly usually the subclasses
Net::SIP::Request or Net::SIP::Response will be used instead.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 7
\&  # create packet from string
\&  my $invite = Net::SIP::Packet\->new(  <<\*(AqEOS\*(Aq );
\&  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( \*(Aqcall\-id\*(Aq )."\en";
\&  print "route=".join( ",", $invite\->get_header( \*(Aqroute\*(Aq ))."\en";
\&  $invite\->set_header( \*(Aqvia\*(Aq => [ $via1,$via2,.. ] );
\&
\&  # get resulting string representation
\&  print $invite\->as_string;
\&
\&  # create packet from parts
\&  my $resp = Net::SIP::Packet\->new(
\&        200, \*(AqOk\*(Aq,
\&        { to => \*(Aq<sip:you@example.com>\*(Aq, from => \*(Aq<sip:me@example.com>\*(Aq,.. }
\&        Net::SIP::SDP\->new(...)
\&  );
\&
\&  # and get the packet as string
\&  print $resp\->as_string;
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP "new ( \s-1STRING\s0 | @PARTS | \s-1HASH\s0 )" 4
.el .IP "new ( \s-1STRING\s0 | \f(CW@PARTS\fR | \s-1HASH\s0 )" 4
.IX Item "new ( STRING | @PARTS | HASH )"
This is the default constructor. Depending on the number of arguments branches
into \fBnew_from_string\fR or \fBnew_from_parts\fR or just creates the object directly
from the given \s-1HASH.\s0
.IP "new_from_string ( \s-1STRING\s0 )" 4
.IX Item "new_from_string ( STRING )"
Interprets \s-1STRING\s0 as a \s-1SIP\s0 request or response and creates Net::SIP::Request
or Net::SIP::Response object accordingly (these classes must have been
loaded already).
Will \fBdie()\fR if it cannot parse the string as a \s-1SIP\s0 packet.
.IP "new_from_parts ( CODE|METHOD, TEXT|URI, \e%HEADER|\e@HEADER, [ \s-1BODY\s0 ] )" 4
.IX Item "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 \s-1CODE\s0 and the text \s-1TEXT.\s0
Otherwise a Net::SIP::Request object will be created with the method \s-1METHOD\s0
and the uri \s-1URI.\s0
Note that the Request or Response class need to be loaded already.
.Sp
Header data can be given as a hash \f(CW%HEADER\fR or array \f(CW@HEADER\fR reference.
In case of a hash the key is the \s-1SIP\s0 field name and the value as either a string
or a \e@list of strings. The fields on the resulting \s-1SIP\s0 packet
will be sorted by name of the fields and fields with multiple values will be
created as seperat lines.
.Sp
If the header is given as an array the elements of the array are \f(CW\*(C`[ key => value ]\*(C'\fR
pairs where the keys are the field names and the values are strings or \e@list of
strings. Each pair will result in a single line in the \s-1SIP\s0 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 \s-1SIP\s0 packet will be the same as in
the array.
.Sp
The \s-1BODY\s0 is optional and can be given either as a string or as an reference to an
object which has a method \fBas_string\fR, like Net::SIP::SDP. If the \s-1BODY\s0 is an
object which has a method \fBcontent_type\fR it will set the \f(CW\*(C`content\-type\*(C'\fR header
of the \s-1SIP\s0 object based on the result of \f(CW\*(C`BODY\->content_type\*(C'\fR unless a
\&\f(CW\*(C`content\-type\*(C'\fR header was explicitly given.
.IP "_new_request | _new_response" 4
.IX Item "_new_request | _new_response"
These work like \f(CW\*(C`new\*(C'\fR but assign the new object to the subclasses
\&\f(CW\*(C`Net::SIP::Request\*(C'\fR resp. \f(CW\*(C`Net::SIP:.Response\*(C'\fR. They are not intended to be
used directly but only for redefining for using different subclasses when
subclassing \f(CW\*(C`Net::SIP::Packet\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
.IP "is_request" 4
.IX Item "is_request"
Returns \s-1TRUE\s0 if the \s-1SIP\s0 packet is a request, otherwise \s-1FALSE.\s0
.IP "is_response" 4
.IX Item "is_response"
Returns \s-1TRUE\s0 if the \s-1SIP\s0 packet is a response, otherwise \s-1FALSE.\s0
.IP "tid" 4
.IX Item "tid"
Returns a transaction \s-1ID\s0 created from the sequence number in
the \f(CW\*(C`CSeq\*(C'\fR header and the \f(CW\*(C`Call\-Id\*(C'\fR header.
All packets with the same tid belong to the same transaction.
.IP "cseq" 4
.IX Item "cseq"
Returns \f(CW\*(C`CSeq\*(C'\fR header. Short for \f(CW\*(C`$self\->get_header( \*(Aqcseq\*(Aq )\*(C'\fR.
.IP "callid" 4
.IX Item "callid"
Returns \f(CW\*(C`Call\-Id\*(C'\fR header. Short for \f(CW\*(C`$self\->get_header( \*(Aqcall\-id\*(Aq )\*(C'\fR.
.IP "get_header ( [ \s-1NAME\s0 ] )" 4
.IX Item "get_header ( [ NAME ] )"
If \s-1NAME\s0 is given it returns the \s-1SIP\s0 header for \s-1NAME.\s0 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 \f(CW@list\fR of all
values, but if \f(CW\*(C`wantarray\*(C'\fR says, that the caller expects only a
single value it will \f(CW\*(C`croak()\*(C'\fR.
.Sp
If no \s-1NAME\s0 is given it will return a reference to a hash which contains
all fields and has the format described in \fBnew_from_parts\fR.
.IP "add_header ( \s-1NAME, VAL\s0 )" 4
.IX Item "add_header ( NAME, VAL )"
Adds the header at the end of the \s-1SIP\s0 header.
\&\s-1VAL\s0 can be a string or a reference to a list of strings.
.IP "insert_header ( \s-1NAME, VAL\s0 )" 4
.IX Item "insert_header ( NAME, VAL )"
Like \fBadd_header\fR, but the lines will be added on top of the header.
.IP "del_header ( \s-1NAME\s0 )" 4
.IX Item "del_header ( NAME )"
Delete all lines from header where the field name is \s-1NAME.\s0
.IP "set_header ( \s-1NAME, VAL\s0 )" 4
.IX Item "set_header ( NAME, VAL )"
Replaces an existing header, like \fBdel_header\fR followed by \fBadd_header\fR.
.IP "set_body ( \s-1VAL\s0 )" 4
.IX Item "set_body ( VAL )"
Sets body to \s-1VAL,\s0 which can be string or object. The handling for body
objects see \fBnew_from_parts\fR.
.IP "as_string" 4
.IX Item "as_string"
Returns string representation of \s-1SIP\s0 packet.
.IP "dump ( [ \s-1LEVEL\s0 ] )" 4
.IX Item "dump ( [ LEVEL ] )"
Returns dump of packet as string for debugging. The higher \s-1LEVEL\s0
is the more details one gets. At the moment a \s-1LEVEL\s0 of 0 gets
a one-line summary and the rest the result from \fBas_string\fR.
.IP "as_parts" 4
.IX Item "as_parts"
Returns Array with CODE|METHOD, TEXT|URI, \e@HEADER and \s-1BODY\s0 like used
in \fBnew_from_parts\fR.
.IP "sdp_body( [ \s-1SDP\s0 ] )" 4
.IX Item "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.
.Sp
If body contains invalid \s-1SDP\s0 it raises an exception (e.g. \fBdie()\fR).
.Sp
If the optional \s-1SDP\s0 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.
.SS "\s-1UNDOCUMENTED METHODS\s0"
.IX Subsection "UNDOCUMENTED METHODS"
.IP "get_header_hashval ( [ \s-1NAME\s0 ] )" 4
.IX Item "get_header_hashval ( [ NAME ] )"
.PD 0
.ie n .IP "scan_header ( @ARG )" 4
.el .IP "scan_header ( \f(CW@ARG\fR )" 4
.IX Item "scan_header ( @ARG )"
.IP "clone" 4
.IX Item "clone"