.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::SIP::Endpoint 3pm"
.TH Net::SIP::Endpoint 3pm "2023-09-29" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::SIP::Endpoint \- Endpoint for SIP packets (UAC,UAS)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&  my $disp = Net::SIP::Dispatcher\->new(...);
\&  my $ua = Net::SIP::Endpoint\->new($disp);
\&  $ua\->register(
\&        from => \*(Aqsip:me@example.com\*(Aq,
\&        contact => \*(Aqsip:me@192.168.0.1\*(Aq,
\&        registrar => \*(Aqsip:192.168.0.10:5060\*(Aq
\&  );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The package implements a communication endpoint for \s-1SIP.\s0
This is usually a phone, but can also be a stateful proxy (because
it retransmits packets itself).
.PP
It provides methods to send arbitrary requests but also for sending
special requests like \s-1INVITE\s0 or \s-1REGISTER.\s0 Together with
Net::SIP::Endpoint::Context it implements the behavior of
the endpoint.
.PP
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).
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new ( \s-1DISPATCHER\s0 )" 4
.IX Item "new ( DISPATCHER )"
Creates a new endpoint and sets it as the receiver for incoming
packets at the Net::SIP::Dispatcher \s-1DISPATCHER.\s0 The endpoint
will use \s-1DISPATCHER\s0 for outgoing packets and will receive
incoming packets from it.
.SH "METHODS"
.IX Header "METHODS"
.IP "set_application ( \s-1APP\s0 )" 4
.IX Item "set_application ( APP )"
Sets \s-1APP\s0 as the upper layer, e.g. the layer between the user
and the endpoint object \f(CW$self\fR. \s-1APP\s0 is either an object which has
a method \fBreceive\fR or a callback usable by \fBinvoke_callback\fR
in Net::SIP::Util.
.Sp
The callback will be invoked with the following arguments:
.RS 4
.IP "\s-1ENDPOINT\s0" 8
.IX Item "ENDPOINT"
This is the endpoint itself, e.g. \f(CW$self\fR.
.IP "\s-1CTX\s0" 8
.IX Item "CTX"
The Net::SIP::Endpoint::Context object for the current call.
.IP "\s-1REQUEST\s0" 8
.IX Item "REQUEST"
The Net::SIP::Request which caused the invocation of the call,
e.g. an \s-1INVITE\s0 on new calls, \s-1ACK\s0 if the peer established the call,
\&\s-1BYE\s0 if a call gets closed by the peer etc.
.IP "\s-1LEG\s0" 8
.IX Item "LEG"
The Net::SIP::Leg object where the call came in. Together
with \s-1FROM\s0 used to send response packet back to peer.
.IP "\s-1FROM\s0" 8
.IX Item "FROM"
Hash with information about the sender of the request (keys \f(CW\*(C`proto\*(C'\fR, \f(CW\*(C`addr\*(C'\fR,
\&\f(CW\*(C`host\*(C'\fR, \f(CW\*(C`port\*(C'\fR and \f(CW\*(C`family\*(C'\fR)
.RE
.RS 4
.Sp
It will call into \s-1APP\s0 in various incoming requests, like:
.IP "\s-1INVITE\s0" 8
.IX Item "INVITE"
In this case \s-1APP\s0 should ring the user and while ringing send
\&\f(CW\*(C`180 Ringing\*(C'\fR responses back to the peer, using
\&\f(CW\*(C`ENDPOINT\->new_response\*(C'\fR. After some time it should
send a final response (like \f(CW\*(C`200 Ok\*(C'\fR if the user accepted
the call).
.IP "\s-1ACK\s0" 8
.IX Item "ACK"
This is the sign, that the peer established the call. \s-1APP\s0 should
now expect to process incoming \s-1RTP\s0 data and send \s-1RTP\s0 data itself.
.IP "\s-1CANCEL, BYE\s0" 8
.IX Item "CANCEL, BYE"
This informs \s-1APP,\s0 that the call is closed. No need for the
\&\s-1APP\s0 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 \s-1BYE\s0).
.IP "other requests" 8
.IX Item "other requests"
Like \s-1OPTION,.. .\s0
Theseneed to be fully handled by \s-1APP,\s0 e.g. send the appropriate
response back using \f(CW\*(C`ENDPOINT\->new_response\*(C'\fR.
.RE
.RS 4
.RE
.ie n .IP "invite ( \s-1CTX,\s0 [ \s-1CALLBACK, BODY,\s0 %ARGS ] )" 4
.el .IP "invite ( \s-1CTX,\s0 [ \s-1CALLBACK, BODY,\s0 \f(CW%ARGS\fR ] )" 4
.IX Item "invite ( CTX, [ CALLBACK, BODY, %ARGS ] )"
Creates a new \s-1INVITE\s0 request and delivers it to the peer.
Simply calls \fBnew_request\fR with the method '\s-1INVITE\s0'.
See this method for information for the arguments.
.ie n .IP "register ( %ARGS )" 4
.el .IP "register ( \f(CW%ARGS\fR )" 4
.IX Item "register ( %ARGS )"
Registers endpoint at remote registrar. \f(CW%ARGS\fR needs to
be filled as follows:
.RS 4
.IP "registrar" 8
.IX Item "registrar"
\&\s-1SIP URI\s0 of registrar, i.e. anything acceptable to \fBsip_uri2parts\fR from
Net::SIP::Util. Mandatory.
.IP "from" 8
.IX Item "from"
The address to register at the registrar. Mandatory.
.IP "contact" 8
.IX Item "contact"
The contact, under which \f(CW\*(C`from\*(C'\fR will be registered. Mandatory.
.IP "auth" 8
.IX Item "auth"
Authorization info, see method \fBauthorize\fR in Net::SIP::Request
for information about the format. Optional.
.IP "expires" 8
.IX Item "expires"
Expires time. Optional, defaults to 900.
.IP "callback" 8
.IX Item "callback"
Optional callback, e.g. called if requests come in from the
peer on the call created for the registration. See \fBinvoke_callback\fR
in Net::SIP::Util for the format.
.RE
.RS 4
.Sp
All other keys will be used as header keys in generating the
Net::SIP::Request object.
.RE
.ie n .IP "new_request ( \s-1METHOD, CTX,\s0 [ \s-1CALLBACK, BODY,\s0 %ARGS ] )" 4
.el .IP "new_request ( \s-1METHOD, CTX,\s0 [ \s-1CALLBACK, BODY,\s0 \f(CW%ARGS\fR ] )" 4
.IX Item "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.
.Sp
\&\s-1CTX\s0 is either an existing Net::SIP::Endpoint::Context object
or a hash reference which will be used to construct one. It contains
information about \f(CW\*(C`from\*(C'\fR and \f(CW\*(C`to\*(C'\fR etc. See
constructor in Net::SIP::Endpoint::Context for details.
In case of a hash reference \fBauth\fR and \fBcallid\fR from \s-1ARGS\s0 will be
used for the newly constructed context.
.Sp
If it is an existing \s-1CTX\s0 it has to be one which is already managed
by this endpoint (e.g. one returned by this method), the endpoint
will only manage \s-1CTX\s0 which it created itself so that a context
cannot be shared between multiple endpoints.
.Sp
\&\s-1CALLBACK\s0 is a callback usable by \fBinvoke_callback\fR in Net::SIP::Util.
If defined it will be set up as the new default callback for the
context.
.Sp
\&\s-1BODY\s0 is a string or an object for the \s-1SIP\s0 body accepted by the
constructor of Net::SIP::Request.  See there.
.Sp
If a response object is given as \fBresp40x\fR in \s-1ARGS\s0 it will be used to 
authorize the newly created request.
.Sp
Anything else in \f(CW%ARGS\fR will be used to construct the \s-1SIP\s0 header. See
constructor in Net::SIP::Request.
.Sp
It returns the Net::SIP::Endpoint::Context object for this
request which can be then used for further requests in the same
call.
.IP "cancel_invite ( \s-1CTX, REQUEST, CALLBACK\s0 )" 4
.IX Item "cancel_invite ( CTX, REQUEST, CALLBACK )"
Cancel the given request within the given context (e.g send \s-1CANCEL\s0 request).
If no \s-1REQUEST\s0 is given it will cancel the most recent \s-1INVITE.\s0 Returns the
number of requests canceled, e.g. 0 or 1.
.Sp
\&\s-1CALLBACK\s0 will be used as the callback for the \s-1CANCEL\s0 request it sends using
\&\fBnew_request\fR.
.IP "close_context ( \s-1CTX\s0 )" 4
.IX Item "close_context ( CTX )"
Delete Net::SIP::Endpoint::Context object \s-1CTX\s0 from the list
of active calls.
.IP "receive ( \s-1PACKET, LEG, FROM\s0 )" 4
.IX Item "receive ( PACKET, LEG, FROM )"
Called from dispatcher on incoming packets.
.Sp
\&\s-1PACKET\s0 is the incoming Net::SIP::Packet, \s-1LEG\s0 the Net::SIP::Leg
where the packet came in and \s-1FROM\s0 the hash with the sender info.
.Sp
Just forwards to \fBreceive_request\fR or \fBreceive_response\fR based
on the type of packet.
.IP "receive_response ( \s-1RESPONSE, LEG, FROM\s0 )" 4
.IX Item "receive_response ( RESPONSE, LEG, FROM )"
Handles incoming response packets. Tries to find an active call based
on the \f(CW\*(C`Call\-Id\*(C'\fR header in the packet. If none was found it
will drop the packet, otherwise call \fBhandle_response\fR on the
call context object (Net::SIP::Endpoint::Context).
.IP "receive_request ( \s-1REQUEST, LEG, FROM\s0 )" 4
.IX Item "receive_request ( REQUEST, LEG, FROM )"
Handles incoming requests.
.Sp
If there is already a call context for this \fBCall-Id\fR in the request
it will use it, otherwise it will create a Net::SIP::Endpoint::Context
object based on the information in the request (\f(CW\*(C`from\*(C'\fR, \f(CW\*(C`to\*(C'\fR, \f(CW\*(C`contact\*(C'\fR,... ).
.Sp
Calls \fBhandle_request\fR on the existing/new context object.
.IP "new_response ( \s-1CTX, RESPONSE, LEG, ADDR\s0 )" 4
.IX Item "new_response ( CTX, RESPONSE, LEG, ADDR )"
Delivers Net::SIP::Response packet \s-1RESPONSE\s0 through the endpoints
dispatcher to \s-1ADDR\s0 (hash) using Net::SIP::Leg \s-1LEG.
LEG\s0 and \s-1ADDR\s0 are usually the leg and the senders address where the
associated request came in.
.Sp
\&\s-1CTX\s0 is the context from the call, where the associated request came in.
.Sp
If the response is a 2xx response to a \s-1INVITE\s0 and no \f(CW\*(C`contact\*(C'\fR header
is given as required from the \s-1RFC\s0 it will add one based on the \s-1CTX.\s0