3PCC Function

CallControlServlet Class

package com.oki.sip.equips.signal;

public class CallControlServlet extends B2BUAServlet
    implements CallControlConstants, SipConstants
{
    public CallingProgressHandler makeCall(SipRequestParams params)
        thorws ServletParseException, SignalingException;

    public CallingProgressHandler makeCall(int flowType,
                                           int timeout,
                                           int timeout2,
                                           CallingEntity caller,
                                           CallingEntity callee,
                                           CallingProgressListener listener)
                                           Locale locale)
        thorws ServletParseException, SignalingException;
}

CallControlServlet is a servlet class that implements the 3PCC function. This class inherits B2BUAServlet. So this servlet functions as B2BUA after establishing a call.

You can set the following two initialization parameters in this SIP servlet.

This servlet exposes two methods used to establish a call between two terminals:

The first makeCall method is used to start the HTTP servlet using SipRequestDispatcher. Internally, information stored in params (SipRequestParams class) is extracted to invoke the second makeCall method. Attributes that can be set in params are:

The second makeCall method specifies all the arguments and invokes processes. If you call this method from an HTTP servlet, write the following code:

ServletContext context = session.getServletContext();
CallControlServlet servlet = (CallControlServlet) context.getServlet("3pcc");
CallingProgressHandler handler = servlet.makeCall(4, 120, 25, caller, callee, listener, Locale.getDefault());

Note that the ServletContext.getServlet is a deprecated method. Use the makeCall method instead as shown earlier. The description of the arguments and returned values of this method is as follows:

flowType (int)

Specifies the type of the call flow. Valid values are 1 and 4. IllegalArgumentException will be thrown if any value other than the above values is specified.

timeout (int)

Timeout time (in seconds).

timeout2 (int)

Timeout time (in seconds) of the callback in the Type 4 sequence.

caller (CallingEntity)

Specifies caller information. IllegalArgumentException will be thrown if null is specified.

callee (CallingEntity)

Specifies receiver information. IllegalArgumentException will be thrown if null is specified.

listener (CallingProgressListener)

The event listener that receives events about the ongoing call control. If this listener is set, CallControlServlet notifies the event information via this listener as the SIP sequence proceeds. Specify null if such event receipt is not required.

locale (Locale)

Specifies the locale of messages extracted from event information (CallingProgress). If the value is null, the default locale of the server is used.

Return Value (CallingProgressMonitor)

Returns the handler to control the ongoing call as the return of the method call. You can use this handler to request the cancellation of the connection.

CallingEntity Class

package com.oki.sip.equips.signal;

public class CallingEntity {
    private final SipURI uri;
    private final String display;
    protected Address contact;

    public CallingEntity(SipURI uri, String display, Address contact);

    public CallingEntity(SipURI uri, String display);

    public SipURI getSipURI();

    public String getDisplay();

    public Address getContact();
    public void setContact(Address contact);
}

The CallingEntity is a container class that stores information on the party (caller or receiver) that establishes the call with 3PCC. It has three instance variables:

uri (SipURI)

Stores the SIP URI of the party.

display (String)

Stores the display name of the party.

contact (Address)

Stores contact information of the connecting terminal.

The CallingEntity class provides only getter methods for uri and display since these variables are declared as final. For contact, both the setter and getter methods are provided.

The getDisplay method returns display if a meaningful value is set in the display variable, otherwise returns the user part in uri.

CallingProgressListener Interface

package com.oki.sip.equips.signal;

public interface CallingProgressListener extends EventListener {
    void statusChanged(CallingProgress progress);
}

CallingProgressListener is an interface used for CallControleServlet to notify the caller of the state of ongoing call control. This event notification is issued whenever the step is changed in Figure 1 (Call Flow Type 1). When the event receipt is required, application developers create a class that implements this interface and pass it to CallControlServlet as the argument of makeCall.

CallingProgress Class

package com.oki.sip.equips.signal;

