/*
 * SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
 *
 * Distributable under LGPL license.
 * See terms of license at gnu.org.
 */
package net.java.sip.communicator.service.protocol;

import net.java.sip.communicator.service.protocol.event.*;
import java.util.*;

/**
 * An Operation Set defining all basic telephony operations such as conducting
 * simple calls and etc. Note that video is not considered as a part of a
 * supplementary operation set and if included in the service should be available
 * behind the basic telephoy set.
 *
 * @author Emil Ivov
 */
public interface OperationSetBasicTelephony
    extends OperationSet
{
    /**
     * Registers the specified CallListener with this provider so that it could
     * be notified when incoming calls are received. This method is called
     * by the implementation of the PhoneUI service.
     * @param listener the listener to register with this provider.
     */
    public void addCallListener(CallListener listener);

    /**
     * Removes the specified listener from the list of call listeners.
     * @param listener the listener to unregister.
     */
    public void removeCallListener(CallListener listener);

    /**
     * Create a new call and invite the specified CallParticipant to it.
     *
     * @param uri the address of the callee that we should invite to a new
     * call.
     * @return CallParticipant the CallParticipant that will represented by the
     * specified uri. All following state change events will be delivered
     * through that call participant. The Call that this participant is a member
     * of could be retrieved from the CallParticipatn instance with the use
     * of the corresponding method.
     */
    public Call createCall(String uri);

    /**
     * Create a new call and invite the specified CallParticipant to it.
     *
     * @param callee the address of the callee that we should invite to a new
     * call.
     * @return CallParticipant the CallParticipant that will represented by the
     * specified uri. All following state change events will be delivered
     * through that call participant. The Call that this participant is a member
     * of could be retrieved from the CallParticipatn instance with the use
     * of the corresponding method.
     */
    public Call createCall(Contact callee);

    /**
     * Indicates a user request to answer an incoming call from the specified
     * CallParticipant.
     * @param participant the call participant that we'd like to anwer.
     */
    public void answerCallParticipant(CallParticipant participant);

    /**
     * Puts the specified CallParticipant "on hold". In other words incoming
     * media flows are not played and outgoing media flows are either muted or
     * stopped, without actually interrupting the session.
     * @param participant the participant that we'd like to put on hold.
     */
    public void putOnHold(CallParticipant participant);

    /**
     * Resumes communication with a call participant previously put on hold. If
     * the specified participant is not "On Hold" at the time putOffHold is
     * called, the method has no effect.
     * @param participant the call participant to put on hold.
     */
    public void putOffHold(CallParticipant participant);

    /**
     * Indicates a user request to end a call with the specified call
     * particiapnt.
     * @param participant the participant that we'd like to hang up on.
     */
    public void hangupCallParticipant(CallParticipant participant);

    /**
     * Returns an iterator over all currently active calls.
     * @return Iterator
     */
    public Iterator getActiveCalls();
}

@@ -283,16 +283,36 @@
 .util.*;
+%0Aimport java.text.*;
 %0A%0A/**%0A *
@@ -957,24 +957,31 @@
 s provider.%0A
+     *%0A
      */%0A    
@@ -1764,48 +1764,310 @@
    *
-/%0A    public Call createCall(String uri)
+ @throws OperationFailedException with the corresponding code if we fail%0A     * to create the call.%0A     * @throws ParseException if %3Ctt%3Ecallee%3C/tt%3E is not a valid sip address%0A     * string.%0A     */%0A    public Call createCall(String uri)%0A        throws OperationFailedException%0A        , ParseException
 ;%0A%0A 
@@ -2587,24 +2587,130 @@
 ing method.%0A
+     * @throws OperationFailedException with the corresponding code if we fail%0A     * to create the call.%0A
      */%0A    
@@ -2747,16 +2747,56 @@
  callee)
+%0A        throws OperationFailedException
 ;%0A%0A    /
@@ -2968,24 +2968,157 @@
 e to anwer.%0A
+     * @throws OperationFailedException with the corresponding code if we%0A     * encounter an error while performing this operation.%0A
      */%0A    
@@ -3171,32 +3171,72 @@
 ant participant)
+%0A        throws OperationFailedException
 ;%0A%0A    /**%0A     
@@ -3510,32 +3510,165 @@
 to put on hold.%0A
+     * @throws OperationFailedException with the corresponding code if we%0A     * encounter an error while performing this operation.%0A
      */%0A    publ
@@ -3705,32 +3705,72 @@
 ant participant)
+%0A        throws OperationFailedException
 ;%0A%0A    /**%0A     
@@ -4256,24 +4256,157 @@
 hang up on.%0A
+     * @throws OperationFailedException with the corresponding code if we%0A     * encounter an error while performing this operation.%0A
      */%0A    
@@ -4459,32 +4459,72 @@
 ant participant)
+%0A        throws OperationFailedException
 ;%0A%0A    /**%0A     

Support for SIP (Work in Progress)