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