/*
* Jitsi, 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 java.awt.*;
import java.beans.*;
import java.text.*;
import net.java.sip.communicator.service.neomedia.*;
import net.java.sip.communicator.service.protocol.event.*;
/**
* Represents an OperationSet giving access to video-specific
* functionality in telephony such as visual Components displaying
* video and listening to dynamic availability of such Components.
*
* @author Lubomir Marinov
* @author Sebastien Vincent
*/
public interface OperationSetVideoTelephony
extends OperationSet
{
/**
* Adds a specific VideoListener to this telephony in order to
* receive notifications when visual/video Components are being
* added and removed for a specific CallPeer.
*
* @param peer the CallPeer whose video the specified listener
* is to be notified about
* @param listener the VideoListener to be notified when
* visual/video Components are being added or removed for
* peer
*/
public void addVideoListener( CallPeer peer, VideoListener listener);
/**
* Creates a visual Component which depicts the local video
* being streamed to a specific CallPeer. The returned
* visual Component should be disposed when it is no longer
* required through {@link #disposeLocalVisualComponent(CallPeer,
* Component) disposeLocalVisualComponent}.
*
* @param peer the CallPeer to whom the local video which is to be
* depicted by the returned visual Component is being streamed
* @param listener if not null, a VideoListener to track
* the progress of the creation in case this telephony chooses to perform it
* asynchronously and to not return the created visual Component
* immediately/as the result of this method call
*
* @return a visual Component which depicts the local video being
* streamed to the specified CallPeer if this telephony chooses to
* carry out the creation synchronously; null if this telephony
* chooses to create the requested visual Component asynchronously.
*
* @throws OperationFailedException if creating the component fails for
* whatever reason.
*/
public Component createLocalVisualComponent(CallPeer peer,
VideoListener listener)
throws OperationFailedException;
/**
* Disposes of a visual Component depicting the local video for
* a specific CallPeer (previously obtained through
* {@link #createLocalVisualComponent(CallPeer, VideoListener)
* createLocalVisualComponent}).
* The disposal may include, but is not limited to, releasing the
* Player which provides the component and renders
* the local video into it, disconnecting from the video capture device.
*
* @param peer the CallPeer for whom the visual Component
* depicts the local video
* @param component the visual Component depicting the local video
* to be disposed
*/
public void disposeLocalVisualComponent(CallPeer peer, Component component);
/**
* Gets the visual/video Component available in this telephony for
* a specific CallPeer.
*
* @param peer the CallPeer whose video is to be retrieved
* @return the visual/video Component available in this telephony
* for the specified peer if any; otherwise, null
*/
public Component getVisualComponent(CallPeer peer);
/**
* Removes a specific VideoListener from this telephony in
* order to no longer have it receive notifications when visual/video
* Components are being added and removed for a specific
* CallPeer.
*
* @param peer the CallPeer whose video the specified listener is
* to no longer be notified about
* @param listener the VideoListener to no longer be notified
* when visual/video Components are being added or removed for
* peer
*/
public void removeVideoListener(CallPeer peer, VideoListener listener);
/**
* Sets the indicator which determines whether the streaming of local video
* in a specific Call is allowed. The setting does not reflect
* the availability of actual video capture devices, it just expresses the
* desire of the user to have the local video streamed in the case the
* system is actually able to do so.
*
* @param call the Call to allow/disallow the streaming of local
* video for
* @param allowed true to allow the streaming of local video for
* the specified Call; false to disallow it
*
* @throws OperationFailedException if initializing local video fails.
*/
public void setLocalVideoAllowed(Call call, boolean allowed)
throws OperationFailedException;
/**
* Gets the indicator which determines whether the streaming of local video
* in a specific Call is allowed. The setting does not reflect
* the availability of actual video capture devices, it just expresses the
* desire of the user to have the local video streamed in the case the
* system is actually able to do so.
*
* @param call the Call to get the indicator of
* @return true if the streaming of local video for the specified
* Call is allowed; otherwise, false
*/
public boolean isLocalVideoAllowed(Call call);
/**
* The property which indicates whether a specific Call is
* currently streaming the local video (to a remote destination).
*/
public static final String LOCAL_VIDEO_STREAMING = "LOCAL_VIDEO_STREAMING";
/**
* Gets the indicator which determines whether a specific Call
* is currently streaming the local video (to a remote destination).
*
* @param call the Call to get the indicator of
* @return true if the specified Call is currently
* streaming the local video (to a remote destination); otherwise,
* false
*/
public boolean isLocalVideoStreaming(Call call);
/**
* Adds a specific PropertyChangeListener to the list of
* listeners which get notified when the properties (e.g.
* {@link #LOCAL_VIDEO_STREAMING}) associated with a specific
* Call change their values.
*
* @param call the Call to start listening to the changes of
* the property values of
* @param listener the PropertyChangeListener to be notified
* when the properties associated with the specified Call change
* their values
*/
public void addPropertyChangeListener(Call call,
PropertyChangeListener listener);
/**
* Removes a specific PropertyChangeListener from the list of
* listeners which get notified when the properties (e.g.
* {@link #LOCAL_VIDEO_STREAMING}) associated with a specific
* Call change their values.
*
* @param call the Call to stop listening to the changes of the
* property values of
* @param listener the PropertyChangeListener to no longer be
* notified when the properties associated with the specified Call
* change their values
*/
public void removePropertyChangeListener(Call call,
PropertyChangeListener listener);
/**
* Create a new video call and invite the specified CallPeer to it.
*
* @param uri the address of the callee that we should invite to a new
* call.
* @return CallPeer the CallPeer that will represented by the
* specified uri. All following state change events will be delivered
* through that call peer. The Call that this peer is a member
* of could be retrieved from the CallParticipatn instance with the use
* of the corresponding method.
* @throws OperationFailedException with the corresponding code if we fail
* to create the video call.
* @throws ParseException if callee is not a valid sip address
* string.
*/
public Call createVideoCall(String uri)
throws OperationFailedException, ParseException;
/**
* Create a new video call and invite the specified CallPeer to it.
*
* @param callee the address of the callee that we should invite to a new
* call.
* @return CallPeer the CallPeer that will represented by the
* specified uri. All following state change events will be delivered
* through that call peer. The Call that this peer is a member
* of could be retrieved from the CallParticipatn instance with the use
* of the corresponding method.
* @throws OperationFailedException with the corresponding code if we fail
* to create the video call.
*/
public Call createVideoCall(Contact callee)
throws OperationFailedException;
/**
* Create a new video call and invite the specified CallPeer to it.
*
* @param uri the address of the callee that we should invite to a new
* call.
* @param qualityPreferences the quality preset we will use establishing
* the video call, and we will expect from the other side. When establishing
* call we don't have any indications whether remote part supports quality
* presets, so this setting can be ignored.
* @return CallPeer the CallPeer that will represented by the
* specified uri. All following state change events will be delivered
* through that call peer. The Call that this peer is a member
* of could be retrieved from the CallParticipatn instance with the use
* of the corresponding method.
* @throws OperationFailedException with the corresponding code if we fail
* to create the video call.
* @throws ParseException if callee is not a valid sip address
* string.
*/
public Call createVideoCall(String uri, QualityPreset qualityPreferences)
throws OperationFailedException, ParseException;
/**
* Create a new video call and invite the specified CallPeer to it.
*
* @param callee the address of the callee that we should invite to a new
* call.
* @param qualityPreferences the quality preset we will use establishing
* the video call, and we will expect from the other side. When establishing
* call we don't have any indications whether remote part supports quality
* presets, so this setting can be ignored.
* @return CallPeer the CallPeer that will represented by the
* specified uri. All following state change events will be delivered
* through that call peer. The Call that this peer is a member
* of could be retrieved from the CallParticipatn instance with the use
* of the corresponding method.
* @throws OperationFailedException with the corresponding code if we fail
* to create the video call.
*/
public Call createVideoCall(Contact callee,
QualityPreset qualityPreferences)
throws OperationFailedException;
/**
* Indicates a user request to answer an incoming call with video enabled
* from the specified CallPeer.
* @param peer the call peer that we'd like to answer.
* @throws OperationFailedException with the corresponding code if we
* encounter an error while performing this operation.
*/
public void answerVideoCallPeer(CallPeer peer)
throws OperationFailedException;
/**
* Returns the quality control for video calls if any. It can be null if we
* were able to successfully determine that other party does not support it.
* @param peer the peer which this control operates on.
* @return the implemented quality control.
*/
public QualityControl getQualityControl(CallPeer peer);
}