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