|
NIST SIP Parser and Stack (v1.2) API | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
DialogState
is
determined by the sequence of messages that occur on the initial dialog.
Dialog States:
Early --> Confirmed --> Completed --> Terminated
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 |
public Address getLocalParty()
This is the value of the To header of recieved responses in this dialog when acting as an User Agent Server.
public Address getRemoteParty()
This is the value of the From header of recieved responses in this dialog when acting as an User Agent Server.
public Address getRemoteTarget()
This is the value of the Contact header of recieved Requests or refresh Requests in this dialog when acting as an User Agent Server.
public String getDialogId()
public CallIdHeader getCallId()
public int getLocalSequenceNumber()
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.
public int getRemoteSequenceNumber()
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.
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.
public boolean isSecure()
true
if this dialog was secure, and
false
otherwise.public boolean isServer()
true
if this is a server dialog and false
if it is a client dialog.public void sendRequest(ClientTransaction clientTransaction, Request request) throws TransactionDoesNotExistException, SipException
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.
request
- - the new Request message to send.clientTransaction
- - the new ClientTransaction object identifying
this transaction, this clientTransaction should be requested from
SipProvider.getNewClientTransaction(Request)
TransactionDoesNotExistException
- if the serverTransaction does
not correspond to any existing server transaction.
SipException
- if implementation cannot send the Request for
any reason.public void sendAck(Request ackRequest) throws SipException
ackRequest
- - the new ACK Request message to send.
SipException
- if implementation cannot send the ACK Request for
any reasonpublic DialogState getState()
DialogState
public void delete()
public Transaction getFirstTransaction()
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.
public String getLocalTag()
public String getRemoteTag()
|
NIST SIP Parser and Stack (v1.2) API | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |