All Downloads are FREE. Search and download functionalities are using the official Maven repository.

android.javax.sip.ClientTransaction Maven / Gradle / Ivy

There is a newer version: 1.3.0-91
Show newest version
/**
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * Unpublished - rights reserved under the Copyright Laws of the United States.
 * Copyright � 2003 Sun Microsystems, Inc. All rights reserved.
 * Copyright � 2005 BEA Systems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * This distribution may include materials developed by third parties. 
 *
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *
 * Module Name   : JSIP Specification
 * File Name     : ClientTransaction.java
 * Author        : Phelim O'Doherty
 *
 *  HISTORY
 *  Version   Date      Author              Comments
 *  1.1     08/10/2002  Phelim O'Doherty    Initial version
 *  1.2     16/06/2005  Phelim O'Doherty    Deprecated createAck method.
 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */
package android.javax.sip;


import android.javax.sip.message.Request;

/**
 * A client transaction is used by a User Agent Client application to send 
 * Request messages to a User Agent Server application. 
 * The client transaction is also used to match Responses from the User Agent 
 * Server to fire Response events to the SipListener for a specific client 
 * transaction. This interfaces enables an application to send a 
 * {@link android.javax.sip.message.Request}'s statefully. A new client transaction 
 * is generated by the application calling the 
 * {@link SipProvider#getNewClientTransaction(Request)} method. 
 * 

* A client transaction of the transaction layer is represented by a finite * state machine that is constructed to process a particular request under * the covers of a stateful SipProvider. The transaction layer handles * application-layer retransmissions, matching of responses to requests, and * application-layer timeouts. Any task that a User Agent Client * accomplishes takes place using a series of transactions. *

* The client transaction must be unique within the underlying * implementation. A common way to create this value is to compute a * cryptographic hash of the To tag, From tag, Call-ID header field, the * Request-URI of the request received (before translation), the topmost Via * header, and the sequence number from the CSeq header field, in addition to * any Proxy-Require and Proxy-Authorization header fields that may be present. * The algorithm used to compute the hash is implementation-dependent. *

* For the detailed client transaction state machines refer to Chapter * 17 of RFC 3261, the * allowable transitions are summarized below: *

* Invite Transaction:
* Calling --> Proceeding --> Completed --> Terminated *

* Non-Invite Transaction:
* Trying --> Proceeding --> Completed --> Terminated * * @author BEA Systems, NIST * @version 1.2 */ public interface ClientTransaction extends Transaction { /** * Sends the Request which created this ClientTransaction. When an * application wishes to send a Request message, it creates a Request from * the {@link android.javax.sip.message.MessageFactory} and then creates a new * ClientTransaction from * {@link SipProvider#getNewClientTransaction(Request)}. Calling this method * on the ClientTransaction sends the Request onto the network. The Request * message gets sent via the ListeningPoint information of the SipProvider * that is associated to this ClientTransaction. *

* This method assumes that the Request is sent out of Dialog. It uses * the Router to determine the next hop. If the Router returns a empty * iterator, and a Dialog is associated with the outgoing request of the * Transaction then the Dialog route set is used to send the outgoing * request. *

* This method implies that the application is functioning as either a UAC * or a stateful proxy, hence the underlying implementation acts statefully. * * @throws SipException if the SipProvider cannot send the Request for any * reason. * @see Request */ public void sendRequest() throws SipException; /** * Creates a new Cancel message from the Request associated with this client * transaction. The CANCEL request, is used to cancel the previous request * sent by this client transaction. Specifically, it asks the UAS to cease * processing the request and to generate an error response to that request. * A CANCEL request constitutes its own transaction, but also references * the transaction to be cancelled. CANCEL has no effect on a request to * which a UAS has already given a final response. *

* Note that both the transaction corresponding to the original request and * the CANCEL transaction will complete independently. However, a UAC * canceling a request cannot rely on receiving a 487 (Request Terminated) * response for the original request, as an RFC 2543 compliant UAS will * not generate such a response. Therefore if there is no final response for * the original request the application will receieve a TimeoutEvent with * {@link android.javax.sip.Timeout#TRANSACTION} and the client should then consider the * original transaction cancelled. *

    *
  • UAC - A UAC should not send a CANCEL request to any request explicitly * supported by this specification other than INVITE request. The reason * being requests other than INVITE are responded to immediately and sending * a CANCEL for a non-INVITE request would always create a race condition. * CANCELs are useful as a UAC can not send a BYE request on a dialog * until receipt of 2xx final response to the INVITE request. The CANCEL * attempts to force a non-2xx response to the INVITE, therefore if a UAC * wishes to give up on its call attempt entirely it can send a CANCEL. *
  • Stateful proxies - A stateful proxy may generate CANCEL requests * for: *
      *
    • INVITE Requests - A CANCEL can be sent on pending INVITE client * transactions based on the period specified in the INVITE's Expires * header field elapsing. However, this is generally unnecessary since * the endpoints involved will take care of signaling the end of the * transaction. *
    • Other Requests - An implementation of this specification does * not need to support CANCELing non-INVITE transactions. *
    *
* * @return the new cancel Request specific to the Request of this client * transaction. * @throws SipException if this method is called to cancel a request that * can't be cancelled i.e. ACK. */ public Request createCancel() throws SipException; /** * Creates a new Ack message from the Request associated with this client * transaction. This ACK can be used to acknowledge the 2xx response to the * request sent by this transaction. * * @return the new ACK Request specific to the Request of this client * transaction. * @throws SipException if this method is called before a final response * is received for the transaction. * @deprecated Since v1.2. As a transaction that received * a 2xx response terminates immediately, it cannot be used for creating * the corresponding ACK. If this transaction created a dialog, the * {@link Dialog#createAck(long)} method * should be used. Otherwise the stack will automatically create and * send the ACK for non-2xx responses that need to be acknowledged. * That is the application should never need to use this method. */ public Request createAck() throws SipException; }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy