gov.nist.javax.sip.stack
Class SIPDialog

java.lang.Object
  gov.nist.javax.sip.stack.SIPDialog

All Implemented Interfaces:

DialogExt, Serializable, Dialog

public class SIPDialog
extends Object
implements Dialog, DialogExt

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.

Version:

1.2 $Revision: 1.207 $ $Date: 2010-12-02 22:04:14 $

Author:

M. Ranganathan

See Also:

Serialized Form

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	acquireTimerTaskSem()
void	addEventListener(SIPDialogEventListener newListener) Adds a new event listener to this dialog.
void	addRoute(SIPRequest sipRequest) Add a Route list extracted from a SIPRequest to this Dialog.
boolean	addTransaction(SIPTransaction transaction) Add a transaction record to the dialog.
void	checkRetransmissionForForking(SIPResponse response)
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.
SIPRequest	createRequest(SipUri requestURI, Via via, CSeq cseq, From from, To to) Generate a request from a response.
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	disableSequenceNumberValidation() Turn off sequence number validation for this dialog.
void	doDeferredDelete() This method is called when a forked dialog is created from the client side.
void	doDeferredDeleteIfNoAckSent(long seqno)
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() Deprecated.
Transaction	getFirstTransactionInt() This is for internal use only.
SIPServerTransaction	getInviteTransaction() Get the INVITE transaction (null if no invite transaction).
SIPRequest	getLastAckSent() Get the last ACK for this transaction.
long	getLastResponseCSeqNumber()
String	getLastResponseMethod()
Integer	getLastResponseStatusCode()
Via	getLastResponseTopMostVia()
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	getMergeId()
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
int	hashCode()
void	incrementLocalSequenceNumber() Increment the local CSeq # for the dialog.
boolean	isAckSeen() Return true if the dialog has already seen the ack.
boolean	isAckSent(long cseqNo) Return true if ACK was sent ( for client tx ).
boolean	isAssigned() Return true if the dialog has already been mapped to a transaction.
boolean	isAtleastOneAckSent()
boolean	isBackToBackUserAgent()
boolean	isReleaseReferences() retrieve the value of release references to know if the stack performs optimizations on cleanup to save on memory
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	isSequnceNumberValidation()
boolean	isServer() Return true if is server.
void	printDebugInfo() Debugging print for the dialog.
void	releaseTimerTaskSem()
void	removeEventListener(SIPDialogEventListener oldListener) Removed an event listener from this 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	setBackToBackUserAgent() Sets a flag that indicates that this Dialog is part of a BackToBackUserAgent.
void	setDialogId(String dialogId) Set the dialog identifier.
void	setEarlyDialogTimeoutSeconds(int seconds) Sets the early dialog timeout period.
void	setLastResponse(SIPTransaction transaction, SIPResponse sipResponse) Set the last response for this dialog.
void	setPendingRouteUpdateOn202Response(SIPRequest sipRequest)
void	setReleaseReferences(boolean releaseReferences) If set to true it will release all references that it no longer needs.
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

equals, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

auditTag

public transient long auditTag

NULL_STATE

public static final int NULL_STATE

See Also:

Constant Field Values

EARLY_STATE

public static final int EARLY_STATE

See Also:

Constant Field Values

CONFIRMED_STATE

public static final int CONFIRMED_STATE

See Also:

Constant Field Values

TERMINATED_STATE

public static final int TERMINATED_STATE

See Also:

Constant Field Values

Constructor Detail

SIPDialog

public SIPDialog(SIPTransaction transaction)

Constructor given the first transaction.

Parameters:

transaction - is the first transaction.

SIPDialog

public SIPDialog(SIPClientTransaction transaction,
                 SIPResponse sipResponse)

Constructor given a transaction and a response.

Parameters:

transaction - -- the transaction ( client/server)

sipResponse - -- response with the appropriate tags.

SIPDialog

public SIPDialog(SipProviderImpl sipProvider,
                 SIPResponse sipResponse)

create a sip dialog with a response ( no tx)

Method Detail

addEventListener

public void addEventListener(SIPDialogEventListener newListener)

Adds a new event listener to this dialog.

Parameters:

newListener - Listener to add.

removeEventListener

public void removeEventListener(SIPDialogEventListener oldListener)

Removed an event listener from this dialog.

Parameters:

oldListener - Listener to remove.

setApplicationData

public void setApplicationData(Object applicationData)

Description copied from interface: Dialog

