.\" 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::Context 3pm"
.TH Net::SIP::Endpoint::Context 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::Context \- Call context for endpoint
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  my $ctx = Net::SIP::Endpoint::Context\->new( to => .., from => .. );
\&  my $request = $ctx\->new_request(..);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package manages the call context (from,to,call\-id, recorded routes..) for
a call to an Net::SIP::Endpoint. It maintains the state of the current
call (local and remote cseq, current state within \s-1INVITE\s0 transaction)
and handles requests and responses according to this state.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new ( \s-1ARGS\s0 )" 4
.IX Item "new ( ARGS )"
\&\s-1ARGS\s0 is either a hash reference or a hash.
It contains the following mandatory keys:
.RS 4
.IP "from" 8
.IX Item "from"
Initiator of call. This is the local address for outgoing calls
and the peers address for incoming calls.
.IP "to" 8
.IX Item "to"
Target of call.
.RE
.RS 4
.Sp
And the following optional keys:
.IP "contact" 8
.IX Item "contact"
Contact info for context.
.IP "incoming" 8
.IX Item "incoming"
Flag, if the context resulted from an incoming call.
.IP "auth" 8
.IX Item "auth"
Authorization info, used if outgoing requests need authorization.
See method \fBauthorize\fR in Net::SIP::Request
for information on the format.
.IP "route" 8
.IX Item "route"
\&\e@List of predefined routes (which will be used to create \fBRoute\fR \s-1SIP\s0
header in requests).
.IP "via" 8
.IX Item "via"
\&\e@List of predefined \fBVia\fR values used in locally generated responses.
This is usually set if the context was created by an incoming request
from the \fBVia\fR header in the request.
.IP "callid" 8
.IX Item "callid"
Value of \fBCall-Id\fR header. If not given it will be generated.
It's usually given for incoming calls, but not for outgoing calls.
.IP "cseq" 8
.IX Item "cseq"
Initial local sequence number for the \fBCSeq\fR \s-1SIP\s0 header.
Defaults to 0, e.g. the first request will get the sequence number 1.
.RE
.RS 4
.RE
.SH "METHODS"
.IX Header "METHODS"
.IP "callid" 4
.IX Item "callid"
Returns callid of current call.
.IP "peer" 4
.IX Item "peer"
Returns peer of call. For incoming calls this is the sender, for
outgoing calls the recipient of the call.
.ie n .IP "new_request ( \s-1METHOD,\s0 [ \s-1BODY,\s0 %ARGS ] )" 4
.el .IP "new_request ( \s-1METHOD,\s0 [ \s-1BODY,\s0 \f(CW%ARGS\fR ] )" 4
.IX Item "new_request ( METHOD, [ BODY, %ARGS ] )"
Creates a new requests for method \s-1METHOD\s0 with body \s-1BODY\s0 and additional
\&\s-1SIP\s0 headers defined by \f(CW%ARGS\fR. The headers for \f(CW\*(C`to\*(C'\fR, \f(CW\*(C`from\*(C'\fR, \f(CW\*(C`contact\*(C'\fR,
\&\f(CW\*(C`route\*(C'\fR will be created from the call context info in \f(CW$self\fR.
.Sp
One special \s-1ARGS\s0 can be \fBresp40x\fR which should point to a 401/407 \s-1SIP\s0 
response containing the offer from the server for authorization. This way
authorization can be fully controlled, e.g. first trying w/o authorization
and then retrying with authorization credentials and the 40x response.
.Sp
\&\s-1METHOD\s0 might be already a Net::SIP::Request object in which case it
will be used unmodified. \s-1BODY\s0 might be a string or object (see constructor
of Net::SIP::Request).
.Sp
It will add the request to the list of active transactions within the
context \f(CW$self\fR, e.g. will be prepared to get responses for it.
The callback for the transaction is copied from the default callback
for the context, so that it stays the same, even if the default callback
changes.
.Sp
It returns the created request object.
.ie n .IP "find_outstanding_requests ( %FILTER )" 4
.el .IP "find_outstanding_requests ( \f(CW%FILTER\fR )" 4
.IX Item "find_outstanding_requests ( %FILTER )"
Returns list of outstanding requests (e.g \s-1INVITE\s0 w/o reply) for this
context. Returns a list of outstanding request (Net::SIP::Request
objects) with the most recent requests first.
.Sp
\&\s-1FILTER\s0 might be used to restrict the search. With key \fBrequest\fR a
Net::SIP::Request object is expected and it will restrict the search to
this object (e.g. it will return the object if it is outstanding). With key
\&\fBmethod\fR a method can be specified and only requests with this method will
be returned.
.IP "set_callback ( \s-1CALLBACK\s0 )" 4
.IX Item "set_callback ( CALLBACK )"
Sets callback for context, which will be used if the upper layer need to
be notified, e.g on incoming requests or an permanent delivery errors.
\&\s-1CALLBACK\s0 is a callback usable by \fBinvoke_callback\fR in Net::SIP::Util and will be
invoked with the following arguments (some arguments make only sense for
incoming packets).
.RS 4
.IP "\s-1CTX\s0" 8
.IX Item "CTX"
The call context, e.g. \f(CW$self\fR.
.IP "\s-1ENDPOINT\s0" 8
.IX Item "ENDPOINT"
The Net::SIP::Endpoint object managing \s-1CTX.\s0
.IP "\s-1ERROR\s0" 8
.IX Item "ERROR"
The errno of the error occurred ( undef or 0 if no error ).
These are the same numbers defined in Errno, but they are
usually not set by a system call, but by the dispatcher
(like \s-1ETIMEDOUT\s0 if delivery failed permanently after none of
the retransmits succeeded or \s-1EHOSTUNREACH\s0 if it cannot resolve
the \s-1SIP URI\s0).
.IP "\s-1CODE\s0" 8
.IX Item "CODE"
This is the response \s-1CODE\s0 from an incoming response packet.
Undef if the incoming packet was no response.
.IP "\s-1PACKET\s0" 8
.IX Item "PACKET"
This is the packet which caused the callback. Only for incoming
packets.
.IP "\s-1LEG\s0" 8
.IX Item "LEG"
Net::SIP::Leg where the packet came in.
.IP "\s-1FROM\s0" 8
.IX Item "FROM"
\&\f(CW"ip:port"\fR of sender of incoming packet.
.RE
.RS 4
.RE
.IP "request_delivery_done ( \s-1ENDPOINT, TID, ERROR\s0 )" 4
.IX Item "request_delivery_done ( ENDPOINT, TID, ERROR )"
Callback setup at delivery of the packet and called with
\&\s-1ERROR FALSE\s0 if the packet was delivered successfully over
a reliable transport or with \s-1ERROR\s0 an errno if the packet
could not be delivered (or no reply came in for packet, so
one can assume that the recipient did not get it).
.Sp
For details on \s-1ERROR\s0 see \fBset_callback\fR.
.Sp
\&\s-1TID\s0 is the transaction \s-1ID,\s0 see method \fBtid\fR in Net::SIP::Packet.
\&\s-1ENDPOINT\s0 is the endpoint managing the context \f(CW$self\fR.
.IP "handle_response ( \s-1RESPONSE,LEG,FROM,ENDPOINT\s0 )" 4
.IX Item "handle_response ( RESPONSE,LEG,FROM,ENDPOINT )"
Called from the endpoints \fBreceive_response\fR method it handles
responses to requests originated from the context \f(CW$self\fR.
.Sp
\&\s-1RESPONSE\s0 is the response packet, \s-1LEG\s0 the leg where the packet
came in and \s-1FROM\s0 the \f(CW"ip:port"\fR of the sender. \s-1ENDPOINT\s0
is the endpoint managing the context \f(CW$self\fR.
.Sp
First it checks if the response matches an active transaction
(which begun its life in \fBnew_request\fR) and if not it drops
the response.
.Sp
Then it checks if the response came in to the right leg, e.g. if
the \fBVia\fR header of the packet matches the \fBVia\fR header
the leg creates. If not the packet will be dropped.
.Sp
Then it checks if the method in the \fBCSeq\fR header of the response
matches the expected method in the transaction (for INVITEs this
could be either \s-1INVITE\s0 or \s-1ACK,\s0 depending on the state of the
transaction). If it not matches the packet will be dropped.
(All of these packet drops could be observed if you enable
debugging, see Net::SIP::Debug.
.Sp
If the response is for a \s-1BYE\s0 or \s-1CANCEL\s0 request the call
will be closed.
.Sp
If the response is the unsuccessful final response for an
\&\s-1INVITE\s0 an \s-1ACK\s0 will be send, if it's preliminary response
it will invoke the callback for the transaction.
.Sp
If the response is a successful final response for an \s-1INVITE\s0
it will save the routes from the \fBRecord-Route\fR header for
future requests and create an \s-1ACK\s0 request. The transaction
callback will be invoked and gets as an additional argument
the created \s-1ACK\s0 request, which then can be modified by the
callback. The callback should not send the \s-1ACK\s0 request by
itself, it should just modify the given request and sending
will be done after the callback returned.
.Sp
If the response is a successful final response to a request
other then \s-1INVITE\s0 it will invoke callback which should fully
handle the response.
.Sp
If the response code is 401 (Unauthorized) or
407 (Proxy Authentication Required) and if the context has
authorization info (key \fBauth\fR in the constructor)) it
will try to authorize the request based on the realms
given in the response and if it can find authorization info
for at least parts of the required realms it will
redeliver the request. Otherwise it will invoke the callback
with an error of \s-1EPERM.\s0
.Sp
If the response code is 300 (Multiple Choices) or 301
(moved permanently) it will invoke the callback because
it cannot resolve the issue automatically.
But if it's 302 (Moved Temporarily) it will rewrite the
request based on the \fBContact\fR header in the response
and redeliver it automatically.
.Sp
If the response is 305 (Use Proxy) it will take the information
from \fBContact\fR as the upstream proxy and insert it into
the routes, so that it will use it as the next hop.
Then it rewrites the request for the new routes and redelivers it.
.Sp
For all other responses the callback will be invoked, e.g
the issue has to be resolved by the users application.
.IP "handle_request ( \s-1REQUEST,LEG,FROM,ENDPOINT\s0 )" 4
.IX Item "handle_request ( REQUEST,LEG,FROM,ENDPOINT )"
Called from the endpoints \fBreceive_request\fR method it handles
incoming requests for call context \f(CW$self\fR.
.Sp
\&\s-1REQUEST\s0 is the request packet, \s-1LEG\s0 the leg where the packet
came in and \s-1FROM\s0 the \f(CW"ip:port"\fR of the sender. \s-1ENDPOINT\s0
is the endpoint managing the context \f(CW$self\fR.
.Sp
First it checks if the sequence number of the incoming
request (\fBCSeq\fR header) is not lower then the sequence
number of the last request received. Otherwise it will drop
the request.
.Sp
The it checks if the sequence number is the same as for the
last request. If it is higher it must be a new request, otherwise
it is a retransmit or an \s-1ACK\s0 or \s-1CANCEL\s0 to an \s-1INVITE\s0 request.
If it's a retransmit it will be dropped.
.Sp
If the incoming request is an \s-1INVITE\s0 it will automatically
deliver a response \f(CW\*(C`100 Trying\*(C'\fR and then invoke the
callback, so that the application might issue \f(CW\*(C`180 Ringing\*(C'\fR
responses and finally a final response, like \f(CW\*(C`200 Ok\*(C'\fR.
.Sp
If the incoming request is \s-1CANCEL\s0 or \s-1BYE\s0 it will issue a
response \f(CW\*(C`200 Closing\*(C'\fR and close the context.
.Sp
All other requests must be handled by the application, e.g.
the callback will be invoked.