Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.cafesip.sipunit
Class SipCall

java.lang.Object
  extended by org.cafesip.sipunit.SipCall
All Implemented Interfaces:
MessageListener, RequestListener, SipActionObject
public class SipCall
extends java.lang.Object
implements SipActionObject, MessageListener

This class is used for handling one leg of a call. That is, it represents an outgoing call leg or an incoming call leg. In a telephone call, there are two call legs. The outgoing call leg is the connection from the phone making the call to the telephone network. The incoming call leg is a connection from the telephone network to the phone being called. For a SIP call, the outbound leg is the User Agent originating the call and the inbound leg is the User Agent receiving the call. For each call leg, a separate SipCall object must be used.

A SipCall object is created by calling SipPhone.createSipCall() or SipPhone.makeCall().

Many of the methods in this class return an object or true return value if successful. In case of an error or caller-specified timeout, a null object or a false is returned. The getErrorMessage(), getReturnCode() and getException() methods may be used for further diagnostics. The getReturnCode() method returns either the SIP response code received from the network (defined in SipResponse) or a SipUnit internal status/return code (defined in SipSession). SipUnit internal codes are in a specially designated range (SipSession.SIPUNIT_INTERNAL_RETURNCODE_MIN and upward). The information provided by the getException() method is only meaningful when the getReturnCode() method returns internal SipUnit return code EXCEPTION_ENCOUNTERED. The getErrorMessage() method returns a descriptive string indicating the cause of the problem. If an exception was involved, this string will contain the name of the Exception class and the exception message. This class has a method, format(), which can be called to obtain a human-readable string containing all of this error information.