Sets application specific data to this dialog. This specification does not define the format of this data. This is the responsibility of the application and is dependent upon the application. This method can be used to link the call state of this dialog to other state, SIP or otherwise in the system. For example this method could be used by a SIP-to-H323 interworking node that would associate the H323 call state associated with a call on the H323 side with this dialog that represents this call on the SIP side. Or a dialog stateful proxy can associate the UAS dialog to the UAC dialog and vice versa.

Specified by:

setApplicationData in interface Dialog

Parameters:

applicationData - the new object containing application specific data.

getApplicationData

public Object getApplicationData()

Description copied from interface: Dialog

Gets the application specific data specific to this dialog. This specification does not define the format of this application specific data. This is the responsibility of the application.

Specified by:

getApplicationData in interface Dialog

Returns:

the object representation of the application specific data.

requestConsumed

public void requestConsumed()

Updates the next consumable seqno.

isRequestConsumable

public boolean isRequestConsumable(SIPRequest dialogRequest)

Return true if this request can be consumed by the dialog.

Parameters:

dialogRequest - is the request to check with the dialog.

Returns:

true if the dialogRequest sequence number matches the next consumable seqno.

doDeferredDelete

public void doDeferredDelete()

This method is called when a forked dialog is created from the client side. It starts a timer task. If the timer task expires before an ACK is sent then the dialog is cancelled (i.e. garbage collected ).

setState

public void setState(int state)

Set the state for this dialog.

Parameters:

state - is the state to set for the dialog.

printDebugInfo

public void printDebugInfo()

Debugging print for the dialog.

isAckSeen

public boolean isAckSeen()

Return true if the dialog has already seen the ack.

Returns:

flag that records if the ack has been seen.

getLastAckSent

public SIPRequest getLastAckSent()

Get the last ACK for this transaction.

isAckSent

public boolean isAckSent(long cseqNo)

Return true if ACK was sent ( for client tx ). For server tx, this is a NO-OP ( we dont send ACK).

getFirstTransaction

@Deprecated
public Transaction getFirstTransaction()

Deprecated.

Description copied from interface: Dialog

This method retrieves the transaction which resulted in the creation of this Dialog. The transaction type either server or client can be determined based on whether this is a server or client Dialog, see Dialog.isServer().

Specified by:

getFirstTransaction in interface Dialog

Returns:

the Transaction that created the Dialog.

getFirstTransactionInt

public Transaction getFirstTransactionInt()

This is for internal use only.

getRouteSet

public Iterator getRouteSet()

Gets the route set for the dialog. When acting as an User Agent Server the route set MUST be set to the list of URIs in the Record-Route header field from the request, taken in order and preserving all URI parameters. When acting as an User Agent Client the route set MUST be set to the list of URIs in the Record-Route header field from the response, taken in reverse order and preserving all URI parameters. If no Record-Route header field is present in the request or response, the route set MUST be set to the empty set. This route set, even if empty, overrides any pre-existing route set for future requests in this dialog.

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.

Specified by:

getRouteSet in interface Dialog

Returns:

an Iterator containing a list of route headers to be used for forwarding. Empty iterator is returned if route has not been established.

addRoute

public void addRoute(SIPRequest sipRequest)

Add a Route list extracted from a SIPRequest to this Dialog.

Parameters:

sipRequest -

setDialogId

public void setDialogId(String dialogId)

Set the dialog identifier.

createFromNOTIFY

public static SIPDialog createFromNOTIFY(SIPClientTransaction subscribeTx,
                                         SIPTransaction notifyST)

Creates a new dialog based on a received NOTIFY. The dialog state is initialized appropriately. The NOTIFY differs in the From tag Made this a separate method to clearly distinguish what's happening here - this is a non-trivial case

Parameters:

subscribeTx - - the transaction started with the SUBSCRIBE that we sent

notifyST - - the ServerTransaction created for an incoming NOTIFY

Returns:

-- a new dialog created from the subscribe original SUBSCRIBE transaction.

isServer

public boolean isServer()

Return true if is server.

Specified by:

isServer in interface Dialog

Returns:

true if is server transaction created this dialog.

getDialogId

public String getDialogId()

Get the id for this dialog.

Specified by:

getDialogId in interface Dialog

Returns:

the string identifier for this dialog.

addTransaction

public boolean addTransaction(SIPTransaction transaction)

Add a transaction record to the dialog.

Parameters:

transaction - is the transaction to add to the dialog.

getLastTransaction

public SIPTransaction getLastTransaction()

Get the last transaction from the dialog.

getInviteTransaction

