|
Smack | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.jivesoftware.smackx.muc.MultiUserChat
public class MultiUserChat
A MultiUserChat is a conversation that takes place among many users in a virtual room. A room could have many occupants with different affiliation and roles. Possible affiliatons are "owner", "admin", "member", and "outcast". Possible roles are "moderator", "participant", and "visitor". Each role and affiliation guarantees different privileges (e.g. Send messages to all occupants, Kick participants and visitors, Grant voice, Edit member list, etc.).
Constructor Summary | |
---|---|
MultiUserChat(XMPPConnection connection,
String room)
Creates a new multi user chat with the specified connection and room name. |
Method Summary | |
---|---|
static void |
addInvitationListener(XMPPConnection conn,
InvitationListener listener)
Adds a listener to invitation notifications. |
void |
addInvitationRejectionListener(InvitationRejectionListener listener)
Adds a listener to invitation rejections notifications. |
void |
addMessageListener(PacketListener listener)
Adds a packet listener that will be notified of any new messages in the group chat. |
void |
addParticipantListener(PacketListener listener)
Adds a packet listener that will be notified of any new Presence packets sent to the group chat. |
void |
addParticipantStatusListener(ParticipantStatusListener listener)
Adds a listener that will be notified of changes in participants status in the room such as the user being kicked, banned, or granted admin permissions. |
void |
addSubjectUpdatedListener(SubjectUpdatedListener listener)
Adds a listener to subject change notifications. |
void |
addUserStatusListener(UserStatusListener listener)
Adds a listener that will be notified of changes in your status in the room such as the user being kicked, banned, or granted admin permissions. |
void |
banUser(String jid,
String reason)
Bans a user from the room. |
void |
changeAvailabilityStatus(String status,
Presence.Mode mode)
Changes the participant's availability status within the room. |
void |
changeNickname(String nickname)
Changes the participant's nickname to a new nickname within the room. |
void |
changeSubject(String subject)
Changes the subject within the room. |
void |
create(String nickname)
Creates the room according to some default configuration, assign the requesting user as the room owner, and add the owner to the room but not allow anyone else to enter the room (effectively "locking" the room). |
Message |
createMessage()
Creates a new Message to send to the chat room. |
Chat |
createPrivateChat(String participant)
Returns a new Chat for sending private messages to a given room participant. |
static void |
decline(XMPPConnection conn,
String room,
String inviter,
String reason)
Informs the sender of an invitation that the invitee declines the invitation. |
void |
destroy(String reason,
String alternateJID)
Sends a request to the server to destroy the room. |
void |
finalize()
|
Form |
getConfigurationForm()
Returns the room's configuration form that the room's owner can use or null if no configuration is possible. |
static Iterator |
getJoinedRooms(XMPPConnection connection,
String user)
Returns an Iterator on the rooms where the requested user has joined. |
String |
getNickname()
Returns the nickname that was used to join the room, or null if not currently joined. |
int |
getParticipantCount()
Returns the number of participants in the group chat. |
String |
getParticipantJID(String participant)
Returns the participant's full JID when joining a Non-Anonymous room or null if the room is of type anonymous. |
Presence |
getParticipantPresence(String participant)
Returns the presence info for a particular participant, or null if the participant is not in the room. |
Iterator |
getParticipants()
Returns an Iterator (of Strings) for the list of fully qualified participants in the group chat. |
Form |
getRegistrationForm()
Returns the room's registration form that an unaffiliated user, can use to become a member of the room or null if no registration is possible. |
String |
getReservedNickname()
Returns the reserved room nickname for the user in the room. |
String |
getRoom()
Returns the name of the room this MultiUserChat object represents. |
String |
getSubject()
Returns the last known room's subject or null if the user hasn't joined the room or the room does not have a subject yet. |
void |
grantAdmin(String jid)
Grants administrator privileges to another user. |
void |
grantMembership(String jid)
Grants membership to a user. |
void |
grantModerator(String nickname)
Grants moderator privileges to a participant or visitor. |
void |
grantOwnership(String jid)
Grants ownership privileges to another user. |
void |
grantVoice(String nickname)
Grants voice to a visitor in the room. |
void |
invite(String participant,
String reason)
Invites another user to the room in which one is an occupant. |
boolean |
isJoined()
Returns true if currently in the multi user chat (after calling the join(String) method). |
static boolean |
isServiceEnabled(XMPPConnection connection,
String user)
Returns true if the specified user supports the Multi-User Chat protocol. |
void |
join(String nickname)
Joins the chat room using the specified nickname. |
void |
join(String nickname,
String password)
Joins the chat room using the specified nickname and password. |
void |
join(String nickname,
String password,
DiscussionHistory history,
long timeout)
Joins the chat room using the specified nickname and password. |
void |
kickParticipant(String nickname,
String reason)
Kicks a visitor or participant from the room. |
void |
leave()
Leave the chat room. |
Message |
nextMessage()
Returns the next available message in the chat. |
Message |
nextMessage(long timeout)
Returns the next available message in the chat. |
Message |
pollMessage()
Polls for and returns the next message, or null if there isn't a message immediately available. |
static void |
removeInvitationListener(XMPPConnection conn,
InvitationListener listener)
Removes a listener to invitation notifications. |
void |
removeInvitationRejectionListener(InvitationRejectionListener listener)
Removes a listener from invitation rejections notifications. |
void |
removeMessageListener(PacketListener listener)
Removes a packet listener that was being notified of any new messages in the multi user chat. |
void |
removeParticipantListener(PacketListener listener)
Remoces a packet listener that was being notified of any new Presence packets sent to the group chat. |
void |
removeParticipantStatusListener(ParticipantStatusListener listener)
Removes a listener that was being notified of changes in participants status in the room such as the user being kicked, banned, or granted admin permissions. |
void |
removeSubjectUpdatedListener(SubjectUpdatedListener listener)
Removes a listener from subject change notifications. |
void |
removeUserStatusListener(UserStatusListener listener)
Removes a listener that was being notified of changes in your status in the room such as the user being kicked, banned, or granted admin permissions. |
void |
revokeAdmin(String jid)
Revokes administrator privileges from a user. |
void |
revokeMembership(String jid)
Revokes a user's membership. |
void |
revokeModerator(String nickname)
Revokes moderator privileges from another user. |
void |
revokeOwnership(String jid)
Revokes ownership privileges from another user. |
void |
revokeVoice(String nickname)
Revokes voice from a participant in the room. |
void |
sendConfigurationForm(Form form)
Sends the completed configuration form to the server. |
void |
sendMessage(Message message)
Sends a Message to the chat room. |
void |
sendMessage(String text)
Sends a message to the chat room. |
void |
sendRegistrationForm(Form form)
Sends the completed registration form to the server. |
Methods inherited from class java.lang.Object |
---|
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public MultiUserChat(XMPPConnection connection, String room)
join
the chat room. On some server implementations,
the room will not be created until the first person joins it.Most XMPP servers use a sub-domain for the chat service (eg chat.example.com for the XMPP server example.com). You must ensure that the room address you're trying to connect to includes the proper chat sub-domain.
connection
- the XMPP connection.room
- the name of the room in the form "roomName@service", where
"service" is the hostname at which the multi-user chat
service is running.Method Detail |
---|
public static boolean isServiceEnabled(XMPPConnection connection, String user)
connection
- the connection to use to perform the service discovery.user
- the user to check. A fully qualified xmpp ID, e.g. jdoe@example.com.
public static Iterator getJoinedRooms(XMPPConnection connection, String user)
connection
- the connection to use to perform the service discovery.user
- the user to check. A fully qualified xmpp ID, e.g. jdoe@example.com.
public String getRoom()
public void create(String nickname) throws XMPPException
To create an "Instant Room", that means a room with some default configuration that is
available for immediate access, the room's owner should send an empty form after creating
the room. sendConfigurationForm(Form)
To create a "Reserved Room", that means a room manually configured by the room creator
before anyone is allowed to enter, the room's owner should complete and send a form after
creating the room. Once the completed configutation form is sent to the server, the server
will unlock the room. sendConfigurationForm(Form)
nickname
- the nickname to use.
XMPPException
- if the room couldn't be created for some reason
(e.g. room already exists; user already joined to an existant room or
405 error if the user is not allowed to create the room)public void join(String nickname) throws XMPPException
nickname
- the nickname to use.
XMPPException
- if an error occurs joining the room. In particular, a
401 error can occur if no password was provided and one is required; or a
403 error can occur if the user is banned; or a
404 error can occur if the room does not exist or is locked; or a
407 error can occur if user is not on the member list; or a
409 error can occur if someone is already in the group chat with the same nickname.public void join(String nickname, String password) throws XMPPException
A password is required when joining password protected rooms. If the room does not require a password there is no need to provide one.
nickname
- the nickname to use.password
- the password to use.
XMPPException
- if an error occurs joining the room. In particular, a
401 error can occur if no password was provided and one is required; or a
403 error can occur if the user is banned; or a
404 error can occur if the room does not exist or is locked; or a
407 error can occur if user is not on the member list; or a
409 error can occur if someone is already in the group chat with the same nickname.public void join(String nickname, String password, DiscussionHistory history, long timeout) throws XMPPException
To control the amount of history to receive while joining a room you will need to provide a configured DiscussionHistory object.
A password is required when joining password protected rooms. If the room does not require a password there is no need to provide one.
If the room does not already exist when the user seeks to enter it, the server will decide to create a new room or not.
nickname
- the nickname to use.password
- the password to use.history
- the amount of discussion history to receive while joining a room.timeout
- the amount of time to wait for a reply from the MUC service(in milleseconds).
XMPPException
- if an error occurs joining the room. In particular, a
401 error can occur if no password was provided and one is required; or a
403 error can occur if the user is banned; or a
404 error can occur if the room does not exist or is locked; or a
407 error can occur if user is not on the member list; or a
409 error can occur if someone is already in the group chat with the same nickname.public boolean isJoined()
join(String)
method).
public void leave()
public Form getConfigurationForm() throws XMPPException
XMPPException
- if an error occurs asking the configuration form for the room.public void sendConfigurationForm(Form form) throws XMPPException
form
- the form with the new settings.
XMPPException
- if an error occurs setting the new rooms' configuration.public Form getRegistrationForm() throws XMPPException
If the user requesting registration requirements is not allowed to register with the room (e.g. because that privilege has been restricted), the room will return a "Not Allowed" error to the user (error code 405).
XMPPException
- if an error occurs asking the registration form for the room or a
405 error if the user is not allowed to register with the room.public void sendRegistrationForm(Form form) throws XMPPException
If the desired room nickname is already reserved for that room, the room will return a "Conflict" error to the user (error code 409). If the room does not support registration, it will return a "Service Unavailable" error to the user (error code 503).
form
- the completed registration form.
XMPPException
- if an error occurs submitting the registration form. In particular, a
409 error can occur if the desired room nickname is already reserved for that room;
or a 503 error can occur if the room does not support registration.public void destroy(String reason, String alternateJID) throws XMPPException
reason
- the reason for the room destruction.alternateJID
- the JID of an alternate location.
XMPPException
- if an error occurs while trying to destroy the room.
An error can occur which will be wrapped by an XMPPException --
XMPP error code 403. The error code can be used to present more
appropiate error messages to end-users.public void invite(String participant, String reason)
If the room is password-protected, the invitee will receive a password to use to join the room. If the room is members-only, the the invitee may be added to the member list.
participant
- the user to invite to the room.(e.g. hecate@shakespeare.lit)reason
- the reason why the user is being invited.public static void decline(XMPPConnection conn, String room, String inviter, String reason)
conn
- the connection to use for sending the rejection.room
- the room that sent the original invitation.inviter
- the inviter of the declined invitation.reason
- the reason why the invitee is declining the invitation.public static void addInvitationListener(XMPPConnection conn, InvitationListener listener)
conn
- the connection where the listener will be applied.listener
- an invitation listener.public static void removeInvitationListener(XMPPConnection conn, InvitationListener listener)
conn
- the connection where the listener was applied.listener
- an invitation listener.public void addInvitationRejectionListener(InvitationRejectionListener listener)
listener
- an invitation rejection listener.public void removeInvitationRejectionListener(InvitationRejectionListener listener)
listener
- an invitation rejection listener.public void addSubjectUpdatedListener(SubjectUpdatedListener listener)
listener
- a subject updated listener.public void removeSubjectUpdatedListener(SubjectUpdatedListener listener)
listener
- a subject updated listener.public String getSubject()
To be notified every time the room's subject change you should add a listener
to this room. addSubjectUpdatedListener(SubjectUpdatedListener)
To change the room's subject use changeSubject(String)
.
public String getReservedNickname()
public String getNickname()
public void changeNickname(String nickname) throws XMPPException
nickname
- the new nickname within the room.
XMPPException
- if the new nickname is already in use by another occupant.public void changeAvailabilityStatus(String status, Presence.Mode mode)
status
- a text message describing the presence update.mode
- the mode type for the presence update.public void kickParticipant(String nickname, String reason) throws XMPPException
nickname
- the nickname of the participant or visitor to kick from the room
(e.g. "john").reason
- the reason why the participant or visitor is being kicked from the room.
XMPPException
- if an error occurs kicking the participant. In particular, a
405 error can occur if a moderator or a user with an affiliation of "owner" or "admin"
was intended to be kicked (i.e. Not Allowed error); or a
403 error can occur if the participant that intended to kick another participant does
not have kicking privileges (i.e. Forbidden error); or a
400 error can occur if the provided nickname is not present in the room.public void grantVoice(String nickname) throws XMPPException
nickname
- the nickname of the visitor to grant voice in the room (e.g. "john").
XMPPException
- if an error occurs granting voice to a visitor. In particular, a
403 error can occur if the participant that intended to grant voice is not
a moderator in this room (i.e. Forbidden error); or a
400 error can occur if the provided nickname is not present in the room.public void revokeVoice(String nickname) throws XMPPException
nickname
- the nickname of the participant to revoke voice (e.g. "john").
XMPPException
- if an error occurs revoking voice from a participant. In particular, a
405 error can occur if a moderator or a user with an affiliation of "owner" or "admin"
was tried to revoke his voice (i.e. Not Allowed error); or a
400 error can occur if the provided nickname is not present in the room.public void banUser(String jid, String reason) throws XMPPException
jid
- the bare XMPP user ID of the user to ban (e.g. "user@host.org").reason
- the reason why the user was banned.
XMPPException
- if an error occurs banning a user. In particular, a
405 error can occur if a moderator or a user with an affiliation of "owner" or "admin"
was tried to be banned (i.e. Not Allowed error).public void grantMembership(String jid) throws XMPPException
jid
- the XMPP user ID of the user to grant membership (e.g. "user@host.org").
XMPPException
- if an error occurs granting membership to a user.public void revokeMembership(String jid) throws XMPPException
jid
- the bare XMPP user ID of the user to grant membership (e.g. "user@host.org").
XMPPException
- if an error occurs revoking membership to a user.public void grantModerator(String nickname) throws XMPPException
nickname
- the nickname of the occupant to grant moderator privileges.
XMPPException
- if an error occurs granting moderator privileges to a user.public void revokeModerator(String nickname) throws XMPPException
nickname
- the nickname of the occupant to revoke moderator privileges.
XMPPException
- if an error occurs revoking moderator privileges from a user.public void grantOwnership(String jid) throws XMPPException
jid
- the bare XMPP user ID of the user to grant ownership (e.g. "user@host.org").
XMPPException
- if an error occurs granting ownership privileges to a user.public void revokeOwnership(String jid) throws XMPPException
jid
- the bare XMPP user ID of the user to grant ownership (e.g. "user@host.org").
XMPPException
- if an error occurs granting ownership privileges to a user.public void grantAdmin(String jid) throws XMPPException
jid
- the bare XMPP user ID of the user to grant administrator privileges
(e.g. "user@host.org").
XMPPException
- if an error occurs granting administrator privileges to a user.public void revokeAdmin(String jid) throws XMPPException
jid
- the bare XMPP user ID of the user to revoke administrator privileges
(e.g. "user@host.org").
XMPPException
- if an error occurs revoking administrator privileges from a user.public int getParticipantCount()
Note: this value will only be accurate after joining the group chat, and may fluctuate over time. If you query this value directly after joining the group chat it may not be accurate, as it takes a certain amount of time for the server to send all presence packets to this client.
public Iterator getParticipants()
StringUtils.parseResource(String)
method.
Note: this value will only be accurate after joining the group chat, and may
fluctuate over time.
public Presence getParticipantPresence(String participant)
participant
- the room occupant to search for his presence. The format of participant must
be: roomName@service/nickname (e.g. darkcave@macbeth.shakespeare.lit/thirdwitch).
public String getParticipantJID(String participant)
participant
- the room occupant to search for his JID. The format of participant must
be: roomName@service/nickname (e.g. darkcave@macbeth.shakespeare.lit/thirdwitch).
public void addParticipantListener(PacketListener listener)
listener
- a packet listener that will be notified of any presence packets
sent to the group chat.public void removeParticipantListener(PacketListener listener)
listener
- a packet listener that was being notified of any presence packets
sent to the group chat.public void sendMessage(String text) throws XMPPException
text
- the text of the message to send.
XMPPException
- if sending the message fails.public Chat createPrivateChat(String participant)
participant
- occupant unique room JID (e.g. 'darkcave@macbeth.shakespeare.lit/Paul').
public Message createMessage()
public void sendMessage(Message message) throws XMPPException
message
- the message.
XMPPException
- if sending the message fails.public Message pollMessage()
nextMessage()
method since it's non-blocking.
In other words, the method call will always return immediately, whereas the
nextMessage method will return only when a message is available (or after
a specific timeout).
public Message nextMessage()
public Message nextMessage(long timeout)
timeout
- the maximum amount of time to wait for the next message.
public void addMessageListener(PacketListener listener)
listener
- a packet listener.public void removeMessageListener(PacketListener listener)
listener
- a packet listener.public void changeSubject(String subject) throws XMPPException
subject
- the new room's subject to set.
XMPPException
- if someone without appropriate privileges attempts to change the
room subject will throw an error with code 403 (i.e. Forbidden)public void addUserStatusListener(UserStatusListener listener)
listener
- a user status listener.public void removeUserStatusListener(UserStatusListener listener)
listener
- a user status listener.public void addParticipantStatusListener(ParticipantStatusListener listener)
listener
- a participant status listener.public void removeParticipantStatusListener(ParticipantStatusListener listener)
listener
- a participant status listener.public void finalize() throws Throwable
finalize
in class Object
Throwable
|
Smack | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |