public interface SipSession
SipFactory.createRequest()
methods. The OutgoingSipRequest
returned by these methods belongs to
a new UAC SipSession. The SBB must attach to the SipSession's ActivityContextInterface
in
order to receive responses. After the request is sent, the SipSession lifecycle proceeds as follows:
If an error response arrives, the SipSession does not end. It may be reused to create another
initial request with the same call-id, tag etc. This is to support the case where a redirect response or
authentication response is received, so the SBB can easily create a new request with the same parameters
and any additional info required, and re-send. If the SBB really does want the SipSession to end at this
point, it must call invalidate()
.
If a successful final response (2xx) arrives, and the initial request was not a dialog-creating request,
then the SipSession activity ends automatically. Out of dialog requests are handled in this way, and the
SipSession activity represents a single SIP client transaction.
If the initial request was dialog-creating (currently INVITE and SUBSCRIBE), then the SipSession stays alive.
The SipSession now represents a "confirmed" SIP dialog between the UAC SBB and the peer UAS, and the SBB may create
and send more in-dialog requests using the SipSession, and will also receive in-dialog requests from the peer,
as long as the SBB stays attached.
When the SipSession sends or receives a request that ends the dialog (a BYE, or NOTIFY with the "Subsciption-State: terminated" header), the SipSession ends after the response to that request is sent or received. The RA will ensure that activites are ended even if the SBB does not process the request.
IncomingSipRequest
event
is fired on the SipSession activity.
If the UAS SBB sends an error (3xx-6xx) response, the SipSession activity ends automatically. If the request was not a dialog-creating request, the SipSession also ends when a 2xx response is sent. In this way it behaves like a SIP server transaction. For dialog-creating requests, sending a 2xx response means the SipSession activity stays alive and now represents a "confirmed" SIP dialog between the UAS SBB and the UAC peer. Similarly, sending a 101-199 response will create an "early" dialog, which transitions to "confirmed" when the 2xx response is sent. Now the SBB may create and send more in-dialog requests using the SipSession, and will also receive in-dialog requests from the peer, as long as the SBB stays attached.
When the SipSession sends or receives a request that ends the dialog (a BYE, or NOTIFY with the "Subsciption-State: terminated" header), the SipSession ends after the response to that request is sent or received. The RA will ensure that activites are ended even if the SBB does not process the request.
If the UAS SBB wishes to proxy the request, it must call IncomingSipRequest.getProxy()
before
generating a response itself. If the SBB generates it's own response, the RA assumes that the SBB is
behaving like a UAS (ie. the endpoint of a dialog) and will not allow the request to be proxied. An IllegalStateException
will be thrown if the UAS SBB attempts to obtain the proxy after it has already sent a dialog-creating response.
If a Proxy
is created, the SipSession continues in Proxy mode, explained below.
IncomingSipRequest.getProxy()
on the initial
request. If the initial request was not a dialog-creating request, the SipSession ends when the final
response is forwarded by the proxy. If the initial request was dialog-creating, the SipSession ends if
an error response is forwarded by the proxy. If a 2xx response is received for a dialog-creating request,
the SipSession represents the confirmed SIP dialog between the 2 SIP endpoints. The proxy SBB will then
receive all subsequent in-dialog requests from either endpoint, as long as it is attached to the SipSession
activity. In-dialog requests will be forwarded automatically (unless the SBB sends it's own response to an
in-dialog request - see the Proxy
documentation for details).
A proxy mode SipSession may not be used for initiating in-dialog requests (createRequest(String)
will throw
an \IllegalStateException
), since this is not the role of a proxy. A proxy may only forward requests
from the SIP endpoints, but can modify these requests as they pass through, or reject them.
As before, when a dialog-ending request is received from either party, the SipSession ends when the corresponding response is received.
invalidate()
. This just removes
the activity state from the SLEE and RA, it does not cause any SIP messages to be sent. If the RA
receives subsequent requests for an unknown SipSession, these will be automatically rejected with a
"481 (Call or Transaction Does Not Exist)" response.
Modifier and Type | Interface and Description |
---|---|
static class |
SipSession.State
Describes the state of a SipSession's underlying SIP dialog.
|
Modifier and Type | Method and Description |
---|---|
OutgoingSipRequest |
createForkedNotify(IncomingSipRequest notify)
Creates a new outgoing NOTIFY request and a new
SipSession , for forwarding forked
NOTIFY requests upstream. |
OutgoingSipRequest |
createRequest(IncomingSipRequest original)
Create a new request on this session, with all headers and content copied from
another request.
|
OutgoingSipRequest |
createRequest(String method) |
Object |
getAttribute(String name)
Returns the object bound to the specified attribute name in this session
|
Iterable<String> |
getAttributeNames()
Returns all attribute names that have been bound to objects in this session.
|
String |
getCallId() |
DialogID |
getDialogID()
Get this session's
DialogID |
String |
getId()
Returns a string containing the unique identifier assigned to this session.
|
SipRequest |
getInitialRequest()
Get the incoming or outgoing request that initiated this session.
|
Address |
getLocalParty() |
IncomingSipRequest |
getPendingIncomingRequest(long cseq)
Retrieve a pending incoming request received on this session.
|
Iterable<IncomingSipRequest> |
getPendingIncomingRequests()
Retrieve all pending incoming requests on this session.
|
OutgoingSipRequest |
getPendingOutgoingRequest(long cseq)
Retrieve a pending outgoing request sent on this session.
|
Iterable<OutgoingSipRequest> |
getPendingOutgoingRequests()
Retrieve all pending outgoing requests on this session.
|
Address |
getRemoteParty() |
SipSession.State |
getSessionState()
Retrieve the current state of the SipSession
|
SipFactory |
getSipFactory()
Get the
SipFactory that created this SipSession. |
void |
invalidate()
Ends this SipSession activity.
|
boolean |
isEndImmediately()
Returns the current value of this session's
endImmediately
flag. |
boolean |
isInviteTerminated() |
boolean |
isSubscriptionsTerminated() |
void |
removeAttribute(String name)
Removes the named object from this session.
|
void |
sendCancel()
Convenience method to send a CANCEL request for the current outgoing INVITE request
on this session.
|
void |
sendCancel(Parameterable... headers)
Convenience method to send a CANCEL request for the current outgoing INVITE request
on this session, with the given Reason headers.
|
void |
sendCancel(SipRequest cancel)
Convenience method to send a CANCEL request for the current outgoing INVITE request
on this session, copying any Reason headers from another CANCEL.
|
void |
setAttribute(String name,
Object value)
Binds an object to an attribute name in this session
|
void |
setEndImmediately(boolean endImmediately)
Specify whether this session activity will end immediately after a dialog-ending
message is sent or received (e.g.
|
void |
setLocalContactAddress(Address address)
Enforces the policy where specified local Contact header is used for all outgoing responses and requests.
|
void |
startReplicating()
Instructs the SIS to begin replicating this session's state.
|
String getId()
void invalidate()
IllegalStateException
.String getCallId()
Address getLocalParty()
Address getRemoteParty()
OutgoingSipRequest createRequest(String method)
OutgoingSipRequest createRequest(IncomingSipRequest original)
original
- the original request, will usually have been received on a different SipSession.OutgoingSipRequest createForkedNotify(IncomingSipRequest notify)
SipSession
, for forwarding forked
NOTIFY requests upstream.
This is a convenience method so that B2BUAs handling several UAC SipSessions created by a
downstream element forking an initial SUBSCRIBE can easily create the corresponding UAS SipSessions.
The new forked UAS session can be obtained by calling SipMessage.getSession()
on the
returned OutgoingSipRequest
.
The caller sends the new NOTIFY upstream by calling its OutgoingSipRequest.send()
method.
notify
- a forked
NOTIFY request received on a UAC SipSessionOutgoingSipRequest
copied from the incoming request, but with the relevant
headers set from the dialog state of the new SipSession
. The Call-Id and remote tag will
are copied from the UAS SipSession that was created by the initial SUBSCRIBE, and the local tag will be
taken from the from-tag of the incoming NOTIFY.IllegalArgumentException
- if the request was not a forked NOTIFY request, see
IncomingSipRequest.isForked()
SipRequest getInitialRequest()
SipFactory getSipFactory()
SipFactory
that created this SipSession.void sendCancel() throws SipException
SipException
- if unable to create the cancel requestvoid sendCancel(SipRequest cancel) throws SipException
cancel
- a CANCEL request that triggered sending a CANCEL on this session.
Any Reason headers from this CANCEL are copied to the outgoing CANCEL.SipException
- if unable to create the cancel requestvoid sendCancel(Parameterable... headers) throws SipException
headers
- zero or more Parameterable
values that will be added to
the outgoing CANCEL as Reason headers.SipException
- if unable to create the cancel requestvoid setAttribute(String name, Object value)
name
- a string specifying the name of the object, may not be null
value
- the object to be boundNullPointerException
- if name or value are null
Object getAttribute(String name)
name
- the attribute name, may not be null
null
if there is no object with that nameNullPointerException
- if name is null
void removeAttribute(String name)
name
- the attribute name, may not be null
NullPointerException
- if name is null
Iterable<String> getAttributeNames()
void setEndImmediately(boolean endImmediately)
true
.
If set to false
, the application must end the session explicitly using
invalidate()
. This gives the application a chance to keep using session
attributes before the activity is finally ended in the SLEE. If the application
does not call invalidate()
itself, the session activity will be ended
automatically by RA's next query-liveness processing, which occurs when the activity
has been idle for some time, typically 5 minutes.endImmediately
- set to false
to delay the automatic ending of this activity.boolean isEndImmediately()
endImmediately
flag.endImmediately
flagvoid setLocalContactAddress(Address address)
address
- local Contact addressIllegalStateException
- if attempted to be set after dialog creating response is sentNullPointerException
- if address is nullSipSession.State getSessionState()
SipSession.State
valueIncomingSipRequest getPendingIncomingRequest(long cseq)
cseq
- the sequence number of the request.IncomingSipRequest
, or null if no such
request was found.OutgoingSipRequest getPendingOutgoingRequest(long cseq)
cseq
- the sequence number of the request.OutgoingSipRequest
, or null if no such
request was found.Iterable<IncomingSipRequest> getPendingIncomingRequests()
IncomingSipRequests
, empty if there are
currently no pending requests.Iterable<OutgoingSipRequest> getPendingOutgoingRequests()
OutgoingSipRequests
, empty if there are
currently no pending requests.void startReplicating()
If replication is disabled in the SIS, or the session is already replicating, this method does nothing.
Otherwise if replication is enabled in the SIS, then this method instructs the SIS to begin replicating the session state.
boolean isInviteTerminated()
boolean isSubscriptionsTerminated()