public SIPServerTransaction getInviteTransaction()

Get the INVITE transaction (null if no invite transaction).

setRemoteSequenceNumber

public void setRemoteSequenceNumber(long rCseq)

Set the remote sequence number for the dialog.

Parameters:

rCseq - is the remote cseq number.

incrementLocalSequenceNumber

public void incrementLocalSequenceNumber()

Increment the local CSeq # for the dialog. This is useful for if you want to create a hole in the sequence number i.e. route a request outside the dialog and then resume within the dialog.

Specified by:

incrementLocalSequenceNumber in interface Dialog

getRemoteSequenceNumber

public int getRemoteSequenceNumber()

Deprecated.

Get the remote sequence number (for cseq assignment of outgoing requests within this dialog).

Specified by:

getRemoteSequenceNumber in interface Dialog

Returns:

local sequence number.

See Also:

Dialog.getRemoteSeqNumber()

getLocalSequenceNumber

public int getLocalSequenceNumber()

Deprecated.

Get the local sequence number (for cseq assignment of outgoing requests within this dialog).

Specified by:

getLocalSequenceNumber in interface Dialog

Returns:

local sequence number.

See Also:

Dialog.getLocalSeqNumber()

getOriginalLocalSequenceNumber

public long getOriginalLocalSequenceNumber()

Get the sequence number for the request that origianlly created the Dialog.

Returns:

-- the original starting sequence number for this dialog.

getLocalSeqNumber

public long getLocalSeqNumber()

Description copied from interface: Dialog

The local sequence number is used to order requests from this User Agent Client to its peer User Agent Server. The local sequence number MUST be set to the value of the sequence number in the CSeq header field of the request. The remote sequence number MUST be empty as it is established when the remote User Agent sends a request within the 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.

Specified by:

getLocalSeqNumber in interface Dialog

Returns:

the value of the local sequence number, returns zero if not set.

getRemoteSeqNumber

public long getRemoteSeqNumber()

Description copied from interface: Dialog

The remote sequence number is used to order requests from its peer User Agent Client to this User Agent Server. When acting an User Agent Server the remote sequence number MUST be set to the value of the sequence number in the CSeq header field of the request from the User Agent Client. The local sequence number MUST be empty.

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.

Specified by:

getRemoteSeqNumber in interface Dialog

Returns:

the value of the remote sequence number, return zero if not set.

getLocalTag

public String getLocalTag()

Description copied from interface: Dialog

Get the Local Tag of this Dialog. On the client side, this tag is assigned to outgoing From headers for Requests within the dialog and To headers for responses within the dialog. On the server side, this tag is associated with outgoing To headers for responses within the dialog.

Specified by:

getLocalTag in interface Dialog

getRemoteTag

public String getRemoteTag()

Description copied from interface: Dialog

Gets the Remote Tag of this Dialog. On the client side, this tag is associated with outgoing To headers for Requests within the dialog. On the server side, this tag is associated with incoming From headers for requests within the dialog.

Specified by:

getRemoteTag in interface Dialog

delete

public void delete()

Description copied from interface: Dialog

This method will release all resources associated with this dialog that are tracked by the SipProvider. Further references to the dialog by incoming messages will result in a mismatch. This delete method is provided methods that do not expect a BYE to terminate a dialog. Such is the case with SUBSCRIBE/NOTIFY within a Dialog that is created with an INIVTE.

Specified by:

delete in interface Dialog

getCallId

public CallIdHeader getCallId()

Description copied from interface: Dialog

Returns the Call-Id for this dialog. This is the value of the Call-Id header for all messages belonging to this session.

Specified by:

getCallId in interface Dialog

Returns:

the Call-Id for this dialog

getLocalParty

public Address getLocalParty()

Description copied from interface: Dialog

Returns the Address identifying the local party. This is the value of the From header of locally initiated requests in this dialog when acting as an User Agent Client.

This is the value of the To header of received responses in this dialog when acting as an User Agent Server.

Specified by:

getLocalParty in interface Dialog

Returns:

the address object of the local party.

getRemoteParty

public Address getRemoteParty()

Returns the Address identifying the remote party. This is the value of the To header of locally initiated requests in this dialogue when acting as an User Agent Client.

This is the value of the From header of recieved responses in this dialogue when acting as an User Agent Server.

Specified by:

getRemoteParty in interface Dialog

Returns:

the address object of the remote party.

getRemoteTarget

public Address getRemoteTarget()

Description copied from interface: Dialog

