/*
* Jitsi, the OpenSource Java VoIP and Instant Messaging client.
*
* Copyright @ 2015 Atlassian Pty Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.java.sip.communicator.service.protocol;
import java.util.*;
import net.java.sip.communicator.service.protocol.event.*;
/**
* Provides basic functionality for white-board.
*
* @author Julien Waechter
*/
public interface OperationSetWhiteboarding
extends OperationSet
{
/**
* Returns a list of the <tt>WhiteboardSession</tt>s that we have joined and
* are currently active in.
*
* @return a <tt>List</tt> of the <tt>WhiteboardSession</tt>s where the user
* has joined using a given connection.
*/
public List<WhiteboardSession> getCurrentlyJoinedWhiteboards();
/**
* Returns a list of the <tt>WhiteboardSession</tt>s that
* <tt>WhiteboardParticipant</tt> has joined and is currently active in.
*
* @param participant the participant whose current
* <tt>WhiteboardSession</tt>s we will be querying.
* @return a list of the <tt>WhiteboardSession</tt>s that
* <tt>WhiteboardParticipant</tt> has joined and is currently active in.
*
* @throws OperationFailedException if an error occurs while trying to
* discover the session.
* @throws OperationNotSupportedException if the server does not support
* white-boarding
*/
public List<WhiteboardSession> getCurrentlyJoinedWhiteboards(
WhiteboardParticipant participant)
throws OperationFailedException, OperationNotSupportedException;
/**
* Creates a <tt>WhiteboardSession</tt> with the name <tt>sessionName</tt>
* and according to the specified <tt>sessionProperties</tt>. When the
* method returns the white-board session object, the local user will not
* have joined it and thus will not receive messages on it until the
* <tt>WhiteboardSession.join()</tt> method is called.
* <p>
* @param sessionName the name of the <tt>WhiteboardSession</tt> to create.
* @param sessionProperties properties specifying how the session should be
* created.
* @throws OperationFailedException if the room couldn't be created for some
* reason (e.g. room already exists; user already joined to an existent
* room or user has no permissions to create a chat room).
* @throws OperationNotSupportedException if chat room creation is not
* supported by this server
*
* @return the newly created <tt>WhiteboardSession</tt> named
* <tt>sessionName</tt>.
*/
public WhiteboardSession createWhiteboardSession(
String sessionName,
Hashtable<Object, Object> sessionProperties)
throws OperationFailedException, OperationNotSupportedException;
/**
* Returns a reference to a <tt>WhiteboardSession</tt> named
* <tt>sessionName</tt> or null if no such session exists.
* <p>
* @param sessionName the name of the <tt>WhiteboardSession</tt> that we're
* looking for.
* @return the <tt>WhiteboardSession</tt> named <tt>sessionName</tt> or null
* if no such session exists on the server that this provider is currently
* connected to.
*
* @throws OperationFailedException if an error occurs while trying to
* discover the white-board session on the server.
* @throws OperationNotSupportedException if the server does not support
* white-boarding
*/
public WhiteboardSession findWhiteboardSession(String sessionName)
throws OperationFailedException, OperationNotSupportedException;
/**
* Informs the sender of an invitation that we decline their invitation.
*
* @param invitation the invitation we are rejecting.
* @param rejectReason the reason to reject the invitation (optional)
*/
public void rejectInvitation(WhiteboardInvitation invitation,
String rejectReason);
/**
* Adds a listener to invitation notifications. The listener will be fired
* anytime an invitation is received.
*
* @param listener an invitation listener.
*/
public void addInvitationListener(WhiteboardInvitationListener listener);
/**
* Removes <tt>listener</tt> from the list of invitation listeners
* registered to receive invitation events.
*
* @param listener the invitation listener to remove.
*/
public void removeInvitationListener(WhiteboardInvitationListener listener);
/**
* Adds a listener to invitation notifications. The listener will be fired
* anytime an invitation is received.
*
* @param listener an invitation listener.
*/
public void addInvitationRejectionListener(
WhiteboardInvitationRejectionListener listener);
/**
* Removes the given listener from the list of invitation listeners
* registered to receive events every time an invitation has been rejected.
*
* @param listener the invitation listener to remove.
*/
public void removeInvitationRejectionListener(
WhiteboardInvitationRejectionListener listener);
/**
* Returns true if <tt>contact</tt> supports white-board sessions.
*
* @param contact reference to the contact whose support for white-boards
* we are currently querying.
* @return a boolean indicating whether <tt>contact</tt> supports
* white-boards.
*/
public boolean isWhiteboardingSupportedByContact(Contact contact);
/**
* Adds a listener that will be notified of changes in our participation in
* a white-board session such as us being joined, left, dropped.
*
* @param listener a local user participation listener.
*/
public void addPresenceListener(
WhiteboardSessionPresenceListener listener);
/**
* Removes a listener that was being notified of changes in our
* participation in a room such as us being kicked, joined, left.
*
* @param listener a local user participation listener.
*/
public void removePresenceListener(
WhiteboardSessionPresenceListener listener);
}