1
2=head1 NAME
3
4Net::SIP::Simple - Simple interface for using Net::SIP
5
6=head1 SYNOPSIS
7
8  use Net::SIP;
9
10  # create new agent
11  my $ua = Net::SIP::Simple->new(
12	outgoing_proxy => '192.168.0.10',
13	registrar => '192.168.0.10',
14	domain => 'example.com',
15	from => 'me',
16	auth => [ 'me','secret' ],
17  );
18
19  # Register agent
20  $ua->register;
21
22  # Invite other party, send announcement once connected
23  my $call = $ua->invite( 'you',
24	init_media => $ua->rtp( 'send_recv', 'announcement.pcmu-8000' ),
25	asymetric_rtp => 1,
26  );
27
28  # Mainloop
29  $ua->loop;
30
31=head1 DESCRIPTION
32
33This package implements a simple layer on top of L<Net::SIP::Endpoint>,
34L<Net::SIP::Registrar> and L<Net::SIP::StatelessProxy>.
35With the help of this package it is possible to write simple SIP applications
36with a few lines perl code.
37
38=head1 CONSTRUCTOR
39
40=over 4
41
42=item new ( %ARGS )
43
44Creates new Net::SIP::Simple object.
45
46It will return the new object for further operations, but the object itself will
47contain back references to itself in the form of callbacks into the eventloop
48and dispatcher.  This means that that object will not self-destroy, but you need
49to call B<cleanup> if you want it to go away.
50
51%ARGS can be:
52
53=over 8
54
55=item outgoing_proxy|proxy
56
57C<< "ip:port" >> of outgoing proxy. The necessary L<Net::SIP::Leg> to
58the proxy will be created if no leg exists.
59
60=item registrar
61
62C<< "ip:port" >> of registrar. Used in method B<register> if there is no
63other registrar given.
64
65=item legs|leg
66
67\@List of legs or single leg. Leg can be an existing L<Net::SIP::Leg> (or derived)
68object, an L<IO::Handle> (existing socket), a hash reference which can be used
69in the constructor of L<Net::SIP::Leg> or a string of C<< "proto:ip:port" >>.
70In the latter case C<proto> can be omitted (including the colon) and defaults
71to 'udp' and C<port> can be omitted to (including the colon) defaulting to 5060.
72
73Either B<legs> or B<outgoing_proxy> has to be provided, e.g. it needs at least one
74leg.
75
76=item auth
77
78Authorization data, see method B<authorize> in L<Net::SIP::Request> for details
79about the format.
80
81=item domain
82
83Default domain for not fully qualified SIP addresses in C<from> and C<to> (method
84B<invite>).
85
86=item from
87
88SIP address of local sender, either full SIP address or only part before \@, in which
89case B<domain> has to be provided.
90
91=item contact
92
93SIP address of local sender, which should be used in the contact header of REGISTER
94and INVITE requests. If not given B<from> will be used.
95
96=item options
97
98This is a hash reference containing headers (header-key,value) for replies to an
99OPTIONS request. If not or only partly given defaults will be used for the headers
100B<Allow>, B<Accept>, B<Accept-Encoding>, B<Accept-Language> and B<Supported>.
101
102=item route
103
104Optional list of SIP routes which will be added to route requests.
105
106=item loop
107
108Eventloop object for dispatcher, see L<Net::SIP::Dispatcher::Eventloop>. Usually
109not given, because the loop from the dispatcher will be used, but can be given
110if no dispatcher was given.
111
112=item dispatcher
113
114L<Net::SIP::Dispatcher> object. Usually not given and will be created, but
115sometimes one need to share the same dispatcher between multiple L<Net::SIP::Simple>
116objects.
117
118=item domain2proxy|d2p
119
120Hash with mapping between domain and upstream proxy. See same key in the constructor
121of L<Net::SIP::Dispatcher> for more details.
122
123=item tls
124
125Common TLS settings for all legs which will be created by this object. See
126C<new> in L<Net::SIP::Leg> for more details.
127
128=back
129
130=back
131
132=head1 METHODS
133
134=over 4
135
136=item cleanup
137
138Cleans up object, removes legs it added from the dispatcher.
139Needs to be called if you want to destroy the object, because it will not
140self-destroy (see B<new>).
141
142=item error ( ERROR )
143
144Either sets current error (used internally) or returns last error.
145
146=item loop ( [ TIMEOUT, @STOPVAR ] )
147
148Calls the event loops (key B<loop> in constructor> B<loop> method.
149TIMEOUT is the timeout for the loop in seconds. If not given it will
150not stop because of timeout. @STOPVAR is a list of scalar references,
151will stop the loop if any of these references contains TRUE.
152See method B<loop> in L<Net::SIP::Dispatcher::Eventloop> for more
153details.
154
155The order of TIMEOUT or the STOPVARs is insignificant, e.g. if it
156finds a reference it will use it as stopvar, otherwise it's used as
157timeout.
158
159=item add_timer ( WHEN, CALLBACK, [ REPEAT ] )
160
161Calls same method from the L<Net::SIP::Dispatcher> object in C<$self>.
162See there for details on arguments.
163
164=item rtp ( METHOD,@ARGS )
165
166Calls the method METHOD in L<Net::SIP::Simple::RTP> with arguments
167@ARGS. Currently only does this and thus works as a shortcut.
168In the future one might add more ways to find the right method
169for RTP handling (e.g. plugins or similar).
170
171=item register ( %ARGS )
172
173Registers the user agent. %ARGS can have the key B<registrar> which
174has precedence over the same key in the constructor.
175B<leg> specifies the leg where the register request will be send through.
176If not given it will pick the right leg.
177
178If B<cb_final> is specified it is a callback usable by B<invoke_callback>
179in L<Net::SIP::Util> which will be called, once the registration is
180completed (e.g. it succeeded or failed). If no B<cb_final> is specified
181the method will wait, until the registration is completed and return
182either the expires time given by the registrar or C<()> if registration
183failed.
184
185All other keys, like B<contact>, B<expires>, B<resp40x>, B<auth>
186will be forwarded to method B<register> in L<Net::SIP::Endpoint>.
187B<from> and B<auth> will be used from %ARGS or if not in %ARGS from
188the constructor.
189
190=item invite ( CTX,%ARGS )
191
192Creates a new call and invites peer.
193Creates a new L<Net::SIP::Simple::Call> object with context CTX
194and creates an INVITE request for this call using %ARGS.
195See B<reinvite> in L<Net::SIP::Simple::Call> for more info on %ARGS.
196
197CTX can be address of peer or context hash containing the address.
198
199Returns with the newly created L<Net::SIP::Simple::Call> object,
200which can later be used for reINVITEs or BYE etc.
201
202Note that in order to have any callbacks triggered by the invite working
203one needs to keep the returned caller object.
204
205=item listen ( %ARGS )
206
207Sets up waiting on all legs in C<$self> for incoming calls, e.g. new INVITE
208requests. All other incoming packets will be dropped.
209If a call comes in a new L<Net::SIP::Simple::Call> object will
210be created using %ARGS.
211
212The method does not wait for the calls, its setting only the callback
213on the legs up. Thus it has to be followed by a call to B<loop>.
214
215If %ARGS contain C<auth_*> keys an Authorizer will be added before the listener.
216See L<Net::SIP::Authorize> for the keys, e.g. C<auth_user2pass> will be
217forwarded as C<user2pass> etc to the authorizer.
218
219Special keys not described in L<Net::SIP::Simple::Call>:
220
221The returned object can be used together with other objects
222within C<create_chain>, but it should be used as the last object.
223
224=over 8
225
226=item filter
227
228A callback usable by B<invoke_callback> in L<Net::SIP::Util> which gets
229called with the value of the B<From> header and the L<Net::SIP::Request>
230object from the incoming request.
231If the callback returns TRUE the call gets accepted, otherwise not.
232
233=item cb_create
234
235Callback which will be called on accepting the call. Will be called
236with C<< CALL,REQUEST,LEG,FROM >> where CALL is the newly created
237L<Net::SIP::Simple::Call> object, REQUEST the creating L<Net::SIP::Request>
238packet, LEG the incoming leg and FROM the C<< "ip:port" >> of the sender.
239
240Must return TRUE or the call gets not answered.
241
242=item cb_established
243
244Callback which will be called, after the call is established, e.g.
245after receiving the ACK from the peer. Will be invoked with 'OK'
246and the L<Net::SIP::Simple::Call> object as argument.
247
248=item cb_cleanup
249
250Callback which will be called when the call gets closed to clean up
251allocated resources. Will be invoked with the  L<Net::SIP::Simple::Call>
252object as argument.
253
254=back
255
256=item create_auth ( %ARGS )
257
258Sets up authorization.
259See L<Net::SIP::Authorize> for the meaning of %ARGS.
260The returned object should be used together with other objects
261within C<create_chain>.
262
263=item create_registrar ( %ARGS )
264
265Sets up a simple registrar using L<Net::SIP::Registrar>.
266See there for the meaning of %ARGS.
267
268Like with B<listen> you need to B<loop> after calling this
269method, the method itself will not wait.
270
271Like with B<listen> authorization can be added uses C<auth_*> keys.
272
273=item create_stateless_proxy ( %ARGS )
274
275Sets up a simple proxy using L<Net::SIP::StatelessProxy>.
276See there for the meaning of %ARGS.
277
278Like with B<listen> you need to B<loop> after calling this
279method, the method itself will not wait.
280
281Like with B<listen> authorization can be added uses C<auth_*> keys.
282
283=item create_chain ( OBJECTS, %ARGS )
284
285Sets up a chain using L<Net::SIP::ReceiveChain>.
286See there for the meaning of OBJECT and %ARGS.
287
288Like with B<listen> you need to B<loop> after calling this
289method, the method itself will not wait.
290
291=back
292