public class CallingProgress extends EventObject
    implements Serializable
{
    public SipURI getCallerURI();
    public SipURI getCalleeURI();

    public int getPercent();

    public boolean isInitiated();

    public boolean isDone();

    public int getStatusCode();

    public String getReasonPhrase();

    public String getMessage();

    public long getCallLength();

    public static final int TERM_NOT_YET;
    public static final int TERM_HOOK;
    public static final int TERM_CANCEL;
    public static final int TERM_TIMEOUT;
    public static final int TERM_ERROR;

    public int getTerminatingCode();
}

CallingProgress is a class that stores the progress of the call, which is used as the argument of CallingProgressListener. It stores various state information as shown below:

getCallerURI and getCalleeURI are methods that get the SIP URI of the party that establishes the call. This information is not changed from the time the first request is delivered to CallControlServlet.

getPercent is a method that returns the percentage that represents the current progress. This method returns 100 (%) upon the establishment of the call, not on the disconnection of it. Use the isDone method to detect that the call is disconnected.

isInitiated is a method that determines whether the call is established. It returns true if the call is established, otherwise (such as on failure) returns false.

isOnline is a method that determines whether the call is online. It returns true if online, otherwise returns false. Note that the call is not controlled strictly in SIP, unlike traditional telephony systems. This method returns the state that CallControlServlet recognizes it as online. Therefore, there is no guarantee that it is really online. For example, if either of the SIP terminals terminates a realtime session without issuing BYE due to a network failure, CallControlServlet recognizes that the session is still online.

isDone is a method that determines whether the call is disconnected. It returns true if the call is successfully completed or the call process is aborted.

getStatusCode and getReasonPhrase returns the status code and description string of the last received SIP response. For example, if the SIP response is "180 RINGING", "180" represents the status code and "RINGING" represents the description string. If an event is triggered based on sending an SIP request, the status code of the SIP response received before then is set.

getMessage is a method that retrieves the description string set by CallControlServlet. Examples of these strings are:

• Connected to the terminal of Mr./Ms. XX.
• Now calling to Mr./Ms. XX.
• Mr./Ms. XX could not respond to the call.

getCallLength returns the call period in msec. This method returns a meaningful value if the call is established and completed. Otherwise (when the call is not established, the call is busy, and an error or cancel occurred), a negative value is returned.

getTerminatingCode is a method that returns the cause of the 3PCC process completion. This method returns one of the following values:

TERM_NOT_YET

Indicates that the 3PCC process in not completed. This corresponds to isDone() == false.

TERM_HOOK

Indicate that the call is completed by the SIP terminal or the CallingProgressHandler.terminate() method. If this value is returned, getCallLength returns a meaningful value.

TERM_CANCEL

Indicate that the 3PCC process is canceled by the CallingProgressHandler.cancel() method.

TERM_TIMEOUT

Indicates that timeout occurred since either of SIP terminals does not respond within the specified period. The timeout period can be specified with the makeCall method.

TERM_ERROR

The 3PCC process is terminated due to a condition such as an error response by the SIP terminal. If an incoming call is rejected with OKISoftphone, a "603 Decline" response is returned. Such case is recognized as an error response.

CallingProgressHandler Interface

package com.oki.sip.equips.signal;

public interface CallingProgressHandler {
    CallingProgress getStatus();

    void cancel() throws IllegalStateException;

    void terminate() throws IllegalStateException;
}

The CallingProgressHandler interface is used to control the call process initiated by makeCall from outside. SIP Servlet Engine 3.0 can disconnect or cancel the call. This object can be retrieved as a return value of the CallControlServlet.makeCall.

getStatus is a method that gets the current state of the 3PCC process. This method returns the CallingProgress object, which is the same class to CallingProgressListener .

cancel is a method that interrupts the current state of the 3PCC process. This method is only available until the call is established. When you disconnect a call already established, use the terminate() method. If you call this method after the process is terminated due to an error response, IllegalStateException is thrown.

terminate is a method that disconnects the call established by 3PCC. This method is available only for the call that has been already established. Use cancel() to cancel the call that has not been established yet. If this method is invoked when the call has not been established, IllegalStateException is thrown.