001: /**
002: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
003: * Unpublished - rights reserved under the Copyright Laws of the United States.
004: * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
005: * Copyright © 2005 BEA Systems, Inc. All rights reserved.
006: *
007: * Use is subject to license terms.
008: *
009: * This distribution may include materials developed by third parties.
010: *
011: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
012: *
013: * Module Name : JSIP Specification
014: * File Name : Dialog.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty Initial version
020: * 1.2 05/04/2005 M. Rangnathan Added Prack Support
021: * Phelim O'Doherty Added createAck method
022: * M. Ranganathan Clarified retransmission behavior.
023: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
024: */package javax.sip;
025:
026: import javax.sip.address.Address;
027: import javax.sip.message.Request;
028: import javax.sip.message.Response;
029:
030: import java.text.ParseException;
031: import java.util.Iterator;
032: import javax.sip.header.CallIdHeader;
033: import java.io.Serializable;
034:
035: /**
036: * A dialog represents a peer-to-peer SIP relationship between two user agents
037: * that persists for some time. Dialogs are typically used by user agents to
038: * facilitate management of state. Dialogs are typically not relevant to proxy
039: * servers. The dialog facilitates sequencing of messages between the user
040: * agents and proper routing of requests between both of them. The dialog
041: * represents a context in which to interpret SIP Transactions and Messages.
042: * However, a Dialog is not necessary for message processing.
043: * <p>
044: * A dialog is identified at each User Agent with a dialog Id, which consists of
045: * a Call-Id value, a local tag and a remote tag. The dialog Id at each User
046: * Agent involved in the dialog is not the same. Specifically, the local tag at
047: * one User Agent is identical to the remote tag at the peer User Agent. The
048: * tags are opaque tokens that facilitate the generation of unique dialog Ids.
049: * <p>
050: * A dialog contains certain pieces of data needed for further message
051: * transmissions within the dialog. This data consists of:
052: * <ul>
053: * <li> Dialog Id - used to identify the dialog.
054: * <li> Local sequence number - used to order requests from the User Agent to
055: * its peer.
056: * <li> Remote sequence number - used to order requests from its peer to the
057: * User Agent.
058: * <li> Local URI - the address of the local party.
059: * <li> Remote URI - the address of the remote party.
060: * <li> Remote target - the address from the Contact header field of the request
061: * or response or refresh request or response.
062: * <li> "secure" boolean - determines if the dialog is secure i.e. use the
063: * <var>sips:</var> scheme.
064: * <li> Route set - an ordered list of URIs. The route set is the list of
065: * servers that need to be traversed to send a request to the peer.
066: * </ul>
067: * A dialog also has its own state machine, the current {@link DialogState} is
068: * determined by the sequence of messages that occur on the initial dialog.
069: * <p>
070: * <b>Invite Dialog States:</b><br>
071: * Null --> Early --> Confirmed --> Terminated
072: * <p>
073: * <b>Other Dialog-creating Requests
074: * Dialog States (ie. SUBSCRIBE):</b><br>
075: * Null --> Confirmed --> Terminated.
076: * <p>
077: * The Listener MUST ACK the 2xx response associated with an INVITE dialog.
078: * Retransmissions of the ACK in response to subsequent INVITE requests are
079: * handled by the dialog layer. If a listener does not ACK a 2XX response
080: * immediately, the implementation will terminate the Dialog automatically and
081: * remove it from the stack when the listener completes its execution.
082: * <p>
083: * The dialog layer MUST respond with an automatic error response when <a href =
084: * "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a> specifies that the User
085: * Agent MUST respond with a certain error. This does not apply for successful
086: * responses like 200 OK. The error condition relates directly to the dialog
087: * layer and the SipListener can add no meaningful information to the response.
088: * Such a response can be constructed and sent entirely by the dialog layer on
089: * behalf of the SipListener. Under such circumstances, it makes sense to let
090: * the dialog support handle the response and not bother the SipListener with
091: * it. The SipListener will not be notified with the RequestEvent upon which the
092: * Response was sent on its behalf by the Dialog layer. However, if no Dialog is
093: * registered for the transaction either automatically or under application
094: * control, then the SipListener is expected to generate and send the
095: * appropriate (error) response.
096: *
097: * <p>
098: * <b>For example:</b> In <a href =
099: * "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a> Chapter 14 a User Agent
100: * Server that receives a second INVITE before it sends the final response to a
101: * first INVITE with a lower CSeq sequence number on the same dialog MUST return
102: * a 500 (Server Internal Error) response to the second INVITE and MUST include
103: * a Retry-After header field with a randomly chosen value of between 0 and 10
104: * seconds.
105: *
106: * In this release of this specification, the implementation handles retransmissions of
107: * Responses that are specified as being handled by the UA core, if there is an
108: * associated Dialog for a given transaction.
109: * If there is no associated Dialog for a given transaction, the application
110: * will be alerted to perform the retransmissions required by the UA core if
111: * desired. Applications should explicitly request such alerts see
112: * {@link ServerTransaction#enableRetransmissionAlerts()}. Once enabled the
113: * SipProvider will deliver retransmission timer
114: * events to the Listener with a {@link Timeout#RETRANSMIT} notification. The
115: * SipListener can then retransmit the Response as necessary, see
116: * {@link SipListener#processTimeout(TimeoutEvent)}.
117: * <p>
118: * For INVITE Client Transactions:
119: * <ul>
120: * <li>UAC ACKs first 2xx response </li>
121: * <li>Additional 2xx responses will be ACKed automatically if a Dialog is
122: * asssociated with the response</li>
123: * <li>Additional 2xx responses will be presented to the listener if no dialog
124: * is associated with the response. In such a case the listener is expected to
125: * ACK the 2xx response.
126: * </ul>
127: *
128: * For INVITE Server Transaction 2xx response:
129: * <ul>
130: * <li> Application sends first 2xx response {@link ServerTransaction#sendResponse(Response)}.
131: * <li> If a Dialog is not associated with a ServerTransaction, and if the
132: * application explicitly requests to be notified of such timeouts (see
133: * {@link ServerTransaction#enableRetransmissionAlerts()} the SipListener is
134: * periodically alerted to retransmit 2xx responses for the ServerTransaction.</li>
135: * <li> If a Dialog is associated with a ServerTransaction then the
136: * implementation takes care of retransmitting final responses until the ACK is
137: * received i.e. the SipListener will receive no notifications to retransmit
138: * responses.
139: * </ul>
140: *
141: * For an INVITE server Transaction 300-699 response:
142: * <ul>
143: * <li> Either the application or the dialog layer sends the first response
144: * <li> Retransmissions of 300-699 responses from the INVITE Server Transaction
145: * are handled by the transaction layer independent of existence of an
146: * associated Dialog.
147: * </ul>
148: *
149: * Because reliable provisional responses are always sent by the Dialog layer,
150: * the Dialog layer takes care of retrasmitting these. The application is never
151: * alerted for retransmissions of Reliable Provisional responses:
152: * <ul>
153: * <li> The application sends a reliable provisional Response to an Invite
154: * Dialog using {@link javax.sip.Dialog#sendReliableProvisionalResponse(Response) }
155: * <li> The Stack takes care of retransmitting the provisional response with
156: * exponentially increasing intervals until a PRACK is received or the
157: * Transaction times out.
158: * </ul>
159: *
160: * Processing Forking INVITES:
161: * <p>
162: * Multiple 2xx responses may arrive at the UAC for a single INVITE request due
163: * to a forking proxy. Each response is distinguished by the tag parameter in
164: * the TO header field, and each represents a distinct Dialog, with a distinct
165: * Dialog identifier. In this case the first 2xx terminates the original INVITE
166: * additional 2xx responses will be presented to the SipListener as a ResponseEvent
167: * with null Client Transaction ID but with a valid and distinct Dialog. The
168: * Listener is expected to ACK the 2xx response - otherwise the Dialog is
169: * terminated after a timeout period. Note that unless automatic dialog creation
170: * is explictly disabled, the 2xx ResponseEvent will always contain a Dialog whether
171: * or not the outgoing INVITE was sent through a ClientTransaction or statelessly
172: * via a SipProvider.
173: *
174: * @author BEA Systems, NIST
175: * @version 1.2
176: */
177:
178: public interface Dialog extends Serializable {
179:
180: /**
181: * Returns the Address identifying the local party. This is the value of the
182: * From header of locally initiated requests in this dialog when acting as
183: * an User Agent Client.
184: * <p>
185: * This is the value of the To header of received responses in this dialog
186: * when acting as an User Agent Server.
187: *
188: * @return the address object of the local party.
189: */
190: public Address getLocalParty();
191:
192: /**
193: * Returns the Address identifying the remote party. This is the value of
194: * the To header of locally initiated requests in this dialog when acting as
195: * an User Agent Client.
196: * <p>
197: * This is the value of the From header of recieved responses in this dialog
198: * when acting as an User Agent Server.
199: *
200: * @return the address object of the remote party.
201: */
202: public Address getRemoteParty();
203:
204: /**
205: * Returns the Address identifying the remote target. This is the value of
206: * the Contact header of received Responses for target refresh Requests in
207: * this dialog when acting as an User Agent Client.
208: * <p>
209: * This is the value of the Contact header of received target refresh
210: * Requests Requests in this dialog when acting as an User Agent Server.
211: *
212: * @return the address object of the remote target.
213: */
214: public Address getRemoteTarget();
215:
216: /**
217: * Get the dialog identifier of this dialog. A dialog Id is associated with
218: * all responses and with any request that contains a tag in the To field.
219: * The rules for computing the dialog Id of a message depends on whether the
220: * SIP element is a User Agent Client or User Agent Server and applies to
221: * both requests and responses.
222: * <ul>
223: * <li>User Agent Client - the Call-Id value of the dialog Id is set to the
224: * Call-Id of the message, the remote tag is set to the tag in the To field
225: * of the message, and the local tag is set to the tag in the From field of
226: * the message.
227: * <li>User Agent Server - the Call-Id value of the dialog Id is set to the
228: * Call-Id of the message, the remote tag is set to the tag in the From
229: * field of the message, and the local tag is set to the tag in the To field
230: * of the message.
231: * </ul>
232: *
233: * @return the string identifier for this dialog.
234: */
235: public String getDialogId();
236:
237: /**
238: * Returns the Call-Id for this dialog. This is the value of the Call-Id
239: * header for all messages belonging to this session.
240: *
241: * @return the Call-Id for this dialog
242: */
243: public CallIdHeader getCallId();
244:
245: /**
246: * The local sequence number is used to order requests from this User Agent
247: * Client to its peer User Agent Server. The local sequence number MUST be
248: * set to the value of the sequence number in the CSeq header field of the
249: * request. The remote sequence number MUST be empty as it is established
250: * when the remote User Agent sends a request within the dialog.
251: * <p>
252: * Requests within a dialog MUST contain strictly monotonically increasing
253: * and contiguous CSeq sequence numbers (increasing-by-one) in each
254: * direction (excepting ACK and CANCEL, whose numbers equal the requests
255: * being acknowledged or cancelled). Therefore, if the local sequence number
256: * is not empty, the value of the local sequence number MUST be incremented
257: * by one, and this value MUST be placed into the CSeq header field. If the
258: * local sequence number is empty, an initial value MUST be chosen.
259: *
260: * @deprecated This method is replaced with {@link #getLocalSeqNumber()} with
261: * type long.
262: * @see #getLocalSeqNumber()
263: *
264: * @return the integer value of the local sequence number, returns zero if
265: * not set.
266: */
267: public int getLocalSequenceNumber();
268:
269: /**
270: * The local sequence number is used to order requests from this User Agent
271: * Client to its peer User Agent Server. The local sequence number MUST be
272: * set to the value of the sequence number in the CSeq header field of the
273: * request. The remote sequence number MUST be empty as it is established
274: * when the remote User Agent sends a request within the dialog.
275: * <p>
276: * Requests within a dialog MUST contain strictly monotonically increasing
277: * and contiguous CSeq sequence numbers (increasing-by-one) in each
278: * direction (excepting ACK and CANCEL, whose numbers equal the requests
279: * being acknowledged or cancelled). Therefore, if the local sequence number
280: * is not empty, the value of the local sequence number MUST be incremented
281: * by one, and this value MUST be placed into the CSeq header field. If the
282: * local sequence number is empty, an initial value MUST be chosen.
283: *
284: * @return the value of the local sequence number, returns zero if
285: * not set.
286: * @since v1.2
287: */
288: public long getLocalSeqNumber();
289:
290: /**
291: * The remote sequence number is used to order requests from its peer User
292: * Agent Client to this User Agent Server. When acting an User Agent Server
293: * the remote sequence number MUST be set to the value of the sequence
294: * number in the CSeq header field of the request from the User Agent
295: * Client. The local sequence number MUST be empty.
296: * <p>
297: * If the remote sequence number is empty, it MUST be set to the value of
298: * the sequence number in the CSeq header field value in the request. If the
299: * remote sequence number was not empty, but the sequence number of the
300: * request is lower than the remote sequence number, the request is out of
301: * order and MUST be rejected with a 500 (Server Internal Error) response.
302: * If the remote sequence number was not empty, and the sequence number of
303: * the request is greater than the remote sequence number, the request is in
304: * order.
305: *
306: * @deprecated This method is replaced with {@link #getRemoteSeqNumber()} with
307: * type long.
308: * @see #getRemoteSeqNumber()
309: * @return the integer value of the remote sequence number, return zero if
310: * not set.
311: */
312: public int getRemoteSequenceNumber();
313:
314: /**
315: * The remote sequence number is used to order requests from its peer User
316: * Agent Client to this User Agent Server. When acting an User Agent Server
317: * the remote sequence number MUST be set to the value of the sequence
318: * number in the CSeq header field of the request from the User Agent
319: * Client. The local sequence number MUST be empty.
320: * <p>
321: * If the remote sequence number is empty, it MUST be set to the value of
322: * the sequence number in the CSeq header field value in the request. If the
323: * remote sequence number was not empty, but the sequence number of the
324: * request is lower than the remote sequence number, the request is out of
325: * order and MUST be rejected with a 500 (Server Internal Error) response.
326: * If the remote sequence number was not empty, and the sequence number of
327: * the request is greater than the remote sequence number, the request is in
328: * order.
329: *
330: *
331: * @return the value of the remote sequence number, return zero if
332: * not set.
333: * @since v1.2
334: */
335: public long getRemoteSeqNumber();
336:
337: /**
338: * When acting as an User Agent Server the routeset MUST be set to the list
339: * of URIs in the Record-Route header field from the request, taken in order
340: * and preserving all URI parameters. When acting as an User Agent Client
341: * the route set MUST be set to the list of URIs in the Record-Route header
342: * field from the response, taken in reverse order and preserving all URI
343: * parameters. If no Record-Route header field is present in the request or
344: * response, the route set MUST be set to the empty set. This route set,
345: * even if empty, overrides any pre-existing route set for future requests
346: * in this dialog.
347: * <p>
348: * Requests within a dialog MAY contain Record-Route and Contact header
349: * fields. However, these requests do not cause the dialog's route set to be
350: * modified.
351: * <p>
352: * The User Agent Client uses the remote target and route set to build the
353: * Request-URI and Route header field of the request.
354: *
355: * @return an Iterator over a list of route headers to be used for
356: * forwarding.
357: */
358: public Iterator getRouteSet();
359:
360: /**
361: * Returns true if this Dialog is secure, for example if the request was sent over a
362: * "sips:" scheme, or a "sip:" scheme over TLS.
363: *
364: * @return <code>true</code> if this dialog was secure, and
365: * <code>false</code> otherwise.
366: */
367: public boolean isSecure();
368:
369: /**
370: * Returns whether this Dialog is a server dialog, for example this side
371: * was initially acting as a UAS.
372: *
373: * @return <code>true</code> if this is a server dialog and
374: * <code>false</code> if it is a client dialog.
375: */
376: public boolean isServer();
377:
378: /**
379: * This method may be used to increment the local sequence number of the
380: * dialog when an application wishes to switch from dialog stateful mode to
381: * transaction stateful mode for client transactions and back again to
382: * dialog stateful mode. Note, the Dialog layer automatically increments the
383: * local sequence number when a request is sent out via the Dialog. However
384: * in special circumstances applications may wish to send a request (from a
385: * sequence of dialog requests) outside of the Dialog using the
386: * {@link ClientTransaction#sendRequest()} method. When sending a request
387: * using the Transaction the Dialog state is unaffected.
388: */
389: public void incrementLocalSequenceNumber();
390:
391: /**
392: * Creates a new Request message based on the dialog creating request. This
393: * method should be used for but not limited to creating Bye's, Refer's and
394: * re-Invite's on the Dialog. The returned Request will be correctly
395: * formatted that is the Dialog implementation is responsible for assigning
396: * the following:
397: * <ul>
398: * <li> RequestURI
399: * <li> FromHeader
400: * <li> ToHeader
401: * <li> CallIdHeader
402: * <li> RouteHeaders
403: * </ul>
404: * The CSeqHeader will be set when the message is sent. If this method
405: * returns a CSeqHeader in the Request it may be overwritten again by the
406: * {@link Dialog#sendRequest(ClientTransaction)} method. Therefore any
407: * Request created by this method must be sent via the
408: * {@link Dialog#sendRequest(ClientTransaction)} method and not via its
409: * {@link ClientTransaction#sendRequest()} method.
410: * <p>
411: * All other headers including any Authentication related headers, and
412: * record route headers should be assigned by the application to the
413: * generated request. The assignment of the topmost via header for the
414: * outgoing request may be deferred until the application creates a
415: * ClientTransaction to send the request out. This method does not increment
416: * the dialog sequence number. This method may not be used for creating
417: * PRACK or ACK. Implementations should throw SipException if this method is
418: * called for creating ACK or PRACK.
419: *
420: * @param method
421: * the string value that determines if the request to be created.
422: * @return the newly created Request message on this Dialog.
423: * @throws SipException
424: * if the Dialog is not yet established (i.e. dialog state
425: * equals null) or is terminated or if the method is invoked for
426: * ACK or PRACK.
427: *
428: */
429: public Request createRequest(String method) throws SipException;
430:
431: /**
432: * Creates a new reliable provisional response based on an Invite request
433: * that created this Dialog or that is now refreshing this Dialog. This new
434: * Response does not contain a body. Only the required headers are copied
435: * from the Request. The response will include also the following headers:
436: * <ul>
437: * <li> RequireHeader
438: * <li> RSeqHeader
439: * </ul>
440: * The RequireHeader will include the 100rel option tag. The Dialog will
441: * handle the RSeq count that will be updated and icreased if needed when
442: * the reliable provisional response is sent. Any Response created by this
443: * method must be sent via the
444: * {@link Dialog#sendReliableProvisionalResponse( Response)} method.
445: * <p>
446: *
447: * @since 1.2
448: *
449: * @param statusCode
450: * the new integer of the statusCode value of this Message.
451: * @return the newly created Response object.
452: * @throws InvalidArgumentException
453: * when an invalid status code or request method is supplied.
454: * @throws SipException when the Dialog is not a server dialog or if this
455: * method is called after a final response is sent to the
456: * ServerTransactin that created the Dialog.
457: *
458: */
459: public Response createReliableProvisionalResponse(int statusCode)
460: throws InvalidArgumentException, SipException;
461:
462: /**
463: * Sends a Request to the remote party of this dialog. When an application
464: * wishes to send a Request message on this dialog, it creates a Request and
465: * creates a new ClientTransaction to handle this request from
466: * {@link SipProvider#getNewClientTransaction(Request)}. This
467: * ClientTransaction is passed to this method to send the request. The
468: * Request message gets sent via the ListeningPoint information of the
469: * SipProvider that is associated to this ClientTransaction.
470: * <p>
471: * This method implies that the application is functioning as UAC hence the
472: * underlying SipProvider acts statefully. This method is useful for sending
473: * Bye's to terminate a dialog or Re-Invites/Refers on the Dialog for third
474: * party call control, call hold etc.
475: * <p>
476: * This method will set the From and the To tags for the outgoing request.
477: * This method increments the dialog sequence number and sets the correct
478: * sequence number to the outgoing Request and associates the client
479: * transaction with this dialog. Note that any tags assigned by the user
480: * will be over-written by this method. If the caller sets no RouteHeader in
481: * the Request to be sent out, the implementation of this method will add
482: * the RouteHeader from the routes that are mantained in the dialog. If the
483: * caller sets the RouteHeader's, the implementation will leave the route
484: * headers unaltered. This allows the application to manage its own route
485: * set if so desired.
486: * <p>
487: * The User Agent traditionally must not send a BYE on a confirmed INVITE
488: * until it has received an ACK for its 2xx response or until the server
489: * transaction timeout is received.
490: * <p>
491: * A Dialog may be created by an INVITE request and subsequently
492: * SUBSCRIBE/NOTIFY are sent withing that Dialog. In this case the
493: * application may call {@link Dialog#terminateOnBye } to prevent the Dialog
494: * from Terminating upon reciept of a BYE.
495: *
496: * @param clientTransaction -
497: * the new ClientTransaction object identifying this transaction,
498: * this clientTransaction should be requested from
499: * {@link SipProvider#getNewClientTransaction(Request)}
500: * @throws TransactionDoesNotExistException
501: * if the clientTransaction does not correspond to any existing
502: * client transaction.
503: * @throws SipException
504: * if implementation cannot send the Request for any reason.
505: */
506: public void sendRequest(ClientTransaction clientTransaction)
507: throws TransactionDoesNotExistException, SipException;
508:
509: /**
510: * Sends a reliable provisional response to the remote party of this dialog.
511: * When an application wishes to send a reliable provisional response on the
512: * Invite transaction that created this dialog or that is now refreshing
513: * this dialog, it creates a reliable provisional response message with
514: * {@link Dialog#createReliableProvisionalResponse(int)}. This Response is
515: * passed to this method that sends it. This method will update the RSeq
516: * header of the response if needed and will increase the RSeq count of the
517: * Transaction. The application will not be able to send further reliable
518: * provisional responses for this Dialog until PRACK is received for a
519: * previously sent provisional response. The only response that can be sent
520: * in parallel with an active reliable Provisional Response is a final
521: * response. The Final response will stop retransmission of the reliable
522: * responses.
523: * <p>
524: *
525: * @since 1.2
526: *
527: * @param relResponse -
528: * the reliable provisional response
529: * @throws SipException
530: * if implementation cannot send the Request for any reason
531: * (e.g. because another reliable response is still pending).
532: */
533: public void sendReliableProvisionalResponse(Response relResponse)
534: throws SipException;
535:
536: /**
537: * Creates a new PRACK Request message based on a reliable provisional
538: * response received by this Dialog and the Dialog internal information. The
539: * returned Request will be correctly formatted that is the Dialog
540: * implementation is responsible for assigning the following:
541: * <ul>
542: * <li> RequestURI
543: * <li> FromHeader
544: * <li> ToHeader
545: * <li> CallIdHeader
546: * <li> RouteHeaders
547: * <li> RAckHeader
548: * </ul>
549: * The CSeqHeader will be set when the message is sent. If this method
550: * returns a CSeqHeader in the Request it may be overwritten again by the
551: * {@link Dialog#sendRequest(ClientTransaction)} method. Therefore any
552: * Request created by this method must be sent via the
553: * {@link Dialog#sendRequest(ClientTransaction)} method and not via its
554: * {@link ClientTransaction#sendRequest()} method.
555: * <p>
556: * All other headers including any Authentication related headers, and
557: * record route headers should be assigned by the application to the
558: * generated request. The assignment of the topmost via header for the
559: * outgoing request may be deferred until the application creates a
560: * ClientTransaction to send the request out. This method does not increment
561: * the dialog sequence number.
562: *
563: * @param relResponse
564: * the reliable provisional response that should result in a
565: * prack reques.
566: * @return the newly created Request message on this Dialog.
567: * @throws SipException
568: * if the Method of the transaction that created the Dialog or
569: * Refeshing the Dialog is not an INVITE ( for example
570: * SUBSCRIBE).
571: * @throws DialogDoesNotExistException
572: * if the Dialog is not yet established (i.e. dialog state
573: * equals null) or is terminated.
574: * @since 1.2
575: */
576: public Request createPrack(Response relResponse)
577: throws DialogDoesNotExistException, SipException;
578:
579: /**
580: * Creates an ACK request for an Invite that was responded with 2xx
581: * response. The cseq number for the invite is supplied to relate the ACK to
582: * its original invite request.
583: *
584: * @param cseq -
585: * the CSeq number to be placed in the ACK request.
586: * @return The newly created ACK request message.
587: * @throws InvalidArgumentException
588: * if there is a problem with the supplied cseq ( for example <=
589: * 0 ).
590: * @throws SipException
591: * if the cseq does not relate to a previously sent INVITE or if
592: * the Method that created the Dialog is not an INVITE ( for
593: * example SUBSCRIBE)
594: * @since 1.2
595: */
596: public Request createAck(long cseq)
597: throws InvalidArgumentException, SipException;
598:
599: /**
600: * Sends ACK Request to the remote party of this dialog. This method implies
601: * that the application is functioning as User Agent Client hence the
602: * underlying SipProvider acts statefully. This method does not increment
603: * the local sequence number.
604: *
605: * @param ackRequest -
606: * the new ACK Request message to send.
607: * @throws SipException
608: * if implementation cannot send the ACK Request for any reason
609: */
610: public void sendAck(Request ackRequest) throws SipException;
611:
612: /**
613: * Returns the current DialogState of the dialog or null. A dialog that is
614: * created but not yet mapped to any state must return null, multiple
615: * requests can be generated on the Dialog in a null state. The dialog
616: * states for INVITE transaction are:
617: * <ul>
618: * <li> Early - A dialog is in the "early" state, which occurs when it is
619: * created when a provisional response is recieved to the INVITE Request.
620: * <li> Confirmed - A dialog transitions to the "confirmed" state when a 2xx
621: * final response is received to the INVITE Request.
622: * <li> Terminated - A dialog transitions to the "terminated" state for all
623: * other reasons or if no response arrives at all on the dialog.
624: * </ul>
625: *
626: * A Subscibe/Refer dialog has the following states:
627: * <ul>
628: * <li> Null - refers to a state that is not terminated.
629: * <li> Terminated - when the Application deletes the Dialog or if no
630: * response arrives at all.
631: * </ul>
632: *
633: * Independent of the method, if a request outside of a dialog generates a
634: * non-2xx final response, any early dialogs created through provisional
635: * responses to that request are "terminated". If no response arrives at all
636: * on the early dialog it is also "terminated".
637: *
638: * @return a DialogState determining the current state of the dialog.
639: * @see DialogState
640: */
641: public DialogState getState();
642:
643: /**
644: * This method will release all resources associated with this dialog that
645: * are tracked by the SipProvider. Further references to the dialog by
646: * incoming messages will result in a mismatch. This delete method is
647: * provided methods that do not expect a BYE to terminate a dialog. Such is
648: * the case with SUBSCRIBE/NOTIFY within a Dialog that is created with an
649: * INIVTE.
650: *
651: */
652: public void delete();
653:
654: /**
655: * This method retrieves the transaction which resulted in the creation of
656: * this Dialog. The transaction type either server or client can be
657: * determined based on whether this is a server or client Dialog, see
658: * {@link Dialog#isServer()}.
659: *
660: * @deprecated Since v1.2. Reduces the amount of state that
661: * the stack needs to keep track of.
662: * @return the Transaction that created the Dialog.
663: */
664: public Transaction getFirstTransaction();
665:
666: /**
667: * Get the Local Tag of this Dialog. On the client side, this tag is
668: * assigned to outgoing From headers for Requests within the dialog and To
669: * headers for responses within the dialog. On the server side, this tag is
670: * associated with outgoing To headers for responses within the dialog.
671: */
672: public String getLocalTag();
673:
674: /**
675: * Gets the Remote Tag of this Dialog. On the client side, this tag is
676: * associated with outgoing To headers for Requests within the dialog. On
677: * the server side, this tag is associated with incoming From headers for
678: * requests within the dialog.
679: */
680: public String getRemoteTag();
681:
682: /**
683: * Sets application specific data to this dialog. This specification does
684: * not define the format of this data. This is the responsibility of the
685: * application and is dependent upon the application. This method can be
686: * used to link the call state of this dialog to other state, SIP or
687: * otherwise in the system. For example this method could be used by a
688: * SIP-to-H323 interworking node that would associate the H323 call state
689: * associated with a call on the H323 side with this dialog that represents
690: * this call on the SIP side. Or a dialog stateful proxy can associate the
691: * UAS dialog to the UAC dialog and vice versa.
692: *
693: * @param applicationData
694: * the new object containing application specific data.
695: */
696: public void setApplicationData(Object applicationData);
697:
698: /**
699: * Gets the application specific data specific to this dialog. This
700: * specification does not define the format of this application specific
701: * data. This is the responsibility of the application.
702: *
703: * @return the object representation of the application specific data.
704: */
705: public Object getApplicationData();
706:
707: /**
708: * Terminate Dialog on BYE. If this flag is set to true then the stack will
709: * Terminate the dialog automatically when BYE is received. This is the
710: * default behavior. This method is useful for SUBSCRIBE/NOTIFY processing
711: * within a Dialog. In the case that several subscriptions are associated
712: * with a single Dialog, the Dialog does not terminate until all the
713: * subscriptions in it are destroyed. Hence, if the application is aware of
714: * active subscriptions in a dialog it should set this flag to false. In
715: * this case when BYE is received the dialog will not be terminated and it
716: * will be the application’s responsibility to call the
717: * {@link Dialog#delete()} function when all active subscriptions are
718: * terminated.
719: *
720: * @param terminateFlag --
721: * if true then the dialog is terminated when a BYE is received.
722: * @throws SipException --
723: * if the dialog is already terminated.
724: * @since 1.2
725: *
726: */
727: public void terminateOnBye(boolean terminateFlag)
728: throws SipException;
729:
730: }
|