org.cafesip.sipunit
Class SipPhone

java.lang.Object
  org.cafesip.sipunit.SipSession
      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, and buddy list/fetch (SUBSCRIBE/NOTIFY) operations. In future, a SipPhone object can have more than one SipCall object associated with it but currently only one is supported. One buddy list is 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

Subscription	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.
Subscription	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.
Subscription	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.
Subscription	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.
Subscription	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.
Subscription	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.
Subscription	getBuddyInfo(java.lang.String uri) This method returns the Subscription object representing a buddy or user whose presence information was fetched at some previous point.
java.util.Hashtable<java.lang.String,Subscription>	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.Hashtable<java.lang.String,Subscription>	getRetiredBuddies() Returns a copy of the list of subscriptions associated with this SipPhone which are not in the current buddy list.
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.
void	processEvent(java.util.EventObject event) For internal SipUnit use only.
Subscription	refreshBuddy(java.lang.String uri, int duration, long timeout) This method is the same as refreshBuddy(uri, duration, eventId, timeout) except that the eventId remains unchanged from whatever it already was.
Subscription	refreshBuddy(java.lang.String uri, int duration, java.lang.String eventId, long timeout) This method updates the presence information of a buddy in the buddy list by initiating a SUBSCRIBE/NOTIFY sequence.
Subscription	refreshBuddy(java.lang.String uri, long timeout) This method is the same as refreshBuddy(uri, duration, eventId, timeout) except that the eventId remains unchanged from whatever it already was and the SUBSCRIBE duration sent will be however much time is left on the current subscription.
Subscription	refreshBuddy(java.lang.String uri, javax.sip.message.Request req, long timeout) This method is the same as refreshBuddy(uri, duration, eventId, timeout) except that instead of creating the SUBSCRIBE request from parameters passed in, the provided request parameter is used for sending out the SUBSCRIBE message.
Subscription	refreshBuddy(java.lang.String uri, java.lang.String eventId, long timeout) This method is the same as refreshBuddy(uri, duration, eventId, timeout) except that the SUBSCRIBE duration sent will be however much time is left on the current subscription.
boolean	register(java.lang.String contact, int expiry) This method is equivalent to the other register() method with no authorization parameters passed in.
boolean	register(java.lang.String user, java.lang.String password, java.lang.String contact, int expiry, long timeout) This method is used to register with the SIP proxy server that was specified when this SipPhone was created.
Subscription	removeBuddy(java.lang.String uri, long timeout) This method is the same as removeBuddy(uri, eventId, timeout) except that no event "id" parameter will be included in the unSUBSCRIBE message.
Subscription	removeBuddy(java.lang.String uri, javax.sip.message.Request req, long timeout) This method is the same as removeBuddy(uri, eventId, timeout) except that instead of creating the SUBSCRIBE request from parameters passed in, the provided request parameter is used for sending out the SUBSCRIBE message if the subscription is active.
Subscription	removeBuddy(java.lang.String uri, java.lang.String eventId, long timeout) This method removes a buddy from the buddy list and initiates a SUBSCRIBE/NOTIFY sequence to terminate the subscription unless the subscription is already terminated.
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, 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, 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 to register with the SIP proxy server that was specified when this SipPhone was created. If none was specified, the REGISTER message is sent using information from this SipPhone's URI (address of record). In either case, if the host is not a numeric IP address (w.x.y.z), DNS will be used to resolve the host name to an address.

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.

register

public boolean register(java.lang.String contact,
                        int expiry)

