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 SipPhone

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

This class provides a test program with User Agent (UA) access to the SIP protocol in the form of a SIP phone. Using this class, a test program can simulate a SIP phone and perform operations such as registration, making an outgoing call or receiving an incoming call, buddy list/fetch (SUBSCRIBE/NOTIFY) operations, call refer, etc. In future, a SipPhone object can have more than one SipCall object associated with it but currently only one is supported. Multiple subscriptions (buddy/presence, refer) are supported per SipPhone object.

A SipPhone object is created by calling 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 DEFAULT_SUBSCRIBE_DURATION
           
 
Fields inherited from class org.cafesip.sipunit.SipSession
ERROR_OF_UNKNOWN_ORIGIN, EXCEPTION_ENCOUNTERED, FAR_END_ERROR, INTERNAL_ERROR, INVALID_ARGUMENT, INVALID_OPERATION, INVALID_UNREGISTERED_OPERATION, MAX_FORWARDS_DEFAULT, MISSING_CREDENTIAL, NONE_YET, SIPUNIT_INTERNAL_RETURNCODE_MIN, statusCodeDescription, TIMEOUT_OCCURRED, UNSUPPORTED_URI_SCHEME
 
Method Summary
 PresenceSubscriber addBuddy(java.lang.String uri, int duration, long timeout)
          This method is the same as addBuddy(uri, duration, eventId, timeout) except that no event "id" parameter will be included.
 PresenceSubscriber addBuddy(java.lang.String uri, int duration, java.lang.String eventId, long timeout)
          This method adds a buddy to the buddy list and starts an ongoing subscription for purposes of tracking the buddy's presence information.
 PresenceSubscriber addBuddy(java.lang.String uri, long timeout)
          This method is the same as addBuddy(uri, duration, eventId, timeout) except that the duration is defaulted to the default period defined in the event package RFC (3600 seconds) and no event "id" parameter will be included.
 PresenceSubscriber addBuddy(java.lang.String uri, java.lang.String eventId, long timeout)
          This method is the same as addBuddy(uri, duration, eventId, timeout) except that the duration is defaulted to the default period defined in the event package RFC (3600 seconds).
 void addUpdateCredential(Credential c)
          This method adds a new credential to the credentials list or updates an existing credential in the list.
 void clearCredentials()
          This method empties out the credentials list - completely - for this SipPhone.
 SipCall createSipCall()
          This method is used to create a SipCall object for handling one leg of a call.
 void dispose()
          This method releases all resources associated with this SipPhone.
 PresenceSubscriber fetchPresenceInfo(java.lang.String uri, long timeout)
          This method is the same as fetchPresenceInfo(uri, eventId, timeout) except that no event "id" parameter will be included in the SUBSCRIBE message.
 PresenceSubscriber fetchPresenceInfo(java.lang.String uri, java.lang.String eventId, long timeout)
          This method performs a presence 'fetch' on the given user, to get a one-time report on the user's presence status and information.
 javax.sip.address.Address getAddress()
          This method returns the user Address for this SipPhone.
 PresenceSubscriber getBuddyInfo(java.lang.String uri)
          This method returns the PresenceSubscriber object representing a buddy or user whose presence information was fetched at some previous point.
 java.util.Hashtable<java.lang.String,PresenceSubscriber> getBuddyList()
          Returns a copy of the current buddy list on this SipPhone.
 SipContact getContactInfo()
          The method getContactInfo() returns the contact information currently in effect for this user agent.
 SipContact getLocalContactInfo()
          Deprecated. Use getContactInfo() instead of this method, the term 'local' in the method name is misleading if the SipUnit test is running behind a NAT.
 java.util.List<ReferSubscriber> getRefererInfo(javax.sip.address.SipURI referToUri)
          This method returns the subscription object(s) associated with the given referToUri.
 java.util.List<ReferSubscriber> getRefererInfoByDialog(java.lang.String dialogId)
          This method returns the subscription object(s) associated with the given dialog ID.
 java.util.List<ReferSubscriber> getRefererList()
          Returns a copy of the list of subscriptions associated with outbound REFER requests from this SipPhone.
 java.util.Hashtable<java.lang.String,PresenceSubscriber> getRetiredBuddies()
          Returns a copy of the list of subscriptions associated with this SipPhone which are not in the current buddy list.
 javax.sip.address.SipURI getUri(java.lang.String scheme, java.lang.String userHostPort, java.lang.String transportUriParameter, java.lang.String methodUriParameter, java.util.Map<java.lang.String,java.lang.String> otherUriParameters, java.lang.String joinUriHeader, java.lang.String replacesUriHeader, java.lang.String bodyUriHeader, java.util.Map<java.lang.String,java.lang.String> otherUriHeaders)
          Creates an URI object useful for passing into methods such as SipPhone.refer().
 SipCall makeCall(java.lang.String to, int response, long timeout, java.lang.String viaNonProxyRoute)
          This blocking basic method is used to make an outgoing call.
 SipCall makeCall(java.lang.String to, int response, long timeout, 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 blocking makeCall() 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 INVITE message.
 SipCall makeCall(java.lang.String to, int response, long timeout, 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 blocking makeCall() 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.
 SipCall makeCall(java.lang.String to, java.lang.String viaNonProxyRoute)
          This nonblocking basic method is used to make an outgoing call.
 SipCall makeCall(java.lang.String to, 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 nonblocking makeCall() 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 INVITE message.
 SipCall makeCall(java.lang.String to, 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 nonblocking makeCall() 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.
 javax.sip.message.Request processAuthChallenge(javax.sip.message.Response response, javax.sip.message.Request req_msg)
          This method is the same as the other processAuthChallenge() without the user/password option.
 javax.sip.message.Request processAuthChallenge(javax.sip.message.Response response, javax.sip.message.Request req_msg, java.lang.String username, java.lang.String password)
          This method is public for test purposes and for use when using low level SipSession methods for sending/receiving messages.
 void processEvent(java.util.EventObject event)
          For internal SipUnit use only.
 ReferSubscriber refer(javax.sip.Dialog dialog, javax.sip.address.SipURI referToUri, java.lang.String eventId, long timeout)
          This basic refer method creates an in-dialog REFER request message, sends it out, and waits for a first response to be received.
 ReferSubscriber refer(javax.sip.Dialog dialog, javax.sip.address.SipURI referToUri, java.lang.String eventId, long timeout, 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 in-dialog refer() 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.
 ReferSubscriber refer(javax.sip.Dialog dialog, javax.sip.address.SipURI referToUri, java.lang.String eventId, long timeout, 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 in-dialog refer() 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.
 ReferSubscriber refer(java.lang.String refereeUri, javax.sip.address.SipURI referToUri, java.lang.String eventId, long timeout, java.lang.String viaNonProxyRoute)
          This basic refer method creates an out-of-dialog REFER request message, sends it out, and waits for a first response to be received.
 ReferSubscriber refer(java.lang.String refereeUri, javax.sip.address.SipURI referToUri, java.lang.String eventId, long timeout, 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 out-of-dialog refer() 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.
 ReferSubscriber refer(java.lang.String refereeUri, javax.sip.address.SipURI referToUri, java.lang.String eventId, long timeout, 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 out-of-dialog refer() 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 register(javax.sip.address.SipURI requestUri, java.lang.String user, java.lang.String password, java.lang.String contact, int expiry, long timeout)
          This method is the same as the register(String user, String password, String contact, int expiry, long timeout) method except for the Request-URI used in the outgoing REGISTER method.
 boolean register(java.lang.String contact, int expiry)
          This method is equivalent to the register(String user, String password, String contact, int expiry, long timeout) method except with no authorization parameters specified.
 boolean register(java.lang.String user, java.lang.String password, java.lang.String contact, int expiry, long timeout)
          This method is used for SIP registration.
 void removeCredential(Credential c)
          This method removes a credential from the credentials list.
 void removeCredential(java.lang.String realm)
          This method removes a credential from the credentials list.
 boolean unregister(java.lang.String contact, long timeout)
          This method performs the SIP unregistration process.
 
Methods inherited from class org.cafesip.sipunit.SipSession
format, generateNewTag, getAuthorization, getErrorMessage, getException, getLocalViaHeaders, getParent, getPublicAddress, getReturnCode, getStackAddress, getViaHeaders, isInternal, isLoopback, listenRequestMessage, processDialogTerminated, processIOException, processRequest, processResponse, processTimeout, processTransactionTerminated, sendReply, sendReply, sendReply, sendReply, sendReply, sendReply, sendReply, sendReply, sendRequestWithTransaction, sendRequestWithTransaction, sendRequestWithTransaction, sendRequestWithTransaction, sendRequestWithTransaction, sendRequestWithTransaction, sendUnidirectionalRequest, sendUnidirectionalRequest, sendUnidirectionalResponse, sendUnidirectionalResponse, setLoopback, setPublicAddress, unlistenRequestMessage, waitRequest, waitResponse
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.cafesip.sipunit.SipActionObject
format, getErrorMessage, getException, getReturnCode
 

Field Detail

DEFAULT_SUBSCRIBE_DURATION

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

register

public boolean register(java.lang.String user,
                        java.lang.String password,
                        java.lang.String contact,
                        int expiry,
                        long timeout)
This method is used for SIP registration. By default, the Request-URI is derived from this SipPhone's proxy host, or if no proxy was specified when this SipPhone was created, the Request-URI address information is taken from this SipPhone's URI (address of record). For other Request-URI alternatives, see the register() method that takes parameter requestUri.

Initially, a REGISTER message is sent without any user name and password. If the server returns an OK, this method returns a true value.

If any challenge is received in response to sending the REGISTER message (response code UNAUTHORIZED or PROXY_AUTHENTICATION_REQUIRED), the SipPhone's credentials list is checked first for the corresponding realm entry. If found, the credentials list entry username and password are used to form the required authorization header for resending the REGISTER message to the server, and the authorization header is saved for later re-use. You can clear out saved authorization headers by calling the unregister() method.

If the challenging realm is not found in the SipPhone credentials list, the user parameter passed to this method is examined. If it is null, this method returns false. If it is not null, the user and password values passed in to this method are used to respond to the challenge. The credentials list is not modified by this scenario (no entry is automatically added with this user, password). Also, the authorization created for this registration is not saved for re-use on a later registration. IE, the user/password parameters are for a one-time, single-shot use only.

After responding to the challenge(s) by resending the REGISTER message, this method returns a true or false value depending on the outcome as indicated by the server.

If the contact parameter is null, user@hostname is used where hostname is the SipStack's IP address property which defaults to InetAddress.getLocalHost().getHostAddress(), and other SipStack properties also apply. Otherwise, the contact parameter given is used in the Registration message sent to the server.

If the expiry parameter is 0, the registration request never expires. Otherwise, the duration, given in seconds, is sent to server.

This method can be called repeatedly to update the expiry or to add new contacts.

This method determines the contact information for this user agent, whether the registration was successful or not. If successful, the contact information may have been updated by the server (such as the expiry time, if not specified to this method by the caller). Once this method has been called, the test program can get information about the contact for this agent by calling the *MyContact*() getter methods.

Parameters:
user - Optional - user name for authenticating with the server. Required if the server issues an authentication challenge.
password - Optional - used only if the server issues an authentication challenge.
contact - An URI string (ex: sip:bob@192.0.2.4), or null to use the default contact for this user agent.
expiry - Expiry time in seconds, or 0 if no registration expiry.
timeout - The maximum amount of time to wait for a response, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
false if registration fails or an error is encountered, true otherwise. In case of false, call getErrorMessage(), getReturnCode() and/or getException() methods to find out why.

register

public boolean register(javax.sip.address.SipURI requestUri,
                        java.lang.String user,
                        java.lang.String password,
                        java.lang.String contact,
                        int expiry,
                        long timeout)
This method is the same as the register(String user, String password, String contact, int expiry, long timeout) method except for the Request-URI used in the outgoing REGISTER method. If the requestUri parameter passed into this method is null, the Request-URI for the REGISTER is derived from this SipPhone's URI, or address of record (for example, if this SipPhone's address of record is "sip:amit@cafesip.org", the REGISTER Request-URI will be sip:cafesip.org). Otherwise, the requestUri passed in is used for the REGISTER Request-URI.

register

public boolean register(java.lang.String contact,
                        int expiry)
This method is equivalent to the register(String user, String password, String contact, int expiry, long timeout) method except with no authorization parameters specified. Call this method if no authorization will be needed or after setting up the SipPhone's credentials list.

Parameters:
contact - An URI string (ex: sip:bob@192.0.2.4)
expiry - Expiry time in seconds, or 0 if no expiry.
Returns:
false if registration fails or an error is encountered, true otherwise.

unregister

public boolean unregister(java.lang.String contact,
                          long timeout)
This method performs the SIP unregistration process. It returns true if unregistration was successful or no unregistration was needed, and false otherwise. Any authorization headers required for the last registration are cleared out.

If the contact parameter is null, user@hostname is unregistered where hostname is obtained by calling InetAddr.getLocalHost(). Otherwise, the contact parameter value is used in the unregistration message sent to the server.

Parameters:
contact - The contact URI (ex: sip:bob@192.0.2.4) to unregister.
timeout - The maximum amount of time to wait for a response, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
true if the unregistration succeeded or no unregistration was needed, false otherwise.

processAuthChallenge

public javax.sip.message.Request processAuthChallenge(javax.sip.message.Response response,
                                                      javax.sip.message.Request req_msg,
                                                      java.lang.String username,
                                                      java.lang.String password)
This method is public for test purposes and for use when using low level SipSession methods for sending/receiving messages. A test program using high level SipUnit doesn't need to call this method. This method modifies the given request to include the authorization header(s) required by the given response. It may cache in SipPhone's authorizations list the AuthorizationHeader(s) created here for use later. The modified Request object is returned, or null in case of error or unresolved challenge.

For each received challenge present in the response message: SipPhone's credentials list is checked first, for the realm entry. If it is not found there, the username parameter passed into this method is checked. If null, this method returns null. If not null, the passed in username and password values are used to respond to the received challenge. In this case an entry is NOT added to the credentials list associating these values with the challenging realm and the authorization created here is NOT saved for later re-use. If the credentials list contains an entry for the challenging realm, then the authorization created here is saved in the authorizations list for later re-use.

Parameters:
response - the challenge that was received
req_msg - the request originally sent (that was challenged)
username - see above
password - see above
Returns:
the original request with the authorization header(s) added, or null if username and password weren't passed in and the SipPhone's credentials list doesn't have an entry for the realm.

processAuthChallenge

public javax.sip.message.Request processAuthChallenge(javax.sip.message.Response response,
                                                      javax.sip.message.Request req_msg)
This method is the same as the other processAuthChallenge() without the user/password option.

createSipCall

public SipCall createSipCall()
This method is used to create a SipCall object 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. The test program can use this method to create a SipCall object for handling an incoming call leg or an outgoing call leg. Currently, only one SipCall object is supported per SipPhone. In future, when more than one SipCall per SipPhone is supported, this method can be called multiple times to create multiple call legs on the same SipPhone object.

Returns:
A SipCall object unless an error is encountered.

makeCall

public SipCall makeCall(java.lang.String to,
                        int response,
                        long timeout,
                        java.lang.String viaNonProxyRoute)
This blocking basic method is used to make an outgoing call. It blocks until the specified INVITE response status code is received. The object returned is a SipCall object representing the outgoing call leg; that is, the UAC originating a call to the network. Then you can take subsequent action on the call by making method calls on the SipCall object.

Use this method when (1) you want to establish a call without worrying about the details and (2) your test program doesn't need to do anything else (ie, it can be blocked) until the response code parameter passed to this method is received from the network.

In case the first condition above is false: If you need to see the (intermediate/provisional) response messages as they come in, then use SipPhone.createSipCall() and SipCall.initiateOutgoingCall() instead of this method. If your test program can tolerate being blocked until the desired response is received, you can still use this method and later look back at all the received responses by calling SipCall.getAllReceivedResponses().

In case the second condition above is false: If your test code is handling both sides of the call, or it has to do other things while this call establishment is in progress, then this method's blocking gets in the way. In that case, use the other SipPhone.makeCall() method. It returns a SipCall object after the INVITE has been successfully sent. Then, later on you can check back with the SipCall object to see the call progress or block on the call establishment, at a more convenient time.

Parameters:
to - The URI string (ex: sip:bob@nist.gov) to which the call should be directed
response - The SipResponse status code to look for after sending the INVITE. This method returns when that status code is received.
timeout - The maximum amount of time to wait for the response, in milliseconds. Use a value of 0 to wait indefinitely.
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/transport" i.e. 129.1.22.333:5060/UDP.
Returns:
A SipCall object representing the outgoing call leg, or null if an error was encountered.

makeCall

public SipCall makeCall(java.lang.String to,
                        int response,
                        long timeout,
                        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 blocking makeCall() 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.

makeCall

public SipCall makeCall(java.lang.String to,
                        int response,
                        long timeout,
                        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 blocking makeCall() 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 INVITE 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.

makeCall

public SipCall makeCall(java.lang.String to,
                        java.lang.String viaNonProxyRoute)
This nonblocking basic method is used to make an outgoing call. It returns when the INVITE request message has been sent out, and after that all received responses (TRYING, RINGING, etc.) are automatically collected and any received authentication challenges are automatically handled as well. The object returned by this method is a SipCall object representing the outgoing call leg; that is, the UAC originating a call to the network.

After calling this method, you can later call one or more of the following methods on the returned SipCall object to see what happened (each is nonblocking unless otherwise noted): isCallAnswered() - to see if the call has been answered, callTimeoutOrError() - to see if an error/timeout has occured, getReturnCode() - to see the last response code received so far, getLastReceivedResponse() - to see the details of the last response received so far, getAllReceivedResponses() - to see the details of all the responses received so far, waitForAnswer() - BLOCKING - when your test program is done with its tasks and can be blocked until OK is received - it returns immediately if OK already received, waitOutgoingCallResponse() - BLOCKING - when your test program is done with its tasks and can be blocked until the next response is received (if you are interested in something other than OK) - use this only if you know that the INVITE transaction is still up.

Call this method when (1) you want to establish a call without worrying about the details and (2) your test program needs to do other tasks after the INVITE is sent but before a final/expected response is received (ie, the calling program cannot be blocked during call establishment).

Otherwise: If you need to see or act on any of the (intermediate/provisional) response messages as they come in, use SipPhone.createSipCall() and SipCall.initiateOutgoingCall() instead of this method. If your test program doesn't need to do anything else until the call is established: use the other SipPhone.makeCall() method which conveniently blocks until the response code you specify is received from the network.

Parameters:
to - The URI string (ex: 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/transport" i.e. 129.1.22.333:5060/UDP.
Returns:
A SipCall object representing the outgoing call leg, or null if an error was encountered.

makeCall

public SipCall makeCall(java.lang.String to,
                        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 nonblocking makeCall() 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 INVITE 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.

makeCall

public SipCall makeCall(java.lang.String to,
                        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 nonblocking makeCall() 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.

dispose

public void dispose()
This method releases all resources associated with this SipPhone. Neither this SipPhone object nor its SipSession base class should be used again after calling the dispose() method. Server/proxy unregistration occurs and SipCall(s) associated with this SipPhone are dropped. No un-SUBSCRIBE is done for active Subscriptions in the buddy list.

Overrides:
dispose in class SipSession
See Also:
SipCall.dispose()

getContactInfo

public SipContact getContactInfo()
The method getContactInfo() returns the contact information currently in effect for this user agent. This may be the value associated with the last registration attempt or as defaulted to user@host if no registration has occurred. Or, if the setPublicAddress() has been called on this object, the returned value will reflect the most recent call to setPublicAddress().

Returns:
The SipContact object currently in effect for this user agent

getLocalContactInfo

public SipContact getLocalContactInfo()
Deprecated. Use getContactInfo() 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 getContactInfo().

Returns:
The SipContact object currently in effect for this user agent

getAddress

public javax.sip.address.Address getAddress()
This method returns the user Address for this SipPhone. This is the same address used in the "from" header field.

Returns:
Returns the javax.sip.address.Address for this SipPhone (UA).

addUpdateCredential

public void addUpdateCredential(Credential c)
This method adds a new credential to the credentials list or updates an existing credential in the list.

Parameters:
c - the credential to be added/updated.

removeCredential

public void removeCredential(Credential c)
This method removes a credential from the credentials list.

Parameters:
c - the credential to be removed.

removeCredential

public void removeCredential(java.lang.String realm)
This method removes a credential from the credentials list.

Parameters:
realm - the realm associated with the credential to be removed.

clearCredentials

public void clearCredentials()
This method empties out the credentials list - completely - for this SipPhone.

processEvent

public void processEvent(java.util.EventObject event)
Description copied from interface: RequestListener
For internal SipUnit use only.

Specified by:
processEvent in interface RequestListener
Parameters:
event - Event received.

addBuddy

public PresenceSubscriber addBuddy(java.lang.String uri,
                                   int duration,
                                   java.lang.String eventId,
                                   long timeout)
This method adds a buddy to the buddy list and starts an ongoing subscription for purposes of tracking the buddy's presence information. Please read the SipUnit User Guide webpage Event Subscription (at least the operation overview part) for information on how to use SipUnit presence capabilities.

This method creates a SUBSCRIBE request message, sends it out, and waits for a response to be received. It saves the received response and checks for a "proceedable" (positive) status code value. Positive response status codes include any of the following: provisional (status / 100 == 1), UNAUTHORIZED, PROXY_AUTHENTICATION_REQUIRED, OK and ACCEPTED. Any other status code, or a response timeout or any other error, is considered fatal to the subscription.

This method blocks until one of the above outcomes is reached.

In the case of a positive response status code, this method returns a PresenceSubscriber object that will represent the buddy for the life of the subscription and puts the PresenceSubscriber object in this SipPhone's buddy list. You can save the returned PresenceSubscriber object yourself or retrieve it anytime later by calling this SipPhone's getBuddyInfo(buddy-uri). Use the returned PresenceSubscriber object to proceed through the remainder of this SUBSCRIBE-NOTIFY sequence as well as for future SUBSCRIBE-NOTIFY sequences and to find out details at any given time such as the subscription state, amount of time left on the subscription, termination reason, presence information, details of received responses and requests, etc.

In the case of a positive response status code (a non-null object is returned), you may find out more about the response that was just received by calling the PresenceSubscriber methods getReturnCode() and getCurrentResponse()/getLastReceivedResponse(). Your next step at this point will be to call the PresenceSubscriber's processResponse() method to proceed with the SUBSCRIBE processing.

In the case of a fatal outcome, no subscription object is created and null is returned. In this case, call the usual SipUnit failed-operation methods to find out what happened (ie, call this SipPhone's getErrorMessage(), getReturnCode(), and/or getException() methods). The getReturnCode() method will tell you the response status code that was received from the network (unless it is an internal SipUnit error code, see the SipSession javadoc for more on that).

Parameters:
uri - the URI (ie, sip:bob@nist.gov) of the buddy to be added to the list.
duration - the duration in seconds to put in the SUBSCRIBE message. If 0, this is equivalent to a fetch except that the buddy stays in the buddy list even though the subscription won't be active.
eventId - the event "id" to use in the SUBSCRIBE message, or null for no event "id" parameter. Whatever is indicated here will be used subsequently (for error checking SUBSCRIBE responses and NOTIFYs from the server as well as for sending subsequent SUBSCRIBEs) unless changed by the caller later on another buddy method call (refreshBuddy(), removeBuddy(), fetch, etc.).
timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
PresenceSubscriber object representing the buddy if the operation is successful so far, null otherwise.

addBuddy

public PresenceSubscriber addBuddy(java.lang.String uri,
                                   long timeout)
This method is the same as addBuddy(uri, duration, eventId, timeout) except that the duration is defaulted to the default period defined in the event package RFC (3600 seconds) and no event "id" parameter will be included.

Parameters:
uri - the URI (ie, sip:bob@nist.gov) of the buddy to be added to the list.
timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
PresenceSubscriber object representing the buddy if the operation is successful so far, null otherwise.

addBuddy

public PresenceSubscriber addBuddy(java.lang.String uri,
                                   int duration,
                                   long timeout)
This method is the same as addBuddy(uri, duration, eventId, timeout) except that no event "id" parameter will be included.

Parameters:
uri - the URI (ie, sip:bob@nist.gov) of the buddy to be added to the list.
duration - the duration in seconds to put in the SUBSCRIBE message. If 0, this is equivalent to a fetch except that the buddy stays in the buddy list even though the subscription won't be active.
timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
PresenceSubscriber object representing the buddy if the operation is successful so far, null otherwise.

addBuddy

public PresenceSubscriber addBuddy(java.lang.String uri,
                                   java.lang.String eventId,
                                   long timeout)
This method is the same as addBuddy(uri, duration, eventId, timeout) except that the duration is defaulted to the default period defined in the event package RFC (3600 seconds).

Parameters:
uri - the URI (ie, sip:bob@nist.gov) of the buddy to be added to the list.
eventId - the event "id" to use in the SUBSCRIBE message, or null for no event "id" parameter. See addBuddy(uri, duration, eventId, timeout) javadoc for details on event "id" treatment.
timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
PresenceSubscriber object representing the buddy if the operation is successful so far, null otherwise.

fetchPresenceInfo

public PresenceSubscriber fetchPresenceInfo(java.lang.String uri,
                                            java.lang.String eventId,
                                            long timeout)
This method performs a presence 'fetch' on the given user, to get a one-time report on the user's presence status and information. Please read the SipUnit User Guide webpage Event Subscription (at least the operation overview part) for information on how to use SipUnit presence capabilities.

This method creates a SUBSCRIBE request message with expiry time of 0, sends it out, and waits for a response to be received. It saves the received response and checks for a "proceedable" (positive) status code value. Positive response status codes include any of the following: provisional (status / 100 == 1), UNAUTHORIZED, PROXY_AUTHENTICATION_REQUIRED, OK and ACCEPTED. Any other status code, or a response timeout or any other error, is considered fatal to the operation.

This method blocks until one of the above outcomes is reached.

In the case of a positive response status code, this method returns a PresenceSubscriber object representing the user and puts the object in this SipPhone's retired buddy list. The retired buddy list consists of subscriptions resulting from a fetch or from removing a buddy from the buddy list. You can save the returned PresenceSubscriber object yourself or retrieve it anytime later by calling this SipPhone's getBuddyInfo(buddy-uri). You will use the returned PresenceSubscriber object to proceed through the remainder of the SUBSCRIBE-NOTIFY sequence and to find out details such as the subscription state, termination reason, presence information, details of received responses and requests, etc.

In the case of a positive response status code (a non-null object is returned), you may find out more about the response that was just received by calling the PresenceSubscriber methods getReturnCode() and getCurrentResponse()/getLastReceivedResponse(). Your next step at this point will be to call the PresenceSubscriber's processResponse() method to proceed with the SUBSCRIBE processing.

In the case of a fatal outcome, no Subscription object is created and null is returned. In this case, call the usual SipUnit failed-operation methods to find out what happened (ie, call this SipPhone's getErrorMessage(), getReturnCode(), and/or getException() methods). The getReturnCode() method will tell you the response status code that was received from the network (unless it is an internal SipUnit error code, see the SipSession javadoc for more on that).

Parameters:
uri - the URI (ie, sip:bob@nist.gov) of the user whose presence info is to be fetched.
eventId - the event "id" to use in the SUBSCRIBE message, or null for no event "id" parameter. Whatever is indicated here will be used subsequently, for error checking the SUBSCRIBE response and NOTIFY from the server.
timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
PresenceSubscriber object representing the user fetch if the operation is successful so far, null otherwise.

fetchPresenceInfo

public PresenceSubscriber fetchPresenceInfo(java.lang.String uri,
                                            long timeout)
This method is the same as fetchPresenceInfo(uri, eventId, timeout) except that no event "id" parameter will be included in the SUBSCRIBE message. When error checking the SUBSCRIBE response and NOTIFY from the server, no event "id" parameter will be expected.

Parameters:
uri - the URI (ie, sip:bob@nist.gov) of the user whose presence info is to be fetched.
timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
PresenceSubscriber object representing the user fetch if the operation is successful so far, null otherwise.

getBuddyInfo

public PresenceSubscriber getBuddyInfo(java.lang.String uri)
This method returns the PresenceSubscriber object representing a buddy or user whose presence information was fetched at some previous point. The returned object contains the most recently obtained presence information for the given user. Status, presence device info, received requests (NOTIFY's) and SUBSCRIBE responses, etc. for this user's subscription can be obtained from the returned object. The user may have been a buddy in the buddy list (but was removed from the list by the test program), or fetchPresenceInfo() was previously called for the user to get a one-time status report, or the user may still be in the buddy list.

Parameters:
uri - the URI (ie, sip:bob@nist.gov) of the user whose subscription object is to be returned.
Returns:
A PresenceSubscriber object that contains information about the user's last obtained presence status and other info, or null if there was never any status fetch done for this user and this user was never in the buddy list.

getBuddyList

public java.util.Hashtable<java.lang.String,PresenceSubscriber> getBuddyList()
Returns a copy of the current buddy list on this SipPhone. These are the buddies that have been added to the buddy list by the test program during the lifetime of this SipPhone object, that are still in the buddy list. A given buddy, or subscription, in this list may be active or not - ie, subscription termination by the far end does not remove a buddy from this list. Buddies are removed from the list only by the test program (by calling removeBuddy()).

See related methods getBuddyInfo(), getRetiredBuddies().

Returns:
a Hashtable of zero or more entries, where the key = URI of the buddy, value = PresenceSubscriber object.

getRetiredBuddies

public java.util.Hashtable<java.lang.String,PresenceSubscriber> getRetiredBuddies()
Returns a copy of the list of subscriptions associated with this SipPhone which are not in the current buddy list. Subscriptions get in this list either because of a 'fetch' or whenever the test program removes a buddy from the buddy list. The main purpose of this list is so the last known presence status of a user can be obtained anytime. This is required to make the fetch case useful.

See related methods getBuddyInfo(), getBuddyList().

Returns:
a Hashtable of zero or more entries, where the key = URI of the user, value = PresenceSubscriber object.

getRefererInfo

public java.util.List<ReferSubscriber> getRefererInfo(javax.sip.address.SipURI referToUri)
This method returns the subscription object(s) associated with the given referToUri. The returned object(s) contains subscription state, received requests (NOTIFY's) and REFER/SUBSCRIBE responses, etc. for outbound REFER subscription(s) associated with the referToUri.

Parameters:
referToUri - the referToUri that was previously passed in to SipPhone.refer(). See javadoc there.
Returns:
ReferSubscriber object(s) associated with the referToUri, or an empty list if there was never a call to SipPhone.refer() with that referToUri.

getRefererInfoByDialog

public java.util.List<ReferSubscriber> getRefererInfoByDialog(java.lang.String dialogId)
This method returns the subscription object(s) associated with the given dialog ID. The returned object(s) contains subscription state, received requests (NOTIFY's) and REFER/SUBSCRIBE responses, etc. for outbound REFER subscription(s) associated with the dialog.

Parameters:
dialogId - the dialog ID of interest
Returns:
ReferSubscriber object(s) associated with the dialog, or an empty list if there was never a refer subscription associated with that dialog.

getRefererList

public java.util.List<ReferSubscriber> getRefererList()
Returns a copy of the list of subscriptions associated with outbound REFER requests from this SipPhone. These are the subscriptions resulting from calling SipPhone.refer() during the lifetime of this SipPhone object. A given subscription in the list may be active or not - subscription termination does not automatically remove a subscription from this list (calling ReferSubscriber.dispose() does that).

See related method getRefererInfo().

Returns:
a list of ReferSubscriber objects or an empty list if there are none.

getUri

public javax.sip.address.SipURI getUri(java.lang.String scheme,
                                       java.lang.String userHostPort,
                                       java.lang.String transportUriParameter,
                                       java.lang.String methodUriParameter,
                                       java.util.Map<java.lang.String,java.lang.String> otherUriParameters,
                                       java.lang.String joinUriHeader,
                                       java.lang.String replacesUriHeader,
                                       java.lang.String bodyUriHeader,
                                       java.util.Map<java.lang.String,java.lang.String> otherUriHeaders)
                                throws java.text.ParseException
Creates an URI object useful for passing into methods such as SipPhone.refer().

Parameters:
scheme - "sip:" or "sips:" or null if the scheme is already included in the userHostPort parameter.
userHostPort - Addressing information in the form of: user@host:port. Port is not required, and the scheme may optionally be included here instead of in the "scheme" parameter. Examples: sipmaster@192.168.1.11:5060 and sip:alice@atlanta.sip.com.
transportUriParameter - Specifies which transport protocol to use for sending requests and responses to this URI, or null if not needed.
methodUriParameter - Specifies which SIP method to use in requests directed at this URI (ie, INVITE), or null if not applicable.
otherUriParameters - Remaining URI parameters affecting a request constructed from this URI (Lr, MAddr, TTL, etc), or null if not applicable. URI parameters are key-value pairs. Any given parameter name (key) MUST NOT appear more than once.
joinUriHeader - This value is the dialog ID for a Join header to be included in a request constructed from this URI, or null if not applicable.
replacesUriHeader - This value is the dialog ID for a Replaces header to be included in a request constructed from this URI, or null if not applicable.
bodyUriHeader - This value is the message body of a SIP request constructed from this URI, or null if not applicable.
otherUriHeaders - Remaining header fields to be included in a request constructed from this URI, or null if not applicable. Header fields are key-value pairs.
Returns:
A SipURI for passing into methods such as SipPhone.refer().
Throws:
java.text.ParseException - On parse error due to invalid scheme or userHostPort parameters.

refer

public ReferSubscriber refer(java.lang.String refereeUri,
                             javax.sip.address.SipURI referToUri,
                             java.lang.String eventId,
                             long timeout,
                             java.lang.String viaNonProxyRoute)
This basic refer method creates an out-of-dialog REFER request message, sends it out, and waits for a first response to be received. It saves the received response and checks for a "proceedable" (positive) status code value. Positive response status codes include any of the following: provisional (status / 100 == 1), UNAUTHORIZED, PROXY_AUTHENTICATION_REQUIRED, OK and ACCEPTED. Any other status code, or a response timeout or any other error, is considered fatal to the subscription.

This method blocks until one of the above outcomes is reached.

In the case of a positive response status code, this method returns a ReferSubscriber object that represents the implicit subscription. You can save the returned object yourself or retrieve it anytime later by calling one of this SipPhone's getReferrerInfo() methods or getRefererList(). Use the returned subscription object to proceed through the remainder of this REFER-NOTIFY sequence as well as for future SUBSCRIBE-NOTIFY sequences on this subscription and also to find out details at any given time such as the subscription state, amount of time left on the subscription, termination reason, details of received responses and requests, etc.

In the case of a positive response status code (a non-null object is returned), you may find out more about the response that was just received by calling the ReferSubscriber methods getReturnCode() and getCurrentResponse(). Your next step will then be to call the ReferSubscriber's processResponse() method to proceed with the REFER processing.

In the case of a fatal outcome, no subscription object is created and null is returned. In this case, call the usual SipUnit failed-operation methods to find out what happened (ie, call this SipPhone's getErrorMessage(), getReturnCode(), and/or getException() methods). The getReturnCode() method will tell you the response status code that was received from the network (unless it is an internal SipUnit error code, see the SipSession javadoc for more on that).

Parameters:
refereeUri - The URI (ie, sip:bob@nist.gov) of the far end of the subscription. This is the party the REFER request is sent to.
referToUri - The URI that the refereeUri is to refer to. You can use SipPhone.getUri() to create this object for you to pass in, or you can create your own using the JAIN SIP API.
eventId - The event "id" to use in the REFER message, or null for no event "id" parameter. If an eventId is specified here, it will be used subsequently for error checking the REFER responses and the NOTIFYs from the far end as well as for sending subsequent SUBSCRIBEs unless changed by the caller later when invoking ReferSubscriber methods refresh() or unsubscribe().
timeout - The maximum amount of time to wait for a response, in milliseconds. Use a value of 0 to wait indefinitely.
viaNonProxyRoute - Affects the routing of the REFER message. By default, the message is routed to the Proxy that was specified when this SipPhone object was created (SipStack.createSipPhone()) or if no proxy was specified then, the REFER is looped back to this local sip stack. If the viaNonProxyRoute parameter is not null, it overrides the default behavior and causes the message to be routed differently, to the viaNonProxyRoute node which is specified as "hostaddress:port/transport" i.e. 129.1.22.333:5060/UDP. A route header will be added to the REFER for this, before the request is sent.
Returns:
ReferSubscriber object representing the implicit subscription if the operation is successful so far, null otherwise.

refer

public ReferSubscriber refer(java.lang.String refereeUri,
                             javax.sip.address.SipURI referToUri,
                             java.lang.String eventId,
                             long timeout,
                             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 out-of-dialog refer() 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.

refer

public ReferSubscriber refer(java.lang.String refereeUri,
                             javax.sip.address.SipURI referToUri,
                             java.lang.String eventId,
                             long timeout,
                             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 out-of-dialog refer() 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, 'message' part of 'message/sipfrag'), 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, 'sipfrag' part of 'message/sipfrag'), 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.

refer

public ReferSubscriber refer(javax.sip.Dialog dialog,
                             javax.sip.address.SipURI referToUri,
                             java.lang.String eventId,
                             long timeout)
This basic refer method creates an in-dialog REFER request message, sends it out, and waits for a first response to be received. It saves the received response and checks for a "proceedable" (positive) status code value. Positive response status codes include any of the following: provisional (status / 100 == 1), UNAUTHORIZED, PROXY_AUTHENTICATION_REQUIRED, OK and ACCEPTED. Any other status code, or a response timeout or any other error, is considered fatal to the subscription.

This method blocks until one of the above outcomes is reached.

In the case of a positive response status code, this method returns a ReferSubscriber object that represents the implicit subscription. You can save the returned object yourself or retrieve it anytime later by calling one of this SipPhone's getReferrerInfo() methods or getRefererList(). Use the returned subscription object to proceed through the remainder of this REFER-NOTIFY sequence as well as for future SUBSCRIBE-NOTIFY sequences on this subscription and also to find out details at any given time such as the subscription state, amount of time left on the subscription, termination reason, details of received responses and requests, etc.

In the case of a positive response status code (a non-null object is returned), you may find out more about the response that was just received by calling the ReferSubscriber methods getReturnCode() and getCurrentResponse(). Your next step will then be to call the ReferSubscriber's processResponse() method to proceed with the REFER processing.

In the case of a fatal outcome, no subscription object is created and null is returned. In this case, call the usual SipUnit failed-operation methods to find out what happened (ie, call this SipPhone's getErrorMessage(), getReturnCode(), and/or getException() methods). The getReturnCode() method will tell you the response status code that was received from the network (unless it is an internal SipUnit error code, see the SipSession javadoc for more on that).

Parameters:
dialog - The existing dialog that this REFER should be associated with. You can get it from SipCall.getDialog() or ReferSubscriber.getDialog().
referToUri - The URI that the far end of the dialog is to refer to. You can use SipPhone.getUri() to create this object for you to pass in, or you can create your own using the JAIN SIP API.
eventId - The event "id" to use in the REFER message, or null for no event "id" parameter. If an eventId is specified here, it will be used subsequently for error checking the REFER responses and the NOTIFYs from the far end as well as for sending subsequent SUBSCRIBEs unless changed by the caller later when invoking ReferSubscriber methods refresh() or unsubscribe().
timeout - The maximum amount of time to wait for a response, in milliseconds. Use a value of 0 to wait indefinitely.
Returns:
ReferSubscriber object representing the implicit subscription if the operation is successful so far, null otherwise.

refer

public ReferSubscriber refer(javax.sip.Dialog dialog,
                             javax.sip.address.SipURI referToUri,
                             java.lang.String eventId,
                             long timeout,
                             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 in-dialog refer() 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.

refer

public ReferSubscriber refer(javax.sip.Dialog dialog,
                             javax.sip.address.SipURI referToUri,
                             java.lang.String eventId,
                             long timeout,
                             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 in-dialog refer() 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, 'message' part of 'message/sipfrag'), 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, 'sipfrag' part of 'message/sipfrag'), 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.
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