|
NIST-SIP: The Reference Implementation for JAIN-SIP 1.2 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectgov.nist.javax.sip.stack.SIPDialog
public class SIPDialog
Tracks dialogs. A dialog is a peer to peer association of communicating SIP entities. For INVITE transactions, a Dialog is created when a success message is received (i.e. a response that has a To tag). The SIP Protocol stores enough state in the message structure to extract a dialog identifier that can be used to retrieve this structure from the SipStack.
Nested Class Summary | |
---|---|
class |
SIPDialog.ReInviteSender
This task waits till a pending ACK has been recorded and then sends out a re-INVITE. |
Field Summary | |
---|---|
long |
auditTag
|
static int |
CONFIRMED_STATE
|
static int |
EARLY_STATE
|
static int |
NULL_STATE
|
static int |
TERMINATED_STATE
|
Constructor Summary | |
---|---|
SIPDialog(SIPClientTransaction transaction,
SIPResponse sipResponse)
Constructor given a transaction and a response. |
|
SIPDialog(SipProviderImpl sipProvider,
SIPResponse sipResponse)
create a sip dialog with a response ( no tx) |
|
SIPDialog(SIPTransaction transaction)
Constructor given the first transaction. |
Method Summary | |
---|---|
void |
addRoute(SIPRequest sipRequest)
Add a Route list extracted from a SIPRequest to this Dialog. |
void |
addTransaction(SIPTransaction transaction)
Add a transaction record to the dialog. |
Request |
createAck(long cseqno)
Creates an ACK request for an Invite that was responded with 2xx response. |
static SIPDialog |
createFromNOTIFY(SIPClientTransaction subscribeTx,
SIPTransaction notifyST)
Creates a new dialog based on a received NOTIFY. |
Request |
createPrack(Response relResponse)
Creates a new PRACK Request message based on a reliable provisional response received by this Dialog and the Dialog internal information. |
Response |
createReliableProvisionalResponse(int statusCode)
Creates a new reliable provisional response based on an Invite request that created this Dialog or that is now refreshing this Dialog. |
Request |
createRequest(String method)
Creates a new Request message based on the dialog creating request. |
void |
delete()
This method will release all resources associated with this dialog that are tracked by the SipProvider. |
void |
doDeferredDelete()
This method is called when a forked dialog is created from the client side. |
boolean |
equals(Object obj)
Override for the equals method. |
Object |
getApplicationData()
Gets the application specific data specific to this dialog. |
CallIdHeader |
getCallId()
Returns the Call-Id for this dialog. |
String |
getDialogId()
Get the id for this dialog. |
Transaction |
getFirstTransaction()
Get the transaction that created this dialog. |
SIPServerTransaction |
getInviteTransaction()
Get the INVITE transaction (null if no invite transaction). |
SIPRequest |
getLastAck()
Get the last ACK for this transaction. |
SIPResponse |
getLastResponse()
|
SIPTransaction |
getLastTransaction()
Get the last transaction from the dialog. |
Address |
getLocalParty()
Returns the Address identifying the local party. |
long |
getLocalSeqNumber()
The local sequence number is used to order requests from this User Agent Client to its peer User Agent Server. |
int |
getLocalSequenceNumber()
Deprecated. |
String |
getLocalTag()
Get the Local Tag of this Dialog. |
String |
getMethod()
Get the method of the request/response that resulted in the creation of the Dialog. |
Contact |
getMyContactHeader()
Get the contact header that the owner of this dialog assigned. |
long |
getOriginalLocalSequenceNumber()
Get the sequence number for the request that origianlly created the Dialog. |
Address |
getRemoteParty()
Returns the Address identifying the remote party. |
long |
getRemoteSeqNumber()
The remote sequence number is used to order requests from its peer User Agent Client to this User Agent Server. |
int |
getRemoteSequenceNumber()
Deprecated. |
String |
getRemoteTag()
Gets the Remote Tag of this Dialog. |
Address |
getRemoteTarget()
Returns the Address identifying the remote target. |
Iterator |
getRouteSet()
Gets the route set for the dialog. |
SipProviderImpl |
getSipProvider()
Get the provider for this Dialog. |
DialogState |
getState()
Returns the current DialogState of the dialog or null. |
boolean |
handleAck(SIPServerTransaction ackTransaction)
Do the necessary processing to handle an ACK directed at this Dialog. |
boolean |
handlePrack(SIPRequest prackRequest)
Do the processing necessary for the PRACK |
void |
incrementLocalSequenceNumber()
Increment the local CSeq # for the dialog. |
boolean |
isAckSeen()
Return true if the dialog has already seen the ack. |
boolean |
isAssigned()
Return true if the dialog has already been mapped to a transaction. |
boolean |
isRequestConsumable(SIPRequest dialogRequest)
Return true if this request can be consumed by the dialog. |
boolean |
isSecure()
Returns true if this Dialog is secure i.e. if the request arrived over TLS, and the Request-URI contained a SIPS URI, the "secure" flag is set to TRUE. |
boolean |
isServer()
Return true if is server. |
void |
printDebugInfo()
Debugging print for the dialog. |
void |
requestConsumed()
Updates the next consumable seqno. |
void |
resendAck()
Resend the last ack. |
void |
sendAck(Request request)
Sends ACK Request to the remote party of this dialog. |
void |
sendReliableProvisionalResponse(Response relResponse)
Sends a reliable provisional response to the remote party of this dialog. |
void |
sendRequest(ClientTransaction clientTransactionId)
Sends a Request to the remote party of this dialog. |
void |
sendRequest(ClientTransaction clientTransactionId,
boolean allowInterleaving)
|
void |
setApplicationData(Object applicationData)
Sets application specific data to this dialog. |
void |
setAssigned()
Set the "assigned" flag to true. |
void |
setDialogId(String dialogId)
Set the dialog identifier. |
void |
setLastResponse(SIPTransaction transaction,
SIPResponse sipResponse)
Set the last response for this dialog. |
void |
setRemoteSequenceNumber(long rCseq)
Set the remote sequence number for the dialog. |
void |
setResponseTags(SIPResponse sipResponse)
Check the tags of the response against the tags of the Dialog. |
void |
setSipProvider(SipProviderImpl sipProvider)
|
void |
setState(int state)
Set the state for this dialog. |
void |
startRetransmitTimer(SIPServerTransaction sipServerTx,
Response response)
Start the retransmit timer. |
void |
terminateOnBye(boolean terminateFlag)
Terminate Dialog on BYE. |
Methods inherited from class java.lang.Object |
---|
getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public long auditTag
public static final int NULL_STATE
public static final int EARLY_STATE
public static final int CONFIRMED_STATE
public static final int TERMINATED_STATE
Constructor Detail |
---|
public SIPDialog(SIPTransaction transaction)
transaction
- is the first transaction.public SIPDialog(SIPClientTransaction transaction, SIPResponse sipResponse)
transaction
- -- the transaction ( client/server)sipResponse
- -- response with the appropriate tags.public SIPDialog(SipProviderImpl sipProvider, SIPResponse sipResponse)
Method Detail |
---|
public void setApplicationData(Object applicationData)
Dialog
setApplicationData
in interface Dialog
applicationData
- the new object containing application specific data.public Object getApplicationData()
Dialog
getApplicationData
in interface Dialog
public void requestConsumed()
public boolean isRequestConsumable(SIPRequest dialogRequest)
dialogRequest
- is the request to check with the dialog.
public void doDeferredDelete()
public void setState(int state)
state
- is the state to set for the dialog.public void printDebugInfo()
public boolean isAckSeen()
public SIPRequest getLastAck()
public Transaction getFirstTransaction()
getFirstTransaction
in interface Dialog
public Iterator getRouteSet()
Requests within a dialog MAY contain Record-Route and Contact header fields. However, these requests do not cause the dialog's route set to be modified.
The User Agent Client uses the remote target and route set to build the Request-URI and Route header field of the request.
getRouteSet
in interface Dialog
public void addRoute(SIPRequest sipRequest)
sipRequest
- public void setDialogId(String dialogId)
public static SIPDialog createFromNOTIFY(SIPClientTransaction subscribeTx, SIPTransaction notifyST)
subscribeTx
- - the transaction started with the SUBSCRIBE that we sentnotifyST
- - the ServerTransaction created for an incoming NOTIFY
public boolean isServer()
isServer
in interface Dialog
public String getDialogId()
getDialogId
in interface Dialog
public void addTransaction(SIPTransaction transaction)
transaction
- is the transaction to add to the dialog.public SIPTransaction getLastTransaction()
public SIPServerTransaction getInviteTransaction()
public void setRemoteSequenceNumber(long rCseq)
rCseq
- is the remote cseq number.public void incrementLocalSequenceNumber()
incrementLocalSequenceNumber
in interface Dialog
public int getRemoteSequenceNumber()
getRemoteSequenceNumber
in interface Dialog
Dialog.getRemoteSeqNumber()
public int getLocalSequenceNumber()
getLocalSequenceNumber
in interface Dialog
Dialog.getLocalSeqNumber()
public long getOriginalLocalSequenceNumber()
public long getLocalSeqNumber()
Dialog
Requests within a dialog MUST contain strictly monotonically increasing and contiguous CSeq sequence numbers (increasing-by-one) in each direction (excepting ACK and CANCEL, whose numbers equal the requests being acknowledged or cancelled). Therefore, if the local sequence number is not empty, the value of the local sequence number MUST be incremented by one, and this value MUST be placed into the CSeq header field. If the local sequence number is empty, an initial value MUST be chosen.
getLocalSeqNumber
in interface Dialog
public long getRemoteSeqNumber()
Dialog
If the remote sequence number is empty, it MUST be set to the value of the sequence number in the CSeq header field value in the request. If the remote sequence number was not empty, but the sequence number of the request is lower than the remote sequence number, the request is out of order and MUST be rejected with a 500 (Server Internal Error) response. If the remote sequence number was not empty, and the sequence number of the request is greater than the remote sequence number, the request is in order.
getRemoteSeqNumber
in interface Dialog
public String getLocalTag()
Dialog
getLocalTag
in interface Dialog
public String getRemoteTag()
Dialog
getRemoteTag
in interface Dialog
public void delete()
Dialog
delete
in interface Dialog
public CallIdHeader getCallId()
Dialog
getCallId
in interface Dialog
public Address getLocalParty()
Dialog
This is the value of the To header of received responses in this dialog when acting as an User Agent Server.
getLocalParty
in interface Dialog
public Address getRemoteParty()
This is the value of the From header of recieved responses in this dialogue when acting as an User Agent Server.
getRemoteParty
in interface Dialog
public Address getRemoteTarget()
Dialog
This is the value of the Contact header of received target refresh Requests Requests in this dialog when acting as an User Agent Server.
getRemoteTarget
in interface Dialog
public DialogState getState()
Dialog
getState
in interface Dialog
DialogState
public boolean isSecure()
isSecure
in interface Dialog
true
if this dialogue was established using a sips URI over TLS, and
false
otherwise.public void sendAck(Request request) throws SipException
Dialog
sendAck
in interface Dialog
request
- -
the new ACK Request message to send.
SipException
- if implementation cannot send the ACK Request for any reasonpublic Request createRequest(String method) throws SipException
Dialog
Dialog.sendRequest(ClientTransaction)
method. Therefore any
Request created by this method must be sent via the
Dialog.sendRequest(ClientTransaction)
method and not via its
ClientTransaction.sendRequest()
method.
All other headers including any Authentication related headers, and record route headers should be assigned by the application to the generated request. The assignment of the topmost via header for the outgoing request may be deferred until the application creates a ClientTransaction to send the request out. This method does not increment the dialog sequence number. This method may not be used for creating PRACK or ACK. Implementations should throw SipException if this method is called for creating ACK or PRACK.
createRequest
in interface Dialog
method
- the string value that determines if the request to be created.
SipException
- if the Dialog is not yet established (i.e. dialog state
equals null) or is terminated or if the method is invoked for
ACK or PRACK.public void sendRequest(ClientTransaction clientTransactionId) throws TransactionDoesNotExistException, SipException
Dialog
SipProvider.getNewClientTransaction(Request)
. This
ClientTransaction is passed to this method to send the request. The
Request message gets sent via the ListeningPoint information of the
SipProvider that is associated to this ClientTransaction.
This method implies that the application is functioning as UAC hence the underlying SipProvider acts statefully. This method is useful for sending Bye's to terminate a dialog or Re-Invites/Refers on the Dialog for third party call control, call hold etc.
This method will set the From and the To tags for the outgoing request. This method increments the dialog sequence number and sets the correct sequence number to the outgoing Request and associates the client transaction with this dialog. Note that any tags assigned by the user will be over-written by this method. If the caller sets no RouteHeader in the Request to be sent out, the implementation of this method will add the RouteHeader from the routes that are mantained in the dialog. If the caller sets the RouteHeader's, the implementation will leave the route headers unaltered. This allows the application to manage its own route set if so desired.
The User Agent traditionally must not send a BYE on a confirmed INVITE until it has received an ACK for its 2xx response or until the server transaction timeout is received.
A Dialog may be created by an INVITE request and subsequently
SUBSCRIBE/NOTIFY are sent withing that Dialog. In this case the
application may call Dialog.terminateOnBye(boolean)
to prevent the Dialog
from Terminating upon reciept of a BYE.
sendRequest
in interface Dialog
clientTransactionId
- -
the new ClientTransaction object identifying this transaction,
this clientTransaction should be requested from
SipProvider.getNewClientTransaction(Request)
TransactionDoesNotExistException
- if the clientTransaction does not correspond to any existing
client transaction.
SipException
- if implementation cannot send the Request for any reason.public void sendRequest(ClientTransaction clientTransactionId, boolean allowInterleaving) throws TransactionDoesNotExistException, SipException
TransactionDoesNotExistException
SipException
public void resendAck() throws SipException
SipException
public String getMethod()
public Request createPrack(Response relResponse) throws DialogDoesNotExistException, SipException
Dialog
Dialog.sendRequest(ClientTransaction)
method. Therefore any
Request created by this method must be sent via the
Dialog.sendRequest(ClientTransaction)
method and not via its
ClientTransaction.sendRequest()
method.
All other headers including any Authentication related headers, and record route headers should be assigned by the application to the generated request. The assignment of the topmost via header for the outgoing request may be deferred until the application creates a ClientTransaction to send the request out. This method does not increment the dialog sequence number.
createPrack
in interface Dialog
relResponse
- the reliable provisional response that should result in a
prack reques.
DialogDoesNotExistException
- if the Dialog is not yet established (i.e. dialog state
equals null) or is terminated.
SipException
- if the Method of the transaction that created the Dialog or
Refeshing the Dialog is not an INVITE ( for example
SUBSCRIBE).public Request createAck(long cseqno) throws InvalidArgumentException, SipException
Dialog
createAck
in interface Dialog
cseqno
- -
the CSeq number to be placed in the ACK request.
InvalidArgumentException
- if there is a problem with the supplied cseq ( for example <=
0 ).
SipException
- if the cseq does not relate to a previously sent INVITE or if
the Method that created the Dialog is not an INVITE ( for
example SUBSCRIBE)public SipProviderImpl getSipProvider()
getSipProvider
in interface DialogExt
public void setSipProvider(SipProviderImpl sipProvider)
sipProvider
- the sipProvider to setpublic void setResponseTags(SIPResponse sipResponse)
sipResponse
- -- the response to check.public void setLastResponse(SIPTransaction transaction, SIPResponse sipResponse)
transaction
- -- the transaction associated with the responsesipResponse
- -- the last response to set.public void startRetransmitTimer(SIPServerTransaction sipServerTx, Response response)
sipServerTx
- -- server transaction on which the response was sentresponse
- - response that was sent.public SIPResponse getLastResponse()
public Response createReliableProvisionalResponse(int statusCode) throws InvalidArgumentException, SipException
Dialog
Dialog.sendReliableProvisionalResponse( Response)
method.
createReliableProvisionalResponse
in interface Dialog
statusCode
- the new integer of the statusCode value of this Message.
InvalidArgumentException
- when an invalid status code or request method is supplied.
SipException
- when the Dialog is not a server dialog or if this
method is called after a final response is sent to the
ServerTransactin that created the Dialog.public boolean handlePrack(SIPRequest prackRequest)
prackRequest
-
public void sendReliableProvisionalResponse(Response relResponse) throws SipException
Dialog
Dialog.createReliableProvisionalResponse(int)
. This Response is
passed to this method that sends it. This method will update the RSeq
header of the response if needed and will increase the RSeq count of the
Transaction. The application will not be able to send further reliable
provisional responses for this Dialog until PRACK is received for a
previously sent provisional response. The only response that can be sent
in parallel with an active reliable Provisional Response is a final
response. The Final response will stop retransmission of the reliable
responses.
sendReliableProvisionalResponse
in interface Dialog
relResponse
- -
the reliable provisional response
SipException
- if implementation cannot send the Request for any reason
(e.g. because another reliable response is still pending).public void terminateOnBye(boolean terminateFlag) throws SipException
Dialog
Dialog.delete()
function when all active subscriptions are
terminated.
terminateOnBye
in interface Dialog
terminateFlag
- --
if true then the dialog is terminated when a BYE is received.
SipException
- --
if the dialog is already terminated.public void setAssigned()
public boolean isAssigned()
public Contact getMyContactHeader()
public boolean equals(Object obj)
equals
in class Object
public boolean handleAck(SIPServerTransaction ackTransaction)
ackTransaction
- -- the ACK transaction that was directed at this dialog.
|
NIST-SIP: The Reference Implementation for JAIN-SIP 1.2 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |