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 SipSession

java.lang.Object
  extended by org.cafesip.sipunit.SipSession
All Implemented Interfaces:
java.util.EventListener, javax.sip.SipListener, SipActionObject
Direct Known Subclasses:
SipPhone
public class SipSession
extends java.lang.Object
implements javax.sip.SipListener, SipActionObject

Methods of this class provide the test program with low-level access to a SIP session. Instead of using the SipPhone methods to communicate with other SIP agents, the test program can use methods of this class to send and receive SIP messages. Methods of this class can be accessed via the SipPhone object returned by SipStack.createSipPhone().

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.

Field Summary
static int ERROR_OF_UNKNOWN_ORIGIN
           
static int EXCEPTION_ENCOUNTERED
           
static int FAR_END_ERROR
           
static int INTERNAL_ERROR
           
static int INVALID_ARGUMENT
           
static int INVALID_OPERATION
           
static int INVALID_UNREGISTERED_OPERATION
           
static int MAX_FORWARDS_DEFAULT
           
static int MISSING_CREDENTIAL
           
static int NONE_YET
           
static int SIPUNIT_INTERNAL_RETURNCODE_MIN
          Comment for SIPUNIT_INTERNAL_RETURNCODE_MIN A constant marking the lowest possible SipUnit internal return code value.
static java.util.HashMap<java.lang.Integer,java.lang.String> statusCodeDescription
          Comment for statusCodeDescription This map yields a descriptive string, given an internal sipunit return code.
static int TIMEOUT_OCCURRED
           