This method is equivalent to the other register() method with no authorization parameters passed in. 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.

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 UAC originating the call and the inbound leg is the UAC 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 Subscription 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 Presence section (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 Subscription object that will represent the buddy for the life of the subscription and puts the Subscription object in this SipPhone's buddy list. You can save the returned Subscription object yourself or retrieve it anytime later by calling this SipPhone's getBuddyInfo(buddy-uri). You will use the returned Subscription object to proceed through the remainder of this SUBSCRIBE-NOTIFY sequence as well as 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 Subscription methods getReturnCode() and getCurrentSubscribeResponse()/getLastReceivedResponse(). Your next step at this point will be to call the Subscription's processSubscribeResponse() method to proceed with the SUBSCRIBE processing.

In the case of a fatal outcome, no Subscription 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:

Subscription object representing the buddy if the operation is successful so far, null otherwise.

addBuddy

public Subscription 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:

Subscription object representing the buddy if the operation is successful so far, null otherwise.

addBuddy

public Subscription 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:

Subscription object representing the buddy if the operation is successful so far, null otherwise.

addBuddy

public Subscription 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:

Subscription object representing the buddy if the operation is successful so far, null otherwise.

fetchPresenceInfo

public Subscription 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 Presence section (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 Subscription object representing the user and puts the Subscription 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 Subscription object yourself or retrieve it anytime later by calling this SipPhone's getBuddyInfo(buddy-uri). You will use the returned Subscription 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 Subscription methods getReturnCode() and getCurrentSubscribeResponse()/getLastReceivedResponse(). Your next step at this point will be to call the Subscription's processSubscribeResponse() method to proceed with the SUBSCRIBE processing.

In the case of a fatal outcome, no Subscription 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:

Subscription object representing the user fetch if the operation is successful so far, null otherwise.

fetchPresenceInfo

public Subscription 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:

Subscription object representing the user fetch if the operation is successful so far, null otherwise.

getBuddyInfo

public Subscription getBuddyInfo(java.lang.String uri)

This method returns the Subscription 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 Subscription 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.

refreshBuddy

public Subscription refreshBuddy(java.lang.String uri,
                                 int duration,
                                 java.lang.String eventId,
                                 long timeout)

This method updates the presence information of a buddy in the buddy list by initiating a SUBSCRIBE/NOTIFY sequence. It is virtually the same as addBuddy(uri, duration, eventId, timeout) except that the buddy list content is not changed by this operation and the existing Subscription object for this buddy continues to be used (no new one is created). For a test program, stepping through and processing the SUBSCRIBE/NOTIFY sequence for a refresh is the same as it is for the addBuddy() case. Please read the addBuddy(uri, duration, eventId, timeout) javadoc.

The subscription duration is reset to the passed in value. If the passed in duration is 0, this is an unsubscribe. Note, the buddy stays in the buddy list even though the subscription won't be active.

Parameters:

uri - the URI (ie, sip:bob@nist.gov) of the buddy in the list to refresh

duration - the duration in seconds to put in the SUBSCRIBE message and reset the subscription time left to.

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:

The existing Subscription object representing the buddy if the refresh operation is successful so far, null otherwise. Null just means this SUBSCRIBE sequence failed, the buddy's Subscription object still exists as before (you can get it by calling SipPhone.getBuddyInfo() if you need it). If this method returns null, call this SipPhone's getReturnCode(), getErrorMessage() and/or getException() methods to see why the operation failed.

refreshBuddy

public Subscription refreshBuddy(java.lang.String uri,
                                 java.lang.String eventId,
                                 long timeout)

This method is the same as refreshBuddy(uri, duration, eventId, timeout) except that the SUBSCRIBE duration sent will be however much time is left on the current subscription. If time left on the subscription <= 0, unsubscribe occurs (note, the buddy stays in the list).

Parameters:

uri - the URI (ie, sip:bob@nist.gov) of the buddy in the list to refresh

eventId - the event "id" to use in the SUBSCRIBE message, or null for no event "id" parameter. See refreshBuddy(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:

The existing Subscription object representing the buddy if the refresh operation is successful so far, null otherwise. Null just means this SUBSCRIBE sequence failed, the buddy's Subscription object still exists as before (you can get it by calling SipPhone.getBuddyInfo() if you need it). If this method returns null, call this SipPhone's getReturnCode(), getErrorMessage() and/or getException() methods to see why the operation failed.

refreshBuddy

public Subscription refreshBuddy(java.lang.String uri,
                                 int duration,
                                 long timeout)

This method is the same as refreshBuddy(uri, duration, eventId, timeout) except that the eventId remains unchanged from whatever it already was.

Parameters:

uri - the URI (ie, sip:bob@nist.gov) of the buddy in the list to refresh

duration - the duration in seconds to put in the SUBSCRIBE message and reset the subscription time left to.

timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.

Returns:

The existing Subscription object representing the buddy if the refresh operation is successful so far, null otherwise. Null just means this SUBSCRIBE sequence failed, the buddy's Subscription object still exists as before (you can get it by calling SipPhone.getBuddyInfo() if you need it). If this method returns null, call this SipPhone's getReturnCode(), getErrorMessage() and/or getException() methods to see why the operation failed.

refreshBuddy

public Subscription refreshBuddy(java.lang.String uri,
                                 long timeout)

This method is the same as refreshBuddy(uri, duration, eventId, timeout) except that the eventId remains unchanged from whatever it already was and the SUBSCRIBE duration sent will be however much time is left on the current subscription. If time left on the subscription <= 0, unsubscribe occurs (note, the buddy stays in the list).

Parameters:

uri - the URI (ie, sip:bob@nist.gov) of the buddy in the list to refresh

timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.

Returns:

The existing Subscription object representing the buddy if the refresh operation is successful so far, null otherwise. Null just means this SUBSCRIBE sequence failed, the buddy's Subscription object still exists as before (you can get it by calling SipPhone.getBuddyInfo() if you need it). If this method returns null, call this SipPhone's getReturnCode(), getErrorMessage() and/or getException() methods to see why the operation failed.

refreshBuddy

public Subscription refreshBuddy(java.lang.String uri,
                                 javax.sip.message.Request req,
                                 long timeout)

This method is the same as refreshBuddy(uri, duration, eventId, timeout) except that instead of creating the SUBSCRIBE request from parameters passed in, the provided request parameter is used for sending out the SUBSCRIBE message.

The Request parameter passed in comes from Subscription.createSubscribeMessage(). The subscription duration is reset to the passed in Request's expiry value. If it is 0, this is an unsubscribe. Note, the buddy stays in the buddy list even though the subscription won't be active. The event "id" in the given request will be used subsequently (for error checking SUBSCRIBE responses and NOTIFYs from the server as well as for sending subsequent SUBSCRIBEs).

Parameters:

uri - the URI (ie, sip:bob@nist.gov) of the buddy in the list to refresh

req - the Request to send to 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:

The existing Subscription object representing the buddy if the refresh operation is successful so far, null otherwise. Null just means this SUBSCRIBE sequence failed, the buddy's Subscription object still exists as before (you can get it by calling SipPhone.getBuddyInfo() if you need it). If this method returns null, call this SipPhone's getReturnCode(), getErrorMessage() and/or getException() methods to see why the operation failed.

removeBuddy

public Subscription removeBuddy(java.lang.String uri,
                                java.lang.String eventId,
                                long timeout)

This method removes a buddy from the buddy list and initiates a SUBSCRIBE/NOTIFY sequence to terminate the subscription unless the subscription is already terminated. Regardless, the buddy is taken out of the active buddy list and put into the retired buddy list (which is a list of Subscription objects of buddies that have been removed from the buddy list and Subscription objects for individual fetch operations that have been done). A retired buddy's Subscription object continues to be accessible (via SipPhone.getBuddyInfo()).

If the subscription is active, this operation is virtually the same as addBuddy(uri, duration, eventId, timeout) except that it is an 'unsubscribe' and also the existing Subscription object for this buddy continues to be used (no new one is created). For a test program, stepping through and processing the SUBSCRIBE/NOTIFY sequence for a "remove" is the same as it is for the addBuddy() case. Please read the addBuddy(uri, duration, eventId, timeout) javadoc.

If the subscription is already terminated, no SUBSCRIBE/NOTIFY sequence is initiated.

In order for you to determine whether or not to proceed forward with the SUBSCRIBE/NOTIFY sequence processing when this method returns non-null, call the returned Subscription's isRemovalComplete() method. It will tell you if an unsubscribe sequence was initiated, by returning false, or not initiated, by returning true.

Parameters:

uri - the URI (ie, sip:bob@nist.gov) of the buddy to be removed

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 unSUBSCRIBE 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:

The existing Subscription object representing the buddy if the unsubscribe operation is successful so far or wasn't needed, null otherwise. In either case, the buddy is removed from the buddy list. Null just means this unSUBSCRIBE sequence failed, the buddy's Subscription object still exists as before (you can get it anytime by calling SipPhone.getBuddyInfo()). If this method returns null, call this SipPhone's getReturnCode(), getErrorMessage() and/or getException() methods to see why the operation failed. If the buddy wasn't in the list, null is returned immediately.

removeBuddy

public Subscription removeBuddy(java.lang.String uri,
                                long timeout)

This method is the same as removeBuddy(uri, eventId, timeout) except that no event "id" parameter will be included in the unSUBSCRIBE 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 buddy to be removed

timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.

Returns:

The existing Subscription object representing the buddy if the unsubscribe operation is successful so far or wasn't needed, null otherwise. In either case, the buddy is removed from the buddy list. Null just means this unSUBSCRIBE sequence failed, the buddy's Subscription object still exists as before (you can get it anytime by calling SipPhone.getBuddyInfo()). If this method returns null, call this SipPhone's getReturnCode(), getErrorMessage() and/or getException() methods to see why the operation failed. If the buddy wasn't in the list, null is returned immediately.

removeBuddy

public Subscription removeBuddy(java.lang.String uri,
                                javax.sip.message.Request req,
                                long timeout)

This method is the same as removeBuddy(uri, eventId, timeout) except that instead of creating the SUBSCRIBE request from parameters passed in, the provided request parameter is used for sending out the SUBSCRIBE message if the subscription is active.

The Request parameter passed in comes from Subscription.createSubscribeMessage(). The event "id" in the given request will be used subsequently for error checking the SUBSCRIBE response and NOTIFY request from the server.

Parameters:

uri - the URI (ie, sip:bob@nist.gov) of the buddy to be removed

req - the Request to send to 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:

The existing Subscription object representing the buddy if the unsubscribe operation is successful so far or wasn't needed, null otherwise. In either case, the buddy is removed from the buddy list. Null just means this unSUBSCRIBE sequence failed, the buddy's Subscription object still exists as before (you can get it anytime by calling SipPhone.getBuddyInfo()). If this method returns null, call this SipPhone's getReturnCode(), getErrorMessage() and/or getException() methods to see why the operation failed. If the buddy wasn't in the list, null is returned immediately.

getBuddyList

public java.util.Hashtable<java.lang.String,Subscription> 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 = Subscription object.

getRetiredBuddies

public java.util.Hashtable<java.lang.String,Subscription> 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 = Subscription object.