NIST SIP Parser and Stack (v1.2) API

javax.sip
Interface Dialog

All Known Implementing Classes:
DialogImpl

public interface Dialog

A dialog represents a peer-to-peer SIP relationship between two user agents that persists for some time. The dialog facilitates sequencing of messages between the user agents and proper routing of requests between both of them. The dialog represents a context in which to interpret SIP messages. However method independent User Agent processing for requests and responses outside of a dialog exists, hence a dialog is not necessary for message processing.

A dialog is identified at each User Agent with a dialog Id, which consists of a Call-Id value, a local tag and a remote tag. The dialog Id at each User Agent involved in the dialog is not the same. Specifically, the local tag at one User Agent is identical to the remote tag at the peer User Agent. The tags are opaque tokens that facilitate the generation of unique dialog Ids.

A dialog contains certain pieces of data needed for further message transmissions within the dialog. This data consists of:

A dialog also has its own state machine, the current DialogState is determined by the sequence of messages that occur on the initial dialog.

Dialog States:
Early --> Confirmed --> Completed --> Terminated

Since:
v1.1
Author:
Sun Microsystems

Method Summary
 void delete()
          This method will release all resources associated with this dialog that are tracked by the SipProvider.
 CallIdHeader getCallId()
          Returns the Call-Id for this SipSession.
 String getDialogId()
          Get the dialog identifer of this dialog.
 Transaction getFirstTransaction()
          This method retrieves the transaction which resulted in the creation of this Dialog.
 Address getLocalParty()
          Returns the Address identifying the local party.
 int getLocalSequenceNumber()
          The local sequence number is used to order requests from this User Agent Client to its peer User Agent Server.
 String getLocalTag()
          Get the Local Tag of this Dialog.
 Address getRemoteParty()
          Returns the Address identifying the remote party.
 int getRemoteSequenceNumber()
          The remote sequence number is used to order requests from its peer User Agent Client to this User Agent Server.
 String getRemoteTag()
          Gets the Remote Tag of this Dialog.
 Address getRemoteTarget()
          Returns the Address identifying the remote target.
 Iterator getRouteSet()
          When acting as an User Agent Server the routeset 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.
 DialogState getState()
          Returns the current state of the dialog.
 boolean isSecure()
          Returns true if this Dialog is secure i.e. if the request was sent over a "sips:" scheme, or a "sip:" scheme over TLS.
 boolean isServer()
          Returns whether this Dialog is a server dialog.
 void sendAck(Request ackRequest)
          Sends ACK Request to the remote party of this dialog.
 void sendRequest(ClientTransaction clientTransaction, Request request)
          Sends a Request to the remote party of this dialog.
 

Method Detail

getLocalParty

public Address getLocalParty()
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 recieved responses in this dialog when acting as an User Agent Server.

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 dialog when acting as an User Agent Client.

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

Returns:
the address object of the remote party.

getRemoteTarget

public Address getRemoteTarget()
Returns the Address identifying the remote target. This is the value of the Contact header of recieved Responses for Requests or refresh Requests in this dialog when acting as an User Agent Client.

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

Returns:
the address object of the remote target.

getDialogId

public String getDialogId()
Get the dialog identifer of this dialog. A dialog Id is associated with all responses and with any request that contains a tag in the To field. The rules for computing the dialog Id of a message depends on whether the SIP element is a User Agent Client or User Agent Server and applies to both requests and responses.

Returns:
the string identifier for this dialog.

getCallId

public CallIdHeader getCallId()
Returns the Call-Id for this SipSession. This is the value of the Call-Id header for all messages belonging to this session.

Returns:
the Call-Id for this dialog

getLocalSequenceNumber

public int getLocalSequenceNumber()
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.

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

getRemoteSequenceNumber

public int getRemoteSequenceNumber()
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.

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

getRouteSet

public Iterator getRouteSet()
When acting as an User Agent Server the routeset 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.

Returns:
an Iterator containing a list of route headers to be used for forwarding.

isSecure

public boolean isSecure()
Returns true if this Dialog is secure i.e. if the request was sent over a "sips:" scheme, or a "sip:" scheme over TLS.

Returns:
true if this dialog was secure, and false otherwise.

isServer

public boolean isServer()
Returns whether this Dialog is a server dialog. A proxy may wish to keep an associated sets of dialogs for forking, i.e. a single server dialog is associated with multiple client dialogs.

Returns:
true if this is a server dialog and false if it is a client dialog.

sendRequest

public void sendRequest(ClientTransaction clientTransaction,
                        Request request)
                 throws TransactionDoesNotExistException,
                        SipException
Sends a Request to the remote party of this dialog. This method implies that the application is functioning as UAC hence the underlying SipProvider acts statefully. This method is useful for sending Bye's for terminating a dialog or Re-Invites on the Dialog for third party call control.

This methods will set the From and the To tags for the outgoing request and also set the correct sequence number to the outgoing Request and associate 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 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.

When the SipStack.getRetransmissionFilter() is true, that is the SipProvider takes care of all retransmissions for the application, and the SipProvider can not deliver the Request after multiple retransmits the SipListener will be notified with a TimeoutEvent when the transaction expires.

Parameters:
request - - the new Request message to send.
clientTransaction - - the new ClientTransaction object identifying this transaction, this clientTransaction should be requested from SipProvider.getNewClientTransaction(Request)
Throws:
TransactionDoesNotExistException - if the serverTransaction does not correspond to any existing server transaction.
SipException - if implementation cannot send the Request for any reason.

sendAck

public void sendAck(Request ackRequest)
             throws SipException
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.

Parameters:
ackRequest - - the new ACK Request message to send.
Throws:
SipException - if implementation cannot send the ACK Request for any reason

getState

public DialogState getState()
Returns the current state of the dialog. 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, e.g. pseudo dialog's. The dialog states are: 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".

Returns:
a DialogState determining the current state of the dialog.
See Also:
DialogState

delete

public void delete()
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 for future use and extension methods that do not require a BYE to terminate a dialog. The basic case of the INVITE and all dialogs that we are aware of today it is expected that BYE requests will end the dialog.


getFirstTransaction

public Transaction getFirstTransaction()
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 isServer().

The first transaction can be used to track peer to peer associations when forwarding proxied requests. For example, a dialog stateful proxy may keep a pair of transactions for a point to point call. When a BYE request comes in on a point to point call, it can retrieve the INVITE transaction that created the Dialog using Dialog.getFirstTransaction(), lookup the associated INVITE transaction for the other Dialog, get its Dialog using Transaction.getDialog() and use this Dialog to send the BYE Request.

Returns:
the Transaction that created the Dialog.

getLocalTag

public String getLocalTag()
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.


getRemoteTag

public String getRemoteTag()
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.


NIST SIP Parser and Stack (v1.2) API

A product of the NIST/ITL Advanced Networking Technologies Division.
See conditions of use.
Get the latest distribution.
Submit a bug report or feature request.