UserStatusListener.java

  1. /**
  2.  *
  3.  * Copyright 2003-2007 Jive Software.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  17. package org.jivesoftware.smackx.muc;

  18. import org.jivesoftware.smack.packet.Presence;

  19. import org.jivesoftware.smackx.muc.packet.MUCUser;

  20. import org.jxmpp.jid.Jid;

  21. /**
  22.  * A listener that is fired anytime your participant's status in a room is changed, such as the user being kicked,
  23.  * banned, or granted admin permissions or the room is destroyed.
  24.  * <p>
  25.  * Note that the methods {@link #kicked(Jid, String)}, {@link #banned(Jid, String)} and
  26.  * {@link #roomDestroyed(MultiUserChat, String, String)} will be called before the generic {@link #removed(MUCUser, Presence)}
  27.  * callback will be invoked. The generic {@link #removed(MUCUser, Presence)} callback will be invoked every time the user
  28.  * was removed from the MUC involuntarily. It is hence the recommended callback to listen for and act upon.
  29.  * </p>
  30.  *
  31.  * @author Gaston Dombiak
  32.  */
  33. public interface UserStatusListener {

  34.     /**
  35.      * Called when a moderator kicked your user from the room. This means that you are no longer
  36.      * participating in the room.
  37.      *
  38.      * @param actor the moderator that kicked your user from the room (e.g. user@host.org).
  39.      * @param reason the reason provided by the actor to kick you from the room.
  40.      * @see #removed(MUCUser, Presence)
  41.      */
  42.     default void kicked(Jid actor, String reason) {
  43.     }

  44.     /**
  45.      * Called when a moderator grants voice to your user. This means that you were a visitor in
  46.      * the moderated room before and now you can participate in the room by sending messages to
  47.      * all occupants.
  48.      *
  49.      */
  50.     default void voiceGranted() {
  51.     }

  52.     /**
  53.      * Called when a moderator revokes voice from your user. This means that you were a
  54.      * participant in the room able to speak and now you are a visitor that can't send
  55.      * messages to the room occupants.
  56.      *
  57.      */
  58.     default void voiceRevoked() {
  59.     }

  60.     /**
  61.      * Called when an administrator or owner banned your user from the room. This means that you
  62.      * will no longer be able to join the room unless the ban has been removed.
  63.      *
  64.      * @param actor the administrator that banned your user (e.g. user@host.org).
  65.      * @param reason the reason provided by the administrator to banned you.
  66.      * @see #removed(MUCUser, Presence)
  67.      */
  68.     default void banned(Jid actor, String reason) {
  69.     }

  70.      /**
  71.       * Called when a user is involuntarily removed from the room.
  72.       *
  73.       * @param mucUser the optional muc#user extension element
  74.       * @param presence the carrier presence
  75.       * @since 4.4.0
  76.       */
  77.      default void removed(MUCUser mucUser, Presence presence) {
  78.      }

  79.      /**
  80.      * Called when an administrator grants your user membership to the room. This means that you
  81.      * will be able to join the members-only room.
  82.      *
  83.      */
  84.     default void membershipGranted() {
  85.     }

  86.     /**
  87.      * Called when an administrator revokes your user membership to the room. This means that you
  88.      * will not be able to join the members-only room.
  89.      *
  90.      */
  91.     default void membershipRevoked() {
  92.     }

  93.     /**
  94.      * Called when an administrator grants moderator privileges to your user. This means that you
  95.      * will be able to kick users, grant and revoke voice, invite other users, modify room's
  96.      * subject plus all the participant privileges.
  97.      *
  98.      */
  99.     default void moderatorGranted() {
  100.     }

  101.     /**
  102.      * Called when an administrator revokes moderator privileges from your user. This means that
  103.      * you will no longer be able to kick users, grant and revoke voice, invite other users,
  104.      * modify room's subject plus all the participant privileges.
  105.      *
  106.      */
  107.     default void moderatorRevoked() {
  108.     }

  109.     /**
  110.      * Called when an owner grants to your user ownership on the room. This means that you
  111.      * will be able to change defining room features as well as perform all administrative
  112.      * functions.
  113.      *
  114.      */
  115.     default void ownershipGranted() {
  116.     }

  117.     /**
  118.      * Called when an owner revokes from your user ownership on the room. This means that you
  119.      * will no longer be able to change defining room features as well as perform all
  120.      * administrative functions.
  121.      *
  122.      */
  123.     default void ownershipRevoked() {
  124.     }

  125.     /**
  126.      * Called when an owner grants administrator privileges to your user. This means that you
  127.      * will be able to perform administrative functions such as banning users and edit moderator
  128.      * list.
  129.      *
  130.      */
  131.     default void adminGranted() {
  132.     }

  133.     /**
  134.      * Called when an owner revokes administrator privileges from your user. This means that you
  135.      * will no longer be able to perform administrative functions such as banning users and edit
  136.      * moderator list.
  137.      *
  138.      */
  139.     default void adminRevoked() {
  140.     }

  141.     /**
  142.      * Called when the room is destroyed.
  143.      *
  144.      * @param alternateMUC an alternate MultiUserChat, may be null.
  145.      * @param password a password for the alternative MultiUserChat, may be null.
  146.      * @param reason the reason why the room was closed, may be null.
  147.      * @see #removed(MUCUser, Presence)
  148.      */
  149.     default void roomDestroyed(MultiUserChat alternateMUC, String password, String reason) {
  150.     }

  151. }