Method Summary
 boolean callTimeoutOrError()
          Indicates if the current outgoing call has encountered a response timeout or any kind of error.
 boolean disconnect()
          This method sends a basic BYE message.
 boolean disconnect(java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is the same as the basic disconnect() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message.
 boolean disconnect(java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is the same as the basic disconnect() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API.
 void dispose()
          This method releases all resources associated with this SipCall.
 SipResponse findMostRecentResponse(int statusCode)
          This method returns the last received response with status code matching the given parameter.
 java.lang.String format()
          The format() method can be used to obtain a human-readable string containing the result of the last operation - either a successful indication or all of the error information associated with the last operation performed.
 javax.sip.address.AddressFactory getAddressFactory()
          This method returns the AddressFactory associated with this object.
 java.util.ArrayList<SipRequest> getAllReceivedRequests()
          This method returns all the requests received on this call.
 java.util.ArrayList<SipResponse> getAllReceivedResponses()
          This method returns all the responses received on this call, including any that required re-initiation of the call (ie, authentication challenge).
 java.lang.String getErrorMessage()
          The getErrorMessage() method returns a descriptive, human-readable string indicating the cause of the problem encountered during the last operation performed.
 java.lang.Throwable getException()
          This method is used to get the Exception object generated during the last operation performed.
 javax.sip.header.HeaderFactory getHeaderFactory()
          This method returns the HeaderFactory associated with this object.
 SipRequest getLastReceivedRequest()
          This method returns the last request received on this call.
 SipResponse getLastReceivedResponse()
          This method returns the last response received on this call.
 SipPhone getParent()
          This method returns the SipPhone object associated with this call.
 int getReturnCode()
          This method returns the status code of the current or last operation performed.
 boolean initiateOutgoingCall(java.lang.String toUri, java.lang.String viaNonProxyRoute)
          This method is the same as the basic initiateOutgoingCall() method, without the 'from URI' parameter which will be defaulted to the 'from' address (me) specified when the SipPhone object was created (SipStack.createSipPhone()).
 boolean initiateOutgoingCall(java.lang.String fromUri, java.lang.String toUri, java.lang.String viaNonProxyRoute)
          This basic method is used to initiate an outgoing call.
 boolean initiateOutgoingCall(java.lang.String fromUri, java.lang.String toUri, java.lang.String viaNonProxyRoute, java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is the same as the basic initiateOutgoingCall() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message.
 boolean initiateOutgoingCall(java.lang.String fromUri, java.lang.String toUri, java.lang.String viaNonProxyRoute, java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is the same as the basic initiateOugoingCall() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API.
 boolean isCallAnswered()
          Indicates if the current call (incoming or outgoing) has been answered.
 boolean listenForAck()
          Start listening for an ACK request.
 boolean listenForCancel()
          Start listening for a CANCEL request.
 boolean listenForDisconnect()
          Start listening for a BYE request.
 boolean listenForIncomingCall()
          Start listening for an INVITE request.
 boolean listenForReinvite()
          Start listening for a RE-INVITE request.
 void processEvent(java.util.EventObject event)
          For internal SipUnit use only.
 boolean respondToCancel(SipTransaction siptrans, int statusCode, java.lang.String reasonPhrase, int expires)
          This method sends a basic response to a previously received CANCEL request.
 boolean respondToCancel(SipTransaction siptrans, int statusCode, java.lang.String reasonPhrase, int expires, java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is equivalent to the basic respondToCancel() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message.
 boolean respondToCancel(SipTransaction siptrans, int statusCode, java.lang.String reasonPhrase, int expires, java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is equivalent to the basic respondToCancel() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API.
 boolean respondToDisconnect()
          This method sends a basic response to a previously received BYE request.
 boolean respondToDisconnect(int statusCode, java.lang.String reasonPhrase)
          This method is the same as the basic respondToDisconnect() method except that it uses the given parameters for the status code and reason in the response message sent out.
 boolean respondToDisconnect(int statusCode, java.lang.String reasonPhrase, java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is the same as the basic respondToDisconnect() method except that it uses the given parameters for the status code and reason in the response message sent out and allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message.
 boolean respondToDisconnect(int statusCode, java.lang.String reasonPhrase, java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is the same as the basic respondToDisconnect() method except that it uses the given parameters for the status code and reason in the response message sent out and allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API.
 boolean respondToReinvite(SipTransaction siptrans, int statusCode, java.lang.String reasonPhrase, int expires, java.lang.String newContact, java.lang.String displayName, java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is equivalent to the basic respondToReinvite() method except that it allows the caller to specify additional JAIN-SIP API message headers to add to or replace in the outbound message.
 boolean respondToReinvite(SipTransaction siptrans, int statusCode, java.lang.String reasonPhrase, int expires, java.lang.String newContact, java.lang.String displayName, java.lang.String body, java.lang.String contentType, java.lang.String contentSubType)
          This method sends a basic response to a previously received RE-INVITE request.
 boolean respondToReinvite(SipTransaction siptrans, int statusCode, java.lang.String reasonPhrase, int expires, java.lang.String newContact, java.lang.String displayName, java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is the same as the basic respondToReinvite() plus it additionally allows the caller to specify additional message headers to add to or replace in the response message without requiring knowledge of the JAIN-SIP API.
 SipTransaction sendCancel()
          This method sends a basic CANCEL in a new transaction on the current dialog.
 SipTransaction sendCancel(java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is equivalent to the basic sendCancel() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message.
 SipTransaction sendCancel(java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is equivalent to the basic sendCancel() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API.
 boolean sendIncomingCallResponse(int statusCode, java.lang.String reasonPhrase, int expires)
          This method sends a basic response to a previously received INVITE request.
 boolean sendIncomingCallResponse(int statusCode, java.lang.String reasonPhrase, int expires, java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is the same as the basic sendIncomingCallResponse() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message.
 boolean sendIncomingCallResponse(int statusCode, java.lang.String reasonPhrase, int expires, java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is the same as the basic sendIncomingCallResponse() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API.
 boolean sendInviteOkAck()
          This method sends a basic ACK in response to an OK received in response to a sent INVITE.
 boolean sendInviteOkAck(java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is the same as the basic sendInviteOkAck() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message.
 boolean sendInviteOkAck(java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is the same as the basic sendInviteOkAck() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API.
 SipTransaction sendReinvite(java.lang.String newContact, java.lang.String displayName, java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is equivalent to the basic sendReinvite() method except that it allows the caller to specify additional JAIN-SIP API message headers to add to or replace in the outbound message.
 SipTransaction sendReinvite(java.lang.String newContact, java.lang.String displayName, java.lang.String body, java.lang.String contentType, java.lang.String contentSubType)
          This method sends a basic RE-INVITE on the current dialog.
 SipTransaction sendReinvite(java.lang.String newContact, java.lang.String displayName, java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is the same as the basic sendReinvite() method except that it allows the caller to specify additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API.
 boolean sendReinviteOkAck(SipTransaction siptrans)
          This basic method sends an ACK in response to an OK received in response to a sent RE-INVITE.
 boolean sendReinviteOkAck(SipTransaction siptrans, java.util.ArrayList<javax.sip.header.Header> additionalHeaders, java.util.ArrayList<javax.sip.header.Header> replaceHeaders, java.lang.String body)
          This method is the same as the basic sendReinviteOkAck() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message.
 boolean sendReinviteOkAck(SipTransaction siptrans, java.lang.String body, java.lang.String contentType, java.lang.String contentSubType, java.util.ArrayList<java.lang.String> additionalHeaders, java.util.ArrayList<java.lang.String> replaceHeaders)
          This method is the same as the basic sendReinviteOkAck() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API.
 boolean stopListeningForRequests()
          Stop listening for requests on this user agent.
 boolean waitForAck(long timeout)
          The waitForAck() method waits for an ACK request addressed to this user agent to be received from the network.
 boolean waitForAnswer(long timeout)
          The waitForAnswer() method waits for answer(OK) to be received from the network.
 SipTransaction waitForCancel(long timeout)
          The waitForCancel() method waits for a CANCEL request addressed to this user agent to be received from the network.
 boolean waitForCancelResponse(SipTransaction siptrans, long timeout)
          The waitForCancelResponse() method waits for a response to be received from the network for a sent CANCEL.
 boolean waitForDisconnect(long timeout)
          The waitForDisconnect() method waits for a BYE request addressed to this user agent to be received from the network.
 boolean waitForIncomingCall(long timeout)
          The waitForIncomingCall() method waits for an INVITE request addressed to this user agent to be received from the network.
 SipTransaction waitForReinvite(long timeout)
          The waitForReinvite() method waits for a RE-INVITE request addressed to this user agent to be received from the network.
 boolean waitOutgoingCallResponse()
          This method is the same as the other waitOutgoingCallResponse() method with an indefinite (no) wait timeout.
 boolean waitOutgoingCallResponse(long timeout)
          The waitOutgoingCallResponse() method waits for a response to be received from the network for a sent INVITE.
 boolean waitReinviteResponse(SipTransaction siptrans, long timeout)
          The waitReinviteResponse() method waits for a response to be received from the network for a sent RE-INVITE.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

dispose

public void dispose()
This method releases all resources associated with this SipCall. This SipCall object must not be used again after calling the dispose() method. BYE is sent to the far end if the call dialog is in the confirmed state.

listenForAck

public boolean listenForAck()
Start listening for an ACK request. This is a non-blocking call. Starting from the time this method is called, any received request(s) for this UA are collected. After calling this method, you can call waitForAck() to process the first ACK received since calling this method. NOTE: it's not necessary to call this method if a previous listenForXyz() method has been called and request listening has NOT been turned off since (ie, method stopListeningForRequests() hasn't been called).

Returns:
true unless an error is encountered, in which case false is returned.

listenForDisconnect

public boolean listenForDisconnect()
Start listening for a BYE request. This is a non-blocking call. Starting from the time this method is called, any received request(s) for this UA are collected. After calling this method, call waitForDisconnect() to process the first BYE received since calling this method.

Returns:
true unless an error is encountered, in which case false is returned.

listenForIncomingCall

public boolean listenForIncomingCall()
Start listening for an INVITE request. This is a non-blocking call. Starting from the time this method is called, any received request(s) for this UA are collected. After calling this method, call waitForIncomingCall() to process the first INVITE received since calling this method.

Returns:
true unless an error is encountered, in which case false is returned.

listenForReinvite

public boolean listenForReinvite()
Start listening for a RE-INVITE request. This is a non-blocking call. Starting from the time this method is called, any received request(s) for this UA are collected. After calling this method, call waitForReinvite() to process the first INVITE received since calling this method.

Returns:
true unless an error is encountered, in which case false is returned.

stopListeningForRequests

public boolean stopListeningForRequests()
Stop listening for requests on this user agent. Call this method after calling any of the listenForXxx()/waitForXxx() methods, when no longer looking for an incoming request. IT IS RECOMMENDED THAT THE CALLING PROGRAM STOP LISTENING FOR REQUESTS WHILE NONE ARE EXPECTED. Otherwise alot of overhead is used up and wasted. If there are any pending requests (received but not processed yet), those are discarded.

Returns:
true unless an error is encountered, in which case false is returned.

waitForDisconnect

public boolean waitForDisconnect(long timeout)
The waitForDisconnect() method waits for a BYE request addressed to this user agent to be received from the network. Call this method after calling the listenForDisconnect() method.

This method blocks until one of the following occurs: 1) A BYE request message has been received, addressed to this user agent. In this case, a value of true is returned. The getLastReceivedRequest() method can be called to get information about the received BYE request. Use the method respondToDisconnect() for responding to the received BYE request. 2) The wait timeout period specified by the parameter to this method expires. false is returned in this case. 3) An error occurs. false is returned in this case.

Any non-BYE requests received for this user agent are discarded while waiting for a BYE message.

Regardless of the outcome, incoming requests associated with this User Agent will continue to be queued up until the stopListeningForRequests() method is called. IT IS RECOMMENDED THAT THE CALLING PROGRAM STOP LISTENING FOR REQUESTS WHILE NONE ARE EXPECTED. Otherwise alot of overhead is used up and wasted. Once a listenForXXX() method has been called (pre-requisite to calling this method) and until the stopListeningForRequests() method is called, the calling program can continue to retrieve specific subsequently received requests by calling one of the waitForXxx() methods.

Parameters:
timeout - The maximum amount of time to wait, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
false in the case of wait timeout or error; call getReturnCode() and/or getErrorMessage() and, if applicable, getException() for further diagnostics. A true value is returned if a BYE message was received. Call the getLastReceivedRequest() method to get information about the BYE, and call the respondToDisconnect() method to send a response to the BYE.

waitForIncomingCall

public boolean waitForIncomingCall(long timeout)
The waitForIncomingCall() method waits for an INVITE request addressed to this user agent to be received from the network. Call this method after calling the listenForIncomingCall() method.

This method blocks until one of the following occurs: 1) An INVITE message has been received, addressed to this user agent. In this case, a value of true is returned. The getLastReceivedRequest() method can be called to get information about the received INVITE request. Use the method sendIncomingCallResponse() for responding to the received INVITE. 2) The wait timeout period specified by the parameter to this method expires. False is returned in this case. 3) An error occurs. False is returned in this case.

Any non-INVITE requests received for this user agent are discarded while waiting for an INVITE message.

Regardless of the outcome, incoming requests associated with this User Agent will continue to be queued up until the stopListeningForRequests() method is called. IT IS RECOMMENDED THAT THE CALLING PROGRAM STOP LISTENING FOR REQUESTS WHILE NONE ARE EXPECTED. Otherwise alot of overhead is used up and wasted. Once a listenForXXX() method has been called (pre-requisite to calling this method) and until the stopListeningForRequests() method is called, the calling program can continue to retrieve specific subsequently received requests by calling one of the waitForXxx() methods.

Parameters:
timeout - The maximum amount of time to wait, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
false in the case of wait timeout or error; call getReturnCode() and/or getErrorMessage() and, if applicable, getException() for further diagnostics. A true value is returned if an INVITE message was received. Call the getLastReceivedRequest() method to get information about the INVITE, and call the sendIncomingCallResponse() method to send a response to the INVITE.

waitForAck

public boolean waitForAck(long timeout)
The waitForAck() method waits for an ACK request addressed to this user agent to be received from the network. Prior to calling this method, any of the listenForXyz() methods must have already been called to turn on request listening. You can call this method to wait for any kind of ACK (invite, re-invite...).

This method blocks until one of the following occurs: 1) An ACK request message has been received, addressed to this user agent. In this case, a value of true is returned. The getLastReceivedRequest() method can be called to get information about the received ACK request. 2) The wait timeout period specified by the parameter to this method expires. false is returned in this case. 3) An error occurs. false is returned in this case.

Any non-ACK requests received for this user agent are discarded while waiting for an ACK message.

Regardless of the outcome, incoming requests associated with this User Agent will continue to be queued up until the stopListeningForRequests() method is called. IT IS RECOMMENDED THAT THE CALLING PROGRAM STOP LISTENING FOR REQUESTS WHILE NONE ARE EXPECTED. Otherwise alot of overhead is used up and wasted. Once a listenForXXX() method has been called (pre-requisite to calling this or other 'wait' methods) and until the stopListeningForRequests() method is called, the calling program can continue to retrieve specific subsequently received requests by calling one of the waitForXxx() methods.

Parameters:
timeout - The maximum amount of time to wait, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
false in the case of wait timeout or error; call getReturnCode() and/or getErrorMessage() and, if applicable, getException() for further diagnostics. A true value is returned if an ACK message was received. Call the getLastReceivedRequest() method to get information about the ACK.

sendIncomingCallResponse

public boolean sendIncomingCallResponse(int statusCode,
                                        java.lang.String reasonPhrase,
                                        int expires)
This method sends a basic response to a previously received INVITE request. The response is constructed based on the parameters passed in. Call this method after waitForIncomingCall() returns true. Call this method multiple times to send multiple responses to the received INVITE. The INVITE being responded to must be the last received request on this SipCall.

Parameters:
statusCode - The status code of the response to send (may use SipResponse constants).
reasonPhrase - If not null, the reason phrase to send.
expires - If not -1, an expiration time is added to the response. This parameter indicates the duration the message is valid, in seconds.
Returns:
true if the response was successfully sent, false otherwise.

sendIncomingCallResponse

public boolean sendIncomingCallResponse(int statusCode,
                                        java.lang.String reasonPhrase,
                                        int expires,
                                        java.util.ArrayList<javax.sip.header.Header> additionalHeaders,
                                        java.util.ArrayList<javax.sip.header.Header> replaceHeaders,
                                        java.lang.String body)
This method is the same as the basic sendIncomingCallResponse() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message. Use of this method requires knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
additionalHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message. These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Use null for no additional message headers.
replaceHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message, replacing existing header(s) of that type if present in the message. These headers are applied to the message after a correct message has been constructed. Use null for no replacement of message headers.
body - A String to be used as the body of the message. The additionalHeaders parameter must contain a ContentTypeHeader for this body to be included in the message. Use null for no body bytes.

sendIncomingCallResponse

public boolean sendIncomingCallResponse(int statusCode,
                                        java.lang.String reasonPhrase,
                                        int expires,
                                        java.lang.String body,
                                        java.lang.String contentType,
                                        java.lang.String contentSubType,
                                        java.util.ArrayList<java.lang.String> additionalHeaders,
                                        java.util.ArrayList<java.lang.String> replaceHeaders)
This method is the same as the basic sendIncomingCallResponse() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
body - A String to be used as the body of the message. Parameters contentType, contentSubType must both be non-null to get the body included in the message. Use null for no body bytes.
contentType - The body content type (ie, 'application' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
contentSubType - The body content sub-type (ie, 'sdp' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
additionalHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no additional message headers.
replaceHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message, replacing existing header(s) of that type if present in the message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are applied to the message after a correct message has been constructed. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no replacement of message headers.

waitForReinvite

public SipTransaction waitForReinvite(long timeout)
The waitForReinvite() method waits for a RE-INVITE request addressed to this user agent to be received from the network. Call this method after calling the listenForReinvite() method.

This method blocks until one of the following occurs: 1) An INVITE message has been received on the current dialog. In this case, a non-null SipTransaction object is returned. The getLastReceivedRequest() method can be called to get information about the received RE-INVITE request. The SipTransaction object is required for responding to the received RE-INVITE. Use the method respondToReinvite() for sending a response to the received RE-INVITE. 2) The wait timeout period specified by the parameter to this method expires. Null is returned in this case. 3) An error occurs. Null is returned in this case.

Any non-INVITE requests received for this user agent are discarded while waiting for the RE-INVITE message.

Parameters:
timeout - The maximum amount of time to wait, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
null in the case of wait timeout or error; call getReturnCode() and/or getErrorMessage() and, if applicable, getException() for further diagnostics. A SipTransaction object is returned if a RE-INVITE message was received. Call the getLastReceivedRequest() method to get information about the RE-INVITE, and call the respondToReinvite() method to send a response to the RE-INVITE, passing it the SipTransaction object returned here.

respondToReinvite

public boolean respondToReinvite(SipTransaction siptrans,
                                 int statusCode,
                                 java.lang.String reasonPhrase,
                                 int expires,
                                 java.lang.String newContact,
                                 java.lang.String displayName,
                                 java.lang.String body,
                                 java.lang.String contentType,
                                 java.lang.String contentSubType)
This method sends a basic response to a previously received RE-INVITE request. The response is constructed based on the parameters passed in. Call this method after waitForReinvite() returns non-null. Call this method multiple times to send multiple responses to the received RE-INVITE.

Parameters:
siptrans - This is the object that was returned by method waitForReinvite(). It identifies a specific RE-INVITE transaction.
statusCode - The status code of the response to send (may use SipResponse constants).
reasonPhrase - If not null, the reason phrase to send.
expires - If not -1, an expiration time is added to the response. This parameter indicates the duration the message is valid, in seconds.
newContact - An URI string (ex: sip:bob@192.0.2.4:5093) for updating the remote target URI kept by the far end (target refresh), or null to not change that information.
displayName - Display name to set in the contact header sent to the far end if newContact is not null.
body - A String to be used as the body of the message, for changing the media session. Use null for no body bytes.
contentType - The body content type (ie, 'application' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
contentSubType - The body content sub-type (ie, 'sdp' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
Returns:
true if the response was successfully sent, false otherwise.

respondToReinvite

public boolean respondToReinvite(SipTransaction siptrans,
                                 int statusCode,
                                 java.lang.String reasonPhrase,
                                 int expires,
                                 java.lang.String newContact,
                                 java.lang.String displayName,
                                 java.lang.String body,
                                 java.lang.String contentType,
                                 java.lang.String contentSubType,
                                 java.util.ArrayList<java.lang.String> additionalHeaders,
                                 java.util.ArrayList<java.lang.String> replaceHeaders)
This method is the same as the basic respondToReinvite() plus it additionally allows the caller to specify additional message headers to add to or replace in the response message without requiring knowledge of the JAIN-SIP API. Additional parameters handled by this method include:

Parameters:
additionalHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no additional message headers.
replaceHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message, replacing existing header(s) of that type if present in the message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are applied to the message after a correct message has been constructed. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no replacement of message headers.
Returns:
true if the response was successfully sent, false otherwise.

respondToReinvite

public boolean respondToReinvite(SipTransaction siptrans,
                                 int statusCode,
                                 java.lang.String reasonPhrase,
                                 int expires,
                                 java.lang.String newContact,
                                 java.lang.String displayName,
                                 java.util.ArrayList<javax.sip.header.Header> additionalHeaders,
                                 java.util.ArrayList<javax.sip.header.Header> replaceHeaders,
                                 java.lang.String body)
This method is equivalent to the basic respondToReinvite() method except that it allows the caller to specify additional JAIN-SIP API message headers to add to or replace in the outbound message. Use of this method requires knowledge of the JAIN-SIP API. NOTE: The additionalHeaders parameter passed to this method must contain a ContentTypeHeader in order for a body to be included in the message. The extra parameters supported by this method are:

Parameters:
additionalHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message. These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Use null for no additional message headers.
replaceHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message, replacing existing header(s) of that type if present in the message. These headers are applied to the message after a correct message has been constructed. Use null for no replacement of message headers.
Returns:
true if the response was successfully sent, false otherwise.

respondToDisconnect

public boolean respondToDisconnect()
This method sends a basic response to a previously received BYE request. The response is constructed using a status code of OK. Call this method after waitForDisconnect() returns true. Call this method multiple times to send multiple OK responses to the received BYE. The BYE being responded to must be the last received request on this SipCall.

Returns:
true if the response was successfully sent, false otherwise.

respondToDisconnect

public boolean respondToDisconnect(int statusCode,
                                   java.lang.String reasonPhrase)
This method is the same as the basic respondToDisconnect() method except that it uses the given parameters for the status code and reason in the response message sent out.

Parameters:
statusCode - The integer status code to use (ie, SipResponse.OK).
reasonPhrase - The String reason phrase to use.
Returns:
true if the response was successfully sent, false otherwise.

respondToDisconnect

public boolean respondToDisconnect(int statusCode,
                                   java.lang.String reasonPhrase,
                                   java.util.ArrayList<javax.sip.header.Header> additionalHeaders,
                                   java.util.ArrayList<javax.sip.header.Header> replaceHeaders,
                                   java.lang.String body)
This method is the same as the basic respondToDisconnect() method except that it uses the given parameters for the status code and reason in the response message sent out and allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message. Use of this method requires knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
statusCode - The integer status code to use (ie, SipResponse.OK).
reasonPhrase - The String reason phrase to use.
additionalHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message. These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Use null for no additional message headers.
replaceHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message, replacing existing header(s) of that type if present in the message. These headers are applied to the message after a correct message has been constructed. Use null for no replacement of message headers.
body - A String to be used as the body of the message. The additionalHeaders parameter must contain a ContentTypeHeader for this body to be included in the message. Use null for no body bytes.

respondToDisconnect

public boolean respondToDisconnect(int statusCode,
                                   java.lang.String reasonPhrase,
                                   java.lang.String body,
                                   java.lang.String contentType,
                                   java.lang.String contentSubType,
                                   java.util.ArrayList<java.lang.String> additionalHeaders,
                                   java.util.ArrayList<java.lang.String> replaceHeaders)
This method is the same as the basic respondToDisconnect() method except that it uses the given parameters for the status code and reason in the response message sent out and allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
statusCode - The integer status code to use (ie, SipResponse.OK).
reasonPhrase - The String reason phrase to use.
body - A String to be used as the body of the message. Parameters contentType, contentSubType must both be non-null to get the body included in the message. Use null for no body bytes.
contentType - The body content type (ie, 'application' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
contentSubType - The body content sub-type (ie, 'sdp' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
additionalHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no additional message headers.
replaceHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message, replacing existing header(s) of that type if present in the message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are applied to the message after a correct message has been constructed. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no replacement of message headers.

initiateOutgoingCall

public boolean initiateOutgoingCall(java.lang.String fromUri,
                                    java.lang.String toUri,
                                    java.lang.String viaNonProxyRoute)
This basic method is used to initiate an outgoing call. That is, it applies to the scenario where a UAC is originating a call to the network. There are two ways to make an outgoing call: 1) Use SipPhone.createSipCall() and then call this method, when you need to see intermediate/provisional responses received - you will have to handle each yourself. Or, 2) use one of the SipPhone.makeCall() methods when you want to establish an outgoing call without worrying about the call establishment details (TRYING, authentication challenge, etc.). Regardless, all received responses are collected, so you will be able to see intermediate/provisional responses received (albeit after the fact, with makeCall()).

This method returns when the request message has been sent out. Your calling program must subsequently call the waitOutgoingCallResponse() method (one or more times) to get the result(s), and optionally at some point, waitForAnswer() if you're no longer interested in processing intermediate responses.

Parameters:
fromUri - An URI string (ex: sip:bob@192.0.2.4), or null to use the default 'from' address (me) specified when the SipPhone object was created (SipStack.createSipPhone()).
toUri - The URI (sip:bob@nist.gov) to which the call should be directed
viaNonProxyRoute - Indicates whether to route the INVITE via Proxy or some other route. If null, route the call to the Proxy that was specified when the SipPhone object was created (SipStack.createSipPhone()). Else route it to the given node, which is specified as "hostaddress:port;parms/transport" i.e. 129.1.22.333:5060;lr/UDP.
Returns:
true if the message was successfully sent, false otherwise.

initiateOutgoingCall

public boolean initiateOutgoingCall(java.lang.String fromUri,
                                    java.lang.String toUri,
                                    java.lang.String viaNonProxyRoute,
                                    java.util.ArrayList<javax.sip.header.Header> additionalHeaders,
                                    java.util.ArrayList<javax.sip.header.Header> replaceHeaders,
                                    java.lang.String body)
This method is the same as the basic initiateOutgoingCall() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message. Use of this method requires knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
additionalHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message. These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Use null for no additional message headers.
replaceHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message, replacing existing header(s) of that type if present in the message. These headers are applied to the message after a correct message has been constructed. Use null for no replacement of message headers.
body - A String to be used as the body of the message. The additionalHeaders parameter must contain a ContentTypeHeader for this body to be included in the message. Use null for no body bytes.

initiateOutgoingCall

public boolean initiateOutgoingCall(java.lang.String fromUri,
                                    java.lang.String toUri,
                                    java.lang.String viaNonProxyRoute,
                                    java.lang.String body,
                                    java.lang.String contentType,
                                    java.lang.String contentSubType,
                                    java.util.ArrayList<java.lang.String> additionalHeaders,
                                    java.util.ArrayList<java.lang.String> replaceHeaders)
This method is the same as the basic initiateOugoingCall() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
body - A String to be used as the body of the message. Parameters contentType, contentSubType must both be non-null to get the body included in the message. Use null for no body bytes.
contentType - The body content type (ie, 'application' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
contentSubType - The body content sub-type (ie, 'sdp' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
additionalHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no additional message headers.
replaceHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message, replacing existing header(s) of that type if present in the message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are applied to the message after a correct message has been constructed. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no replacement of message headers.

initiateOutgoingCall

public boolean initiateOutgoingCall(java.lang.String toUri,
                                    java.lang.String viaNonProxyRoute)
This method is the same as the basic initiateOutgoingCall() method, without the 'from URI' parameter which will be defaulted to the 'from' address (me) specified when the SipPhone object was created (SipStack.createSipPhone()).

Parameters:
toUri - The URI (sip:bob@nist.gov) to which the call should be directed
viaNonProxyRoute - Indicates whether to route the INVITE via Proxy or some other route. If null, route the call to the Proxy that was specified when the SipPhone object was created (SipStack.createSipPhone()). Else route it to the given node, which is specified as "hostaddress:port;parms/transport" i.e. 129.1.22.333:5060;lr/UDP.
Returns:
true if the message was successfully sent, false otherwise.

sendReinvite

public SipTransaction sendReinvite(java.lang.String newContact,
                                   java.lang.String displayName,
                                   java.lang.String body,
                                   java.lang.String contentType,
                                   java.lang.String contentSubType)
This method sends a basic RE-INVITE on the current dialog.

This method returns when the request message has been sent out. The calling program must subsequently call the waitReinviteResponse() method (one or more times) to get the response(s) and perhaps the sendReinviteOkAck() method to send an ACK. On the receive side, pertinent methods include waitForReinvite(), respondToReinvite(), and waitForAck().

Parameters:
newContact - An URI string (ex: sip:bob@192.0.2.4:5093) for updating the remote target URI kept by the far end (target refresh), or null to not change that information.
displayName - Display name to set in the contact header sent to the far end if newContact is not null.
body - A String to be used as the body of the message, for changing the media session. Use null for no body bytes.
contentType - The body content type (ie, 'application' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
contentSubType - The body content sub-type (ie, 'sdp' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
Returns:
A SipTransaction object if the message was successfully sent, null otherwise. You don't need to do anything with this returned object other than to pass it to methods that you call subsequently for this operation, namely waitReinviteResponse() and sendReinviteOkAck().

sendReinvite

public SipTransaction sendReinvite(java.lang.String newContact,
                                   java.lang.String displayName,
                                   java.util.ArrayList<javax.sip.header.Header> additionalHeaders,
                                   java.util.ArrayList<javax.sip.header.Header> replaceHeaders,
                                   java.lang.String body)
This method is equivalent to the basic sendReinvite() method except that it allows the caller to specify additional JAIN-SIP API message headers to add to or replace in the outbound message. Use of this method requires knowledge of the JAIN-SIP API. NOTE: The additionalHeaders parameter passed to this method must contain a ContentTypeHeader in order for a body to be included in the message. The extra parameters supported by this method are:

Parameters:
additionalHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message. These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Use null for no additional message headers.
replaceHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message, replacing existing header(s) of that type if present in the message. These headers are applied to the message after a correct message has been constructed. Use null for no replacement of message headers.
Returns:
A SipTransaction object if the message was successfully sent, null otherwise. You don't need to anything with this returned object other than to pass it to methods that you call subsequently for this operation, namely waitReinviteResponse() and sendReinviteOkAck().

sendReinvite

public SipTransaction sendReinvite(java.lang.String newContact,
                                   java.lang.String displayName,
                                   java.lang.String body,
                                   java.lang.String contentType,
                                   java.lang.String contentSubType,
                                   java.util.ArrayList<java.lang.String> additionalHeaders,
                                   java.util.ArrayList<java.lang.String> replaceHeaders)
This method is the same as the basic sendReinvite() method except that it allows the caller to specify additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
additionalHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no additional message headers.
replaceHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message, replacing existing header(s) of that type if present in the message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are applied to the message after a correct message has been constructed. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no replacement of message headers.
Returns:
A SipTransaction object if the message was successfully sent, null otherwise. You don't need to anything with this returned object other than to pass it to methods that you call subsequently for this operation, namely waitReinviteResponse() and sendReinviteOkAck().

sendInviteOkAck

public boolean sendInviteOkAck()
This method sends a basic ACK in response to an OK received in response to a sent INVITE.

Returns:
true if the message was successfully sent, false otherwise.

sendInviteOkAck

public boolean sendInviteOkAck(java.util.ArrayList<javax.sip.header.Header> additionalHeaders,
                               java.util.ArrayList<javax.sip.header.Header> replaceHeaders,
                               java.lang.String body)
This method is the same as the basic sendInviteOkAck() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message. Use of this method requires knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
additionalHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message. These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Use null for no additional message headers.
replaceHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message, replacing existing header(s) of that type if present in the message. These headers are applied to the message after a correct message has been constructed. Use null for no replacement of message headers.
body - A String to be used as the body of the message. The additionalHeaders parameter must contain a ContentTypeHeader for this body to be included in the message. Use null for no body bytes.

sendInviteOkAck

public boolean sendInviteOkAck(java.lang.String body,
                               java.lang.String contentType,
                               java.lang.String contentSubType,
                               java.util.ArrayList<java.lang.String> additionalHeaders,
                               java.util.ArrayList<java.lang.String> replaceHeaders)
This method is the same as the basic sendInviteOkAck() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
body - A String to be used as the body of the message. Parameters contentType, contentSubType must both be non-null to get the body included in the message. Use null for no body bytes.
contentType - The body content type (ie, 'application' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
contentSubType - The body content sub-type (ie, 'sdp' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
additionalHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no additional message headers.
replaceHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message, replacing existing header(s) of that type if present in the message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are applied to the message after a correct message has been constructed. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no replacement of message headers.

sendReinviteOkAck

public boolean sendReinviteOkAck(SipTransaction siptrans)
This basic method sends an ACK in response to an OK received in response to a sent RE-INVITE.

Parameters:
siptrans - This is the object that was returned by method sendReinvite(). It identifies a specific RE-INVITE transaction.
Returns:
true if the message was successfully sent, false otherwise.

sendReinviteOkAck

public boolean sendReinviteOkAck(SipTransaction siptrans,
                                 java.util.ArrayList<javax.sip.header.Header> additionalHeaders,
                                 java.util.ArrayList<javax.sip.header.Header> replaceHeaders,
                                 java.lang.String body)
This method is the same as the basic sendReinviteOkAck() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message. Use of this method requires knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
additionalHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message. These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Use null for no additional message headers.
replaceHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message, replacing existing header(s) of that type if present in the message. These headers are applied to the message after a correct message has been constructed. Use null for no replacement of message headers.
body - A String to be used as the body of the message. The additionalHeaders parameter must contain a ContentTypeHeader for this body to be included in the message. Use null for no body bytes.

sendReinviteOkAck

public boolean sendReinviteOkAck(SipTransaction siptrans,
                                 java.lang.String body,
                                 java.lang.String contentType,
                                 java.lang.String contentSubType,
                                 java.util.ArrayList<java.lang.String> additionalHeaders,
                                 java.util.ArrayList<java.lang.String> replaceHeaders)
This method is the same as the basic sendReinviteOkAck() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
body - A String to be used as the body of the message. Parameters contentType, contentSubType must both be non-null to get the body included in the message. Use null for no body bytes.
contentType - The body content type (ie, 'application' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
contentSubType - The body content sub-type (ie, 'sdp' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
additionalHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no additional message headers.
replaceHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message, replacing existing header(s) of that type if present in the message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are applied to the message after a correct message has been constructed. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no replacement of message headers.

waitOutgoingCallResponse

public boolean waitOutgoingCallResponse()
This method is the same as the other waitOutgoingCallResponse() method with an indefinite (no) wait timeout.

Returns:
true if a response was received - in that case, call getReturnCode() to get the status code that was contained in the received response, or call getLastReceivedResponse() to see the response details. Returns false if timeout or error.

waitOutgoingCallResponse

public boolean waitOutgoingCallResponse(long timeout)
The waitOutgoingCallResponse() method waits for a response to be received from the network for a sent INVITE. Call this method after calling initiateOutgoingCall() (or SipPhone.makeCall() if you know the transaction is still up).

This method blocks until one of the following occurs: 1) A response message has been received. In this case, a value of true is returned. Call the getLastReceivedResponse() method to get the response details. Use the method sendInviteOkAck() for responding to an OK. 2) A timeout occurs. A false value is returned in this case. 3) An error occurs. False is returned in this case.

Regardless of the outcome, getReturnCode() can be called after this method returns to get the status code: IE, the SIP response code received from the network (defined in SipResponse, along with the corresponding textual equivalent) or a SipUnit internal status/return code (defined in SipSession, along with the corresponding textual equivalent). SipUnit internal codes are in a specially designated range (SipSession.SIPUNIT_INTERNAL_RETURNCODE_MIN and upward).

This method can be called repeatedly to get each subsequently received response.

Parameters:
timeout - The maximum amount of time to wait, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
true if a response was received - in that case, call getReturnCode() to get the status code that was contained in the received response, and/or call getLastReceivedResponse() to see the response details. Returns false if timeout or error.

waitReinviteResponse

public boolean waitReinviteResponse(SipTransaction siptrans,
                                    long timeout)
The waitReinviteResponse() method waits for a response to be received from the network for a sent RE-INVITE. Call this method after calling sendReinvite().

This method blocks until one of the following occurs: 1) A response message has been received. In this case, a value of true is returned. Call the getLastReceivedResponse() method to get the response details. Use the method sendReinviteOkAck() for responding to an OK. 2) A timeout occurs. A false value is returned in this case. 3) An error occurs. False is returned in this case.

Regardless of the outcome, getReturnCode() can be called after this method returns to get the status code: IE, the SIP response code received from the network (defined in SipResponse, along with the corresponding textual equivalent) or a SipUnit internal status/error code (defined in SipSession, along with the corresponding textual equivalent). SipUnit internal codes are in a specially designated range (SipSession.SIPUNIT_INTERNAL_RETURNCODE_MIN and upward).

This method can be called repeatedly to get each subsequently received response for this particular RE-INVITE transaction.

Parameters:
siptrans - This is the object that was returned by method sendReinvite(). It identifies a specific RE-INVITE transaction.
timeout - The maximum amount of time to wait, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
true if a response was received - in that case, call getReturnCode() to get the status code that was contained in the received response, and/or call getLastReceivedResponse() to see the response details. Returns false if timeout or error.

disconnect

public boolean disconnect()
This method sends a basic BYE message. It incorporates required authorization headers that have previously been accumulated during the call. This SipCall object will handle an authentication request received in response to the BYE.

Returns:
true if the message was successfully sent, false otherwise.

disconnect

public boolean disconnect(java.util.ArrayList<javax.sip.header.Header> additionalHeaders,
                          java.util.ArrayList<javax.sip.header.Header> replaceHeaders,
                          java.lang.String body)
This method is the same as the basic disconnect() method except that it allows the caller to specify a message body and/or additional JAIN-SIP API message headers to add to or replace in the outbound message. Use of this method requires knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
additionalHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message. These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Use null for no additional message headers.
replaceHeaders - ArrayList of javax.sip.header.Header, each element a SIP header to add to the outbound message, replacing existing header(s) of that type if present in the message. These headers are applied to the message after a correct message has been constructed. Use null for no replacement of message headers.
body - A String to be used as the body of the message. The additionalHeaders parameter must contain a ContentTypeHeader for this body to be included in the message. Use null for no body bytes.

disconnect

public boolean disconnect(java.lang.String body,
                          java.lang.String contentType,
                          java.lang.String contentSubType,
                          java.util.ArrayList<java.lang.String> additionalHeaders,
                          java.util.ArrayList<java.lang.String> replaceHeaders)
This method is the same as the basic disconnect() method except that it allows the caller to specify a message body and/or additional message headers to add to or replace in the outbound message without requiring knowledge of the JAIN-SIP API. The extra parameters supported by this method are:

Parameters:
body - A String to be used as the body of the message. Parameters contentType, contentSubType must both be non-null to get the body included in the message. Use null for no body bytes.
contentType - The body content type (ie, 'application' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
contentSubType - The body content sub-type (ie, 'sdp' part of 'application/sdp'), required if there is to be any content (even if body bytes length 0). Use null for no message content.
additionalHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are added to the message after a correct message has been constructed. Note that if you try to add a header that there is only supposed to be one of in a message, and it's already there and only one single value is allowed for that header, then this header addition attempt will be ignored. Use the 'replaceHeaders' parameter instead if you want to replace the existing header with your own. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no additional message headers.
replaceHeaders - ArrayList of String, each element representing a SIP message header to add to the outbound message, replacing existing header(s) of that type if present in the message. Examples: "Priority: Urgent", "Max-Forwards: 10". These headers are applied to the message after a correct message has been constructed. Unpredictable results may occur if your headers are not syntactically correct or contain nonsensical values (the message may not pass through the local SIP stack). Use null for no replacement of message headers.

getParent

public SipPhone getParent()
This method returns the SipPhone object associated with this call.

Returns:
This call's SipPhone parent.

getAddressFactory

public javax.sip.address.AddressFactory getAddressFactory()
This method returns the AddressFactory associated with this object. It may be needed by the caller if providing additional or replacement JAIN SIP headers for outbound messages.

Returns:
This SipCall's javax.sip.address.AddressFactory

getHeaderFactory

public javax.sip.header.HeaderFactory getHeaderFactory()
This method returns the HeaderFactory associated with this object. It will be needed by the caller if providing additional or replacement JAIN SIP headers for outbound messages.

Returns:
This SipCall's javax.sip.header.HeaderFactory

getErrorMessage

public java.lang.String getErrorMessage()
Description copied from interface: SipActionObject
The getErrorMessage() method returns a descriptive, human-readable string indicating the cause of the problem encountered during the last operation performed. If an exception was involved, this string will contain the name of the Exception class and the exception message.

Specified by:
getErrorMessage in interface SipActionObject
Returns:
A descriptive string describing the cause of the problem encountered during the last operation performed, or an empty string if no problem was encountered.

getException

public java.lang.Throwable getException()
Description copied from interface: SipActionObject
This method is used to get the Exception object generated during the last operation performed. It applies whenever the getReturnCode() method returns internal SipUnit return code EXCEPTION_ENCOUNTERED.

Specified by:
getException in interface SipActionObject