Returns the Address identifying the remote target. This is the value of the Contact header of received Responses for target refresh Requests in this dialog when acting as an User Agent Client.

This is the value of the Contact header of received target refresh Requests Requests in this dialog when acting as an User Agent Server.

Specified by:

getRemoteTarget in interface Dialog

Returns:

the address object of the remote target.

getState

public DialogState getState()

Description copied from interface: Dialog

Returns the current DialogState of the dialog or null. A dialog that is created but not yet mapped to any state must return null, multiple requests can be generated on the Dialog in a null state. The dialog states for INVITE transaction are:

• Early - A dialog is in the "early" state, which occurs when it is created when a provisional response is recieved to the INVITE Request.
• Confirmed - A dialog transitions to the "confirmed" state when a 2xx final response is received to the INVITE Request.
• Terminated - A dialog transitions to the "terminated" state for all other reasons or if no response arrives at all on the dialog.

A Subscibe/Refer dialog has the following states:

• Null - refers to a state that is not terminated.
• Terminated - when the Application deletes the Dialog or if no response arrives at all.

Independent of the method, if a request outside of a dialog generates a non-2xx final response, any early dialogs created through provisional responses to that request are "terminated". If no response arrives at all on the early dialog it is also "terminated".

Specified by:

getState in interface Dialog

Returns:

a DialogState determining the current state of the dialog.

See Also:

DialogState

isSecure

public 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.

Specified by:

isSecure in interface Dialog

Returns:

true if this dialogue was established using a sips URI over TLS, and false otherwise.

sendAck

public void sendAck(Request request)
             throws SipException

Description copied from interface: Dialog

Sends ACK Request to the remote party of this dialog. This method implies that the application is functioning as User Agent Client hence the underlying SipProvider acts statefully. This method does not increment the local sequence number.

Specified by:

sendAck in interface Dialog

Parameters:

request - - the new ACK Request message to send.

Throws:

SipException - if implementation cannot send the ACK Request for any reason

createRequest

public Request createRequest(String method)
                      throws SipException

Description copied from interface: Dialog

Creates a new Request message based on the dialog creating request. This method should be used for but not limited to creating Bye's, Refer's and re-Invite's on the Dialog. The returned Request will be correctly formatted that is the Dialog implementation is responsible for assigning the following:

• RequestURI
• FromHeader
• ToHeader
• CallIdHeader
• RouteHeaders

The CSeqHeader will be set when the message is sent. If this method returns a CSeqHeader in the Request it may be overwritten again by the 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.

Specified by:

createRequest in interface Dialog

Parameters:

method - the string value that determines if the request to be created.

Returns:

the newly created Request message on this Dialog.

Throws:

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.

createRequest

public SIPRequest createRequest(SipUri requestURI,
                                Via via,
                                CSeq cseq,
                                From from,
                                To to)

Generate a request from a response.

Parameters:

requestURI - -- the request URI to assign to the request.

via - -- the Via header to assign to the request

cseq - -- the CSeq header to assign to the request

from - -- the From header to assign to the request

to - -- the To header to assign to the request

Returns:

-- the newly generated sip request.

sendRequest

public void sendRequest(ClientTransaction clientTransactionId)
                 throws TransactionDoesNotExistException,
                        SipException

Description copied from interface: Dialog

Sends a Request to the remote party of this dialog. When an application wishes to send a Request message on this dialog, it creates a Request and creates a new ClientTransaction to handle this request from 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.

Specified by:

sendRequest in interface Dialog

Parameters:

clientTransactionId - - the new ClientTransaction object identifying this transaction, this clientTransaction should be requested from SipProvider.getNewClientTransaction(Request)

Throws:

TransactionDoesNotExistException - if the clientTransaction does not correspond to any existing client transaction.

SipException - if implementation cannot send the Request for any reason.

sendRequest

public void sendRequest(ClientTransaction clientTransactionId,
                        boolean allowInterleaving)
                 throws TransactionDoesNotExistException,
                        SipException

Throws:

TransactionDoesNotExistException

SipException

resendAck

public void resendAck()
               throws SipException

Resend the last ack.

Throws:

SipException

getMethod

public String getMethod()

Get the method of the request/response that resulted in the creation of the Dialog.

Returns:

-- the method of the dialog.

createPrack

public Request createPrack(Response relResponse)
                    throws DialogDoesNotExistException,
                           SipException

Description copied from interface: Dialog

Creates a new PRACK Request message based on a reliable provisional response received by this Dialog and the Dialog internal information. The returned Request will be correctly formatted that is the Dialog implementation is responsible for assigning the following:

