1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
=head1 NAME
Net::SIP::Leg - Wrapper around Socket for sending and receiving SIP packets
=head1 SYNOPSIS
my $leg = Net::SIP::Leg->new( addr => '192.168.0.2' );
$leg->deliver( $packet, '192.168.0.5:5060' );
=head1 DESCRIPTION
A B<Leg> wraps the socket which is used to send and receive packets.
It provides ways to strip B<Via> header from incoming packets, to
add B<Via> header to outgoing packets and to add B<Record-Route> header
while forwarding.
It's usually not used directly, but from L<Net::SIP::Dispatcher>.
=head1 CONSTRUCTOR
=over 4
=item new ( %ARGS )
The constructor creates a new object based on the hash %ARGS.
The following keys are used from %ARGS:
=over 8
=item sock
The socket as IO::Socket::INET object. C<addr>, C<port> and C<proto>
will be determined from this object and not from %ARGS.
=item 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 C<< host:port >>.
=item port
The port of the socket. Defaults to 5060.
=item proto
The connection protocol, e.g. 'tcp' or 'udp'. Defaults to 'udp'.
=item contact
Optional contact information which will be added as B<Record-route> header
to outgoing requests. If not given it will be created based on C<addr>, C<port>
and C<proto>.
=back
If no socket is given with C<sock> it will be created based on C<addr>, C<port>
and C<proto>. If this fails the constructur will C<< die() >>.
The constructor will creeate a uniq branch tag for this leg.
=back
=head1 METHODS
=over 4
=item forward_incoming ( PACKET )
Modifies the L<Net::SIP::Packet> PACKET in-place for forwarding, e.g
strips top B<Via> header in responses, adds B<received> parameter to
top B<Via> header in requests, handles the difference between forwarding
of requests to strict or loose routes and inserts B<Record-Route>
header in requests.
=item forward_outgoing ( PACKET, LEG_IN )
Similar to B<forward_incoming>, but will be called on the outgoing
leg. LEG_IN is the L<Net::SIP::Leg>, where the packet came in (and where
B<forward_incoming> was called). Will add B<Record-Route> header and
remove itself from B<Route>.
=item deliver ( PACKET, ADDR, [ CALLBACK ] )
Delivers L<Net::SIP::Packet> PACKET through the leg C<$self> to ADDR, which
is C<< "ip:port" >>.
Usually this method will be call from within L<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 B<invoke_callback> in L<Net::SIP::Util> for
the format of callbacks. If the packet could not be delivered CALLBACK
will be invoked with the appropriate errno (C<$!>).
While delivering requests it adds a B<Via> header.
=item receive
Reads a packet from the socket and returns the L<Net::SIP::Packet> PACKET
and the senders ADDR as C<< "ip:port" >>. If reading failed will return C<()>.
=item check_via ( PACKET )
Returns TRUE if the top B<Via> header in the L<Net::SIP::Packet> PACKET contains
the B<branch>-tag from C<$self>, otherwise FALSE. Used to check if the response
came in through the same leg the response was send.
=item 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. C<udp:host> )
and postfixed by the port ( C<host:port>, C<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.
=item 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
B<receive> from L<Net::SIP::Dispatcher> yourself, because it cannot be
called automatically once it receives data on the socket.
=item dump
Returns string containing information about the leg.
Used for debugging.
=back
|
