NAME¶
Net::SIP::Endpoint - Endpoint for SIP packets (UAC,UAS)
SYNOPSIS¶
my $disp = Net::SIP::Dispatcher->new(...);
my $ua = Net::SIP::Endpoint->new($disp);
$ua->register(
from => 'sip:me@example.com',
contact => 'sip:me@192.168.0.1',
registrar => '192.168.0.10:5060'
);
DESCRIPTION¶
The package implements a communication endpoint for SIP. This is usually a
phone, but can also be a stateful proxy (because it retransmits packets
itself).
It provides methods to send arbitrary requests but also for sending special
requests like INVITE or REGISTER. Together with Net::SIP::Endpoint::Context it
implements the behavior of the endpoint.
For incoming requests the endpoint usually communicates with the upper layer,
the application, which is the interface to the user (e.g. let it ring for
incoming calls, create response for call accepted if user picks up phone on
incoming call etc).
CONSTRUCTOR¶
- new ( DISPATCHER )
- Creates a new endpoint and sets it as the receiver for
incoming packets at the Net::SIP::Dispatcher DISPATCHER. The endpoint will
use DISPATCHER for outgoing packets and will receive incoming packets from
it.
METHODS¶
- set_application ( APP )
- Sets APP as the upper layer, e.g. the layer between the
user and the endpoint object $self. APP is either an object which has a
method receive or a callback usable by invoke_callback in
Net::SIP::Util.
The callback will be invoked with the following arguments:
- ENDPOINT
- This is the endpoint itself, e.g. $self.
- CTX
- The Net::SIP::Endpoint::Context object for the current
call.
- REQUEST
- The Net::SIP::Request which caused the invocation of the
call, e.g. an INVITE on new calls, ACK if the peer established the call,
BYE if a call gets closed by the peer etc.
- LEG
- The Net::SIP::Leg object where the call came in. Together
with FROM used to send response packet back to peer.
- FROM
- "ip:port" of the sender of the request.
It will call into APP in various incoming requests, like:
- INVITE
- In this case APP should ring the user and while ringing
send "180 Ringing" responses back to the peer, using
"ENDPOINT->new_response". After some time it should send a
final response (like "200 Ok" if the user accepted the
call).
- ACK
- This is the sign, that the peer established the call. APP
should now expect to process incoming RTP data and send RTP data
itself.
- CANCEL, BYE
- This informs APP, that the call is closed. No need for the
APP to send a response itself, this was already handled by the endpoint
(because there is no choice of responses, it can hardly not accept a
BYE).
- other requests
- Like OPTION,.. . Theseneed to be fully handled by APP, e.g.
send the appropriate response back using
"ENDPOINT->new_response".
- invite ( CTX, [ CALLBACK, BODY, %ARGS ] )
- Creates a new INVITE request and delivers it to the peer.
Simply calls new_request with the method 'INVITE'. See this method
for information for the arguments.
- register ( %ARGS )
- Registers endpoint at remote registrar. %ARGS needs to be
filled as follows:
- registrar
- "ip:port" of registrar. Mandatory.
- from
- The address to register at the registrar. Mandatory.
- contact
- The contact, under which "from" will be
registered. Mandatory.
- auth
- Authorization info, see method authorize in
Net::SIP::Request for information about the format. Optional.
- expires
- Expires time. Optional, defaults to 900.
- callback
- Optional callback, e.g. called if requests come in from the
peer on the call created for the registration. See invoke_callback
in Net::SIP::Util for the format.
All other keys will be used as header keys in generating the Net::SIP::Request
object.
- new_request ( METHOD, CTX, [ CALLBACK, BODY, %ARGS ] )
- Method is the uppercase name of the method for which a
request should be generated. It can also be already a Net::SIP::Request
object in which case no new request object will be generated, but the
provided delivered.
CTX is either an existing Net::SIP::Endpoint::Context object or a hash
reference which will be used to construct one. It contains information
about "from" and "to" etc. See constructor in
Net::SIP::Endpoint::Context for details. In case of a hash reference
auth and callid from ARGS will be used for the newly
constructed context.
If it is an existing CTX it has to be one which is already managed by this
endpoint (e.g. one returned by this method), the endpoint will only manage
CTX which it created itself so that a context cannot be shared between
multiple endpoints.
CALLBACK is a callback usable by invoke_callback in Net::SIP::Util.
If defined it will be set up as the new default callback for the context.
BODY is a string or an object for the SIP body accepted by the constructor
of Net::SIP::Request. See there.
If a response object is given as resp40x in ARGS it will be used to
authorize the newly created request.
Anything else in %ARGS will be used to construct the SIP header. See
constructor in Net::SIP::Request.
It returns the Net::SIP::Endpoint::Context object for this request which can
be then used for further requests in the same call.
- cancel_invite ( CTX, REQUEST, CALLBACK )
- Cancel the given request within the given context (e.g send
CANCEL request). If no REQUEST is given it will cancel the most recent
INVITE. Returns the number of requests canceled, e.g. 0 or 1.
CALLBACK will be used as the callback for the CANCEL request it sends using
new_request.
- close_context ( CTX )
- Delete Net::SIP::Endpoint::Context object CTX from the list
of active calls.
- receive ( PACKET, LEG, FROM )
- Called from dispatcher on incoming packets.
PACKET is the incoming Net::SIP::Packet, LEG the Net::SIP::Leg where the
packet came in and FROM the "ip:port" of the sender.
Just forwards to receive_request or receive_response based on
the type of packet.
- receive_response ( RESPONSE, LEG, FROM )
- Handles incoming response packets. Tries to find an active
call based on the "Call-Id" header in the packet. If none was
found it will drop the packet, otherwise call handle_response on
the call context object (Net::SIP::Endpoint::Context).
- receive_request ( REQUEST, LEG, FROM )
- Handles incoming requests.
If there is already a call context for this Call-Id in the request it
will use it, otherwise it will create a Net::SIP::Endpoint::Context object
based on the information in the request ("from", "to",
"contact",... ).
Calls handle_request on the existing/new context object.
- new_response ( CTX, RESPONSE, LEG, ADDR )
- Delivers Net::SIP::Response packet RESPONSE through the
endpoints dispatcher to ADDR ("ip:port") using Net::SIP::Leg
LEG. LEG and ADDR are usually the leg and the senders address where the
associated request came in.
CTX is the context from the call, where the associated request came in.
If the response is a 2xx response to a INVITE and no "contact"
header is given as required from the RFC it will add one based on the
CTX.