• RequestURI
• FromHeader
• ToHeader
• CallIdHeader
• RouteHeaders
• RAckHeader

The CSeqHeader will be set when the message is sent. If this method returns a CSeqHeader in the Request it may be overwritten again by the 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.

Specified by:

createPrack in interface Dialog

Parameters:

relResponse - the reliable provisional response that should result in a prack reques.

Returns:

the newly created Request message on this Dialog.

Throws:

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).

createAck

public Request createAck(long cseqno)
                  throws InvalidArgumentException,
                         SipException

Description copied from interface: Dialog

Creates an ACK request for an Invite that was responded with 2xx response. The cseq number for the invite is supplied to relate the ACK to its original invite request.

Specified by:

createAck in interface Dialog

Parameters:

cseqno - - the CSeq number to be placed in the ACK request.

Returns:

The newly created ACK request message.

Throws:

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)

getSipProvider

public SipProviderImpl getSipProvider()

Get the provider for this Dialog. SPEC_REVISION

Specified by:

getSipProvider in interface DialogExt

Returns:

-- the SIP Provider associated with this transaction.

setSipProvider

public void setSipProvider(SipProviderImpl sipProvider)

Parameters:

sipProvider - the sipProvider to set

setResponseTags

public void setResponseTags(SIPResponse sipResponse)

Check the tags of the response against the tags of the Dialog. Return true if the respnse matches the tags of the dialog. We do this check wehn sending out a response.

Parameters:

sipResponse - -- the response to check.

setLastResponse

public void setLastResponse(SIPTransaction transaction,
                            SIPResponse sipResponse)

Set the last response for this dialog. This method is called for updating the dialog state when a response is either sent or received from within a Dialog.

Parameters:

transaction - -- the transaction associated with the response

sipResponse - -- the last response to set.

startRetransmitTimer

public void startRetransmitTimer(SIPServerTransaction sipServerTx,
                                 Response response)

Start the retransmit timer.

Parameters:

sipServerTx - -- server transaction on which the response was sent

response - - response that was sent.

createReliableProvisionalResponse

public Response createReliableProvisionalResponse(int statusCode)
                                           throws InvalidArgumentException,
                                                  SipException

Description copied from interface: Dialog

Creates a new reliable provisional response based on an Invite request that created this Dialog or that is now refreshing this Dialog. This new Response does not contain a body. Only the required headers are copied from the Request. The response will include also the following headers:

• RequireHeader
• RSeqHeader

The RequireHeader will include the 100rel option tag. The Dialog will handle the RSeq count that will be updated and icreased if needed when the reliable provisional response is sent. Any Response created by this method must be sent via the Dialog.sendReliableProvisionalResponse( Response) method.

Specified by:

createReliableProvisionalResponse in interface Dialog

Parameters:

statusCode - the new integer of the statusCode value of this Message.

Returns:

the newly created Response object.

Throws:

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.

handlePrack

public boolean handlePrack(SIPRequest prackRequest)

Do the processing necessary for the PRACK

Parameters:

prackRequest -

Returns:

true if this is the first time the tx has seen the prack ( and hence needs to be passed up to the TU)

sendReliableProvisionalResponse

public void sendReliableProvisionalResponse(Response relResponse)
                                     throws SipException

Description copied from interface: Dialog

Sends a reliable provisional response to the remote party of this dialog. When an application wishes to send a reliable provisional response on the Invite transaction that created this dialog or that is now refreshing this dialog, it creates a reliable provisional response message with 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.

Specified by:

sendReliableProvisionalResponse in interface Dialog

Parameters:

relResponse - - the reliable provisional response

Throws:

SipException - if implementation cannot send the Request for any reason (e.g. because another reliable response is still pending).

terminateOnBye

public void terminateOnBye(boolean terminateFlag)
                    throws SipException

Description copied from interface: Dialog

Terminate Dialog on BYE. If this flag is set to true then the stack will Terminate the dialog automatically when BYE is received. This is the default behavior. This method is useful for SUBSCRIBE/NOTIFY processing within a Dialog. In the case that several subscriptions are associated with a single Dialog, the Dialog does not terminate until all the subscriptions in it are destroyed. Hence, if the application is aware of active subscriptions in a dialog it should set this flag to false. In this case when BYE is received the dialog will not be terminated and it will be the application�s responsibility to call the Dialog.delete() function when all active subscriptions are terminated.

Specified by:

terminateOnBye in interface Dialog

Parameters:

