+ * @param sessionName the name of the WhiteboardSession 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 * - * @throws OperationFailedException with the corresponding code if we fail - * to create the whiteboard. + * @return the newly created WhiteboardSession named + * sessionName. */ - public WhiteboardSession createWhiteboardSession (Contact whiteboardContact) - throws OperationFailedException; + public WhiteboardSession createWhiteboardSession( + String sessionName, + Hashtable sessionProperties) + throws OperationFailedException, OperationNotSupportedException; /** - * Closes the specified whiteboardSession and destroys all objects - * and states associated with it. + * Returns a reference to a WhiteboardSession named + * sessionName or null if no such session exists. + *
+ * @param sessionName the name of the WhiteboardSession that we're + * looking for. + * @return the WhiteboardSession named sessionName or null + * if no such session exists on the server that this provider is currently + * connected to. * - * @param whiteboardSession the session that we'd like to end. + * @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 listener from the list of invitation listeners + * registered to receive invitation events. * - * @throws OperationFailedException with the corresponding code if we fail - * to finish the whiteboard. + * @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 contact supports white-board sessions. + * + * @param contact reference to the contact whose support for white-boards + * we are currently querying. + * @return a boolean indicating whether contact 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 endWhiteboardSession (WhiteboardSession whiteboardSession) - throws OperationFailedException; + public void removePresenceListener( + WhiteboardSessionPresenceListener listener); } diff --git a/src/net/java/sip/communicator/service/protocol/WhiteboardInvitation.java b/src/net/java/sip/communicator/service/protocol/WhiteboardInvitation.java new file mode 100644 index 000000000..71d8bd252 --- /dev/null +++ b/src/net/java/sip/communicator/service/protocol/WhiteboardInvitation.java @@ -0,0 +1,51 @@ +/* + * 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; + +/** + * This interface represents an invitation, which is send from a whiteboard + * participant to another user in order to invite this user to join the + * whiteboard. + * + * @author Yana Stamcheva + */ +public interface WhiteboardInvitation +{ + /** + * Returns the WhiteboardSession, which is the target of this + * invitation. + * The whiteboard returned by this method will be the one to which the user + * is invited to join to. + * + * @return the WhiteboardSession, which is the target of this + * invitation + */ + public WhiteboardSession getTargetWhiteboard(); + + /** + * Returns the password to use when joining the whiteboard. + * + * @return the password to use when joining the whiteboard + */ + public byte[] getWhiteboardPassword(); + + /** + * Returns the WhiteboardParticipant that sent this invitation. + * + * @return the WhiteboardParticipant that sent this invitation. + */ + public String getInviter(); + + /** + * Returns the reason of this invitation, or null if there is no reason + * specified. + * + * @return the reason of this invitation, or null if there is no reason + * specified + */ + public String getReason(); +} diff --git a/src/net/java/sip/communicator/service/protocol/WhiteboardObject.java b/src/net/java/sip/communicator/service/protocol/WhiteboardObject.java deleted file mode 100644 index 121c2dcd3..000000000 --- a/src/net/java/sip/communicator/service/protocol/WhiteboardObject.java +++ /dev/null @@ -1,214 +0,0 @@ -/* - * 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 java.util.*; - -/** - * Used to access the content of instant whiteboard objects that are sent or - * received via the WhiteboardOperationSet. - *
- * WhiteboardObject are created through the WhiteboardSession session. - *
- * - * All WhiteboardObjects have whiteboard object id. - * - * @author Julien Waechter - * @author Emil Ivov - */ -public interface WhiteboardObject -{ - /** - * A type string constant indicating that an object is of type binary image. - */ - public static final String TYPE_IMAGE = "IMAGE"; - - /** - * A type string constant indicating that an object is of type rectangle. - */ - public static final String TYPE_RECT = "RECT"; - - /** - * A type string constant indicating that an object is of type circle. - */ - public static final String TYPE_CIRCLE = "CIRCLE"; - - /** - * A type string constant indicating that an object is of type binary line. - */ - public static final String TYPE_LINE = "LINE"; - - /** - * A type string constant indicating that an object is of type polyline. - */ - public static final String TYPE_POLYLINE = "POLYLINE"; - - /** - * A type string constant indicating that an object is of type binary - * plygon. - */ - public static final String TYPE_POLYGON = "POLYGON"; - - /** - * A type string constant indicating that an object is of type elipse. - */ - public static final String TYPE_ELLIPSE = "ELLIPSE"; - - /** - * A type string constant indicating that an object is of type path. - */ - public static final String TYPE_PATH = "PATH"; - - /** - * A type string constant indicating that an object is of type text. - */ - public static final String TYPE_TEXT = "TEXT"; - - /** - * Returns a String uniquely identifying this WhiteboardObject. - * - * @return a String that uniquely identifies this WhiteboardObject. - */ - public String getID (); - - /** - * Returns the type of this object. Currently this service defines - * a limited set of types (i.e. the TYPE_XXX constants defined above) that - * may be extended in the future. - * - * @return one of the TYPE_XXX constants defined by this interface, - * indicating the type of this whiteboard object. - */ - public String getType (); - - /** - * Returns an integer indicating the thickness (represented as number of - * pixels) of this whiteboard object (or its border). - * - * @return the thickness (in pixels) of this object (or its border). - */ - public int getThickness (); - - /** - * Sets the thickness (in pixels) of this whiteboard object. - * - * @param thickness the number of pixels that this object (or its border) - * should be thick. - */ - public void setThickness (int thickness); - - /** - * Returns an integer representing the color of this object. The return - * value uses standard RGB encoding: bits 24-31 are alpha, 16-23 are red, - * 8-15 are green, 0-7 are blue. - * - * @return the RGB value of the color of this object. - */ - public int getColor (); - - /** - * Sets the color of this whiteboard object (or rather it's border). The - * color parameter must be encoded with standard RGB encoding: bits 24-31 - * are alpha, 16-23 are red, 8-15 are green, 0-7 are blue. - * - * @param color the color that we'd like to set on this object (using - * standard RGB encoding). - */ - public void setColor (int color); - - /** - * Returns a list of all the WhiteboardPoint instances that this - * WhiteboardObject is composed of. - * - * @return the list of WhiteboardPoints composing this object. - */ - public List getPoints (); - - /** - * Sets the list of WhiteboardPoint instances that this - * WhiteboardObject is composed of. - * - * @param points the list of WhiteboardPoint instances that this - * WhiteboardObject is composed of. - */ - public void setPoints(List points); - - /** - * Specifies an image that should be displayed as the background of this - * object. - * - * @param background a binary array containing the image that should be - * displayed as the object background. - */ - public void setBackgroundImage(byte[] background); - - /** - * Returns a binary array containing the image that should be displayed as - * the background of this WhiteboardObject. - * - * @return a binary array containing the image that should be displayed as - * the object background. - */ - public byte[] getBackgroundImage(); - - /** - * Specifies the background color for this object. The color parameter - * must be encoded with standard RGB encoding: bits 24-31 are alpha, 16-23 - * are red, 8-15 are green, 0-7 are blue. - * - * @param color the color that we'd like to set for the background of this - * WhiteboardObject (using standard RGB encoding). - */ - public void setBackgroundColor(int color); - - /** - * Returns an integer representing the background color of this object. The - * return value uses standard RGB encoding: bits 24-31 are alpha, 16-23 are - * red, 8-15 are green, 0-7 are blue. - * - * @return the RGB value of the background color of this object. - */ - public int getBackgroundColor(); - - /** - * Sets value as the value of the key attribute. - * - * @param key the name of the attribute that we'd like to set. - * @param value value to be associated with the specified key - */ - public void addAttribute (String key, String value); - - /** - * Returns the value to which the specified key is mapped, or null if this - * map contains no value for the key. - * - * @param key the key the value of which we'd like to retrieve. - * - * @return the value associated with key, or null - * if there was no such key. - */ - public String getAttribute (String key); - - /** - * Returns a HashMap containing all attributes currently set for - * this WhiteboardObject. - * - * @return a HashMap mapping attribute keys to values for all - * attributes currently set for this WhiteboardObject. - */ - public HashMap getAttributes (); - - /** - * Sets map as the complete set of attributes available for this - * WhiteboardObject. Any existing attributes will be removed prior - * to setting the new map. - * - * @param map the complete map of attributes defined for this - * WhiteboardObject. - */ - public void setAttributes (HashMap map); -} diff --git a/src/net/java/sip/communicator/service/protocol/WhiteboardParticipant.java b/src/net/java/sip/communicator/service/protocol/WhiteboardParticipant.java index 32ff78d13..05deaf1f4 100644 --- a/src/net/java/sip/communicator/service/protocol/WhiteboardParticipant.java +++ b/src/net/java/sip/communicator/service/protocol/WhiteboardParticipant.java @@ -9,7 +9,8 @@ import net.java.sip.communicator.service.protocol.event.*; /** - * The WhiteboardParticipant is an interface that represents participants in a whiteboard. + * The WhiteboardParticipant is an interface that represents participants in a + * whiteboard. * * @author Julien Waechter * @author Emil Ivov diff --git a/src/net/java/sip/communicator/service/protocol/WhiteboardPoint.java b/src/net/java/sip/communicator/service/protocol/WhiteboardPoint.java index e49ee5461..faaf80957 100644 --- a/src/net/java/sip/communicator/service/protocol/WhiteboardPoint.java +++ b/src/net/java/sip/communicator/service/protocol/WhiteboardPoint.java @@ -6,6 +6,8 @@ */ package net.java.sip.communicator.service.protocol; +import java.awt.geom.*; + /** * A point representing a location in {@code (x,y)} coordinate space, * specified in integer precision. @@ -71,6 +73,26 @@ public double getY() return y; } + /** + * Sets a new value to the x coordinate. + * + * @param y the new value of the x coordinate + */ + public void setX(double x) + { + this.x = x; + } + + /** + * Sets a new value to the y coordinate. + * + * @param y the new value of the y coordinate + */ + public void setY(double y) + { + this.y = y; + } + /** * Determines whether or not two points are equal. Two instances of * WhiteboardPoint are equal if the values of their @@ -119,4 +141,17 @@ protected Object clone() return new WhiteboardPoint(this); } + /** + * Calculates the distance from this point the given point. + * + * @param p the point to which to calculate the distance + * @return the distance between this point and the given point + */ + public double distance(WhiteboardPoint p) + { + double PX = p.getX() - this.getX(); + double PY = p.getY() - this.getY(); + + return Math.sqrt(PX * PX + PY * PY); + } } diff --git a/src/net/java/sip/communicator/service/protocol/WhiteboardSession.java b/src/net/java/sip/communicator/service/protocol/WhiteboardSession.java index e4c1cbe76..62a8dba2d 100644 --- a/src/net/java/sip/communicator/service/protocol/WhiteboardSession.java +++ b/src/net/java/sip/communicator/service/protocol/WhiteboardSession.java @@ -10,6 +10,8 @@ import net.java.sip.communicator.service.protocol.event.*; +import net.java.sip.communicator.service.protocol.whiteboardobjects.WhiteboardObject; + /** * A represenation of a WhiteboardSession. * @@ -24,7 +26,7 @@ public interface WhiteboardSession * * @return a String uniquely identifying the whiteboard. */ - public String getWhiteboardID(); + public String getWhiteboardID (); /** * Returns an iterator over all whiteboard participants. @@ -32,7 +34,7 @@ public interface WhiteboardSession * @return an Iterator over all participants currently involved in the * whiteboard. */ - public Iterator getWhiteboardParticipants(); + public Iterator getWhiteboardParticipants (); /** * Returns the number of participants currently associated @@ -41,7 +43,7 @@ public interface WhiteboardSession * @return an int indicating the number of participants currently * associated with this whiteboard. */ - public int getWhiteboardParticipantsCount(); + public int getWhiteboardParticipantsCount (); /** * Adds a whiteboard change listener to this whiteboard so that it could @@ -49,7 +51,7 @@ public interface WhiteboardSession * * @param listener the listener to register */ - public void addWhiteboardChangeListener(WhiteboardChangeListener listener); + public void addWhiteboardChangeListener (WhiteboardChangeListener listener); /** * Removes listener to this whiteboard so that it won't receive @@ -57,8 +59,8 @@ public interface WhiteboardSession * * @param listener the listener to register */ - public void removeWhiteboardChangeListener( - WhiteboardChangeListener listener); + public void removeWhiteboardChangeListener ( + WhiteboardChangeListener listener); /** * Returns a reference to the ProtocolProviderService instance @@ -67,7 +69,7 @@ public void removeWhiteboardChangeListener( * @return a reference to the ProtocolProviderService instance that * created this whiteboard. */ - public ProtocolProviderService getProtocolProvider(); + public ProtocolProviderService getProtocolProvider (); /** * Joins this whiteboard with the nickname of the local user so that the @@ -76,7 +78,7 @@ public void removeWhiteboardChangeListener( * @throws OperationFailedException with the corresponding code if an error * occurs while joining the room. */ - public abstract void join() throws OperationFailedException; + public abstract void join () throws OperationFailedException; /** * Joins this whiteboard so that the user would start receiving events and @@ -88,16 +90,16 @@ public void removeWhiteboardChangeListener( * @throws OperationFailedException with the corresponding code if an error * occurs while joining the room. */ - public abstract void join(byte[] password) throws OperationFailedException; + public abstract void join (byte[] password) throws OperationFailedException; /** * Returns true if the local user is currently in the whiteboard session - * (after whiteboarding one of the {@link #join()} methods). + * (after whiteboarding one of the {@link #join(String)} methods). * * @return true if currently we're currently in this whiteboard and false * otherwise. */ - public abstract boolean isJoined(); + public abstract boolean isJoined (); /** * Leave this whiteboard. Once this method is whiteboarded, the user won't @@ -106,8 +108,7 @@ public void removeWhiteboardChangeListener( * and implementation leave() might cause the room to be destroyed if it has * been created by the local user. */ - public abstract void leave(); - + public abstract void leave (); /** * Invites another user to this room. @@ -119,8 +120,7 @@ public void removeWhiteboardChangeListener( * @param userAddress the address of the user to invite to the room. * (one may also invite users not on their contact list). */ - public abstract void invite(String userAddress); - + public abstract void invite (String userAddress); /** * Registers listener so that it would receive events every time a @@ -131,7 +131,7 @@ public void removeWhiteboardChangeListener( * notified every time a new WhiteboardObject * is received on this whiteboard. */ - public abstract void addWhiteboardObjectListener( + public abstract void addWhiteboardObjectListener ( WhiteboardObjectListener listener); /** @@ -142,7 +142,7 @@ public abstract void addWhiteboardObjectListener( * @param listener the WhiteboardObjectListener * to remove from this room */ - public abstract void removeWhiteboardObjectListener( + public abstract void removeWhiteboardObjectListener ( WhiteboardObjectListener listener); /** @@ -151,12 +151,12 @@ public abstract void removeWhiteboardObjectListener( * session participants until it is resolved with the * sendWhiteboardObject(WhiteboardObject) method. * - * @param type the type of the object to create (should be one of the - * WhiteboardObject.TYPE_XXX fields). + * @param name the name of the object to create (should be one of the ++ * WhiteboardObjectXXX.NAME fields). * * @return the newly created WhiteboardObject with an id */ - public abstract WhiteboardObject createWhiteboardObject(String type); + public abstract WhiteboardObject createWhiteboardObject(String name); /** * Resolves obj with the other session participants. When called @@ -171,17 +171,29 @@ public abstract void removeWhiteboardObjectListener( * @throws OperationFailedException if sending the WhiteboardObject fails * for some reason. */ - public abstract void sendWhiteboardObject(WhiteboardObject obj) + public abstract void sendWhiteboardObject (WhiteboardObject obj) throws OperationFailedException; /** - * Sends the obj + * Sends a WhiteboardObject to modify + * and modifies the local WhiteboardObject * - * @param obj the WhiteboardObject to send. + * @param obj the WhiteboardObject to send and modify + * @throws OperationFailedException if sending + * the WhiteboardObject fails for some reason. + */ + public abstract void moveWhiteboardObject (WhiteboardObject obj) + throws OperationFailedException; + + /** + * Sends a WhiteboardObject to delete + * and delete the local WhiteboardObject + * + * @param obj the WhiteboardObject to send and delete * @throws OperationFailedException if sending * the WhiteboardObject fails for some reason. */ - public abstract void moveWhiteboardObject(WhiteboardObject obj) + public abstract void deleteWhiteboardObject (WhiteboardObject obj) throws OperationFailedException; /** @@ -192,8 +204,8 @@ public abstract void moveWhiteboardObject(WhiteboardObject obj) * * @param wbParticipant the new WhiteboardParticipant */ - public abstract void addWhiteboardParticipant( - WhiteboardParticipant wbParticipant); + public abstract void addWhiteboardParticipant ( + WhiteboardParticipant wbParticipant); /** * Removes whiteboardParticipant from the list of participants in @@ -203,14 +215,16 @@ public abstract void addWhiteboardParticipant( * @param wbParticipant the WhiteboardParticipant leaving the * whiteboard; */ - public abstract void removeWhiteboardParticipant( - WhiteboardParticipant wbParticipant); + + public abstract void removeWhiteboardParticipant ( + WhiteboardParticipant wbParticipant); + /** * Returns the WhiteboardObjects in this whiteboard session. * @return an Vector of WhiteboardObjects associated * with this whiteboard. */ - public Vector getWhiteboardObjects(); + public Vector getWhiteboardObjects (); /** * Sets the state of this whiteboard @@ -218,12 +232,20 @@ public abstract void removeWhiteboardParticipant( * @param newState a reference to the WhiteboardState instance that * the whiteboard is to enter. */ - public void setState(WhiteboardSessionState newState); + public void setState (WhiteboardSessionState newState); + /** * Returns the state that this whiteboard is currently in. * * @return a reference to the WhiteboardState instance * that the whiteboard is currently in. */ - public WhiteboardSessionState getState(); + public WhiteboardSessionState getState (); + + /** + * Returns all the type of WhiteboardObject that this whiteboard support. + * + * @return all the WhiteboardObject supported by this WhiteboardSession. + */ + public String[] getSupportedWhiteboardObjects(); } diff --git a/src/net/java/sip/communicator/service/protocol/protocol.provider.manifest.mf b/src/net/java/sip/communicator/service/protocol/protocol.provider.manifest.mf index bfa86604f..557bd2bbe 100644 --- a/src/net/java/sip/communicator/service/protocol/protocol.provider.manifest.mf +++ b/src/net/java/sip/communicator/service/protocol/protocol.provider.manifest.mf @@ -12,4 +12,5 @@ Export-Package: net.java.sip.communicator.service.protocol, net.java.sip.communicator.service.protocol.jabberconstants, net.java.sip.communicator.service.protocol.msnconstants, net.java.sip.communicator.service.protocol.yahooconstants, - net.java.sip.communicator.service.protocol.event + net.java.sip.communicator.service.protocol.event, + net.java.sip.communicator.service.protocol.whiteboardobjects