static int UNSUPPORTED_URI_SCHEME
           
 
Method Summary
 void dispose()
          This method idles this SipSession.
 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.
 java.lang.String generateNewTag()
          This method returns a newly generated unique tag ID.
 javax.sip.header.AuthorizationHeader getAuthorization(java.lang.String method, java.lang.String uri, java.lang.String requestBody, javax.sip.header.WWWAuthenticateHeader authHeader, java.lang.String username, java.lang.String password)
          The getAuthorization() method generates an authorisation header in response to an 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.
 java.util.ArrayList<javax.sip.header.ViaHeader> getLocalViaHeaders()
          Deprecated. Use getViaHeaders() instead of this method, the term 'local' in the method name is misleading if the SipUnit test is running behind a NAT.
 SipStack getParent()
          The getParent() method returns the org.cafesip.sipunit.SipStack object that is associated with this SipSession object.
 java.lang.String getPublicAddress()
          This method returns the IP address and port currently being used in this Sip agent's contact address, via, and listening point 'sentby' components.
 int getReturnCode()
          This method returns the status code of the current or last operation performed.
 java.lang.String getStackAddress()
          Call this method to get the IP address being used by this user agent (ie, the address it is putting in its contact header, via header, etc.
 java.util.ArrayList<javax.sip.header.ViaHeader> getViaHeaders()
          This method returns the Via Header currently in effect for this user agent, needed for sending requests such as INVITE.
static boolean isInternal(int returnCode)
          This method indicates if the given return code is an internal SipUnit return code or not.
 boolean listenRequestMessage()
          This method prepares the SipSession for reception of a request message addressed to this SipSession's URI.
 void processDialogTerminated(javax.sip.DialogTerminatedEvent arg0)
           
 void processIOException(javax.sip.IOExceptionEvent arg0)
           
 void processRequest(javax.sip.RequestEvent request)
          FOR INTERNAL USE ONLY.
 void processResponse(javax.sip.ResponseEvent response)
          FOR INTERNAL USE ONLY.
 void processTimeout(javax.sip.TimeoutEvent timeout)
          FOR INTERNAL USE ONLY.
 void processTransactionTerminated(javax.sip.TransactionTerminatedEvent arg0)
           
 SipTransaction sendReply(javax.sip.RequestEvent request, int statusCode, java.lang.String reasonPhrase, java.lang.String toTag, javax.sip.address.Address contact, int expires)
          This method sends a basic, stateful response to a previously received request.
 SipTransaction sendReply(javax.sip.RequestEvent request, int statusCode, java.lang.String reasonPhrase, java.lang.String toTag, javax.sip.address.Address contact, 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 sendReply(RequestEvent, ...) 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 sendReply(javax.sip.RequestEvent request, int statusCode, java.lang.String reasonPhrase, java.lang.String toTag, javax.sip.address.Address contact, 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 sendReply(RequestEvent, ...) 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 sendReply(javax.sip.RequestEvent request, javax.sip.message.Response response)
          This method sends a stateful response to a previously received request.
 SipTransaction sendReply(SipTransaction transaction, int statusCode, java.lang.String reasonPhrase, java.lang.String toTag, javax.sip.address.Address contact, int expires)
          This method sends a basic, stateful response to a previously received request.
 SipTransaction sendReply(SipTransaction transaction, int statusCode, java.lang.String reasonPhrase, java.lang.String toTag, javax.sip.address.Address contact, 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 sendReply(SipTransaction, ...) 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 sendReply(SipTransaction transaction, int statusCode, java.lang.String reasonPhrase, java.lang.String toTag, javax.sip.address.Address contact, 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 sendReply(SipTransaction, ...) 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 sendReply(SipTransaction transaction, javax.sip.message.Response response)
          This method sends a stateful response to a previously received request.
 SipTransaction sendRequestWithTransaction(javax.sip.message.Request request, boolean viaProxy, javax.sip.Dialog dialog)
          This basic method sends out a request message as part of a transaction.
 SipTransaction sendRequestWithTransaction(javax.sip.message.Request request, boolean viaProxy, javax.sip.Dialog dialog, 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 sendRequestWithTransaction(Request,...) 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 sendRequestWithTransaction(javax.sip.message.Request request, boolean viaProxy, javax.sip.Dialog dialog, 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 sendRequestWithTransaction(Request,...) 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 sendRequestWithTransaction(java.lang.String reqMessage, boolean viaProxy, javax.sip.Dialog dialog)
          This basic method sends out a request message as part of a transaction.
 SipTransaction sendRequestWithTransaction(java.lang.String reqMessage, boolean viaProxy, javax.sip.Dialog dialog, 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 sendRequestWithTransaction(String,...) 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 sendRequestWithTransaction(java.lang.String reqMessage, boolean viaProxy, javax.sip.Dialog dialog, 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 sendRequestWithTransaction(String,...) 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 sendUnidirectionalRequest(javax.sip.message.Request request, boolean viaProxy)
          This sendUnidirectionalRequest() method sends out a request message with no response expected.
 boolean sendUnidirectionalRequest(java.lang.String reqMessage, boolean viaProxy)
          This sendUnidirectionalRequest() method sends out a request message with no response expected.
 boolean sendUnidirectionalResponse(javax.sip.RequestEvent request, int statusCode, java.lang.String reasonPhrase, java.lang.String toTag, javax.sip.address.Address contact, int expires)
          This method sends out a stateless response to the given request.
 boolean sendUnidirectionalResponse(javax.sip.message.Response response)
          The sendUnidirectionalResponse() method sends out a stateless response message.
 boolean setPublicAddress(java.lang.String host, int port)
          This method replaces the host/port values currently being used in this Sip agent's contact address, via, and listening point 'sentby' components with the given host and port parameters.
 boolean unlistenRequestMessage()
          The unlistenRequestMessage() method cancels out a previous directive to listen for reception of a request addressed to this SipSession's URI.
 javax.sip.RequestEvent waitRequest(long timeout)
          The waitRequest() method waits for a request addressed to this SipSession's URI to be received from the network.
 java.util.EventObject waitResponse(SipTransaction trans, long timeout)
          The waitResponse() method waits for a response to a previously sent transactional request message.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SIPUNIT_INTERNAL_RETURNCODE_MIN

public static final int SIPUNIT_INTERNAL_RETURNCODE_MIN
Comment for SIPUNIT_INTERNAL_RETURNCODE_MIN A constant marking the lowest possible SipUnit internal return code value. Anything below this is not internal, but a standard RFC3261 SIP status code. A test program can refer to this constant or call isInternal() to determine if the value returned by SipSession.getReturnCode() is an internal SipUnit return code or a SIP response code received from the network.

See Also:
Constant Field Values

NONE_YET

public static final int NONE_YET
See Also:
Constant Field Values

EXCEPTION_ENCOUNTERED

public static final int EXCEPTION_ENCOUNTERED
See Also:
Constant Field Values

UNSUPPORTED_URI_SCHEME

public static final int UNSUPPORTED_URI_SCHEME
See Also:
Constant Field Values

INVALID_UNREGISTERED_OPERATION

public static final int INVALID_UNREGISTERED_OPERATION
See Also:
Constant Field Values

TIMEOUT_OCCURRED

public static final int TIMEOUT_OCCURRED
See Also:
Constant Field Values

FAR_END_ERROR

public static final int FAR_END_ERROR
See Also:
Constant Field Values

INTERNAL_ERROR

public static final int INTERNAL_ERROR
See Also:
Constant Field Values

ERROR_OF_UNKNOWN_ORIGIN

public static final int ERROR_OF_UNKNOWN_ORIGIN
See Also:
Constant Field Values

INVALID_OPERATION

public static final int INVALID_OPERATION
See Also:
Constant Field Values

INVALID_ARGUMENT

public static final int INVALID_ARGUMENT
See Also:
Constant Field Values

MISSING_CREDENTIAL

public static final int MISSING_CREDENTIAL
See Also:
Constant Field Values

statusCodeDescription

public static java.util.HashMap<java.lang.Integer,java.lang.String> statusCodeDescription
Comment for statusCodeDescription This map yields a descriptive string, given an internal sipunit return code.

MAX_FORWARDS_DEFAULT

public static final int MAX_FORWARDS_DEFAULT
See Also:
Constant Field Values
Method Detail

generateNewTag

public java.lang.String generateNewTag()
This method returns a newly generated unique tag ID.

Returns:
A String tag ID

dispose

public void dispose()
This method idles this SipSession. This SipSession object must not be used again after calling the dispose() method.

getParent

public SipStack getParent()
The getParent() method returns the org.cafesip.sipunit.SipStack object that is associated with this SipSession object. A test program can use the SipStack object to get the header, address, and message factories for building requests and responses, before passing those to methods of this class.

Returns:
Returns the parent.

getPublicAddress

public java.lang.String getPublicAddress()
This method returns the IP address and port currently being used in this Sip agent's contact address, via, and listening point 'sentby' components. Example: 66.32.44.114:5066

Returns:
A String containing address + ':' + port.

setPublicAddress

public boolean setPublicAddress(java.lang.String host,
                                int port)
This method replaces the host/port values currently being used in this Sip agent's contact address, via, and listening point 'sentby' components with the given host and port parameters. Call this method when you are running a SipUnit testcase behind a NAT and need to register with a proxy on the public internet. Before creating the SipStack and SipPhone, you'll need to first obtain the public IP address/port using a mechanism such as the Stun4j API. See the TestWithStun.java file in the sipunit test/examples directory for an example of how to do it.

Parameters:
host - The publicly accessible IP address for this Sip client (ex: 66.32.44.112).
port - The port to be used with the publicly accessible IP address.
Returns:
true if the parameters are successfully parsed and this client's information is updated, false otherwise.

processRequest

public void processRequest(javax.sip.RequestEvent request)
FOR INTERNAL USE ONLY. Not to be used by a test program.

Specified by:
processRequest in interface javax.sip.SipListener

processResponse

public void processResponse(javax.sip.ResponseEvent response)
FOR INTERNAL USE ONLY. Not to be used by a test program.

Specified by:
processResponse in interface javax.sip.SipListener

processTimeout

public void processTimeout(javax.sip.TimeoutEvent timeout)
FOR INTERNAL USE ONLY. Not to be used by a test program.

Specified by:
processTimeout in interface javax.sip.SipListener

sendUnidirectionalRequest

public boolean sendUnidirectionalRequest(java.lang.String reqMessage,
                                         boolean viaProxy)
                                  throws java.text.ParseException
This sendUnidirectionalRequest() method sends out a request message with no response expected. A Request object is constructed from the string parameter passed in. Example: StringBuffer invite = new StringBuffer("INVITE sip:becky@" + PROXY_HOST + ':' + PROXY_PORT + ";transport=" + PROXY_PROTO + " SIP/2.0\n"); invite.append("Call-ID: 5ff235b07a7e4c19784d138fb26c1ec8@" + thisHostAddr + "\n"); invite.append("CSeq: 1 INVITE\n"); invite.append("From: ;tag=1181356482\n"); invite.append("To: \n"); invite.append("Contact: \n"); invite.append("Max-Forwards: 5\n"); invite.append("Via: SIP/2.0/" + PROXY_PROTO + " " + thisHostAddr + ":5060;branch=322e3136382e312e3130303a3530363\n"); invite.append("Event: presence\n"); invite.append("Content-Length: 5\n"); invite.append("\n"); invite.append("12345"); SipTransaction trans = ua.sendRequestWithTransaction(invite .toString(), true, null); assertNotNull(ua.format(), trans);

Parameters:
reqMessage - A request message in the form of a String with everything from the request line and headers to the body. It must be in the proper format per RFC-3261.
viaProxy - If true, send the message to the proxy. In this case the request URI is modified by this method. Else send it to the user specified in the given request URI. In this case, for an INVITE request, a route header must be present for the request routing to complete. This method does NOT add a route header.
Returns:
true if the message was successfully built and sent, false otherwise.
Throws:
java.text.ParseException - if an error was encountered while parsing the string.

sendUnidirectionalRequest

public boolean sendUnidirectionalRequest(javax.sip.message.Request request,
                                         boolean viaProxy)
This sendUnidirectionalRequest() method sends out a request message with no response expected. The Request object passed in must be a fully formed Request with all required content, ready to be sent.

Parameters:
request - The request to be sent out.
viaProxy - If true, send the message to the proxy. In this case a Route header is added by this method. Else send the message as is. In this case, for an INVITE request, a route header must have been added by the caller for the request routing to complete.
Returns:
true if the message was successfully sent, false otherwise.

sendRequestWithTransaction

public SipTransaction sendRequestWithTransaction(java.lang.String reqMessage,
                                                 boolean viaProxy,
                                                 javax.sip.Dialog dialog)
                                          throws java.text.ParseException
This basic method sends out a request message as part of a transaction. A test program should use this method when a response to a request is expected. A Request object is constructed from the string passed in. This method returns when the request message has been sent out. The calling program must subsequently call the waitResponse() method to wait for the result (response, timeout, etc.).

Parameters:
reqMessage - A request message in the form of a String with everything from the request line and headers to the body. It must be in the proper format per RFC-3261.
viaProxy - If true, send the message to the proxy. In this case the request URI is modified by this method. Else send it to the user specified in the given request URI. In this case, for an INVITE request, a route header must be present for the request routing to complete. This method does NOT add a route header.
dialog - If not null, send the request via the given dialog. Else send it outside of any dialog.
Returns:
A SipTransaction object if the message was built and sent successfully, null otherwise. The calling program doesn't need to do anything with the returned SipTransaction other than pass it in to a subsequent call to waitResponse().
Throws:
java.text.ParseException - if an error is encountered while parsing the string.

sendRequestWithTransaction

public SipTransaction sendRequestWithTransaction(java.lang.String reqMessage,
                                                 boolean viaProxy,
                                                 javax.sip.Dialog dialog,
                                                 java.util.ArrayList<javax.sip.header.Header> additionalHeaders,
                                                 java.util.ArrayList<javax.sip.header.Header> replaceHeaders,
                                                 java.lang.String body)
                                          throws java.text.ParseException
This method is the same as the basic sendRequestWithTransaction(String,...) 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.
Throws:
java.text.ParseException

sendRequestWithTransaction

public SipTransaction sendRequestWithTransaction(java.lang.String reqMessage,
                                                 boolean viaProxy,
                                                 javax.sip.Dialog dialog,
                                                 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)
                                          throws java.text.ParseException
This method is the same as the basic sendRequestWithTransaction(String,...) 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.
Throws:
java.text.ParseException

sendRequestWithTransaction

public SipTransaction sendRequestWithTransaction(javax.sip.message.Request request,
                                                 boolean viaProxy,
                                                 javax.sip.Dialog dialog)
This basic method sends out a request message as part of a transaction. A test program should use this method when a response to a request is expected. The Request object passed in must be a fully formed Request with all required content, EXCEPT for the Via header branch parameter, which cannot be filled in until a client transaction is obtained. That happens in this method. If the Via branch value is set in the request parameter passed to this method, it is nulled out by this method so that a new client transaction can be created by the stack. This method returns when the request message has been sent out. The calling program must subsequently call the waitResponse() method to wait for the result (response, timeout, etc.).

Parameters:
request - The request to be sent out.
viaProxy - If true, send the message to the proxy. In this case a Route header is added by this method. Else send the message as is. In this case, for an INVITE request, a route header must have been added by the caller for the request routing to complete.
dialog - If not null, send the request via the given dialog. Else send it outside of any dialog.
Returns:
A SipTransaction object if the message was sent successfully, null otherwise. The calling program doesn't need to do anything with the returned SipTransaction other than pass it in to a subsequent call to waitResponse().

sendRequestWithTransaction

public SipTransaction sendRequestWithTransaction(javax.sip.message.Request request,
                                                 boolean viaProxy,
                                                 javax.sip.Dialog dialog,
                                                 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 sendRequestWithTransaction(Request,...) 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.

sendRequestWithTransaction

public SipTransaction sendRequestWithTransaction(javax.sip.message.Request request,
                                                 boolean viaProxy,
                                                 javax.sip.Dialog dialog,
                                                 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 sendRequestWithTransaction(Request,...) 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.

waitResponse

public java.util.EventObject waitResponse(SipTransaction trans,
                                          long timeout)
The waitResponse() method waits for a response to a previously sent transactional request message. Call this method after using one of the sendRequestWithTransaction() methods. This method blocks until one of the following occurs: 1) A javax.sip.ResponseEvent is received. This is the object returned by this method. 2) A javax.sip.TimeoutEvent is received. This is the object returned by this method. 3) The wait timeout period specified by the parameter to this method expires. Null is returned in this case. 4) An error occurs. Null is returned in this case. Note that this method can be called repeatedly upon receipt of provisional response message(s).

Parameters:
trans - The SipTransaction object associated with the sent request.
timeout - The maximum amount of time to wait, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
A javax.sip.ResponseEvent, javax.sip.TimeoutEvent, or null in the case of wait timeout or error. If null, call getReturnCode() and/or getErrorMessage() and, if applicable, getException() for further diagnostics.

listenRequestMessage

public boolean listenRequestMessage()
This method prepares the SipSession for reception of a request message addressed to this SipSession's URI. It is non-blocking and returns immediately. A test program must subsequently call the waitRequest() method which blocks until a request is received for this session's URI.

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

unlistenRequestMessage

public boolean unlistenRequestMessage()
The unlistenRequestMessage() method cancels out a previous directive to listen for reception of a request addressed to this SipSession's URI. That is, it undoes a previous call to listenRequestMessage(). 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.

waitRequest

public javax.sip.RequestEvent waitRequest(long timeout)
The waitRequest() method waits for a request addressed to this SipSession's URI to be received from the network. Call this method after calling the listenRequestMessage() method. This method blocks until one of the following occurs: 1) A javax.sip.RequestEvent is received, addressed to this URI. This is the object returned by this method. 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.

Parameters:
timeout - The maximum amount of time to wait, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
A RequestEvent or null in the case of wait timeout or error. If null, call getReturnCode() and/or getErrorMessage() and, if applicable, getException() for further diagnostics.

sendReply

public SipTransaction sendReply(javax.sip.RequestEvent request,
                                int statusCode,
                                java.lang.String reasonPhrase,
                                java.lang.String toTag,
                                javax.sip.address.Address contact,
                                int expires)
This method sends a basic, stateful response to a previously received request. Call this method after calling waitRequest(). The response is constructed based on the parameters passed in. The returned SipTransaction object must be used in any subsequent calls to sendReply() for the same received request, if there are any.

Parameters:
request - The RequestEvent object that was returned by a previous call to waitRequest().
statusCode - The status code of the response to send (may use SipResponse constants).
reasonPhrase - If not null, the reason phrase to send.
toTag - If not null, it will be put into the 'To' header of the response. Required by final responses such as OK.
contact - If not null, it will be used to create a 'Contact' header to be added to the response.
expires - If not -1, an 'Expires' header is added to the response containing this value, which is the time the message is valid, in seconds.
Returns:
A SipTransaction object that must be passed in to any subsequent call to sendReply() for the same received request, or null if an error was encountered while sending the response. The calling program doesn't need to do anything with the returned SipTransaction other than pass it in to a subsequent call to sendReply() for the same received request.

sendReply

public SipTransaction sendReply(javax.sip.RequestEvent request,
                                int statusCode,
                                java.lang.String reasonPhrase,
                                java.lang.String toTag,
                                javax.sip.address.Address contact,
                                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 sendReply(RequestEvent, ...) 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.

sendReply

public SipTransaction sendReply(javax.sip.RequestEvent request,
                                int statusCode,
                                java.lang.String reasonPhrase,
                                java.lang.String toTag,
                                javax.sip.address.Address contact,
                                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 sendReply(RequestEvent, ...) 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.

sendReply

public SipTransaction sendReply(javax.sip.RequestEvent request,
                                javax.sip.message.Response response)
This method sends a stateful response to a previously received request. Call this method after calling waitRequest(). The returned SipTransaction object must be used in any subsequent calls to sendReply() for the same received request, if there are any.

Parameters:
request - The RequestEvent object that was returned by a previous call to waitRequest().
response - The response to send, as is.
Returns:
A SipTransaction object that must be passed in to any subsequent call to sendReply() for the same received request, or null if an error was encountered while sending the response. The calling program doesn't need to do anything with the returned SipTransaction other than pass it in to a subsequent call to sendReply() for the same received request.

sendReply

public SipTransaction sendReply(SipTransaction transaction,
                                int statusCode,
                                java.lang.String reasonPhrase,
                                java.lang.String toTag,
                                javax.sip.address.Address contact,
                                int expires)
This method sends a basic, stateful response to a previously received request. The response is constructed based on the parameters passed in. The returned SipTransaction object must be used in any subsequent calls to sendReply() for the same received request, if there are any.

Parameters:
transaction - The SipTransaction object returned from a previous call to sendReply().
statusCode - The status code of the response to send (may use SipResponse constants).
reasonPhrase - If not null, the reason phrase to send.
toTag - If not null, it will be put into the 'To' header of the response. Required by final responses such as OK.
contact - If not null, it will be used to create a 'Contact' header to be added to the response.
expires - If not -1, an 'Expires' header is added to the response containing this value, which is the time the message is valid, in seconds.
Returns:
A SipTransaction object that must be passed in to any subsequent call to sendReply() for the same received request, or null if an error was encountered while sending the response. The calling program doesn't need to do anything with the returned SipTransaction other than pass it in to a subsequent call to sendReply() for the same received request.

sendReply

public SipTransaction sendReply(SipTransaction transaction,
                                int statusCode,
                                java.lang.String reasonPhrase,
                                java.lang.String toTag,
                                javax.sip.address.Address contact,
                                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 sendReply(SipTransaction, ...) 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.

sendReply

public SipTransaction sendReply(SipTransaction transaction,
                                int statusCode,
                                java.lang.String reasonPhrase,
                                java.lang.String toTag,
                                javax.sip.address.Address contact,
                                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 sendReply(SipTransaction, ...) 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.

sendReply

public SipTransaction sendReply(SipTransaction transaction,
                                javax.sip.message.Response response)
This method sends a stateful response to a previously received request. The returned SipTransaction object must be used in any subsequent calls to sendReply() for the same received request, if there are any.

Parameters:
transaction - The SipTransaction object returned from a previous call to sendReply().
response - The response to send, as is.
Returns:
A SipTransaction object that must be passed in to any subsequent call to sendReply() for the same received request, or null if an error was encountered while sending the response. The calling program doesn't need to do anything with the returned SipTransaction other than pass it in to a subsequent call to sendReply() for the same received request.

sendUnidirectionalResponse

public boolean sendUnidirectionalResponse(javax.sip.message.Response response)
The sendUnidirectionalResponse() method sends out a stateless response message. The response is sent out as is.

Parameters:
response - The response to be sent out.
Returns:
true if the message was successfully sent, false otherwise.

sendUnidirectionalResponse

public boolean sendUnidirectionalResponse(javax.sip.RequestEvent request,
                                          int statusCode,
                                          java.lang.String reasonPhrase,
                                          java.lang.String toTag,
                                          javax.sip.address.Address contact,
                                          int expires)
This method sends out a stateless response to the given request.

Parameters:
request - The RequestEvent object that contains the request we are responding to.
statusCode - The status code of the response to send (may use SipResponse constants).
reasonPhrase - If not null, the reason phrase to send.
toTag - If not null, it will be put into the 'To' header of the response. Required by final responses such as OK.
contact - If not null, it will be used to create a 'Contact' header to be added to the response.
expires - If not -1, an 'Expires' header is added to the response containing this value, which is the time the message is valid, in seconds.
Returns:
True if the response was successfully sent, false otherwise.

getAuthorization

public javax.sip.header.AuthorizationHeader getAuthorization(java.lang.String method,
                                                             java.lang.String uri,
                                                             java.lang.String requestBody,
                                                             javax.sip.header.WWWAuthenticateHeader authHeader,
                                                             java.lang.String username,
                                                             java.lang.String password)
                                                      throws java.lang.SecurityException
The getAuthorization() method generates an authorisation header in response to an authentication challenge. The WWWAuthenticateHeader parameter can represent an UAS->UAC challenge (received status code = Response.UNAUTHORIZED) or a Proxy->UAC challenge (received status code = Response.PROXY_AUTHENTICATION_REQUIRED). This method was copied from the Sip Communicator project (package net.java.sip.communicator.sip.security.SipSecurityManager, its author is Emil Ivov) and slightly modified to fit here. Thanks for making it publicly available. It is licensed under the Apache Software License, Version 1.1 Copyright (c) 2000.

Parameters:
method - method of the request being authenticated.
uri - digest-uri. This is the request uri of the request (ie, request.getRequestURI().toString()).
requestBody - the body of the request message being authenticated. IE: request.getContent()==null?"":request.getContent().toString()
authHeader - the challenge that we are responding to. The caller should pass in one of the following received response headers: WWWAuthenticateHeader (typically associated with status code Response.UNAUTHORIZED) or ProxyAuthenticateHeader (usually associated with status code Response.PROXY_AUTHENTICATION_REQUIRED).
username - the name of the user to send to the challenging server
password - the user's password
Returns:
The AuthorizationHeader to use for this challenge.
Throws:
java.lang.SecurityException

getViaHeaders

public java.util.ArrayList<javax.sip.header.ViaHeader> getViaHeaders()
This method returns the Via Header currently in effect for this user agent, needed for sending requests such as INVITE. By default, it is set to the IP address and port used by this user agent's sip stack. But if the setPublicAddress() has been called on this object, the returned value will reflect the most recent call to setPublicAddress().

Returns:
an ArrayList containing a single element: the javax.sip.header.ViaHeader currently in effect for this user agent.

getLocalViaHeaders

public java.util.ArrayList<javax.sip.header.ViaHeader> getLocalViaHeaders()
Deprecated. Use getViaHeaders() instead of this method, the term 'local' in the method name is misleading if the SipUnit test is running behind a NAT.

This method is the same as getViaHeaders().

Returns:
A list of ViaHeader

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
Returns:
The Throwable object generated during the last operation performed, or null if an Exception didn't occur.

getReturnCode

public int getReturnCode()
Description copied from interface: SipActionObject
This method returns the status code of the current or last operation performed. It returns either 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).

Specified by:
getReturnCode in interface SipActionObject
Returns:
The status code of the last operation performed, or the status code so far of the current ongoing operation.

isInternal

public static boolean isInternal(int returnCode)
This method indicates if the given return code is an internal SipUnit return code or not.

Parameters:
returnCode - the return code in question
Returns:
true if the return code is internal to SipUnit, false if it is a SIP RFC 3261 return code.

format

public java.lang.String format()
Description copied from interface: SipActionObject
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.

Specified by:
format in interface SipActionObject
Returns:
A string fully describing the error information associated with the last operation performed, or a successful indication if no error occurred.

getStackAddress

public java.lang.String getStackAddress()
Call this method to get the IP address being used by this user agent (ie, the address it is putting in its contact header, via header, etc. when it sends out messages).

Returns:
A String containing the host IP address being used by this user agent.

processIOException

public void processIOException(javax.sip.IOExceptionEvent arg0)
Specified by:
processIOException in interface javax.sip.SipListener

processTransactionTerminated

public void processTransactionTerminated(javax.sip.TransactionTerminatedEvent arg0)
Specified by:
processTransactionTerminated in interface javax.sip.SipListener

processDialogTerminated

public void processDialogTerminated(javax.sip.DialogTerminatedEvent arg0)
Specified by:
processDialogTerminated in interface javax.sip.SipListener
Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
http://www.cafesip.org