terminateFlag - -- if true then the dialog is terminated when a BYE is received.

Throws:

SipException - -- if the dialog is already terminated.

setAssigned

public void setAssigned()

Set the "assigned" flag to true. We do this when inserting the dialog into the dialog table of the stack.

isAssigned

public boolean isAssigned()

Return true if the dialog has already been mapped to a transaction.

getMyContactHeader

public Contact getMyContactHeader()

Get the contact header that the owner of this dialog assigned. Subsequent Requests are considered to belong to the dialog if the dialog identifier matches and the contact header matches the ip address and port on which the request is received.

Returns:

contact header belonging to the dialog.

handleAck

public boolean handleAck(SIPServerTransaction ackTransaction)

Do the necessary processing to handle an ACK directed at this Dialog.

Parameters:

ackTransaction - -- the ACK transaction that was directed at this dialog.

Returns:

-- true if the ACK was successfully consumed by the Dialog and resulted in the dialog state being changed.

isAtleastOneAckSent

public boolean isAtleastOneAckSent()

Returns:

true if an ack was ever sent for this Dialog

isBackToBackUserAgent

public boolean isBackToBackUserAgent()

doDeferredDeleteIfNoAckSent

public void doDeferredDeleteIfNoAckSent(long seqno)

setBackToBackUserAgent

public void setBackToBackUserAgent()

Description copied from interface: DialogExt

Sets a flag that indicates that this Dialog is part of a BackToBackUserAgent. If this flag is set, INVITEs are not allowed to interleave and timed out ACK transmission results in a BYE being sent to the other side. Setting this flag instructs the stack to automatically handle dialog errors. Once this flag is set for a dialog, it cannot be changed. This flag can be set on a stack-wide basis, on a per-provider basis or on a per Dialog basis. This flag must only be set at the time of Dialog creation. If the flag is set after the first request or response is seen by the Dialog, the behavior of this flag is undefined.

Specified by:

setBackToBackUserAgent in interface DialogExt

isSequnceNumberValidation

public boolean isSequnceNumberValidation()

disableSequenceNumberValidation

public void disableSequenceNumberValidation()

Description copied from interface: DialogExt

Turn off sequence number validation for this dialog. This passes all requests to the application layer including those that arrive out of order. This is good for testing purposes. Validation is delegated to the application and the stack will not attempt to block requests arriving out of sequence from reaching the application. In particular, the validation of CSeq and the ACK retransmission recognition are delegated to the application. Your application will be responsible for error handling of these cases.

Specified by:

disableSequenceNumberValidation in interface DialogExt

acquireTimerTaskSem

public void acquireTimerTaskSem()

releaseTimerTaskSem

public void releaseTimerTaskSem()

getMergeId

public String getMergeId()

setPendingRouteUpdateOn202Response

public void setPendingRouteUpdateOn202Response(SIPRequest sipRequest)

getLastResponseMethod

public String getLastResponseMethod()

getLastResponseStatusCode

public Integer getLastResponseStatusCode()

getLastResponseCSeqNumber

public long getLastResponseCSeqNumber()

getLastResponseTopMostVia

public Via getLastResponseTopMostVia()

Returns:

the lastResponseTopMostVia

isReleaseReferences

public boolean isReleaseReferences()

Description copied from interface: DialogExt

retrieve the value of release references to know if the stack performs optimizations on cleanup to save on memory

Specified by:

isReleaseReferences in interface DialogExt

Returns:

release references value

setReleaseReferences

public void setReleaseReferences(boolean releaseReferences)

Description copied from interface: DialogExt

If set to true it will release all references that it no longer needs. This will include the reference to the Request, Transactions, Any unused timers etc. This will significantly reduce memory consumption under high load

Specified by:

setReleaseReferences in interface DialogExt

setEarlyDialogTimeoutSeconds

public void setEarlyDialogTimeoutSeconds(int seconds)

Description copied from interface: DialogExt

Sets the early dialog timeout period. Overrides the value set by the stack configuration property EARLY_DIALOG_TIMEOUT_SECONDS. A dialog may remain in early state indefinitely. UACs may kill a dialog in early state of periodic provisional responses are not seen for 3 minutes. This allows you to override the RFC specified value of 3 minutes hence allowing for fast fail over from unresponsive servers.

Specified by:

setEarlyDialogTimeoutSeconds in interface DialogExt

checkRetransmissionForForking

public void checkRetransmissionForForking(SIPResponse response)

hashCode

public int hashCode()

Overrides:

hashCode in class Object